myYouTube/analytics/2026-09-25-download-status-fixes.md

# Фиксы статусов загрузки: самоисцеление зависших job, откат completed неавторитетными событиями, субтитры off после ready

> **Статус (2026-09-25): Баг 3 (субтитры) ОТКАЧЕН.** Вместе с решением по `analytics/2026-09-25-subtitles-off-by-default.md` правки Бага 3 отменены и откатываются из `Player.tsx`; пользователь отключит субтитры сам в настройках YouTube-аккаунта. **Баги 1 и 2 остаются в силе** и выполняются в полном объёме. Детали — в журнале.

## Задача

Три независимых бага (2026-09-25):

**Баг 1 — job висит в queued.** MeTube вернул done-запись со статусом `error` (HTTP 429 от YouTube — бот-проверка; инцидент: job id 14, видео COSMIC), но наш job остался `queued`: событие ошибки пропущено, а сверка с историей MeTube (`reconcile_on_startup`) работает только при старте. Нужно самоисцеление: при `GET /videos/{id}/download-status`, если последний job в `ACTIVE_STATUSES` и устарел (нет событий дольше порога, ~5 минут) — один раз сверить его с MeTube history и применить авторитетный статус.

**Баг 2 — двойная шкала прогресса.** В `_apply_metube_info` неавторитетное событие `updated` со статусом downloading/postprocessing откатывает completed-джоб назад (`elif our_status != "unknown": job.status = our_status`): после completed приходит поздний `updated` → статус снова downloading → шкала заполняется второй раз.

**Баг 3 — субтитры включаются по умолчанию.** `cc_load_policy=0` = предпочтение пользователя (у пользователя включено в аккаунте) — force-off у YouTube не существует; нужен сброс через официальное IFrame API после `onReady`. Локальное видео: возможны поздние in-band дорожки после `loadedmetadata` — нужен обработчик `addtrack` на `textTracks`.

## Контекст

### Текущее состояние кода (проверено)

- `backend/app/services/download_jobs.py`:
  - `_apply_metube_info` (строки 195–225): обновляет `metube_job_id`, `started_at`, `progress_percent`; затем ветки: `failed` (без проверки authoritative!), `completed` (только если authoritative), иначе `elif our_status != "unknown": job.status = our_status` — **именно эта ветка откатывает completed** (Баг 2). Ветка `failed` тоже не гвардится по authoritative: поздний `updated` с `error` на completed-джобе превратит его в failed.
  - `reconcile_on_startup` (строки 228–268): сверяет только джобы в `ACTIVE_STATUSES + ["unknown"]`; `by_url` собирается из bucket'ов history (queue/pending — неавторитетные, done — авторитетный); нет совпадения → `unknown`; fetch упал → всем `unknown`. Вызывается только из lifespan (`backend/app/main.py:62–65`) — при работе сервиса не срабатывает.
  - Константы в `backend/app/models/download_job.py`: `ACTIVE_STATUSES = ("queued", "downloading", "postprocessing")` (строка 11), `TERMINAL_STATUSES = ("completed", "failed", "deleted")` (строка 12).
- `backend/app/api/videos.py` — `download_status` (строки 97–103): просто `get_latest_job` + `_serialize_job`, никакой сверки с MeTube. `_serialize_job` (34–43) отдаёт `media_url` только при `completed`. `get_db` (`app/db.py:14–19`) не коммитит — обработчики коммитят сами.
- `backend/app/services/metube_client.py`: `fetch_history` (78–81) возвращает `{"queue": [], "pending": [], "done": []}`; `METUBE_STATUS_MAP` (37–45): `finished→completed`, `error→failed`.
- Frontend `DownloadButton.tsx:29–35`: пока статус в `ACTIVE_STATUSES`, поллит `GET /download-status` каждые 2 с — это готовый триггер для самоисцеления Бага 1; для Бага 2 фронт менять не нужно (он лишь читает статус: при terminal рендерит бейдж, а не шкалу).
- `frontend/src/components/Player.tsx` (worktree): уже содержит незакоммиченные правки двух предыдущих задач — `cc_load_policy: 0` в `playerVars` (строка 188) и в `src` фолбэк-iframe (295), `onLoadedMetadata` с `mode='disabled'` (266–270), создание YT.Player на императивном дочернем div. Интерфейс `YoutubePlayerApi` (13–18) не содержит `loadModule`/`unloadModule`. Работа с `textTracks` только в `onLoadedMetadata` — обработчика `addtrack` нет (grep: `addtrack|loadModule|unloadModule` не встречаются).

### Детали инцидентов

- Баг 1: Socket.IO-событие `completed` с done-записью `{"status": "error", ...}` пропущено (backend был недоступен/событие потеряно) — job остался `queued` навсегда, поллинг бесконечен.
- Баг 2: Socket.IO доставляет события с задержкой; после авторитетного `completed` приходит поздний `updated` (downloading/postprocessing) → откат статуса → в UI шкала заполняется заново.
- Баг 3: по диагнозу оркестратора у пользователя субтитры включены в настройках YouTube-аккаунта — `cc_load_policy=0` их не отключает (force-off не существует, задокументировано в `analytics/2026-09-25-subtitles-off-by-default.md`, «Риски»). MeTube качает субтитры (`subtitle_mode prefer_manual`) — наш `enqueue_video` (`metube_client.py:57–69`) subtitle-настройки не передаёт, конфиг живёт на mediaVM вне нашего контроля (AGENTS.md:11); локальные дорожки возможны только in-band в медиаконтейнере (backend `.vtt` не отдаёт, `<track>` в JSX нет).

## Затронутые подсистемы и файлы

- `backend/app/services/download_jobs.py` — хелперы `job_is_stale(db, job)` / `reconcile_stale_job(db, job)`, гвард терминальных статусов в `_apply_metube_info`.
- `backend/app/api/videos.py` — `download_status`: триггер самоисцеления.
- `frontend/src/components/Player.tsx` — Баг 3: `unloadModule/loadModule('captions')` после `onReady`; обработчик `addtrack` в локальной ветке; расширение интерфейса `YoutubePlayerApi`.
- `tests/test_download_jobs.py`, `tests/test_videos.py` — новые тесты.
- Без изменений: `DownloadButton.tsx` (фронт Бага 2 не требует), миграции, модели, README, `App.css`.

## Критерии приёмки

1. **Баг 1 (самоисцеление):** при `GET /videos/{id}/download-status` устаревший job в `ACTIVE_STATUSES` сверяется с MeTube history: done[`finished`] → `completed` (+ `media_url`), done[`error`] → `failed` (+ `error_message`), в queue/pending → остаётся активным (не `unknown`), нет в истории → `unknown`. Fetch history упал → статус не меняется, исключение не всплывает в ответ API.
2. **Баг 1 (не чаще раза за окно):** свежий job (события шли недавно) и терминальный job не триггерят `fetch_history`; повторный поллинг (2 с) не молотит MeTube.
3. **Баг 2:** неавторитетные события (`updated`) никогда не меняют статус терминального джоба (completed/failed/deleted) — ни ветка `downloading/postprocessing`, ни ветка `error`; при этом для активных джобов ветка `error` по-прежнему переводит в `failed`, а авторитетный `completed` по-прежнему завершает джоб.
4. **Баг 3 (YouTube):** при включённом пользовательском предпочтении субтитров после `onReady` субтитры выключены; CC-кнопка в UI плеера остаётся и вручную включает дорожку. `cc_load_policy: 0` сохраняется.
5. **Баг 3 (локально):** поздние in-band дорожки, добавленные после `loadedmetadata`, получают `mode='disabled'`; ранее включённая пользователем дорожка при этом не трогается; нативная CC-кнопка работает.
6. **Регрессий нет:** `pytest` (все существующие тесты зелёные, включая `test_handle_metube_event_error_marks_failed` и `test_transient_finished_in_updated_event_does_not_complete_job`), `npm run lint`, `npm run build` чистые.
7. **Деплой:** `docker compose up -d --build`, `curl http://localhost:8080/api/health` → OK.

## План

1. **Баг 2, `_apply_metube_info`** (ядро фикса, от него зависят тесты Бага 1):
   - После обновления `metube_job_id`/`started_at`/`progress_percent` добавить гвард: `if not authoritative and job.status in TERMINAL_STATUSES: return` — статус терминального джоба не трогается, `error_message`/`completed_at`/`media_url` не перезаписываются.
   - Ветку `failed` и `elif our_status != "unknown"` не менять: они продолжают работать для активных/`unknown` джобов; авторитетный `completed` завершает любой джоб (включая failed), как сейчас.
2. **Баг 1, `download_jobs.py`**:
   - Константа порога, напр. `STALE_JOB_AFTER = timedelta(minutes=5)`.
   - `def job_is_stale(job, *, now=None) -> bool`: `job.status in ACTIVE_STATUSES and now - job.requested_at > STALE_JOB_AFTER and now - job.updated_at > STALE_JOB_AFTER`. Второе условие (`updated_at`) реализует «один раз»: пока события идут, `updated_at` свежий и сверка не нужна; после пропавшего события оба поля устаревают.
   - `def reconcile_stale_job(db, job) -> None`: `MeTubeClient().fetch_history()` → `by_url` из bucket'ов в том же порядке, что `reconcile_on_startup` (queue/pending неавторитетные, done авторитетный) → match по `video.youtube_url` → `_apply_metube_info(job, info, authoritative)`; нет совпадения → `job.status = "unknown"`; исключение fetch → логировать и **не менять статус** (в отличие от startup-reconcile: здесь это не перезапуск, а транзиентная ошибка поллинга). В конце явно `job.updated_at = datetime.now(timezone.utc)` и `db.commit()` — это и есть «один раз сверить»: следующая попытка не раньше чем через `STALE_JOB_AFTER` после этой (commit и так бампает `updated_at` через `onupdate`, но только если был реальный UPDATE — явное присваивание гарантирует бэкофф и при fetch-ошибке и при «ничего не изменилось»).
   - `get_db` не коммитит — хелпер обязан закоммитить сам (как `request_download`/`delete_local_copy`).
3. **Баг 1, `api/videos.py::download_status`**:
   - После `get_latest_job`: `if job and download_jobs.job_is_stale(job):` → в try/except вызвать `reconcile_stale_job(db, job)` (исключение → `logger.warning`, ответ отдаём по текущему состоянию). Импортировать `ACTIVE_STATUSES` не нужно (предикат внутри хелпера); импорт `job_is_stale`/`reconcile_stale_job`.
4. **Баг 3, `Player.tsx`**:
   - Расширить `YoutubePlayerApi`: `loadModule(module: string): void`, `unloadModule(module: string): void`.
   - В `onReady` (после гардов `cancelled/timedOut`, сброса таймаута и `setYtApiStatus('ready')`): `event.target.unloadModule('captions'); event.target.loadModule('captions')` — сброс на выкл, CC-кнопка остаётся. Использовать `event.target` (типизированный), а не замыкание на `player` (чище, без TDZ-нюансов).
   - Локальная ветка: добавить обработчик `addtrack` на `video.textTracks` (`TextTrackList` — EventTarget), в колбэке `event.track.mode = 'disabled'` (только новая дорожка — ручной выбор пользователя на существующих не трогаем). Регистрировать в `useEffect` с deps `[useLocal, video.local.media_url]` (guard `videoRef.current`, cleanup с `removeEventListener`) — поверх существующего `onLoadedMetadata`, который не трогаем.
   - Фолбэк plain-iframe не менять (API недоступно — см. «Риски»); `cc_load_policy: 0` оставить в обеих YouTube-ветках.
5. **Тесты** (mock'и, реальные вызовы MeTube запрещены — AGENTS.md):
   - `tests/test_download_jobs.py`: `reconcile_stale_job` — done[finished]→completed+media_url; done[error]→failed+error_message; в queue/pending→остаётся active; нет в истории→unknown; fetch упал→статус не меняется. Гвард Бага 2 — completed + `updated` downloading/postprocessing/error → остаётся completed (`media_url`/`completed_at` целы, `error_message` не пишется); failed + `updated` downloading → остаётся failed; авторитетный `completed` завершает queued-джоб. Существующие тесты `_apply_metube_info` не ломаются.
   - `tests/test_videos.py`: `GET download-status` — устаревший queued → самоисцеление в completed (mock history); свежий job → `fetch_history` не вызывается (monkeypatch, который падает при вызове); терминальный job → не вызывается; нет в истории → `unknown`.
   - **Внимание к SQLite:** `func.now()` в тестах наивен (naive), сравнение с `datetime.now(timezone.utc)` упадёт `TypeError` — в тестах явно задавать `requested_at`/`updated_at` осознанными (aware) значениями в прошлом.
6. **Проверки:** `backend/.venv/bin/python -m pytest tests/ -v`; `cd frontend && npm run lint && npm run build`; ручные: зависший job → самоисцеление при открытии страницы; скачивание → шкала заполняется один раз; YouTube-видео при включённом предпочтении субтитров → off после ready, CC-кнопка включает; локальное видео с субтитрами → off, поздние дорожки тоже off; деплой + health.

## Риски и ограничения

- **GET с побочным эффектом:** `download-status` мутирует состояние. Принято осознанно (задано оркестратором): операция идемпотентная и вынесена в сервис-хелпер; REST-чистота (AGENTS.md:13, mobile-клиент) сохранена на уровне семантики «статус с ленивой самокоррекцией». Фоновый воркер-самоисцелитель — альтернатива, отклонена как избыточная для single-user.
- **Молотилка MeTube:** без гварда по `updated_at` поллинг раз в 2 с при длинной (>5 мин) загрузке дёргал бы `/history` на каждый запрос — гвард и явный touch `updated_at` дают одну сверку за окно `STALE_JOB_AFTER`. Раса двух параллельных GET безвредна (обе сверки идемпотентны).
- **`unknown` vs «оставить queued»:** выбрано `unknown` — согласовано с семантикой `reconcile_on_startup` (не сверяемое состояние) и с UI (`DownloadButton.tsx:106` показывает «Загрузить снова»). Оставить queued = вечный поллинг.
- **Задержка самоисцеления:** до 5 минут после пропажи событий; live-события Socket.IO остаются основным каналом, сверка — страховка.
- **Баг 2, деградация `deleted`:** авторитетный `completed` на джобе со статусом `deleted` формально может «воскресить» его (media_url перезапишется). Практически невозможно (после /delete MeTube шлёт `cleared`, replay'ов нет); гвардить отдельно не будем — зафиксировано, вне скоупа.
- **Баг 3, фолбэк-iframe:** без IFrame API сброс captions невозможен — в деградированном пути субтитры могут показаться по предпочтению пользователя. Принято: фолбэк — редкий путь при сбое API.
- **Баг 3, порядок unload/load:** `unloadModule('captions')` сбрасывает на выкл, `loadModule('captions')` возвращает модуль (CC-кнопка); без повторного load кнопка CC пропала бы. Порядок обязателен.
- **Worktree:** правки `Player.tsx`/`App.css` двух предыдущих задач (`2026-09-25-subtitles-off-by-default.md`, `2026-09-25-player-blank-page-after-download.md`) не коммичены — фиксы накладываются поверх, не откатывать. Номера строк Player.tsx указаны для текущего состояния worktree.
- **MeTube-конфиг субтитров** (`subtitle_mode prefer_manual`) живёт на mediaVM, вне нашего контроля (AGENTS.md:11) — мы обрабатываем результат (in-band дорожки) у себя.

## Журнал изменений

- 2026-09-25 (ОТКАТ Бага 3): **Баг 3 (субтитры) откатывается вместе с `analytics/2026-09-25-subtitles-off-by-default.md`** — решение отменено пользователем (у YouTube нет force-off субтитров без потери кнопки CC; пользователь сам отключит субтитры в настройках YouTube-аккаунта: Настройки → Воспроизведение и производительность → Субтитры и CC → снять «Всегда показывать субтитры»). Из `Player.tsx` убираются: `unloadModule`/`loadModule('captions')` после `onReady`, методы `loadModule`/`unloadModule` из `YoutubePlayerApi`, `onLoadedMetadata` с `mode='disabled'` и эффект с обработчиком `addtrack`, `cc_load_policy` из `playerVars` и `src` фолбэк-iframe. **Баги 1 и 2 остаются в силе и реализуются в полном объёме** (самоисцеление зависших job, гвард терминальных статусов) — их задачи, критерии, план и тесты не меняются; в «Критериях» пункты 4–5 (Баг 3) снимаются, фолбэк plain-iframe остаётся без параметра `cc_load_policy`.
- 2026-09-25: документ создан до реализации. Проверено по коду: `download_status` без сверки (videos.py:97–103), `reconcile_on_startup` только из lifespan (main.py:62–65), `_apply_metube_info` откатывает терминальные статусы веткой `elif our_status != "unknown"` (download_jobs.py:224–225) и веткой `failed` без гварда (209–211), `TERMINAL_STATUSES`/`ACTIVE_STATUSES` (download_job.py:11–12), `fetch_history` и `METUBE_STATUS_MAP` (metube_client.py:37–45, 78–81), поллинг фронта 2 с (DownloadButton.tsx:29–35), `YoutubePlayerApi` без `loadModule/unloadModule` и без `addtrack` (Player.tsx:13–18, 266–270). Решения: самоисцеление по устареванию `requested_at` И `updated_at` (гвард «один раз» через touch `updated_at`, без миграции); «нет в истории» → `unknown`; на ошибке fetch статус не менять; гвард `not authoritative and job.status in TERMINAL_STATUSES` с сохранением ветки error для активных джобов; сброс captions через `unloadModule`+`loadModule` после `onReady` (через `event.target`); `addtrack`-обработчик, отключающий только новую дорожку. README не обновляется: изменения — внутренний hardening, уровень описания («полная MeTube-интеграция … recovery после рестарта», README.md:10) остаётся верным; прецедент — предыдущие документы 2026-09-25 также без README-правок. Баг 3 — продолжение `2026-09-25-subtitles-off-by-default.md` (его риски подтвердились: force-off нет, дорожки могут появляться после `loadedmetadata`), туда добавлена журнальная запись-ссылка.