122 lines
7.7 KiB
Markdown
122 lines
7.7 KiB
Markdown
# Жизненный цикл загрузки и машина состояний
|
||
|
||
Как загрузка проходит путь от приёма источника до разложенных файлов:
|
||
состояния, переходы и то, что их вызывает. Кто владеет переходами и общее
|
||
устройство — в [architecture.md](architecture.md); детали распознавания —
|
||
в [recognition.md](recognition.md); действия человека в ревью — в
|
||
[review-ux.md](review-ux.md).
|
||
|
||
## Граф состояний
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> downloading: ingest (источник отдан в qBittorrent)
|
||
|
||
downloading --> completed: файлы на месте
|
||
downloading --> stuck: stalledDL дольше stuck_after
|
||
downloading --> failed: metaDL дольше magnet_timeout / error
|
||
|
||
completed --> recognizing
|
||
|
||
recognizing --> linking: авто (матч в базе + валидация)
|
||
recognizing --> review: нужно подтверждение / ответ LLM не разобран
|
||
|
||
review --> linking: Применить
|
||
review --> recognizing: Уточнить / Распознать заново
|
||
review --> deferred: Позже
|
||
review --> cancelled: Отклонить
|
||
deferred --> review: любое действие (та же поверхность)
|
||
|
||
linking --> done
|
||
linking --> review: коллизия цели
|
||
linking --> failed: ошибка ФС
|
||
|
||
done --> reverted: Undo
|
||
|
||
reverted --> recognizing: Привязать заново
|
||
cancelled --> recognizing: Привязать заново
|
||
|
||
stuck --> downloading: Retry
|
||
failed --> downloading: Retry
|
||
|
||
done --> [*]
|
||
cancelled --> [*]
|
||
reverted --> [*]
|
||
|
||
note right of cancelled
|
||
«Отклонить» доступно из любого
|
||
нетерминального состояния
|
||
end note
|
||
```
|
||
|
||
Условно-терминальные состояния — `done`, `cancelled`, `failed`,
|
||
`reverted`: задача в них останавливается, но из `failed`/`stuck` есть
|
||
**Retry**, а из `reverted`/`cancelled` — **Привязать заново**. `stuck`
|
||
восстановимо ретраем.
|
||
|
||
## Состояния и переходы
|
||
|
||
- **ingest → downloading** — приняли источник + контекст, отдали в
|
||
qBittorrent (категория `qbittorrent.category`), записали в БД с ключом
|
||
идемпотентности. См. [architecture.md](architecture.md) → «Транспорты».
|
||
- **downloading / completed** — `worker` поллит qBittorrent
|
||
(`worker.poll_interval`, 5 с). Готовность — только когда файлы на месте
|
||
(не `moving`/`checking*`), см. «Завершение в qBittorrent» ниже.
|
||
- **recognizing** — `recognize` строит план и оценку уверенности
|
||
([recognition.md](recognition.md)). Невалидный/непарсящийся ответ LLM →
|
||
review (не failed).
|
||
- **review** — план уходит человеку ([review-ux.md](review-ux.md)); цикл
|
||
`review ⇄ recognizing` — перераспознавание по подсказке. «Уточнить» —
|
||
подсказка + перераспознавание; «Распознать заново» — повторный прогон
|
||
без новой подсказки, по уже накопленному контексту и подсказкам.
|
||
- **deferred** — «Позже» паркует задачу; принимает те же команды, что и
|
||
`review`, и возвращается в поверхность ревью по любому действию.
|
||
- **linking** — `layout` создаёт хардлинки; идемпотентно, батчем. Коллизия
|
||
цели возвращает в review, ошибка ФС → failed. См.
|
||
[architecture.md](architecture.md) → «Раскладка файлов».
|
||
- **done** — при входе неблокирующе дёргаем пересканирование Jellyfin
|
||
(опц., см. [architecture.md](architecture.md) → «Пересканирование
|
||
Jellyfin»); доступен **Undo** → `reverted` (убрать созданные ссылки).
|
||
- **stuck / failed / cancelled** — не качается дольше таймаута; ошибка
|
||
(ретраибельна); «Отклонить».
|
||
- **reverted / cancelled → recognizing** — «Привязать заново»: после
|
||
отката или отклонения можно перезапустить распознавание для той же
|
||
раздачи. Перепривязка всегда идёт через review с ручным подтверждением
|
||
(авто-раскладку не делаем) и требует, чтобы раздача всё ещё была в
|
||
qBittorrent.
|
||
|
||
Все переходы и команды идут через `worker` под per-download блокировкой —
|
||
два транспорта не гонятся за одно состояние. Состояние персистентно в
|
||
SQLite; `worker` периодически сверяет qBittorrent с БД и **усыновляет**
|
||
раздачи с нашей категорией (`qbittorrent.category`) **или** тегом
|
||
(`qbittorrent.tag`), которых ещё нет в БД, заводя для них задачу в
|
||
состоянии `downloading`. Категория ставится на добавляемые нами раздачи
|
||
(push, задаёт savepath); тег позволяет подхватить уже существующую
|
||
раздачу, не трогая её категорию и файлы (pull).
|
||
|
||
## Завершение в qBittorrent
|
||
|
||
`worker` опрашивает qBittorrent и сопоставляет его состояния с нашими:
|
||
|
||
- **готово к раскладке:** `uploading`/`stalledUP`/`pausedUP`/`stoppedUP`/
|
||
`queuedUP`/`forcedUP` (имена `paused*`/`stopped*` различаются между qBit
|
||
v4 и v5 — поддержаны оба).
|
||
- **переходное, ждём:** `moving`/`checkingUP`/`checkingResumeData`/
|
||
`allocating` — остаёмся в `downloading`, пока qBit не закончит перенос/
|
||
проверку (готовность не объявляем, даже если флаги «UP»).
|
||
- **ещё качается:** `downloading`/`stalledDL`/`metaDL`/`forcedMetaDL`/
|
||
`queuedDL`/`checkingDL`/`forcedDL`/`pausedDL`/`stoppedDL`.
|
||
- **застряло/ошибка по таймауту:** `metaDL`/`forcedMetaDL` дольше
|
||
`magnet_timeout` → `failed`; `stalledDL` дольше `stuck_after` → `stuck`
|
||
(восстановимо ретраем). Возраст считаем от создания задачи.
|
||
- **ошибка:** `error`/`missingFiles` → `failed`.
|
||
|
||
Пути файлов берём из API (`save_path` + относительные имена из
|
||
`/torrents/files`, уже включающие корневую папку торрента), не из
|
||
константы (обычно это уже хост-путь). «Incomplete»-каталог в
|
||
qBittorrent **включён** (`/srv/media/incomplete`): пока качается — файлы
|
||
там, по завершении qBit переносит их в `/srv/media/downloads` (состояние
|
||
`moving` — дожидаемся окончания переноса и только потом берём финальный
|
||
путь). Подробнее о путях и песочнице — [architecture.md](architecture.md)
|
||
→ «Пути и контейнеры».
|