# Паспорт проекта

Зачем это и для кого. [architecture.md](architecture.md) отвечает «как
устроено», [tasks/PLAN.md](tasks/PLAN.md) — «в каком порядке», паспорт —
«зачем и для кого».

## Цель

Сократить путь «нашёл раздачу → смотрю на телевизоре» до одного действия:
кинуть торрент с парой слов контекста и получить фильм или сериал в библиотеке
Jellyfin, без ручного переименования и без каталога индексаторов.

**Потребители** — список закрытый: он определяет, что считать нужным, а что
интересным.

| Кто | Что ему нужно от нас |
| --- | --- |
| Владелец медиасервера (единственный оператор) | одна точка входа для magnet/`.torrent` + контекста; когда система не уверена — чтобы позвали, а не замяли молча; чтобы ошибку можно было откатить |
| Домашние зрители (через Jellyfin, о jellybit не знают) | правильные названия, годы, сезоны и серии — иначе Jellyfin подтянет чужие метаданные |
| Jellyfin | файлы, разложенные по его конвенциям имён, и сигнал пересканировать библиотеку, когда они изменились |

Цель достигнута, когда:

- русский контент и аниме раскладываются так же буднично, как англоязычные —
  это ровно то, на чём разваливается arr-стек;
- типовое добавление не требует ни одного ручного действия после отправки
  торрента, а нетиповое требует ровно одного — подтверждения в ревью;
- ошибочная раскладка откатывается одной кнопкой, не задев раздачу.

## Что целью не является

Граница домена. По ней архитектурный проход судит, не перенесено ли понятие
через границу.

- **Не индексатор и не поисковик по трекерам** (роль prowlarr). Раздачу находит
  человек и приносит сам — вместе с контекстом, который он и так видит глазами.
- **Не менеджер качества релизов** (правила radarr/sonarr). Версии, репаки и
  апгрейд 1080p → 2160p не отслеживаем; коллизия уходит в ревью, а не в
  политику качества.
- **Не подписка на выходящие серии.** Никакого monitoring: система не ищет
  ничего сама и не добавляет загрузок по своей инициативе.
- **Не торрент-клиент.** Качает qBittorrent, мы им управляем и не подменяем его
  функциональность.
- **Не медиасервер.** Обложки, метаданные, учёт просмотренного и сам просмотр —
  забота Jellyfin. Мы отвечаем только за то, чтобы файл лежал там, где Jellyfin
  его правильно опознает.
- **Не хранилище медиа.** Данные живут в раздаче; мы создаём только хардлинки и
  не владеем ни одним байтом контента.
- **Не мультипользовательский сервис.** Контур один, оператор один; разграничение
  доступа сводится к allowlist Telegram (см. [security.md](security.md)).

## Типовые сценарии

1. **Фильм через Telegram.** Переслать боту сообщение торрент-бота → magnet и
   текст сообщения становятся источником и контекстом → загрузка → распознавание
   → при подтверждённом матче в метабазе авто-раскладка → пинг «готово».
2. **Сезон сериала.** То же, но файлов много; они раскладываются сериями, а
   второй сезон ложится в **ту же** папку тайтла, что и первый.
3. **Русский фильм, которого нет в базе.** Уходит в ревью: подсказка текстом и
   перераспознавание, выбор источника совпадения из списка, ручной ввод id или
   URL записи, предпросмотр целевых путей, «Применить».
4. **Ошиблись с привязкой.** Undo снимает наши ссылки (раздача цела) →
   «Привязать заново» → правка в ревью → повторное применение.
5. **Раздачу или файлы удалили руками.** Фоновая сверка констатирует рассинхрон
   (`target_missing`/`orphaned`/`deleted`), не теряя последнюю копию данных, и
   лечится сама, если реальность вернулась.

## Референсы

Где смотреть prior art, когда упёрлись.

- [Jellyfin: Movies](https://jellyfin.org/docs/general/server/media/movies) и
  [Shows](https://jellyfin.org/docs/general/server/media/shows) — целевые
  конвенции имён, источник истины по формату, в который раскладываем.
- **arr-стек** (radarr/sonarr/prowlarr) — прежде всего как каталог того, чего мы
  намеренно **не** берём; полезен по крайним случаям именования.
- **umbar** (`/home/av/projects/private/umbar`) — соседний проект того же
  хозяйства: форма деплоя, раскладка `/srv`, стиль «минимум компонентов».