transcriber/CLAUDE.md

CLAUDE.md

Памятка для работы над transcriber. Перед задачей прочитай также docs/passport.md, docs/architecture.md и docs/conventions/.

Проект ведём по-русски.

Что это

Сервис расшифровки аудио в текст. Принимает запись одним входом — HTTP API, — конвертирует её ffmpeg в ogg, отдаёт на отложенное распознавание Yandex SpeechKit и отдаёт текст тому, кто запись загрузил, по опросу готовности. Состояние записей, метаданные и сами файлы лежат во встроенной PocketBase, и она же даёт владельцу панель администратора. Вход Telegram убран 2026-08-14 — временно, до задачи, которая свяжет чат с учётной записью.

Чего не делает: сам речь не распознаёт и своих моделей не держит, текст руками не правит и в форматы документов не экспортирует, учётных записей не заводит, с живым потоком не работает и складом произвольных файлов не служит. Записи и расшифровки хранит бессрочно: решением от 2026-08-11 сервис — архив. Перечень выше — выжимка, границу домена целиком держит docs/passport.md.

Стек

Go 1.26 (сборке CGO не нужен; детектору гонок в гейте — нужен), встроенная PocketBase — хранилище, файлы записей и панель администратора, — aws-sdk-go-v2 для Object Storage, gRPC-клиент Yandex SpeechKit v3, Prometheus, slog. Приложение — Vue 3 с роутером пятой версии и сборкой Vite; собранное вшито в бинарник, проверяют его Biome и юнит-тесты Vue. Сборка — Taskfile, образ — Docker, выкладка — Ansible из pet-project-server.

Проектирование

Чистая архитектура. Зависимости направлены внутрь, к домену: домен не знает ни хранилища, ни транспорта, знание о внешнем мире приходит интерфейсом порта, а реализацию подставляет точка входа. Направления держат тесты-сканеры internal/archrules, а не договорённость.

Модель домена ведётся тактическими шаблонами DDD — сущность и корень агрегата, объект-значение, доменное событие, репозиторий, служба домена, фабрика. Анемичной модели не заводим: поведение записи живёт в домене, а прикладной слой назначает порядок шагов, а не правила.

Слои, их дома, что каждому знать нельзя и чем шаблон занят сегодня — docs/architecture.md, «Слои и модель домена». Здесь это не повторяется: перечень растёт вместе с моделью, и вторая копия разошлась бы с ним молча.

Инварианты

Что нарушать нельзя.

• Секрет не покидает конфиг. Ключ SpeechKit и пара ключей Object Storage не попадают в git, в лог, в ответ пользователю и в колонку error_text. Нарушение необратимо: утёкший ключ отзывают и меняют вручную во всех местах выкладки. critical Изъятия у инварианта нет. Оно было — секрет клиента OIDC жил ещё и в настройках коллекции пользователей хранилища, — и снято 2026-08-22 вместе с самим секретом: вход переехал на доверенный заголовок, обменивать код стало не на что. Чтение файла базы больше не равносильно чтению секрета.
• Содержимое записи остаётся приватным. Текст расшифровки, имя файла пользователя и его сообщение в лог не пишутся — только длина и идентификаторы. Нарушение необратимо: строки уже уехали в журнал контейнера. critical Изъятие: расширение — хвост после последней точки — в журнал попадает собственным полем: по нему прослеживается путь записи. Имени файла в журнале нет вовсе (инвариант ниже). Изъятие узкое и кончается журналом: наружу, меткой метрики, расширение выходит только приведённым к перечню известных форматов. Границу держит спека intake, цена — adr/ADR-2026-08-11-known-format-label.md, остаток — docs/security.md.
• Принятая запись не теряется молча. Отказ на любом шаге либо оставляет запись пригодной к повтору, либо ставит на неё признак остановки с причиной — и тогда причина видна её владельцу карточкой записи, а владельцу сервиса журналом. Молчаливый выход из шага без записи в лог и без смены состояния запрещён. Обязанность сменила направление 2026-08-14 вместе с убранным входом Telegram: прежде об отказе сообщали, теперь отказ доступен спросившему, и отправитель, который не спрашивает, о нём не узнаёт. Адрес, которым он спрашивает, сменился 2026-08-15: опрос готовности убран, и обязанность целиком переехала на карточку. major
• NoopJobError — не ошибка. Значение «задач в этом состоянии нет» не логируется, не считается в метрику и не поднимает уровень. Нарушение даёт запись раз в секунду на каждый воркер. major
• Миграция, уехавшая на сервер, не переписывается. Изменение — только новым файлом шага. Необратимо: хранилище считает применённое по имени файла. critical
• Имя файла в хранилище задаёт сервис, а в журнал не идёт. Умолчание PocketBase строит имя из имени, данного отправителем, — оно не применяется. Само имя — последняя часть ссылки /api/files/..., поэтому в журнал пишется расширение, а не имя: строка журнала иначе стала бы бессрочным ключом к чужой записи. critical
• Колонки записи правятся в двух местах пакета хранилища — applyOwnedByPipeline вместе с applyToRecord и recordToAudioRecord, — плюс шаг схемы. Компилятор не видит ни одного: колонка, забытая в одном из них, теряется молча — запись сохранится без поля либо приедет с нулевым. Мест было четыре, пока захват перечислял колонки поимённо; теперь он возвращает идентификатор и признак своего захвата, и перечень перестал расти с моделью. Сверку держат правила internal/archrules. major
• Рубеж объявляется одним дескриптором — internal/entity/stage.go. Из него выводятся выбор шага, отбор захвата, срок протухания захвата и предел простоя; перечислять рубежи порознь в каждом потребителе нельзя. Рубеж, забытый в отборе, не выдаётся ни одному воркеру никогда, а пустой прогон по инварианту ниже не пишется в журнал и не считается в метрику: запись встанет без единого следа. Сверку держат правила internal/archrules. major
• Результат пишет только держатель захвата, и держатель узнаётся значением. Признак захвата уникален для каждого захвата, и запись результата условна по нему, а не по занятости записи. Шаг, чей захват за время работы достался другому — по протуханию срока или после того, как человек снял признак остановки в панели, — завершается без записи результата. Условие по непустоте признака пропустило бы обоих: два воркера писали бы в одну запись по очереди, портя её результат. major
• У записи есть владелец, и колонка пустого значения не принимает. Ничья запись не заводится ничем — ни приёмом, ни конвейером, ни рукой в панели, — и держит это схема хранилища, а не договорённость. Пока обязательность жила в одном приёме, ничью запись заводили в панели, она уходила в конвейер, стоила денег на распознавание и не доставалась потом никому. Правило со стороны спрашивающего при этом остаётся: пустой владелец не совпадает ни с одной записью, потому что схема запрещает заводить ничью, а это правило — спрашивать ничьим именем. major
• Остановленная запись несёт причину, какой бы та ни была. Причин три — приговор шага, исчерпанные отказы, застревание, — и каждая записывается в саму запись и в её журнал событий. Остановленная запись захвату не выдаётся, значит исход «пригодна к повтору» исключён, и другого следа у неё не будет. Обязанность, записанная у одной причины, у остальных читалась бы как снятая. major

Команды

go build ./...            # CGO не нужен
go test ./...             # в гейте идёт с -race, и там нужен компилятор C
go vet ./...
gofmt -l .
golangci-lint run
go run ./cmd/transcriber -c config.toml   # флаг -c или --config, по умолчанию config.toml
go run ./cmd/devtools proxy   # подставной прокси: ставит заголовок входа локально
task front                # приложение: зависимости, Biome, юнит-тесты, сборка
task image                # docker-образ; тег и раскладка — docs/architecture.md
task gate                 # весь набор проверок разом

Node на машину не ставится: шаг сборки приложения зовёт его контейнером, а образ берёт из ступени Dockerfile. Требованием к машине разработчика поэтому становится docker — тот же, которым собирается образ.

Локальный запуск требует ffmpeg и ffprobe в PATH и своего config.toml — скопируй config.example.toml и заполни; известные прорехи образца перечислены в docs/conventions/config.md строками «Расхождение:».

Гейт

• Команда целиком: task gate. База диффа — переменная BASE, по умолчанию origin/master; переопределяется task gate BASE=<rev>.
• Какое правило чем проверяется — конвенция docs/conventions/go-linters.md. Здесь семантика гейта, там перечень правил, подавлений и место настройки каждого; перечень здесь не повторяется.
• Где логи шагов: вывод команды, отдельного файла нет.
• Что означает каждый исход: ненулевой код любого шага роняет гейт. У docs.py check, tasks.py check, openspec.py check и scripts/check-go-version.sh словарь кодов общий: 0 сошлось, 1 дрейф, 2 ошибка употребления, 3 окружение (не корень проекта, каталог или файл не найден), 4 внутренний сбой. Последний своего словаря не заводит намеренно: четвёртый шаг с собственной семантикой сделал бы это утверждение неверным. Тому же словарю следуют обёртки шагов в Taskfile.yml — все, включая tests, migrations, shell, dockerfile и vulns: недостающий инструмент — отказ окружения, код 3. У tests это отсутствие CGO или компилятора C, без которых не работает детектор гонок — тесты он в этом случае всё равно гоняет, без -race, и краснеет уже после них. У migrations код 3 — неразрешимая база диффа, отсутствующий каталог шагов и каталог без единого шага; код 1 — переписанный шаг схемы. Сами чужие инструменты (shellcheck, hadolint, govulncheck, golangci-lint) держат свои коды, и гейту от них нужно только «ненулевой». Недостающий скрипт — отказ окружения, код 3. Наружу все эти коды приходят одним: сам task на любой отказ шага выходит с 201, а код шага печатает строкой («exit status 3»), поэтому словарь читается по коду скрипта.
• Что красит безусловно и почему: красная сборка приложения, находка Biome, красный юнит-тест приложения, отказ сборки, тестов, go vet, гонка, найденная детектором (go test -race), переписанный применённый шаг схемы, неотформатированный файл, находка golangci-lint, расхождение объявленных версий Go, дрейф раскладки документов, дрейф каталога задач, форма openspec/config.yaml, достижимая из кода уязвимость в зависимостях (govulncheck), находка shellcheck в скриптах оболочки и hadolint в Dockerfile. Машина проверяет всё перечисленное, и это не обсуждается. Шаг, чей скрипт не найден, краснеет с именем недостающего плагина, а не пропускается молча.
• Что ловит pre-commit, а что только гейт. lefthook.yml гоняет на затронутых файлах дешёвую часть: gofmt (правит на месте и добавляет в коммит), golangci-lint по пакетам тронутых файлов, shellcheck, hadolint, gitleaks по индексу. Только гейту остаются сборка, go vet, тесты целиком, сверка версий Go, сверки документов и govulncheck: они смотрят всё дерево либо требуют сети, а pre-commit обязан быть быстрым.
• Сетезависимые шаги названы здесь поимённо, и перечень этот закрыт. Один из них — front: он ставит зависимости приложения из реестра пакетов, а docker до того тянет образ сборочного окружения. Отказ сети и реестра там — отказ окружения, код 3, отдельно от красной сборки, у которой код 1; полный кэш установщика снимает поход в сеть вовсе. Без короткого обращения-пробы шаг висел бы вместо отказа: установщик уходит в повторы с нарастающей паузой на каждом пакете, а гейт, который висит, хуже красного.
• Шагу vulns нужна сеть тоже: база уязвимостей живёт на vuln.go.dev. Без сети шаг краснеет, а не пропускается молча; сам инструмент ставится go install golang.org/x/vuln/cmd/govulncheck@latest. Судит он достижимость из кода: находка в модуле, чей уязвимый символ мы не вызываем, шаг не роняет. Такая сегодня одна — GO-2026-5932 в golang.org/x/crypto/openpgp, исправления у неё нет вовсе.
• Чего в гейте намеренно нет и кто тогда обязан это гонять:
  • сборка образа — дорога, и отказ от неё сознательный. Дешёвая замена стоит шагом сверки версий: он сравнивает строки и ловит расхождение, из-за которого образ перестаёт собираться, но собираемости не проверяет. Собрать образ по-прежнему может только человек — task image, и на подъёме версии это обязательно;
  • собираемость Dockerfile: hadolint судит форму, а не сборку, и часть его правил подавлена поимённо — DL3007 до задачи pin-runtime-image-base и DL3018 по существу (alpine не держит старые версии пакетов, закрепление ломает сборку через недели). Причины стоят строками в Taskfile.yml;
  • gitleaks — висит на pre-commit в lefthook.yml и смотрит только индекс коммита. Полную историю никто не проверяет;
  • согласованность документов между собой и с кодом — её судят агенты, зовёт их скилл av-dev:doc-healthcheck, и звать его надо руками;
  • покрытие изменённых строк не считается ничем.

Гейт на master сегодня зелёный целиком, и объявленных долгов у него нет. Красный шаг означает поломку — свою или чужую, но поломку, а не наследство. Списывать отказ на долг больше нельзя: списывать не на что.

Три прежних долга закрыты и здесь названы, чтобы отказ на их месте читался как новый:

• hadolint давал DL3066 на строке USER transcriber — «Non-numeric user-id may not be resolvable by host system». Отказ пришёл с обновлением hadolint, а не с правкой репозитория, и жил на master незамеченным. Закрыто решением владельца 2026-08-22: пользователь называется числом — USER 1000:1000. Владельца файлов в смонтированном каталоге это не двигает, потому что те же числа уже стояли при заведении пользователя (-u 1000, -g 1000);

• golangci-lint run давал 4 замечания — два непроверенных Close и два сравнения ошибок приведением типа. Закрыто задачей errors-as-instead-of-typecast 2026-08-11; тогда же у errcheck включена настройка check-blank, поэтому _ = x.Close() больше не снимает замечание: отказ, который решено не проверять, объявляют в exclude-functions поимённо;

• go test ./... чинила задача http-handler-tests-never-green.

Запреты

• Боевой каталог данных не трогать. data/ на сервере целиком: под ним и база (data/data.db), и записи живых людей (data/storage/<коллекция>/<запись>/). На стройке под ним пусто и сервис остановлен — запрет от этого не снимается: каталог принадлежит серверу, и выкладка с чистого листа наполнит его снова. Локальный каталог данных — свой, его ронять и пересоздавать можно свободно.
• Локальный запуск не ходит наружу. Секции [auth] и [yandex] проверяются на старте, но наружу при этом не обращаются. У [auth] остался один ключ — перечень доверенных адресов, — и он проверяется на читаемость, а не на достижимость. Расшифровка при выдуманных ключах не работает: её подменяют internal/adapter/recognizer/memory.go. Подробности строками в config.example.toml. На машине без прокси представиться нечем: сервис узнаёт пришедшего по заголовку, который на сервере ставит Caddy, а браузер заголовков не ставит. На место контура встаёт подставной прокси — go run ./cmd/devtools proxy: он слушает свой порт, ставит заголовок и переправляет запрос сервису, а проверок не делает никаких. Приложение при этом открывают по адресу прокси, а не по адресу сервиса. Ключей боевого провайдера на машине разработчика не нужно вовсе — их больше нет и в конфиге.
• Yandex Cloud за деньги. Распознавание и хранение в Object Storage оплачиваются по факту. Прогон на реальных ключах ради проверки кода запрещён — подставляй internal/adapter/recognizer/memory.go.
• Выкладку не запускать. inv pl -- transcriber из pet-project-server запускает человек.
• Проверок над проверками не заводить. Уровень проверки один: линтеры и тесты судят код сервиса, а судить их самих незачем. Под запрет попадают тесты на шаги гейта и на свои скрипты проверок, стражи предмета у правил, механизация покрытия изменённого кода, мутационная сверка оракулов и требование мутировать тест, чтобы убедиться в его способности упасть. Решение владельца 2026-08-13; им закрыты четыре задачи — причины и даты в tasks/REJECTED.md, — и тем же решением снесены двадцать сценариев шага сверки версий Go, единственный такой файл в проекте. Исключений у запрета нет.
• testdata в проекте нет. Тесты, которым нужен файл, создают его во временном каталоге и убирают за собой.
• Временное — t.TempDir() в тестах, /tmp вне их. В data/ временное не писать: этот каталог смонтирован на сервере.

Работа

• Стадия проекта — стройка ([tasks] stage = "build", объявлена в tasks/BACKLOG.md). Приложение строим заново: на сервере данных нет, сервис остановлен, выкладка пойдёт с чистого листа. Совместимость с тем, что уже лежит на сервере, поэтому не требуется — переносить нечего: ни базы, ни файлов записей, ни истории. Что это не отменяет: гейт краснеет на переписанном шаге схемы, как и краснел, и снятие этого запрета — отдельное решение человека; боевой каталог данных остаётся под запретом; выкладку по-прежнему запускает человек.
• Основная ветка: master. Коммиты идут в неё напрямую, веток и PR нет.
• Сообщение коммита без трейлера Co-Authored-By.
• Необратимое (спрашивается у человека всегда): применённая миграция, формат файла на диске и раскладка каталога данных, публичный контракт HTTP API, имя ключа конфига, любое действие с боевыми данными и с Yandex Cloud, ротация секрета.
• Что считается сломанным — новый красный шаг гейта, которого не было до твоей правки. Такое чинится прежде любой другой работы. Исключений из этого правила нет: раздел «Гейт» называет оба прежних долга закрытыми, и списывать красный шаг больше не на что.
• Ориентир по размеру порции: не замерялся.
• Что такое «сделана»: task gate зелёный и критерии приёмки проверены поимённо.

Язык

• Документация, комментарии, сообщения коммитов — русский.

• Код и идентификаторы — английский.

• Текст, который видит пользователь сервиса, — русский.

• Точного числа накопленного в документах нет. «Три capability», «пять прогонов ревью», «две типизированные ошибки» расходятся с действительностью на первой же задаче, которая прибавит четвёртую, — и расходятся молча: машина такое не считает, а читатель верит написанному. Ссылаться можно только на конкретную запись (по имени, со ссылкой) либо на весь корпус разом («заведённые capability», «записи журнала ниже»). Само перечисление при этом законно: перечень обновляют вместе с предметом, а число живёт отдельно от него и потому протухает в одиночку.

  Изъятие: число, которое не растёт с работой, остаётся числом — количество уровней журнала в библиотеке, ступеней сборки образа, состояний списка на экране. Так же законно историческое число в записи о прошлом: «решением от 2026-08-13 закрыты четыре задачи» описывает событие, а не сегодняшний счёт. Настройки с числовым значением — свой случай, их дом docs/database.md.