transcriber/docs/architecture.md

Архитектура

Обзор: как сложено и где что работает. Поведение системы здесь не описывается — нормативно оно живёт в openspec/specs/. Места, где оно всё-таки описано, помечены маркером долга и переезжают туда первой же задачей, которая их трогает.

Документ описывает сегодняшнее устройство. Куда проект идёт — в passport.md и в tasks/BACKLOG.md; что из этого ещё не решено — в разделе «Открытые вопросы».

Заведённые capability нормируют поведение сервиса для его потребителей — все до одной. Инструмент, которым сервис собирают, спеками не нормируется вовсе: у набора проверок и сборки другой потребитель — тот, кто собирает, — и решением от 2026-08-13 его нормы живут в самих шагах, их проверках и conventions/go-linters.md.

• intake — приём по HTTP плюс наличие входов: приём и опрос за сессией, имя отправителя не доходит ни до хранилища, ни до журнала, метка метрики несёт только известное расширение, а выключенный вход Telegram не мешает подъёму. Задачи http-handler-tests-never-green и no-user-filename-in-log 2026-08-11, pocketbase-storage и oidc-login 2026-08-12, local-run-without-telegram-token 2026-08-13. Приём из Telegram по существу — кто допущен и как забирается запись — здесь по-прежнему не описан;
• pipeline — пустой прогон воркера, захват задачи и срок его протухания, число попыток, состояние «мертва», пауза перед повтором и недоставленный ответ отправителю: задачи errors-as-instead-of-typecast 2026-08-11, pocketbase-storage 2026-08-12 и local-run-without-telegram-token 2026-08-13. Переходы состояний и отмена контекста посреди шага остаются долгом; что именно не описано, перечисляет раздел Purpose самой спеки;
• storage — где живут запись, её метаданные и её файл, как файл отдаётся и что видит владелец: задача pocketbase-storage 2026-08-12;
• recognition — попытка распознавания у внешнего провайдера: что о ней хранится, почему сырой ответ сохраняется целиком и вложением, как из сохранённого строится структура реплик без повторной оплаты и почему разбор формата провайдера не доходит до конвейера. Задача record-centric-model 2026-08-14;
• access — кто пришёл в сервис и пускают ли его дальше: вход через внешнего провайдера OIDC, чем предъявляется сессия, что её прекращает и какие адреса остаются открытыми. Задача oidc-login 2026-08-12. Здесь же разграничение записей по владельцу: запись из веба принадлежит тому, кто её принёс, чужая неотличима от несуществующей, а запись из Telegram владельца не имеет и по API не достаётся никому. Задача record-ownership 2026-08-14.

Поведение прочих узлов, включая приём из Telegram, по-прежнему живёт только в коде. Задача, которая его трогает, дописывает спеку своей capability.

Принципы

• Один процесс. Бот, HTTP-сервер и фоновые воркеры живут в одном бинарнике и делят одну базу. Отдельного воркер-процесса нет намеренно.
• Очередь таблицей. Состояние задачи лежит коллекцией хранилища; неделимость захвата и порядок выборки нормирует pipeline, «Захват задачи неделим». Внешний брокер не заводим: нагрузка — единицы записей в день (оценка владельца, не замер). Готовую библиотеку очереди тоже не заводим — решено 2026-08-11, ADR, сравнение кандидатов в research/job-queue.md.
• Шаг конвейера идемпотентен по повтору. Что делает срок захвата и когда задача возвращается в работу, нормирует pipeline, «Брошенная задача возвращается в работу»; здесь это принцип письма шага, а не описание поведения.
• Ядро зависит от интерфейсов. internal/service знает только internal/contract; ffmpeg, Yandex, Telegram и хранилище подставляются в main.go. Правило механизировано тестами-сканерами internal/archrules, и они же держат обратные направления: транспорты не знают друг о друге, адаптер не знает ни ядра, ни транспортов. Изъятие: транспорт вправе знать адаптер хранилища — controller/http импортирует adapter/repo/pocketbase, потому что HTTP-поверхность и есть роутер этого хранилища, а не наш сервер поверх него. Правила на это направление нет намеренно.

Компоненты

Каждый — строкой со ссылкой на capability, а не пересказом её требований.

Компонент	Где	Что делает
Telegram-бот	internal/controller/tg	Принимает голосовые, аудиофайлы и документы с аудио, скачивает их, заводит задачу
HTTP API	internal/controller/http	Приём файла и опрос статуса задачи
Воркеры	internal/controller/worker	Пул одинаковых потоков: каждый берёт любую пригодную запись и опрашивает базу. Число — настройкой, ноль законен
Сервис расшифровки	internal/service	Конвейер: приём, приведение, отправка, опрос, завершение. Шаг выбирается по рубежу записи
Конвертер и метаданные	internal/adapter/{converter,metaviewer}/ffmpeg	ffmpeg в ogg/vorbis, ffprobe для длительности
Распознаватель	internal/adapter/recognizer/yandex	Заливка в Object Storage и отложенное распознавание SpeechKit; разбор ответа в реплики со временем
Отправитель Telegram	internal/adapter/telegram	Отправка текста, деление длинного по словам
Репозитории	internal/adapter/repo/pocketbase	Записи, файлы, тексты, структура, попытки распознавания и журнал событий — коллекциями хранилища; захват — сырым запросом
Шаги схемы	internal/adapter/repo/pocketbase/migrations	Файл на шаг, имя файла — имя шага; там же имена коллекций
Панель владельца	internal/adapter/repo/pocketbase, panel.go	Панель хранилища; правила правки записи нормирует storage, «Владелец видит записи в панели»

Цепочка рубежей — uploaded → normalized → submitted → transcribed → done; рубеж называет достигнутое, а не предстоящее, и нормирует его pipeline, «Рубеж записи называет достигнутое». Отказ рубежом не является: он ставит признак остановки, а рубеж сохраняется — там же, «Остановка записи — признак, а не рубеж». Шаг выбирается по рубежу одним местом, воркеры к шагам не привязаны, а их число приходит настройкой.

Внешние границы и форматы

• Telegram Bot API. Вход — обновления длинным опросом, выход — сообщения. Файл скачивается по ссылке file.Link(token) запросом с контекстом, клиентом самого бота. Клиента заводит единая точка internal/adapter/telegram: токен стоит в пути каждого обращения, и снятие адреса с отказа живёт там — conventions/logging.md, «Безопасность: что не логируем». Telegram не отдаёт файлы больше 20 МиБ — это потолок приёма из бота.
• Yandex Object Storage. S3-совместимый, клиент aws-sdk-go-v2 с UsePathStyle. Ключ объекта — имя файла, то есть UUID с расширением.
• Yandex SpeechKit v3. gRPC, stt.api.cloud.yandex.net:443, модель deferred-general, авторизация заголовком Api-Key. Распознавание асинхронное: запрос возвращает идентификатор операции, готовность опрашивается через operation.api.cloud.yandex.net:443, текст читается потоком.
• ffmpeg и ffprobe. Внешние процессы, ищутся в PATH.

Эксплуатация

• Где работает, что рядом, кто перезапускает: один контейнер на личном сервере, разворачивает и перезапускает Ansible из pet-project-server. Рядом — обратный прокси, который публикует HTTP-порт наружу.

• Порядок выкладки задаётся по ключу, а не по файлу целиком. Общего правила «сперва образ» или «сперва конфиг» нет: два ключа секции Telegram требуют противоположного, и оба правила действуют одновременно.

  • Признак включения telegram.enabled едет в конфиг раньше образа. Он обязателен с 2026-08-13, умолчания у него нет, и образ, который его ждёт, без него выходит с кодом 1 до открытия порта — вместе с HTTP, панелью и конвейером. Прежний образ лишний ключ TOML просто не читает, поэтому ранняя правка конфига безопасна, а поздняя роняет сервис.
  • Пустой ключ доступа telegram.bot_token едет позже образа. Образы старше 2026-08-13 роняли старт на пустом ключе, тоже до открытия порта.
  • Откат при выключенном входе допустим только на образ от 2026-08-13 и новее. На более старом состояния «сервис поднят, бот опущен» не существует вовсе: пустой ключ роняет старт, негодный роняет старт, годный поднимает бота. Откат туда делают с непустым годным ключом, приняв, что бот поднимется.
  • Откат образа при enabled = false и заполненном ключе отменяет решение владельца молча: прежний образ признака не видит и поднимает бота. Если вход был выключен потому, что бот с этим токеном поднят где-то ещё, два процесса поделят один длинный опрос и часть ответов до людей не дойдёт.

  Ревью кода воспроизвело порядок на прежней версии, живой прогон — на нынешней.

• Откат образа через шаг схемы 202608140002 не работает и не говорит об этом. Шаг удаляет прежнюю коллекцию задач, а библиотека накатывает только те шаги, которые знает сам бинарь: прежний образ шагов новее не видит, поднимается без единой ошибки и отвечает зелёной пробой здоровья — после чего всякое обращение к очереди отказывает «коллекции нет». Проверено прогоном двух бинарей на одном каталоге данных.

  Значит штатное средство владельца на инциденте — «вернём прошлый образ» — с этого шага делает хуже и молчит. Лечится повторной выкладкой нового образа; обратного шага схемы нет и не планируется. Порог перехода назван прямо: до выкладки record-centric-model откат образа работает, после — нет.

• Внешние зависимости поимённо и чем каждая отказывает. Столбец «отвечает медленно» читается вместе с тем, что таймаута нет ни у одного обращения наружу — database.md, «Настройки с числовым значением»:

  Зависимость	Падает	Отвечает медленно	Молчит	Отдаёт мусор
  Telegram Bot API	Сервис поднимается без Telegram и работает по HTTP; старт роняют только ошибки настройки — ответ «такого бота нет» и включённый вход с пустым ключом доступа. Норму держит intake, «Признак включения решает, поднимается ли вход Telegram»	На старте — ждём не дольше срока, дальше поднимаемся без Telegram. У поднятого сервиса скачивание файла висит бесконечно: там срока нет	То же, что «отвечает медленно»: на старте — подъём без Telegram по истечении срока, у поднятого — длинный опрос пуст и новые задачи не заводятся	Файл скачался битым, отказ вылезет на конвертации
  Yandex SpeechKit	Шаг возвращает ошибку, запись остаётся на повтор	Захват держится час, запись не двигается; по истечении предела простоя она останавливается с причиной «застряла», не теряя идентификатора операции	Операция вечно in progress, повтор каждые 5 секунд — до предела простоя в сутки	Пустой текст — запись завершается заглушкой «на записи нет текста»
  ↳ остановка сервиса	Принятие операции от отмены защищено своим пределом в 10 секунд: операцию там могли принять и начать считать деньги, а потерянный идентификатор заставил бы повтор оплатить ту же запись второй раз. Заливка в Object Storage отменяется штатно — её повтор бесплатен, объект ложится под тем же ключом	—	—	—
  Yandex Object Storage	Заливка падает, запись остаётся на рубеже normalized	То же, что падение: висит до конца захвата	—	SpeechKit не прочитает объект и вернёт отказ операции
  ffmpeg, ffprobe	Запись останавливается признаком с текстом «сбой конвертации файла» — рубеж при этом сохраняется, и снятие признака продолжает с него. Остановка сервиса — исход другой: процесс убивают контекстом, запись остаётся на повтор и отказа не тратит	Конвейер стоит: вызов синхронный	—	Выходной файл пуст, отказ вылезет на распознавании
  Хранилище (файл на диске)	Приложение не стартует либо шаг падает на каждом запросе	Блокировка записи держит воркеры	—	—
  Диск	Запись файла падает, задача не заводится	—	—	—

• Кто заметит отказ и когда: пользователь Telegram — сразу, по молчанию бота или по сообщению об ошибке. Владелец — по метрике transcriber_worker_job_count с меткой error="true", и метка stage называет рубеж, с которого запись взята: с появлением пула одинаковых воркеров имя потока перестало что-либо значить, а разрез по шагу — единственное, чем «падает приведение» отличается от «падает распознавание». Плюс логи контейнера. Отдельного оповещения нет.

• Журнал событий записи — второй канал наблюдения, record_events. Пишется на смену рубежа, на остановку и на снятие остановки; читает его человек в панели, ни один шаг конвейера на него не смотрит. Экрана у него пока нет.

• Характер потока: непрерывный, но разреженный. Бот держит длинный опрос, воркеры опрашивают базу вхолостую с паузой из database.md, «Настройки с числовым значением».

Единые точки проекта

Что	Где
Приём аудио и заведение записи	TranscribeService.createRecord — через него идут оба входа
Правка записи владельцем	панель хранилища; правка запросом проходит правила перехода (pocketbase.BindPanelRules), а шаг конвейера пишет только свои поля и правку владельца не стирает
Захват записи воркером	AudioRecordRepository.FindAndAcquire — один запрос с RETURNING, отдаёт идентификатор и признак захвата
Объявление рубежа	internal/entity/stage.go — выбор шага, отбор захвата, срок протухания и предел простоя выводятся отсюда
Выбор шага по рубежу	TranscribeService.stepFor — таблица, а не привязка к воркеру
Рабочая копия файла на диске	FileRepository.Localize, Stage, StageEmpty — они же дают единственный способ её убрать (WorkFile.Close); зовёт его шаг
Переход записи на рубеж	entity.AudioRecord.MoveToState — чистит служебные поля прошлого рубежа и ставит время входа
Откладывание работы	entity.AudioRecord.Postpone — ставит паузу и снимает захват, рубежа не трогая
Остановка и перезапуск	entity.AudioRecord.Halt и Resume; ответ отправителю — TranscribeService.halt, одно место на все причины
Разбор конфигурации	internal/config.LoadConfig
Чтение времени	internal/clock — Now даёт метку в UTC, Start — начало измерения длительности; time.Now вне пакета запрещён правилом линтера
Метрики	internal/metrics, префикс имени transcriber_
Значения метки формата	internal/metrics.FormatLabel — приводит расширение к закрытому перечню, прочее заменяет на other; нормирует спека intake

Единых точек, которых нет и которые ожидались бы: идентификаторы генерируются вызовом uuid.NewString() по месту, отображения доменной ошибки в код HTTP-ответа нет — обработчик решает сам. Время из этого перечня ушло 2026-08-13: его читает internal/clock, и запрет держит линтер.

Деплой

Образ собирается по контракту роли app_image: task image даёт transcriber:$BUILD_ID, по умолчанию transcriber:dev. Реестр не участвует — образ едет на сервер через docker save/load. Выкладку целиком запускает человек командой inv pl -- transcriber из pet-project-server.

Сборка двухступенчатая, финальный слой — alpine с ca-certificates и ffmpeg, процесс работает под непривилегированным пользователем transcriber.

Открытые вопросы

• Учётные записи. Вход через OIDC решён и развёрнут 2026-08-12: провайдер — Authelia, ответ провайдера обрабатывает PocketBase, а не наш код (ADR), сессия живёт кукой transcriber_session и сама себя не продлевает. Норма — access, решения — ADR-2026-08-12-session-without-refresh и ADR-2026-08-12-oidc-exchange-via-own-route. Не решено одно: как связываются пользователь Telegram и пользователь веба. Панель администратора при этом Authelia не закрывает: у неё свой пароль суперпользователя.
• Приложение. Экранов нет вовсе, есть только API. Решено делать SPA, устанавливаемое на телефон, а фреймворком взят Vue 3 с роутером пятой версии и сборкой Vite — 2026-08-11, ADR, сравнение кандидатов в research/spa-framework.md. Тем же решением Node входит в гейт и слоем в сборку образа. Пишет это spa-skeleton; во что обходится слой Node в образе, не замерялось. Не решено, брать ли готовый набор компонентов.
• Уведомления. Пользователь веба узнаёт о готовности только опросом. Доставку решено брать внешнюю — apprise как отправитель, ntfy как канал; Web Push с VAPID отвергнут. Появляется внешняя зависимость, которой сегодня нет, и текст расшифровки начинает уходить на сторону — сдвиг периметра security.md.
• Долгие записи. Потолок сегодня неизвестен и не замерялся: 20 МиБ на приём из Telegram — точно, ограничения deferred-general по длине — нет. Расчётные шесть часов нормирует storage, «Файл записи живёт в хранилище»; откуда взято число — research/pocketbase-defaults.md, «Чего эта записка не узнала».
• Приём большого файла. Форма читается целиком, предел памяти под multipart задан числом в database.md, «Настройки с числовым значением»; обрыв начинает загрузку заново. Загрузку частями разбирает разведка chunked-upload-choice; её выбор меняет публичный контракт приёма и потому идёт через решение в adr/.
• Учёт расхода. Распознавание и языковая модель оплачиваются по факту, а учёта по пользователям нет: метрики считают сервис целиком. Что именно копится — записи о потреблении или счётчики — решает задача usage-accounting.
• Срок хранения. Записи и тексты решено хранить бессрочно (паспорт, 2026-08-11), а рост каталога данных ничем не ограничен и не наблюдается.
• Резервные копии. Копии делает сервер своими средствами, и приложение о них ничего не знает. Не решено, хватит ли копировать каталог данных файлами, или приложению нужна команда выгрузки: база под нагрузкой копируется файлом не всегда целой. Своё копирование по расписанию у PocketBase есть — берём мы его или нет, тоже не решено.
• Формат для распознавания. Конвертер отдаёт ogg/vorbis (libvorbis), а SpeechKit получает ContainerAudio_OGG_OPUS. Расхождение не разобрано: то ли сервис определяет содержимое сам, то ли часть записей теряется на этом.
• Видео. Дорожку из видеофайла бот принимает по MIME-типу video/, но конвертер этот случай не проверялся.
• Очередь. Модель очереди сделана задачей pocketbase-storage 2026-08-12 (ADR), перестроена вокруг аудиозаписи задачей record-centric-model 2026-08-14 и нормирована спекой pipeline. Не решено, отказываться ли от холостого опроса: он даёт сотни тысяч запросов к базе в сутки — расчёт из числа воркеров и их паузы, а не замер (research/job-queue.md, «Как снималось»), — при нагрузке в единицы записей в день, и во что это обходится, никто не мерил.
• Наблюдаемость. /metrics остаётся и развивается. Чем — дописывать счётчики через client_golang или перейти на OpenTelemetry с трассировкой — решает разведка opentelemetry-fit. Коллектор был бы процессом, которого в выкладке сегодня нет.
• Выводы из текста. Литературный текст, заголовок, темы и пересказ решено считать внешним сервисом с OpenAI-совместимым интерфейсом за шлюзом bifrost. Появляется пятая внешняя зависимость, платная, и текст расшифровки начинает уходить ещё на одну сторону — сдвиг периметра security.md. Не решено, отдельный это шаг конвейера или продолжение шага распознавания.