av
09228f23d8
- шаг go-version в task gate сверяет объявленную версию в go.mod, Dockerfile, CLAUDE.md и README.md; судит по репозиторию, go не зовёт, docker и сети не требует - заведена capability toolchain: до сих пор спеки нормировали только поведение сервиса, теперь и инструмент сборки. Причина и цена — в двух ADR - закрыт дефект 2026-08-12: образ на golang:1.24-alpine разошёлся с go.mod и перестал собираться, а восемь шагов гейта и шесть проходов ревью были зелёными
6.6 KiB
Transcriber Service
Сервис расшифровки аудиозаписей. Два входа — Telegram-бот и HTTP API.
Возможности
- Приём аудио из Telegram: голосовые сообщения, аудиофайлы и документы с аудио
- Приём аудиофайлов через HTTP API
- Конвертация в ogg через ffmpeg
- Распознавание речи через Yandex SpeechKit
- Отслеживание статуса задач расшифровки
- Встроенная PocketBase для метаданных, файлов и панели владельца; метрики Prometheus
Технологии
- Язык: Go 1.26, CGO не нужен
- Веб-фреймворк: gin-gonic/gin
- Telegram: go-telegram-bot-api
- Распознавание: Yandex SpeechKit + Yandex Object Storage (S3)
- Конвертация: ffmpeg
- Хранилище, файлы и панель: встроенная PocketBase
- База данных: SQLite внутри PocketBase (через modernc.org/sqlite, CGO не нужен)
- Метрики: prometheus/client_golang
Установка и запуск
- Клонируйте репозиторий
- Установите зависимости:
go mod tidy - Скопируйте образец конфига и заполните его:
cp config.dist.toml config.toml - Запустите приложение:
go run . -c config.toml
Сервер запустится на порту из [server] port, по умолчанию 8080. Нужен
установленный ffmpeg.
Белый список Telegram
Бот отвечает только тем, кто перечислен в конфиге. Кого и по какому признаку он пускает — docs/security.md, «Что разграничивает доступ»; известные прорехи образца конфига, включая недостающий ключ белого списка, — docs/conventions/config.md.
Деплой
Деплой запускается из pet-project-server:
inv pl -- transcriber
Плейбук сам зовёт task image (контракт роли app_image): образ собирается
локально и едет на сервер через docker save/load, реестр не участвует.
Локально образ можно собрать и руками — task image даст transcriber:dev.
HTTP API
Четыре маршрута: POST /api/audio — приём записи, GET /api/status/:id —
готовность задачи, GET /metrics — метрики Prometheus с префиксом
transcriber_, GET /health — проверка живости.
Контракт приёма и опроса нормативен и живёт в openspec/specs/intake/spec.md: поля запроса и ответа, коды и условия. Менять его — необратимое действие (CLAUDE.md, «Работа»), и второго описания у него быть не должно.
Состояния задач
Перечень состояний, переходы между ними и число воркеров — docs/database.md, разделы «Таблицы» и «Представление данных»; как сложен конвейер целиком — docs/architecture.md.
Структура проекта
transcriber/
├── main.go # Точка входа: конфиг, миграции, сборка зависимостей, запуск
├── internal/
│ ├── entity/ # Модели: задача, файл, результат распознавания
│ ├── contract/ # Интерфейсы адаптеров и репозиториев, типы ошибок
│ ├── config/ # Разбор config.toml
│ ├── metrics/ # Метрики Prometheus
│ ├── service/ # Конвейер расшифровки
│ ├── controller/
│ │ ├── http/ # HTTP-обработчики
│ │ ├── tg/ # Telegram-бот
│ │ └── worker/ # Фоновые воркеры
│ └── adapter/
│ ├── converter/ffmpeg/ # Конвертация аудио
│ ├── metaviewer/ffmpeg/ # Длительность аудио
│ ├── recognizer/yandex/ # SpeechKit + Object Storage
│ ├── telegram/ # Отправка сообщений
│ └── repo/pocketbase/ # Репозитории, схема коллекций, правила панели
└── data/ # Каталог данных: база и файлы записей вместе
├── data.db # База хранилища (создаётся автоматически)
└── storage/ # Файлы записей в раскладке хранилища
Хранилище
Две коллекции, files и transcribe_jobs. Поля, ключи, правило времени и
идентификаторов, а также механика захвата задачи воркером —
docs/database.md. Панель владельца — по адресу /_/ того же
порта; пароль от неё задаёт сам владелец по приглашению, которое сервис печатает
в журнал при первом запуске.
Разработка
Схему двигают шаги миграций PocketBase на Go —
internal/adapter/repo/pocketbase. Непринятые шаги накатываются при подъёме
хранилища, прежде чем стартуют воркеры и сервер. Применённый шаг не
переписывается: изменение — только новым файлом шага.
Проверки перед коммитом — одной командой:
task gate
Что она гоняет, чем краснеет и какой отказ считается объявленным долгом — CLAUDE.md, раздел «Гейт».