docs: перевод документации на канон av-dev

- Раскладка docs/ приведена к канону 2: заведены passport/architecture/
  database/security/review и research; docs/specs, drafts, backlog, review/
  и BRIEF.md разобраны и удалены, беклог переехал в docs/tasks (34 задачи,
  6 целей, слаги на английский).
- Нарративы specs удалены как дубли openspec-спек после поимённой сверки;
  остаток заведён задачами (редактор маппинга ревью, крайние случаи
  именования), отказ от сущности title промоутнут в ADR.
- Проектные копии агентов и скиллов ревью/пайплайна удалены в пользу
  плагинов av-dev-pm и av-dev-pipeline; в task gate добавлен шаг canon
  вместо er-schema.
This commit is contained in:
av
2026-08-04 09:27:26 +03:00
parent 08bef2cac0
commit 42d5b73a04
128 changed files with 1606 additions and 4889 deletions
+78
View File
@@ -0,0 +1,78 @@
# Паспорт проекта
Зачем это и для кого. [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`, стиль «минимум компонентов».