av
ba7b4f37a6
- README разгружен: контракт HTTP API, таблицы БД, состояния задач и белый список отданы нормативным источникам ссылками - в `architecture.md` и `review.md` числа и механика захвата задачи заменены ссылками на `database.md`, а описание конвейера ревью — на прогон от 2026-08-11 - в `CLAUDE.md` и `security.md` поправлены границы домена, оценка объёма записи и адрес очереди задач
139 lines
6.3 KiB
Markdown
139 lines
6.3 KiB
Markdown
# Transcriber Service
|
|
|
|
Сервис расшифровки аудиозаписей. Два входа — Telegram-бот и HTTP API.
|
|
|
|
## Возможности
|
|
|
|
- Приём аудио из Telegram: голосовые сообщения, аудиофайлы и документы с аудио
|
|
- Приём аудиофайлов через HTTP API
|
|
- Конвертация в ogg через ffmpeg
|
|
- Распознавание речи через Yandex SpeechKit
|
|
- Отслеживание статуса задач расшифровки
|
|
- SQLite для хранения метаданных, метрики Prometheus
|
|
|
|
## Технологии
|
|
|
|
- **Веб-фреймворк**: gin-gonic/gin
|
|
- **Telegram**: go-telegram-bot-api
|
|
- **Распознавание**: Yandex SpeechKit + Yandex Object Storage (S3)
|
|
- **Конвертация**: ffmpeg
|
|
- **SQL Builder**: doug-martin/goqu
|
|
- **Миграции БД**: pressly/goose
|
|
- **База данных**: SQLite
|
|
- **Метрики**: 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/sqlite/ # Репозитории
|
|
├── migrations/ # Миграции goose, вшиты в бинарник через go:embed
|
|
└── data/
|
|
├── files/ # Директория для сохранения файлов
|
|
└── transcriber.db # SQLite база данных (создается автоматически)
|
|
```
|
|
|
|
## База данных
|
|
|
|
Две таблицы, `files` и `transcribe_jobs`. Колонки, ключи, правило времени и
|
|
идентификаторов, а также механика захвата задачи воркером —
|
|
[docs/database.md](docs/database.md).
|
|
|
|
## Разработка
|
|
|
|
Миграции накатываются автоматически при старте сервиса — они вшиты в бинарник
|
|
через `//go:embed`. Достаточно положить новый файл в `migrations/`.
|
|
|
|
Создать файл миграции и накатить или откатить её вручную:
|
|
|
|
```bash
|
|
# Создание новой миграции
|
|
goose -dir migrations create migration_name sql
|
|
|
|
# Применение миграций
|
|
goose -dir migrations sqlite3 data/transcriber.db up
|
|
|
|
# Откат миграций
|
|
goose -dir migrations sqlite3 data/transcriber.db down
|
|
```
|
|
|
|
Проверки перед коммитом — одной командой:
|
|
|
|
```bash
|
|
task gate
|
|
```
|
|
|
|
Что она гоняет, чем краснеет и какой отказ считается объявленным долгом —
|
|
[CLAUDE.md](CLAUDE.md), раздел «Гейт».
|