# Конвенции кода: бэклог

Кандидаты в [docs/conventions/](../conventions/README.md), ещё не принятые.
Пишем по мере реального трения, а не вперёд; принятое переезжает в
`docs/conventions/`. Уже приняты: `logging.md`, `config.md`, `errors.md`.

## Tier 2 — кандидаты в отдельный доку

Завести, когда паттерн подтвердит второй-третий проект (или поймаем трение
в jellybit).

### Раскладка пакетов и направление зависимостей

`cmd/<bin>` (точка входа) + `internal/<компонент>` по доменам. Домен не
импортирует транспорт; зависимости направлены внутрь, к домену. Без свалок
`util`/`common`/`helpers`. Стыкуется с «тонкие транспорты, единое ядро» из
архитектуры.

### context.Context

Первый параметр функции; не хранить в структурах; в `Value` только
request-scoped данные, не зависимости. Перенос логгера/корреляции через ctx
(уже реализовано — `internal/logctx`, см. `logging.md`). Дедлайны/отмена
протягиваются сквозь стадии.

### Внешние клиенты (HTTP к зависимостям)

Таймаут на **каждый** исходящий вызов (не полагаться на дефолт); не
`http.DefaultClient`; ретраи с backoff и потолком попыток; HTTP-прокси из
конфига (`proxy`-поля уже есть). Прямое продолжение `ext.*`-логирования
(`logging.md`) и трансляции ошибок (`errors.md`). Кандидат — общий
конструктор клиента вместо копипасты в qbt/llm/jellyfin/metadata.

### Тесты

Table-driven; фикстуры в `testdata/`; `t.Parallel()` где безопасно; выбрать
и зафиксировать stdlib `testing` vs `testify`; разделение быстрых и
интеграционных (уже есть `*_integration_test.go` + env-гейты). Что считаем
обязательным к покрытию (валидация конфига, распознавание, раскладка).

## Tier 3 — тонкий бюллетень или мелочь

Не тянет на отдельный доку: строка-инвариант в `CLAUDE.md` или стек-специфика.

### БД и миграции (SQLite + goose)

Миграции forward-only; запросы только параметризованные (без склейки строк);
явные транзакции для многошаговых изменений; context-aware запросы. Сильно
стек-специфично — возможно, в `CLAUDE.md`, не в общий доку.

### Конкурентность

Каждая горутина знает, **как** останавливается (ctx/закрытие канала); без
утечек; `errgroup` для связанных задач; фоновые процессы гасятся при
shutdown. Актуально для воркера/фоновых задач, не для всего проекта.

### CLI

Данные — в `stdout`, логи и диагностика — в `stderr`; осмысленные коды
возврата. Для CLI-подмножества проектов (у jellybit — диагностические
команды `add`/`recognize`/`healthcheck`).

### Время

Явный TZ всегда; хранение и логи — в UTC; бизнес-логика в `Europe/Moscow`.
Уже частично в `CLAUDE.md` и `logging.md` — при желании свести в один
короткий инвариант.