# 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/migrations`, файл на шаг. Непринятые шаги
накатываются при подъёме хранилища, прежде чем стартуют воркеры и сервер.
Применённый шаг не переписывается: изменение — только новым файлом шага.

Проверки перед коммитом — одной командой:

```bash
task gate
```

Что она гоняет, чем краснеет и какой отказ считается объявленным долгом —
[CLAUDE.md](CLAUDE.md), раздел «Гейт».