69 lines
4.0 KiB
Markdown
69 lines
4.0 KiB
Markdown
# 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) опциональны, включаются конфигом.
|
|
|
|
## Инварианты (безопасность данных)
|
|
|
|
- **Источник неприкосновенен:** только `mkdir` / `link(2)` / `unlink`
|
|
своих ссылок; никогда не трогаем файлы под `paths.downloads`.
|
|
- **Целевой путь санитизируется** и проверяется, что он строго под
|
|
`paths.movies`/`series` (защита от traversal); существующее не
|
|
перезаписываем.
|
|
- **Выход LLM недоверенный** — безопасность на валидации пути, не на
|
|
промпте. Авто-раскладка только при подтверждённом матче в базе.
|
|
- **Запуск:** контейнер под `1000:1000`, `network_mode: host`, mount
|
|
`/srv` + data-том для SQLite/конфига.
|
|
|
|
## Документация: три раздела
|
|
|
|
- `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`).
|