Добавил документацию и описание репозитория

2026-06-13 17:10:53 +03:00
parent 82a81c16af
commit 5b53f4e8e8
12 changed files with 647 additions and 0 deletions
@@ -0,0 +1,56 @@
+# CLAUDE.md
+
+Памятка для работы над jellybit. Перед задачей прочитай также
+[README.md](README.md), [BRIEF.md](BRIEF.md) и
+[docs/specs/architecture.md](docs/specs/architecture.md).
+
+## Что это
+
+Связующий сервис qBittorrent ↔ Jellyfin: принимает торрент + контекст,
+качает, распознаёт фильм/сериал (LLM + контекст + опц. метабазы) и
+раскладывает файлы для Jellyfin хардлинками. Деплоится на домашний
+медиа-сервер umbar (`/home/av/projects/private/umbar`) — туда копируется
+готовый бинарь.
+
+## Стек и принципы
+
+- **Go**, один статический бинарь (`CGO_ENABLED=0`). Почему — см.
+  [ADR-2026-06-13-go-single-binary](docs/adr/ADR-2026-06-13-go-single-binary.md).
+- **SQLite** как хранилище (чистый Go-драйвер `modernc.org/sqlite`).
+- **Конфигурация — TOML**. **Логи — структурированный JSON** (`log/slog`).
+- **Хардлинки, источник не трогаем** — qBittorrent продолжает раздачу,
+  диск не дублируется.
+- **Единое ядро, тонкие транспорты** — вся логика приёма в use-case
+  `Ingest`; HTTP API, веб-UI и Telegram — лишь обёртки над ним.
+- **Минимум компонентов** — в духе umbar, без зоопарка сервисов. Внешние
+  базы метаданных (TMDB/TVDB) опциональны, включаются конфигом.
+
+## Документация: три раздела
+
+- `docs/specs/` — **живые** спецификации целевого состояния. Меняем по
+  мере развития, держим в соответствии с кодом.
+- `docs/adr/` — **неизменяемый** журнал решений, пишется постфактум,
+  хранит *почему*. Правила — [docs/adr/README.md](docs/adr/README.md).
+- `docs/drafts/` — черновики: планы, идеи, ещё не принятые решения. Не
+  источник истины.
+
+## Язык
+
+- Документация, комментарии, сообщения коммитов — **русский**.
+- Код и идентификаторы — английский.
+
+## Команды
+
+Кода ещё нет (фаза каркаса). По мере появления Ф0:
+
+- сборка: `go build ./cmd/jellybit`
+- тесты: `go test ./...`
+- линт: `golangci-lint run`
+
+## Конвенции кода
+
+- Раскладка: `cmd/jellybit` (точка входа) + `internal/<пакет>` по
+  компонентам из [architecture.md](docs/specs/architecture.md).
+- Ошибки оборачиваем с контекстом (`fmt.Errorf("...: %w", err)`).
+- Логирование только через `slog`, без `fmt.Println`.
+- Время — всегда с явным TZ (сервер в `Europe/Moscow`).