av
ce0ae76977
- имя приведено к конвенции, которая сама называла его расхождением; ссылки поправлены в README, CLAUDE.md, конвенциях, docs/review.md и двух записях задач - в шапке docs/conventions/config.md заодно поправлен второй пункт перечня: проверки на старте у `[auth]` и `[telegram]` уже есть - архив openspec/changes/archive/ не тронут: это запись о прошлом
133 lines
7.0 KiB
Markdown
133 lines
7.0 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.example.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 /auth/login`, `GET /auth/callback` и
|
||
`POST /auth/logout` — вход через провайдера
|
||
([access](openspec/specs/access/spec.md)), `GET /metrics` — метрики Prometheus с
|
||
префиксом `transcriber_`, `GET /health` — проверка живости. Сверх них тем же
|
||
портом отдаётся собственная поверхность встроенного хранилища и панель `/_/` —
|
||
[docs/security.md](docs/security.md), «Из чего строятся пути и ключи».
|
||
|
||
Контракт приёма и опроса нормативен и живёт в
|
||
[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/migrations`, файл на шаг. Непринятые шаги
|
||
накатываются при подъёме хранилища, прежде чем стартуют воркеры и сервер.
|
||
Применённый шаг не переписывается: изменение — только новым файлом шага.
|
||
|
||
Проверки перед коммитом — одной командой:
|
||
|
||
```bash
|
||
task gate
|
||
```
|
||
|
||
Что она гоняет, чем краснеет и какой отказ считается объявленным долгом —
|
||
[CLAUDE.md](CLAUDE.md), раздел «Гейт».
|