av
1576d06735
- audiorecords вместо transcribe_jobs: приложения (texts, structures, recognitions, record_events, topics) живут своими коллекциями, ссылки на исходник и на приведённую копию перестали переставляться - рубеж называет достигнутое, отказ стал признаком остановки с причиной, а сторожей стало двое: число отказов и время в рубеже - воркеры потеряли специализацию, их число задаётся [pipeline] workers, шаг выбирается по рубежу, а захват отдаёт идентификатор и признак захвата
287 lines
32 KiB
Markdown
287 lines
32 KiB
Markdown
# Архитектура
|
||
|
||
Обзор: как сложено и где что работает. **Поведение системы здесь не описывается**
|
||
— нормативно оно живёт в `openspec/specs/`. Места, где оно всё-таки описано,
|
||
помечены маркером долга и переезжают туда первой же задачей, которая их трогает.
|
||
|
||
Документ описывает **сегодняшнее** устройство. Куда проект идёт — в
|
||
[passport.md](passport.md) и в [tasks/BACKLOG.md](../tasks/BACKLOG.md); что из
|
||
этого ещё не решено — в разделе «Открытые вопросы».
|
||
|
||
Заведённые capability нормируют **поведение сервиса** для его потребителей —
|
||
все до одной. Инструмент, которым сервис собирают, спеками не нормируется вовсе:
|
||
у набора проверок и сборки другой потребитель — тот, кто собирает, — и решением
|
||
от 2026-08-13 его нормы живут в самих шагах, их проверках и
|
||
[conventions/go-linters.md](conventions/go-linters.md).
|
||
|
||
- [intake](../openspec/specs/intake/spec.md) — **приём по 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](../openspec/specs/pipeline/spec.md) — пустой прогон воркера, захват
|
||
задачи и срок его протухания, число попыток, состояние «мертва», пауза перед
|
||
повтором и недоставленный ответ отправителю: задачи
|
||
`errors-as-instead-of-typecast` 2026-08-11, `pocketbase-storage` 2026-08-12 и
|
||
`local-run-without-telegram-token` 2026-08-13. Переходы состояний и отмена
|
||
контекста посреди шага остаются
|
||
долгом; что именно не описано, перечисляет раздел `Purpose` самой спеки;
|
||
- [storage](../openspec/specs/storage/spec.md) — где живут запись, её метаданные
|
||
и её файл, как файл отдаётся и что видит владелец: задача `pocketbase-storage`
|
||
2026-08-12;
|
||
- [recognition](../openspec/specs/recognition/spec.md) — **попытка распознавания
|
||
у внешнего провайдера**: что о ней хранится, почему сырой ответ сохраняется
|
||
целиком и вложением, как из сохранённого строится структура реплик без
|
||
повторной оплаты и почему разбор формата провайдера не доходит до конвейера.
|
||
Задача `record-centric-model` 2026-08-14;
|
||
- [access](../openspec/specs/access/spec.md) — кто пришёл в сервис и пускают ли
|
||
его дальше: вход через внешнего провайдера OIDC, чем предъявляется сессия, что
|
||
её прекращает и какие адреса остаются открытыми. Задача `oidc-login`
|
||
2026-08-12. Здесь же разграничение записей по владельцу: запись из веба
|
||
принадлежит тому, кто её принёс, чужая неотличима от несуществующей, а запись
|
||
из Telegram владельца не имеет и по API не достаётся никому. Задача
|
||
`record-ownership` 2026-08-14.
|
||
|
||
Поведение прочих узлов, включая приём из Telegram, по-прежнему живёт только в
|
||
коде. Задача, которая его трогает, дописывает спеку своей capability.
|
||
|
||
## Принципы
|
||
|
||
- **Один процесс.** Бот, HTTP-сервер и фоновые воркеры живут в одном бинарнике и
|
||
делят одну базу. Отдельного воркер-процесса нет намеренно.
|
||
- **Очередь таблицей.** Состояние задачи лежит коллекцией хранилища; неделимость
|
||
захвата и порядок выборки нормирует
|
||
[pipeline](../openspec/specs/pipeline/spec.md), «Захват задачи неделим».
|
||
Внешний брокер не заводим: нагрузка — единицы записей в день (оценка владельца,
|
||
не замер). Готовую библиотеку очереди тоже не заводим — решено 2026-08-11,
|
||
[ADR](adr/ADR-2026-08-11-queue-as-pocketbase-collection.md), сравнение
|
||
кандидатов в [research/job-queue.md](research/job-queue.md).
|
||
- **Шаг конвейера идемпотентен по повтору.** Что делает срок захвата и когда
|
||
задача возвращается в работу, нормирует
|
||
[pipeline](../openspec/specs/pipeline/spec.md), «Брошенная задача возвращается
|
||
в работу»; здесь это принцип письма шага, а не описание поведения.
|
||
- **Ядро зависит от интерфейсов.** `internal/service` знает только
|
||
`internal/contract`; ffmpeg, Yandex, Telegram и хранилище подставляются в
|
||
`main.go`. Правило механизировано тестами-сканерами `internal/archrules`, и
|
||
они же держат обратные направления: транспорты не знают друг о друге, адаптер
|
||
не знает ни ядра, ни транспортов.
|
||
*Изъятие:* транспорт **вправе** знать адаптер хранилища — `controller/http`
|
||
импортирует `adapter/repo/pocketbase`, потому что HTTP-поверхность и есть
|
||
роутер этого хранилища, а не наш сервер поверх него. Правила на это
|
||
направление нет намеренно.
|
||
|
||
## Компоненты
|
||
|
||
Каждый — строкой со ссылкой на capability, а не пересказом её требований.
|
||
|
||
<!-- канон: поведение → openspec/specs/intake, pipeline, storage; ещё НЕ переехало: приём из Telegram, деление длинного текста по словам -->
|
||
|
||
| Компонент | Где | Что делает |
|
||
| --- | --- | --- |
|
||
| 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](../openspec/specs/storage/spec.md), «Владелец видит записи в панели» |
|
||
|
||
Цепочка рубежей — `uploaded` → `normalized` → `submitted` → `transcribed` →
|
||
`done`; рубеж называет достигнутое, а не предстоящее, и нормирует его
|
||
[pipeline](../openspec/specs/pipeline/spec.md), «Рубеж записи называет
|
||
достигнутое». Отказ рубежом не является: он ставит признак остановки, а рубеж
|
||
сохраняется — там же, «Остановка записи — признак, а не рубеж». Шаг выбирается
|
||
по рубежу одним местом, воркеры к шагам не привязаны, а их число приходит
|
||
настройкой.
|
||
|
||
## Внешние границы и форматы
|
||
|
||
- **Telegram Bot API.** Вход — обновления длинным опросом, выход — сообщения.
|
||
Файл скачивается по ссылке `file.Link(token)` запросом с контекстом, клиентом
|
||
самого бота. Клиента заводит единая точка `internal/adapter/telegram`: токен
|
||
стоит в пути каждого обращения, и снятие адреса с отказа живёт там —
|
||
[conventions/logging.md](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](database.md), «Настройки с числовым значением»:
|
||
|
||
<!-- канон: поведение → openspec/specs/intake, pipeline -->
|
||
|
||
| Зависимость | Падает | Отвечает медленно | Молчит | Отдаёт мусор |
|
||
| --- | --- | --- | --- | --- |
|
||
| Telegram Bot API | Сервис поднимается без Telegram и работает по HTTP; старт роняют только ошибки настройки — ответ «такого бота нет» и включённый вход с пустым ключом доступа. Норму держит [intake](../openspec/specs/intake/spec.md), «Признак включения решает, поднимается ли вход 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](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](adr/ADR-2026-08-11-pocketbase-storage-with-admin-panel.md)), сессия
|
||
живёт кукой `transcriber_session` и сама себя не продлевает. Норма —
|
||
[access](../openspec/specs/access/spec.md), решения —
|
||
[ADR-2026-08-12-session-without-refresh](adr/ADR-2026-08-12-session-without-refresh.md)
|
||
и [ADR-2026-08-12-oidc-exchange-via-own-route](adr/ADR-2026-08-12-oidc-exchange-via-own-route.md).
|
||
**Не решено одно:** как связываются пользователь Telegram и пользователь веба.
|
||
Панель администратора при этом Authelia не закрывает: у неё свой пароль
|
||
суперпользователя.
|
||
- **Приложение.** Экранов нет вовсе, есть только API. Решено делать SPA,
|
||
устанавливаемое на телефон, а фреймворком взят Vue 3 с роутером пятой версии и
|
||
сборкой Vite — 2026-08-11,
|
||
[ADR](adr/ADR-2026-08-11-spa-on-vue.md), сравнение кандидатов в
|
||
[research/spa-framework.md](research/spa-framework.md). Тем же решением Node
|
||
входит в гейт и слоем в сборку образа. Пишет это `spa-skeleton`; во что
|
||
обходится слой Node в образе, не замерялось. Не решено, брать ли готовый набор
|
||
компонентов.
|
||
- **Уведомления.** Пользователь веба узнаёт о готовности только опросом.
|
||
Доставку решено брать внешнюю — apprise как отправитель, ntfy как канал; Web
|
||
Push с VAPID отвергнут. Появляется внешняя зависимость, которой сегодня нет, и
|
||
текст расшифровки начинает уходить на сторону — сдвиг периметра
|
||
[security.md](security.md).
|
||
- **Долгие записи.** Потолок сегодня неизвестен и не замерялся: 20 МиБ на приём
|
||
из Telegram — точно, ограничения `deferred-general` по длине — нет. Расчётные
|
||
шесть часов нормирует [storage](../openspec/specs/storage/spec.md), «Файл
|
||
записи живёт в хранилище»; откуда взято число —
|
||
[research/pocketbase-defaults.md](research/pocketbase-defaults.md), «Чего эта
|
||
записка не узнала».
|
||
- **Приём большого файла.** Форма читается целиком, предел памяти под multipart
|
||
задан числом в [database.md](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](adr/ADR-2026-08-11-queue-as-pocketbase-collection.md)), перестроена
|
||
вокруг аудиозаписи задачей `record-centric-model` 2026-08-14 и нормирована
|
||
спекой `pipeline`. Не решено, отказываться ли от холостого опроса: он
|
||
даёт сотни тысяч запросов к базе в сутки — расчёт из числа воркеров и их
|
||
паузы, а не замер
|
||
([research/job-queue.md](research/job-queue.md), «Как снималось»), — при
|
||
нагрузке в единицы записей в день, и во что это обходится, никто не мерил.
|
||
- **Наблюдаемость.** `/metrics` остаётся и развивается. Чем — дописывать
|
||
счётчики через `client_golang` или перейти на OpenTelemetry с трассировкой —
|
||
решает разведка `opentelemetry-fit`. Коллектор был бы процессом, которого в
|
||
выкладке сегодня нет.
|
||
- **Выводы из текста.** Литературный текст, заголовок, темы и пересказ решено
|
||
считать внешним сервисом с OpenAI-совместимым интерфейсом за шлюзом bifrost.
|
||
Появляется пятая внешняя зависимость, платная, и текст расшифровки начинает
|
||
уходить ещё на одну сторону — сдвиг периметра [security.md](security.md). Не
|
||
решено, отдельный это шаг конвейера или продолжение шага распознавания.
|