transcriber/tasks/items/json-api-for-spa.md

✨ Свести приём и чтение записей к одному контракту для приложения

• Тип: feature
• Категория: Очередь
• Зачем: Сегодняшний API отвечает 404 на любую ошибку чтения и 500 на любую ошибку приёма: строить на нём экраны нечем.
• Теги: goal:web-access

Двигает пункты 1, 2 и 4 «Завершения» цели: экраны заводят задачу, видят её состояние и листают список — всё через один контракт.

Обработчик GET /api/status/:id сегодня отвечает 404 на любую ошибку чтения, включая сбой базы, а POST /api/audio — 500 на любую ошибку заведения, включая негодный файл. Экран, построенный на таком контракте, показывает «не найдено» при упавшей базе.

Затрагивает

• POST /api/audio и GET /api/status/:id — коды ответа и форма ошибки;
• новый эндпоинт списка своих записей с постраничным чтением;
• единая точка отображения доменной ошибки в код ответа — её сегодня нет (conventions/errors.md);
• internal/contract — доменные ошибки под отображение;
• internal/controller/http целиком;
• docs/architecture.md, раздел «Единые точки проекта».

Критерии приёмки

• Сбой базы при чтении задачи даёт 500, а не 404. Оракул — тест с репозиторием, возвращающим ошибку драйвера.
• Негодный файл даёт 400 с человекочитаемым текстом, а не 500. Оракул — тест: файл, который отвергает разбор метаданных.
• Тело ошибки одной формы на всех эндпоинтах, не содержит сырого err.Error() и опечатки transcibe. Оракул — тест на четырёх ветвях отказа (форма совпадает, текста внутренней ошибки в теле нет) плюс пустой grep -rn 'transcibe' internal/.
• Список записей отдаётся страницами и упорядочен по времени создания. Оракул — тест на выборке больше страницы.
• Отображение ошибки живёт в одной функции, и она названа в docs/architecture.md. Оракул — task gate, шаг docs.py check.

Рамки

Аутентификацию и владельца не заводим — это oidc-login и record-ownership; задача про форму контракта. Публичный контракт после мерджа обратной правкой не откатывается — поэтому сюда же приехала опечатка transcibe в тексте ошибки приёма (нашёл проход review-specs на ревью change 2026-08-11-fix-http-handler-tests): в одиночку текст ошибки менять нельзя, а здесь контракт переписывается целиком.