transcriber/openspec/specs/intake/spec.md

intake Specification

Purpose

Приём записи и опрос готовности задачи расшифровки: что считается принятой записью, что уезжает в ответ и что происходит, когда запись не удалось прочитать.

Описан пока только приём по HTTP — тот, что нормируют проверки. Приём из Telegram делит с ним общий шаг заведения задачи, но требований на него нет: требование, написанное без проверки, — предположение, а не норма. Первая задача, которая трогает поведение приёма из Telegram, дописывает его сюда.

Requirements

Requirement: Приём записи по HTTP

Сервис SHALL принимать запись от внешней программы запросом POST /api/audio с телом multipart/form-data и полем audio. Принятая запись MUST быть сохранена и получить заведённую под неё задачу расшифровки в состоянии created; ответ MUST нести идентификатор задачи полем job_id и её состояние полем status.

Имена полей ответа нормативны: контракт HTTP API объявлен проектом необратимым, и переименование поля ломает внешнюю программу молча.

Приём не судит о годности записи сам: расширение он берёт из имени файла, а пригодность содержимого узнаёт у источника метаданных.

Scenario: Запись принята

• GIVEN источник метаданных читает запись и отдаёт её длительность
• WHEN программа шлёт POST /api/audio с полем audio
• THEN ответ имеет код 201, а в теле лежат непустой job_id и status со значением created
• AND содержимое записи целиком лежит в каталоге хранения одним файлом

Scenario: Поля с записью нет

• WHEN программа шлёт POST /api/audio без поля audio
• THEN ответ имеет код 400 и сообщение об отсутствии записи
• AND ни файла, ни задачи не заводится

Scenario: Размеру записи приём не судья

• GIVEN источник метаданных читает запись и отдаёт её длительность
• WHEN программа шлёт запись нулевой длины
• THEN ответ имеет код 201: собственного порога по размеру у приёма нет

Requirement: Имя файла в хранилище

Сервис SHALL сохранять принятую запись под собственным именем — идентификатором, к которому приписано расширение из имени файла отправителя. Имя, данное отправителем, MUST не попадать в хранилище: оно приходит извне и содержимым своим приёму не подконтрольно.

Расширения в присланном имени нет — сервис MUST подставить .audio, чтобы у файла на диске расширение было всегда.

Scenario: Расширение взято из имени отправителя

• WHEN программа шлёт запись с именем test.mp3
• THEN файл в каталоге хранения имеет расширение .mp3

Scenario: Имени без расширения назначено своё

• WHEN программа шлёт запись с именем test без расширения
• THEN файл в каталоге хранения имеет расширение .audio

Requirement: Отказ чтения метаданных

Сервис SHALL отвечать отказом, когда источник метаданных не смог прочитать принятую запись. Ответ MUST иметь код 500, а причина отказа MUST не попадать в тело ответа: она принадлежит журналу, а не отправителю.

Scenario: Источник метаданных вернул ошибку

• GIVEN источник метаданных не может прочитать запись
• WHEN программа шлёт POST /api/audio с этой записью
• THEN ответ имеет код 500
• AND задача расшифровки не заводится

Requirement: Имя файла, данное отправителем, не попадает в журнал

Приём SHALL не писать имя файла, данное отправителем, ни в одну свою журнальную запись — ни на успешном пути, ни на пути отказа, где имя могло бы приехать текстом ошибки. Имя приходит извне вместе с записью и принадлежит содержимому личной переписки наравне с текстом расшифровки; журнал уезжает в собранные логи, откуда строку не убрать.

Расширение, взятое из этого имени, в журнале остаётся: оно стоит в собственном имени файла на диске, и по нему прослеживается путь записи. Что именно попадает в журнал ради прослеживаемости, нормирует требование ниже; наружу расширение выходит только приведённым к известному виду — этому отдано отдельное требование.

Сценарии судят приём по HTTP, потому что имя, данное отправителем, доходит до сервиса только оттуда: из Telegram приходит путь, выданный самим Telegram, а не имя человека. Правка при этом ложится на общий шаг заведения задачи, через который идут оба входа, поэтому своей нормы приём из Telegram здесь не получает — её напишет задача, которая тронет его поведение.

Scenario: Имя записи не видно в журнале принятой записи

• GIVEN источник метаданных читает запись и отдаёт её длительность
• WHEN программа шлёт POST /api/audio с записью, чья основа имени несёт опознаваемую строку при обычном расширении .mp3
• THEN ни одна журнальная запись приёма этой строки не содержит
• AND расширение .mp3 в журнале допустимо

Scenario: Имя записи не видно в журнале при отказе приёма

• GIVEN источник метаданных не может прочитать запись
• WHEN программа шлёт POST /api/audio с записью, чья основа имени несёт опознаваемую строку
• THEN ни одна журнальная запись приёма, включая запись об ошибке, этой строки не содержит

Requirement: Журнал приёма прослеживает запись

Приём SHALL писать в журнал идентификатор заведённого файла, расширение принятой записи и её размер в байтах. По ним путь записи собирается отбором по журналу, и удаление имени отправителя прослеживаемости не отнимает.

Расширение засчитывается присутствием собственного имени файла в хранилище: отдельного поля под него приём не заводит.

Scenario: Идентификатор, расширение и размер на месте

• GIVEN источник метаданных читает запись и отдаёт её длительность
• WHEN программа шлёт POST /api/audio с записью
• THEN журнал приёма несёт идентификатор заведённого файла, расширение принятой записи и её размер в байтах

Requirement: Метка метрики несёт только известное расширение

Сервис SHALL приводить расширение принятой записи к известному виду прежде, чем употребить его меткой метрики: расширение приводится к нижнему регистру и сверяется с закрытым перечнем; совпавшее идёт приведённым, всякое другое MUST заменяться единым значением other. Перечень — mp3, wav, ogg, oga, opus, flac, m4a, aac, wma, mp4, mkv, mov, avi, webm, плюс audio: последнее не формат, а собственное умолчание сервиса на случай имени без расширения, и различать его от чужого хвоста метка обязана.

Страница метрик отдаётся без проверки отправителя, поэтому метка — поверхность пошире журнала: её читает кто угодно. Тем же ограничением снимается и рост числа временных рядов, которым иначе распоряжается анонимный отправитель.

Требование намеренно шире приёма: под него подпадает и метка шага конвертации. Когда конвертацию нормируют своей capability, обязанность переезжает туда вместе с ней.

Имя файла на диске это требование не трогает: там расширение остаётся тем, каким пришло, — это уже нормировано требованием «Имя файла в хранилище».

Настоящий формат записи, попавшей в other, остаётся видимым в журнале: значение other в метке означает «расширение не из перечня», а само оно стоит в поле пути журнальной строки приёма и в поле формата строки конвертации.

Scenario: Незнакомое расширение наружу не выходит

• GIVEN источник метаданных читает запись и отдаёт её длительность
• WHEN программа шлёт запись с именем, чей хвост после последней точки не принадлежит перечню known-форматов
• THEN метка метрики принимает значение other
• AND файл в каталоге хранения сохраняет пришедшее расширение

Scenario: Известное расширение идёт как есть

• GIVEN источник метаданных читает запись и отдаёт её длительность
• WHEN программа шлёт запись с именем sample.MP3
• THEN метка метрики принимает значение mp3

Requirement: Опрос готовности задачи

Сервис SHALL отдавать состояние задачи расшифровки по запросу GET /api/status/:id. Ответ MUST нести идентификатор полем job_id, состояние полем status и время заведения полем created_at, а текст расшифровки полем transcription_text, и это поле MUST отсутствовать в ответе, пока текста нет: пустая строка на месте отсутствующего текста читается как «расшифровка пуста».

Scenario: Задача найдена

• WHEN программа спрашивает состояние заведённой задачи
• THEN ответ имеет код 200 и несёт job_id, status и created_at

Scenario: Расшифровки ещё нет

• WHEN программа спрашивает состояние задачи, которая ещё не дошла до текста
• THEN поля transcription_text в ответе нет вовсе

Scenario: Задачи с таким идентификатором нет

• WHEN программа спрашивает состояние по неизвестному идентификатору
• THEN ответ имеет код 404 и сообщение о ненайденной задаче