myYouTube/analytics/2026-09-17-project-baseline.md

# Базовый документ проекта (baseline)

## Задача

Зафиксировать фактическое состояние проекта MyYouTube на 2026-09-17 как точку отсчёта для будущих задач агентской команды. Документ описывает: обзор, архитектуру, интеграции, ключевые решения с причинами из git-истории, известные ограничения/техдолг и устройство команды агентов. Факты сверены с кодом, `README.md`, `AGENTS.md`, миграциями и `git log`.

## 1. Обзор проекта

Персональный single-user YouTube-клиент с категориями подписок и интеграцией с существующим MeTube. Скачивание выполняет MeTube на `mediaVM`; этот сервис ничего не скачивает сам и не хранит видео локально (только проксирует/линкует `media_url`).

- **Статус:** функционально готово. Этапы 1–6 реализованы (каркас, OAuth, категории, синк подписок/видео, лента, воспроизведение, MeTube-интеграция), плюс доработки по итогам live-тестирования. Развёрнуто на тестовом окружении: `testmyyoutube.vrubel.xyz` → hermesVM `192.168.8.173` (порт 8080) → MeTube на mediaVM `192.168.8.177:8081`.
- **Стек:** Python 3.13 + FastAPI + SQLAlchemy 2.x + Alembic + Pydantic Settings + APScheduler; React 19 + TypeScript + Vite 8 + React Router 7 + TanStack Query 5; PostgreSQL 16; Docker Compose.
- **Масштаб:** single-user — вход разрешён только `ALLOWED_GOOGLE_EMAIL`; фронтенд не ходит в Google API и MeTube write API напрямую (только через backend).
- **Реализованные возможности:** Google OAuth (allow-list) → синк подписок (APScheduler) и видео (по активности); категории (CRUD, reorder, many-to-many с каналами, постоянные URL); лента с курсорной пагинацией, поиском по видео/каналам и фильтром «только новые»; YouTube-плеер; MeTube-интеграция (download/delete, Socket.IO live-статусы, recovery после рестарта); раздел «На сервере» (`/local`, перенаправление с `/saved`); отписка на YouTube; удаление скачанной копии; тёмный адаптивный UI с мобильным меню; скрытие отписанных каналов; счётчики подписчиков и бейджи «N новых» (окно 2 дня).
- **Быстрая проверка (prod):** `docker compose up -d --build` → `curl http://localhost:8080/api/health` (возвращает `status`/`database`/`metube`).
- **Состояние worktree на момент фиксации:** ветка `master` впереди `origin/master` на 1 коммит (f0ca7b9 не запушен); в работе документационная задача «Удалить AGENT_TEAM.md» (`analytics/2026-09-17-remove-agent-team-guide.md`, staged-удаление `AGENT_TEAM.md`, правки `README.md` и `.opencode/agent/analyst.md`).

## 2. Архитектура

### Backend (`backend/app/`)

- **`main.py`** — FastAPI app: `SessionMiddleware` (cookie `myyoutube_session`, 30 дней, `same_site=lax`, `https_only` по `APP_BASE_URL`), lifespan = reconcile download jobs по `/history` MeTube + старт APScheduler + Socket.IO-листенер MeTube (переподключения). Статика собранного фронта монтируется в `/` с fallback на `index.html` (`SPAStaticFiles`).
- **`api/`** (группы, кроме `auth/status`, `auth/google/*` и `health` — за `require_session`):
  - `health` — `GET /api/health` (status, database, metube).
  - `auth` — `GET /auth/status`, `/auth/google/start`, `/auth/google/callback` (state-проверка, allow-list, background initial sync), `POST /auth/logout`.
  - `channels` — `GET /channels` (фильтры `subscribed/search/category_id/uncategorized`), `GET /channels/{id}`, `PUT /channels/{id}/categories`, `POST /channels/{id}/unsubscribe` (реальная отписка на YouTube).
  - `categories` — CRUD + `POST /categories/reorder` (slug-генерация, проверка дублей имён).
  - `feed` — `GET /feed` (курсорная пагинация base64 `published_at|id`, фильтры category/uncategorized/channel/downloaded/search/new_only, лимит 30/100), `GET /feed/saved-counts`.
  - `videos` — `GET /videos/{youtube_video_id}`, `POST .../download`, `DELETE .../download`, `GET .../download-status`, `POST .../recheck-local`.
  - `sync` — `POST /sync/subscriptions`, `POST /sync/videos`, `GET /sync/status`.
- **`services/`** — `google_oauth` (flow, allow-list, кэш токена), `youtube_client` (все вызовы YouTube API, ошибки квоты/scope), `sync` (подписки и видео, thread-lock'и), `sync_trigger` (синк по активности), `scheduler` (APScheduler, только подписки), `metube_client` (HTTP+Socket.IO к MeTube), `download_jobs` (машина состояний, reconcile), `state` (AppSetting get/set), `video_presentation` (сериализация).
- **`core/`** — `auth_dependency.require_session` (+триггер синка видео), `crypto` (Fernet для refresh token), `duration` (ISO 8601 → секунды), `slugify`.
- **Модели БД:** `AppSetting` (key/value — статусы синков), `OAuthCredentials` (singleton `id=1`, `encrypted_refresh_token`), `Channel` (`youtube_channel_id`, `youtube_subscription_id`, `uploads_playlist_id`, `subscriber_count`, `subscribed`, `last_synced_at`), `Video` (`youtube_video_id` unique, `published_at`, `duration_seconds`, `youtube_url`), `Category` (name/slug unique, `sort_order`), `channel_categories` (m2m, PK-пара), `DownloadJob` (статусы `queued/downloading/postprocessing/completed/failed/deleted/unknown`, `metube_job_id`, `metube_filename`, `media_url`).
- **Миграции (Alembic, `migrations/versions/`):** 0001 `app_settings` → 0002 `oauth_credentials` + `channels` → 0003 `categories` + `channel_categories` → 0004 `videos` (+индексы) → 0005 `download_jobs` → 0006 `channels.youtube_subscription_id` → 0007 drop `access_token_expires_at` (мёртвая после in-process кэша) → 0008 `channels.subscriber_count` (BigInteger, из `statistics`).

### Frontend (`frontend/src/`)

- **Роуты (`App.tsx`):** `/` Feed, `/category/:categoryId`, `/uncategorized`, `/local` (скачанные), `/search`, `/saved` → redirect `/local`, `/channels`, `/channels/:channelId/videos`, `/video/:youtubeVideoId`, `/settings`, `/settings/categories` (и `/categories` → redirect), 404. До входа — страница `Connect`.
- **Страницы:** `Connect`, `Feed` (infinite-query, фильтры, бейджи новых, кнопка «Обновить»), `Channels` (поиск, `CategoryNav`, назначение категорий, отписка), `ChannelVideos` (счётчик подписчиков), `VideoPage`, `Categories` (CRUD, reorder, confirm-диалог), `Settings` (health MeTube, статусы синков, переподключение, logout).
- **Компоненты:** `AppShell` (сайдбар с категориями и бейджами новых, поиск по видео/каналам, индикатор синка, мобильное drawer-меню), `VideoCard`, `ChannelCard` (popover категорий, создание категории на лету), `DownloadButton` (polling 2 с только для активных статусов), `Player` (локальная копия через `media_url`, при ошибке — fallback на iframe `youtube-nocookie.com` + `recheck-local`), `Icon`.
- **API-клиент** — `api/client.ts`, fetch с `credentials: include`, все эндпоинты типизированы; `utils/format.ts` — форматирование длительности/времени/счётчиков подписчиков.
- **Стили/состояние:** `App.css`/`index.css` (тёмная адаптивная тема); TanStack Query с invalidation по ключам `['feed']`, `['channels']`, `['categories']`, `['download-status', id]` и т.д.; позиция скролла ленты восстанавливается через `sessionStorage` (`feed-scroll:*`).

### Деплой

- **`Dockerfile`** — multi-stage: node:22-slim собирает фронт (`npm ci && npm run build`), python:3.13-slim — бэкенд; dist → `backend/static`; **non-root** пользователь `uid 10001`; `EXPOSE 8080`.
- **`entrypoint.sh`** — `alembic upgrade head` → `uvicorn app.main:app` (`--proxy-headers --forwarded-allow-ips="*"`, порт `APP_PORT`).
- **`compose.yml`** — `app` (env_file `.env`, healthcheck `curl /api/health`) + `postgres:16` (volume `postgres_data`, healthcheck `pg_isready`). Миграции применяются при старте контейнера.
- **`.env`** — секреты: `APP_SECRET_KEY`, `TOKEN_ENCRYPTION_KEY` (Fernet, менять нельзя), `GOOGLE_CLIENT_SECRET`, `POSTGRES_PASSWORD`; все внешние URL (Google/YouTube/MeTube) и параметры синка — в env (см. `.env.example`).
- **Локальная разработка:** backend — `uv venv`/`uv pip install -r requirements-dev.txt` + `alembic upgrade head` + `uvicorn app.main:app --app-dir backend --port 8080`; тесты — `pytest tests/ -v` (SQLite in-memory, Google/MeTube mock). Frontend — `npm install` + `npm run dev`, Vite проксирует `/api/*` на `127.0.0.1:8080` (`vite.config.ts`); lint — `oxlint`, сборка — `tsc -b && vite build`.

### Ключевые настройки (`config.py`, все переопределяются env)

- Google/YouTube endpoints: `google_auth_uri`, `google_token_uri`, `google_userinfo_uri`, `google_revoke_uri`, `youtube_api_base_url` (`https://www.googleapis.com/youtube/v3`), `youtube_watch_url_template`.
- MeTube: `metube_api_base_url` (дефолт `http://127.0.0.1:8081`, реально `http://192.168.8.177:8081`), `metube_public_base_url` (для браузера), `metube_container_download_dir` (`/downloads`), `metube_request_timeout_seconds` (30).
- Синк: `subscriptions_sync_interval_hours=6` (APScheduler), `videos_sync_idle_hours=2` (триггер по активности), `videos_backfill_cap=200`, `videos_known_stop_threshold=50`, `new_videos_window_days=2`.

## 3. Интеграции

### Google OAuth / синк

- **Scope:** полный `https://www.googleapis.com/auth/youtube` (read/write — ради `subscriptions.delete` при отписке; сознательное отступление от `youtube.readonly` по явному запросу пользователя) + `openid`, `userinfo.email`, `userinfo.profile`. Старые readonly-токены не покрывают отписку → нужен один переподключение.
- **Single-user:** email из userinfo сверяется с `ALLOWED_GOOGLE_EMAIL`; недопустимый аккаунт — `revoke_token` + редирект с `auth_error=account_not_allowed`. Redirect URI фиксирован: `{APP_BASE_URL}/api/auth/google/callback` (должен быть в Authorized redirect URIs Google-клиента).
- **Кэш токена:** refresh token хранится в БД шифрованным (Fernet, `TOKEN_ENCRYPTION_KEY`); access token — в памяти процесса под `threading.Lock`, проактивный refresh за 60 с до expiry (`OAUTHLIB_RELAX_TOKEN_SCOPE=1` снимает ложный scope-mismatch при расширении scope). Обмен кода на токен с `access_type=offline`, `prompt=consent`.
- **После подключения** — фоновый initial sync (подписки + видео) через `BackgroundTasks`.

### YouTube API (`youtube_client.py`)

- Ресурсы: `subscriptions.list` (`mine=true`, пагинация по 50), `channels.list` (`snippet,contentDetails,statistics` — uploads playlist и подписчики, батчи по 50), `playlistItems.list` (`contentDetails`, лимит `MAX_PLAYLIST_PAGES=10` страниц), `videos.list` (`snippet,contentDetails,status`, батчи по 50), `subscriptions.delete`.
- Ошибки → HTTP: `quotaExceeded/dailyLimitExceeded/rateLimitExceeded` → 503 «quota exhausted»; insufficient scope → 403 с подсказкой переподключиться; прочее → 502.
- **Квота (оценка из паттерна вызовов):** видео-синк на канал — 1 юнит `playlistItems.list` + 1 юнит `videos.list` на каждые ≤50 новых id → практически **~2 юнита на канал за синк видео** при малом числе новых видео; синк подписок — 1 юнит `subscriptions.list` на 50 подписок + 1 юнит `channels.list` на 50 каналов. Расход пропорционален числу каналов.

### MeTube (`metube_client.py`)

- Весь HTTP/Socket.IO к MeTube инкапсулирован в `MeTubeClient` (правило AGENTS.md): `POST /add` (url, `download_type=video`, codec auto, format mp4, quality best, `auto_start`, `custom_name_prefix` = youtube_video_id), `GET /history`, `POST /delete` (**ключ — URL, не job id**; `where=done`), `build_media_url` (публичный `/download/<filename>` с защитой от path traversal), `check_media` (HEAD), `health`.
- **Socket.IO-события** `added/updated/completed/canceled/cleared` (payload — JSON-строка от `DownloadInfo.to_public_dict()`); маппинг статусов MeTube (`pending/preparing/scheduled/downloading/postprocessing/finished/error`) → свои. Только событие `completed` — авторитетный терминальный статус (yt-dlp шлёт `finished` по отдельным потокам → иначе flapping). `media_url` строится из точного `filename` события (не из title) и отдаётся только при `completed`.
- **Recovery:** при старте `reconcile_on_startup` сверяет активные/`unknown` job'ы с `/history`; completed с `media_url` не трогаются. «cleared»/«canceled» матчатся по URL, несовпавшие игнорируются.

### Процессы синка (`services/sync.py`)

- **Подписки:** `subscriptions.list` (пагинация) → upsert каналов (заполняется и `youtube_subscription_id` для будущей отписки); каналы, которых нет в ответе API, помечаются `subscribed=False` (скрываются в UI). Затем батчами по 50 `channels.list` добираются `uploads_playlist_id` и `subscriber_count`; неудача этой фазы не валит весь синк. Запуск: APScheduler каждые 6 ч + ручной `POST /sync/subscriptions`; параллельный запуск блокируется `threading.Lock` → 409 `SyncInProgress`.
- **Видео:** по каждому подписанному каналу с uploads-плейлистом — инкрементальный `playlistItems.list` (ранняя остановка на 50 подряд известных, кап 200 новых на канал, максимум 10 страниц на плейлист); известные id собраны заранее одним запросом к БД (без N+1). Для неизвестных id — `videos.list` батчами по 50 и insert. Существующие видео не обновляются. Запуск: триггер по активности (`maybe_trigger_videos_sync` в `require_session`, idle ≥2 ч, фоновый поток) + ручной `POST /sync/videos`.
- **Статусы синков** персистятся в `app_settings` (JSON: status/started_at/finished_at/error + счётчики), отдаются через `GET /api/sync/status` (плюс флаг `running` из lock'а); UI опрашивает каждые 2 с пока идёт синк, иначе раз в 60 с.

## 4. Ключевые решения и политики (из git log)

- **2026-09-16, `0ed20bb`** — этапы 1–5: каркас, OAuth, категории, синк видео/лента, воспроизведение.
- **2026-09-16, `fe16c08`** — этап 6: MeTube-интеграция (download/delete, live-статусы).
- **2026-09-16, `e333296`/`10c16ba`** — статусы загрузки: терминален только `completed`; кнопка не откатывается в «Скачать» после завершения.
- **2026-09-16, `3089202`+`8ddea87`** — реальная отписка (`subscriptions.delete`) и удаление скачанного — сверх MVP по запросу пользователя; из-за этого scope расширен до полного `youtube` (потребовался `OAUTHLIB_RELAX_TOKEN_SCOPE`).
- **2026-09-16, `62f8fb7`/`441a3ef`** — `DELETE /videos/{id}/download`: ключ `/delete` — URL (по id — тихий no-op); после запроса проверяем фактическое удаление файла (настройка `DELETE_FILE_ON_TRASHCAN` MeTube вне нашего контроля → 409).
- **2026-09-16, `b29bcfb`…`90eb012`** — отписанные каналы скрываются; вкладка Saved; счётчики каналов/сохранённых в сайдбарах.
- **2026-09-16, `c4a772b`** — тёмный адаптивный редизайн интерфейса.
- **2026-09-16, `6c704ca`** — переход на opencode-команду агентов (Codex/Herdr выброшены).
- **2026-09-17, `fde9a43`** — review-фиксы: in-process кэш access token (+миграция 0007), обработка cleared/canceled по URL, email в `/auth/status` только при валидной сессии, Google base URLs в настройки, **non-root контейнер**; убран «Без категории» из сайдбара (фильтр остался на странице каналов), локальные фильтры в query key, Content-Type только с телом.
- **2026-09-17, `e10df8d`** — канальные фичи: подписчики из `statistics` (0008), бейджи «N новых» (окно **`NEW_VIDEOS_WINDOW_DAYS=2`**), **синк видео по активности** (idle **`VIDEOS_SYNC_IDLE_HOURS=2`** вместо ежечасного планировщика), **инкрементальная догрузка**: ранняя остановка после **50 подряд известных** id (`VIDEOS_KNOWN_STOP_THRESHOLD`), жёсткий кап **200 последних видео на канал** (`VIDEOS_BACKFILL_CAP`); клик по бейджу фильтрует категорию (`new_only`).
- **2026-09-17, `2e5ef8e`** — `.env.example` с комментариями к каждому полю.
- **2026-09-17, `f0ca7b9`** — введён субагент Analyst и конвенция `analytics/`.

## 5. Известные ограничения и техдолг

- **Квота YouTube:** основной расход — по каналу за видео-синк (~1–2 юнита, см. п. 3); при текущем числе подписок практический запас — **порядка 2–4 полных синков видео в день** (оценка, зависит от числа каналов). Исчерпание → 503, обновления пропускаются до сброса суточной квоты; ручной «Обновить» в UI не «пробьёт» квоту.
- **Браузерная проверка только пользователем:** в команде нет Playwright/скриншот-инструментов; reviewer/tester честно помечают визуальное как неверифицированное, финальную визуальную приёмку делает пользователь после деплоя.
- **Edge-кейсы MeTube:** удаление записи вне нашего приложения (`cleared` done-записи) матчится по URL и может быть не связано с нашими job'ами; re-download после удаления создаёт новый `DownloadJob`, значимым считается последний; после рестарта активные job'ы сверяются с `/history` (иначе → `unknown`, пользователь видит «Загрузить снова»).
- **Отсутствует CI и E2E:** тесты — только backend `pytest` (`tests/`, 12 файлов, SQLite in-memory, Google/MeTube замоканы; реальные вызовы к MeTube — opt-in). GitHub Actions нет, E2E/снапшотов нет.
- **Single-worker lock:** защита от параллельных синков — `threading.Lock` в одном процессе (uvicorn запускается одним worker'ом); при scale-out и триггер по активности, и блокировки перестанут быть глобальными — сознательное упрощение single-user сервиса.
- **Синк видео не обновляет метаданные** уже известных видео (`videos_updated` всегда 0, обновляются только новые id).
- **Сознательно не реализовано:** YouTube Recommendations/Home (запрещено), PWA, watch later, Shorts-фильтр, SponsorBlock; полная история канала не бэкапится (кап 200).
- **Удаление файла на диске** зависит от `DELETE_FILE_ON_TRASHCAN` MeTube (вне нашего контроля, правило 11); чужие (не наши) файлы MeTube не удаляем никогда (правило 10).

## 6. Команда агентов

- **Конфиг:** `opencode.json` → `default_agent: orchestrator`. Работа — в одной сессии opencode; задача пишется обычным сообщением.
- **Роли (`.opencode/agent/`):** `orchestrator` (primary; декомпозиция, единственный говорит с пользователем, собирает отчёт, деплой на тестовый сервис `docker compose up -d --build` после закрытия Critical/Major), `analyst` (subagent; только документация `analytics/**` и точечные правки `README.md`), `coder` (subagent; единственный меняет код продукта), `reviewer` (subagent, `edit: deny`; read-only review диффа, severity Critical/Major/Minor), `tester` (subagent, `edit: deny`; прогон проверок, ничего не чинит).
- **Цикл:** `orchestrator → analyst (фиксация задачи) → coder → reviewer + tester (параллельно) → follow-up по находкам → деплой → отчёт пользователю`. Отчёты субагентов заканчиваются маркерами `ANALYST_DONE` / `CODER_DONE` / `REVIEW_DONE` / `TEST_DONE`. Коммит/пуш — только по явному запросу.
- **Конвенция `analytics/` (`analytics/README.md`):** один файл на задачу `analytics/<YYYY-MM-DD>-<slug>.md`; секции: Задача, Контекст, Затронутые подсистемы и файлы, Критерии приёмки, План, Риски и ограничения, Журнал изменений; follow-up дополняет существующий файл (журнал + только затронутые секции); документы на русском, кратко, но полно; код не пишется.

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

- 2026-09-17 — создан baseline-документ (Analyst). Сверено с кодом: модули backend/frontend, все миграции 0001–0008, настройки `.env.example`/`config.py`, `git log -25`, роли агентов.