Жизненный цикл: claim-токен распознавания, индексация хешей, retry сломанного торрента

Три мелких фикса из docs/backlog/review-lifecycle-minor.md (ревью Fable 2026-07-08). MINOR-9 (I/O под глобальным w.mu) осознанно waive для one-user home-сервера — не трогаем. MINOR-8: claim-токен распознавания. recognizeOne фиксирует updated_at на момент claim (перечитывая запись после перехода в recognizing), а finishRecognition коммитит результат, только если токен совпал. Иначе за время LLM-вызова задачу увели из recognizing и вернули обратно (cancel → relink revive) — это уже другой эпизод, устаревший результат отбрасываем, задача остаётся в recognizing для перезапуска поллингом. NIT-11: lookup-мапы (byHash/live/torrentByInfohash) больше не индексируют усечённый 40-hex t.Hash v2-only торрентов. Новый хелпер torrentIndexHashes зеркалит выбор torrentHashes: t.Hash берём только при отсутствии обоих infohash_v1/v2. Убирает теоретический ложный матч по коллизии длины. NIT-12: retry живого, но сломанного торрента (error/missingFiles) теперь отклоняется с подсказкой починить раздачу (recheck) в qBittorrent, вместо бессмысленной переотдачи источника (сверка тут же вернула бы задачу в failed). Повторный Add — только когда раздачи в qBittorrent нет. Меняет спеку state-reconciliation → дельта openspec/changes/2026-07-17-retry-reject-broken-torrent (не архивировал). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-17 20:35:14 +03:00
parent b8017d65eb
commit bcc7b2d76b
10 changed files with 330 additions and 27 deletions
@@ -0,0 +1,42 @@
+## Why
+
+Retry задачи в `failed`/`stuck`, чей торрент ЖИВ в qBittorrent, но в состоянии
+ошибки (`error`/`missingFiles`), сейчас повторно отдаёт источник. На живом
+сломанном торренте это бесполезно: qBittorrent отвергает дубль, задача уходит в
+`downloading`, а на ближайшем тике сверки `classErrored` тут же возвращает её в
+`failed` (+ дебаунс уведомления). Пользователю retry выглядит сломанным, а
+реальное лекарство (перепроверка/`recheck`/восстановление файлов в qBittorrent)
+не подсказано (находка ревью NIT-12).
+
+## What Changes
+
+- **Retry сломанного живого торрента отклоняется**, а не переотдаёт источник.
+  Отказ несёт понятное сообщение: починить раздачу (`recheck`/восстановить
+  файлы) в qBittorrent и повторить. Состояние задачи не меняется, повторного
+  `Add` не происходит.
+- Повторный `Add` при retry остаётся только для случая, когда раздачи в
+  qBittorrent НЕТ (перецепка к здоровому живому торренту — без `Add`, как и
+  раньше).
+
+## Capabilities
+
+### New Capabilities
+
+Нет.
+
+### Modified Capabilities
+
+- `state-reconciliation`: требование «Ручной повтор зависшей/упавшей загрузки из
+  транспортов» — ветка живого сломанного торрента меняет исход с «повторно отдать
+  источник» на «отклонить с подсказкой про `recheck`». Прочие ветки retry (нет
+  раздачи → `Add`; жив и здоров → перецепка без `Add`; сброс базиса `retried_at`)
+  без изменений.
+
+## Impact
+
+- **Спеки:** дельта `state-reconciliation` (одно MODIFIED-требование).
+- **Код:** `internal/worker/worker.go` — `Retry` (ветка `alive && classErrored`
+  → отказ `ErrConflict` с сообщением вместо `reAdd`).
+- **Тесты:** `internal/worker/worker_test.go` — отклонение retry на живом
+  сломанном торренте (`error`/`missingFiles`), контроль перецепки здорового.
+- **Миграции БД:** нет.
@@ -0,0 +1,84 @@
+## MODIFIED Requirements
+
+### 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 отклоняться с понятным пользователю сообщением — починить раздачу
+(`recheck`/восстановить файлы) в qBittorrent и повторить. Повторная отдача
+источника такой торрент не чинит (qBittorrent отверг бы дубль), а простой
+возврат в `downloading` тут же снова упал бы `qbit_error` по сверке (+ дебаунс
+уведомления) — retry выглядел бы сломанным. При отказе состояние задачи
+(`failed`/`stuck`) система менять SHALL NOT и повторный `Add` выполнять SHALL NOT.
+
+Повторный `Add` при retry система SHALL выполнять, только когда раздачи в
+qBittorrent нет, — **по типу источника** (`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** retry отклоняется с сообщением починить раздачу (`recheck`) в
+  qBittorrent
+- **AND** состояние задачи не меняется (остаётся `failed`), повторный `Add` не
+  выполняется
+
+#### Scenario: Retry torrent-загрузки без живого источника
+
+- **GIVEN** задача с `source_type = torrent` в `failed`, раздачи в qBittorrent
+  нет, байты `.torrent` сохранены
+- **WHEN** пользователь инициирует retry
+- **THEN** сохранённые байты добавляются в qBittorrent файлом
+- **AND** задача переходит в `downloading` (не остаётся без раздачи)
@@ -0,0 +1,17 @@
+## 1. Код
+
+- [x] 1.1 В `Worker.Retry` заменить ветку `alive && classify(state)==classErrored`:
+  вместо `reAdd=true` — отказ `ErrConflict` с понятным сообщением (починить
+  раздачу `recheck` в qBittorrent), без изменения состояния и без `Add`
+- [x] 1.2 `reAdd` оставить `true` только когда раздачи нет (`!alive`)
+
+## 2. Тесты
+
+- [x] 2.1 `TestRetryRejectsLiveErroredTorrent` — `error`/`missingFiles`: retry
+  возвращает `ErrConflict`, состояние `failed` не тронуто, `Add` не вызван
+- [x] 2.2 `TestRetryReattachesLiveHealthyTorrent` — контроль: живой здоровый
+  торрент перецепляется без `Add`
+
+## 3. Спека
+
+- [x] 3.1 MODIFIED-требование в `state-reconciliation`; `openspec validate --strict`