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 и перестал собираться, а восемь шагов гейта и шесть проходов ревью были зелёными
129 lines
6.6 KiB
Markdown
129 lines
6.6 KiB
Markdown
# 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
|
|
|
|
## Установка и запуск
|
|
|
|
1. Клонируйте репозиторий
|
|
2. Установите зависимости:
|
|
```bash
|
|
go mod tidy
|
|
```
|
|
3. Скопируйте образец конфига и заполните его:
|
|
```bash
|
|
cp config.dist.toml config.toml
|
|
```
|
|
4. Запустите приложение:
|
|
```bash
|
|
go run . -c config.toml
|
|
```
|
|
|
|
Сервер запустится на порту из `[server] port`, по умолчанию 8080. Нужен
|
|
установленный `ffmpeg`.
|
|
|
|
### Белый список Telegram
|
|
|
|
Бот отвечает только тем, кто перечислен в конфиге. Кого и по какому признаку он
|
|
пускает — [docs/security.md](docs/security.md), «Что разграничивает доступ»;
|
|
известные прорехи образца конфига, включая недостающий ключ белого списка, —
|
|
[docs/conventions/config.md](docs/conventions/config.md).
|
|
|
|
## Деплой
|
|
|
|
Деплой запускается из `pet-project-server`:
|
|
|
|
```bash
|
|
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](openspec/specs/intake/spec.md): поля запроса и
|
|
ответа, коды и условия. Менять его — необратимое действие
|
|
([CLAUDE.md](CLAUDE.md), «Работа»), и второго описания у него быть не должно.
|
|
|
|
## Состояния задач
|
|
|
|
Перечень состояний, переходы между ними и число воркеров —
|
|
[docs/database.md](docs/database.md), разделы «Таблицы» и «Представление
|
|
данных»; как сложен конвейер целиком — [docs/architecture.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](docs/database.md). Панель владельца — по адресу `/_/` того же
|
|
порта; пароль от неё задаёт сам владелец по приглашению, которое сервис печатает
|
|
в журнал при первом запуске.
|
|
|
|
## Разработка
|
|
|
|
Схему двигают шаги миграций PocketBase на Go —
|
|
`internal/adapter/repo/pocketbase`. Непринятые шаги накатываются при подъёме
|
|
хранилища, прежде чем стартуют воркеры и сервер. Применённый шаг не
|
|
переписывается: изменение — только новым файлом шага.
|
|
|
|
Проверки перед коммитом — одной командой:
|
|
|
|
```bash
|
|
task gate
|
|
```
|
|
|
|
Что она гоняет, чем краснеет и какой отказ считается объявленным долгом —
|
|
[CLAUDE.md](CLAUDE.md), раздел «Гейт».
|