avandClaude Opus 4.8
4cc4de4269
Итог параллельной волны фиксов (worktree-изоляция, cherry-pick в master): - ingest-dedup-integrity (F1, F6) → спека ingest - retry-stall-basis (MAJOR-1, MAJOR-2) → спека state-reconciliation - linking-transition-robustness (MAJOR-4, MINOR-7) → спеки file-layout и state-reconciliation Дельты влиты в openspec/specs, changes перенесены в openspec/changes/archive/2026-07-08-*. Беклог не трогаю (по решению). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
155 lines
12 KiB
Markdown
155 lines
12 KiB
Markdown
## MODIFIED Requirements
|
||
|
||
### Requirement: Восстановление зависшей загрузки при оживлении источника
|
||
|
||
Система SHALL возвращать в активный поток задачу, упавшую из-за нашей
|
||
нетерпеливости (`failed`/`magnet_timeout` или `stuck`/`stalled`), если её
|
||
источник в qBittorrent жив и продвинулся: переход выводится из текущего
|
||
состояния торрента так же, как при штатной сверке загрузки
|
||
(`uploading`/`stalledUP`/… → `completed`; `downloading`/`metaDL`/… →
|
||
`downloading`). Восстановление SHALL опираться на фактическое состояние
|
||
торрента в qBittorrent, а не на время с момента создания записи.
|
||
|
||
После возврата в любое нетерминальное состояние (`downloading` или
|
||
`completed`) повторный приём того же infohash SHALL снова дедуплицироваться
|
||
на эту задачу: активность задачи выводится только из её `state`, отдельный
|
||
восстанавливаемый ключ идемпотентности отсутствует. Если за время простоя в
|
||
`failed`/`stuck` тем же infohash (любым из хешей задачи) уже завладела
|
||
другая активная задача (новый приём, пока эта лежала упавшей), система
|
||
SHALL NOT воскрешать упавшую задачу и SHALL оставить её в `failed`/`stuck`,
|
||
сохраняя инвариант «не более одной активной задачи на infohash».
|
||
|
||
`magnet_timeout`/`stalled` SHALL быть редким страховочным исходом, а не
|
||
рабочим механизмом. Две страховочные меры при этом РАЗНЫЕ: `magnet_timeout`
|
||
SHALL мериться по **возрасту** торрента (время от добавления в qBittorrent,
|
||
`added_on`, с фолбэком на `created_at` задачи), а `stuck_after` — по
|
||
**длительности простоя** (время от `last_activity` qBittorrent — момента
|
||
последнего движения данных), а НЕ по возрасту. Пока торрент в
|
||
`metaDL`/`forcedMetaDL` или иным образом прогрессирует в пределах
|
||
страховочного таймаута, задача в `failed`/`stuck` из-за него оказаться
|
||
SHALL NOT; в частности, торрент со свежим `last_activity` в `stuck` система
|
||
пометить SHALL NOT, даже если его общий возраст превышает `stuck_after` (см.
|
||
требование о терпеливости к долгим метаданным и меры таймаутов в
|
||
`docs/specs/workflow.md`).
|
||
|
||
#### Scenario: Метаданные пришли после magnet_timeout
|
||
|
||
- **GIVEN** задача в `failed` с `error_code` `magnet_timeout`, а её торрент
|
||
в qBittorrent уже получил метаданные и качается (`downloading`)
|
||
- **WHEN** срабатывает фоновая сверка
|
||
- **THEN** задача возвращается в `downloading`
|
||
- **AND** повторный приём того же infohash снова дедуплицируется на неё
|
||
|
||
#### Scenario: Торрент уже завершился, пока задача была в failed
|
||
|
||
- **GIVEN** задача в `failed` с `error_code` `magnet_timeout`, а её торрент
|
||
в qBittorrent уже готов к раскладке (`uploading`/`stalledUP`)
|
||
- **WHEN** срабатывает фоновая сверка
|
||
- **THEN** задача переходит в `completed` и продолжает обычный поток
|
||
(распознавание/раскладка)
|
||
|
||
#### Scenario: Источник так и не ожил — состояние не меняется
|
||
|
||
- **GIVEN** задача в `failed` с `error_code` `magnet_timeout`, а её торрент
|
||
всё ещё висит в `metaDL` без метаданных (или отсутствует в qBittorrent)
|
||
- **WHEN** срабатывает фоновая сверка
|
||
- **THEN** задача остаётся в `failed`
|
||
|
||
#### Scenario: infohash уже занят другой активной задачей
|
||
|
||
- **GIVEN** задача #1 в `failed`/`magnet_timeout`, а тем же infohash уже
|
||
владеет другая активная задача #2 (приём повторили, пока #1 лежала упавшей)
|
||
- **WHEN** источник ожил (торрент получил метаданные или готов) и сверка
|
||
пытается воскресить #1
|
||
- **THEN** #1 остаётся в `failed` (восстановление не выполняется)
|
||
- **AND** активной по этому infohash остаётся #2
|
||
|
||
#### Scenario: Долго качавшийся торрент на миг зашёл в stalledDL
|
||
|
||
- **GIVEN** торрент качался часами и двигал данные только что (свежий
|
||
`last_activity`), но на текущем тике qBittorrent показывает его `stalledDL`
|
||
- **WHEN** `worker` проверяет таймаут зависания
|
||
- **THEN** задача остаётся в `downloading` (простой меньше `stuck_after`),
|
||
несмотря на большой возраст торрента
|
||
- **AND** ложного `stuck` со «stalled for <возраст>» и уведомления о падении
|
||
не возникает
|
||
|
||
### Requirement: Ручной повтор зависшей/упавшей загрузки из транспортов
|
||
|
||
Система SHALL предоставлять пользователю команду повторной попытки (retry)
|
||
для задач в `failed`/`stuck` из веб-UI и Telegram (не только через REST API).
|
||
Retry SHALL переводить задачу обратно в `downloading`, не вызывая её
|
||
немедленного повторного падения по таймауту: базис отсчёта таймаутов SHALL
|
||
сбрасываться.
|
||
|
||
Сброс базиса система SHALL выполнять сохранением времени retry в поле задачи
|
||
(`retried_at`, RFC 3339 UTC), которое приподнимает пол ОБОИХ страховочных мер
|
||
(`magnet_timeout` по возрасту и `stuck_after` по простою): отсчёт ведётся от
|
||
`max(базис, retried_at)`. `retried_at` SHALL храниться в задаче (не в памяти
|
||
процесса), чтобы сброс базиса пережил интервал поллинга и рестарт процесса.
|
||
Благодаря этому даже живой, но давно добавленный либо давно простаивающий
|
||
торрент после retry SHALL получать свежее окно и на ближайшем тике сверки
|
||
падать снова SHALL NOT.
|
||
|
||
Если источник задачи уже жив и ЗДОРОВ в qBittorrent, retry SHALL перецепляться
|
||
к существующему торренту, а не добавлять источник повторно вслепую. Если же
|
||
живой торрент в состоянии ошибки qBittorrent (`error`/`missingFiles`), retry
|
||
перецепляться к нему SHALL NOT (перецепка к сломанному торренту тут же вернула
|
||
бы задачу в `failed` по сверке) и SHALL повторно отдать источник, как при
|
||
отсутствии раздачи. Повторный `Add` выполняется, только когда раздачи в
|
||
qBittorrent нет ЛИБО она сломана.
|
||
|
||
Повторный `Add` при retry система SHALL выполнять **по типу источника**
|
||
(`source_type`), как и добавление пойманной загрузки (см. `download-tracking`
|
||
«Добавление пойманной загрузки в qBittorrent»): magnet/url — ссылкой; torrent —
|
||
сохранёнными байтами `.torrent` файлом. Для torrent-источника retry БЕЗ живой
|
||
раздачи система SHALL добавлять раздачу байтами и SHALL NOT активировать задачу
|
||
в `downloading`, не добавив её (иначе задача повиснет как «нет в qBittorrent»).
|
||
|
||
#### Scenario: Retry упавшей magnet-загрузки из веб-UI
|
||
|
||
- **GIVEN** задача в `failed`, её торрент жив и здоров в qBittorrent
|
||
- **WHEN** пользователь нажимает retry в веб-UI
|
||
- **THEN** задача возвращается в `downloading` без повторного `Add`
|
||
- **AND** не падает снова на ближайшем тике сверки по таймауту
|
||
|
||
#### Scenario: Retry живого, но давно простаивающего торрента не падает снова
|
||
|
||
- **GIVEN** задача в `stuck`/`stalled`, её торрент жив в qBittorrent, но
|
||
добавлен давно и данные не двигались дольше `stuck_after`
|
||
- **WHEN** пользователь нажимает retry
|
||
- **THEN** задача возвращается в `downloading` без повторного `Add`
|
||
- **AND** на ближайшем тике сверки НЕ падает снова в `stuck` (базис сброшен
|
||
через `retried_at`)
|
||
|
||
#### Scenario: Retry доступен в Telegram
|
||
|
||
- **WHEN** для задачи в `failed`/`stuck` пользователь вызывает retry в
|
||
Telegram-боте
|
||
- **THEN** задача возвращается в `downloading`
|
||
|
||
#### Scenario: Retry без живого источника добавляет источник заново
|
||
|
||
- **GIVEN** задача в `failed`, раздачи в qBittorrent нет
|
||
- **WHEN** пользователь инициирует retry
|
||
- **THEN** источник добавляется в qBittorrent заново — magnet/url ссылкой,
|
||
torrent сохранёнными байтами файлом
|
||
- **AND** задача переходит в `downloading`
|
||
|
||
#### Scenario: Retry сломанного живого торрента повторно отдаёт источник
|
||
|
||
- **GIVEN** задача в `failed`, её торрент присутствует в qBittorrent, но в
|
||
состоянии ошибки (`error`/`missingFiles`)
|
||
- **WHEN** пользователь инициирует retry
|
||
- **THEN** источник отдаётся заново (перецепка к сломанному торренту не
|
||
выполняется)
|
||
- **AND** задача переходит в `downloading`
|
||
|
||
#### Scenario: Retry torrent-загрузки без живого источника
|
||
|
||
- **GIVEN** задача с `source_type = torrent` в `failed`, раздачи в qBittorrent
|
||
нет, байты `.torrent` сохранены
|
||
- **WHEN** пользователь инициирует retry
|
||
- **THEN** сохранённые байты добавляются в qBittorrent файлом
|
||
- **AND** задача переходит в `downloading` (не остаётся без раздачи)
|