From c6daba46d99723dc235bf8a51f2755fb1bad150f Mon Sep 17 00:00:00 2001
From: Anton Vakhrushev <anwinged@ya.ru>
Date: Sun, 28 Jun 2026 21:10:44 +0300
Subject: [PATCH] =?UTF-8?q?=D0=97=D0=B0=D0=BF=D0=B8=D1=81=D0=B0=D0=BB=20?=
 =?UTF-8?q?=D0=B8=D0=BB=D0=B5=D0=B8=20=D0=BA=D0=BE=D0=BD=D0=B2=D0=B5=D0=BD?=
 =?UTF-8?q?=D1=86=D0=B8=D0=B9=20=D0=BD=D0=B0=20=D0=B1=D1=83=D0=B4=D1=83?=
 =?UTF-8?q?=D1=89=D0=B5=D0=B5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/drafts/conventions-backlog.md | 67 ++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 docs/drafts/conventions-backlog.md

diff --git a/docs/drafts/conventions-backlog.md b/docs/drafts/conventions-backlog.md
new file mode 100644
index 0000000..865fc07
--- /dev/null
+++ b/docs/drafts/conventions-backlog.md
@@ -0,0 +1,67 @@
+# Конвенции кода: бэклог
+
+Кандидаты в [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` — при желании свести в один
+короткий инвариант.