> Исторический документ исходного WTG. Сервис удалён 07.09.2026; описанные здесь команды эксплуатации не являются действующей конфигурацией VPS.

# API и admin UI

Актуально на 2026-06-22.

## Цель

Admin UI не является BI-дашбордом. Его задача:

- запускать сбор, синхронизацию и обработку через `admin_jobs`;
- показывать фактически собранные raw/normalized данные;
- давать оператору быстрый путь к ошибкам, artifacts и logs;
- поддерживать review, teacher/eval и canonical publication output;
- не выполнять долгие VK/OCR/processing операции синхронно в web request.

## Backend API

Один FastAPI-сервис отдает JSON API, static files и server-rendered Jinja admin.

Публичные/diagnostic endpoints:

- `GET /health`
- `GET /communities`
- `GET /communities/{id}`
- `GET /posts`
- `GET /posts/{id}`
- `GET /crawl-runs`
- `GET /debug-artifacts`
- `GET /manual-test-report`

Collection/admin JSON groups:

- `/api/collection/accounts`
- `/api/collection/browser/status`
- `/api/collection/groups`
- `/api/collection/groups/{id}`
- `/api/collection/groups/{id}/posts`
- `/api/collection/posts/{id}`
- `/api/collection/jobs`
- `/api/admin/accounts`
- `/api/admin/jobs`
- `/api/admin/jobs/{id}/detail`
- `/api/admin/jobs/{id}/stages/{stage}/*`
- `/api/admin/communities/{binding_id}/*`

Schedule/API polling JSON groups:

- `/api/admin/schedules/status`
- `/api/admin/schedules`
- `/api/admin/schedules/details`
- `/api/admin/schedules/settings`
- `/api/admin/schedules/reschedule`
- `/api/admin/schedules/run`
- `/api/admin/schedules/refresh`
- `/api/admin/schedules/rate-probe/*`
- `/api/admin/schedules/posts/force/*`

Legacy aliases under `/api/admin/api-log/*` remain as compatibility wrappers
for schedule endpoints.

Processing/results/logs JSON groups:

- `/api/admin/processing/teacher/*`
- `/api/admin/processing/ocr/status`
- `/api/admin/results/materials`
- `/api/admin/results/posts`
- `/api/admin/results/groups`
- `/api/admin/logs/events`
- `/api/admin/logs/files`
- `/api/admin/logs/archive-batches`
- `/api/admin/file-logs*`
- `/api/admin/labels/{kind}/autolabel`
- `/api/admin/labels/{kind}/{item_id}/review`
- `/api/admin/pipeline/runs`
- `/api/admin/pipeline/*`

Pool/fleet JSON groups:

- `/api/admin/group-pool/fleet-pass/*`
- `/api/admin/accounts-vnc/*`

## Главные admin-страницы

### `/admin`

Совместимый редирект на `/admin/schedules`.

### `/admin/accounts`

Список VK-аккаунтов, browser auth и API auth state.

Показывает:

- account key/title/status;
- storage paths;
- last browser session validation;
- User Token/API polling state;
- включены ли account updates;
- действия для reauth, validation, initial sync и archive.

### `/admin/schedules`

Операционный экран persisted API-расписания выбранного аккаунта.

Показывает:

- счетчики групп, постов, активных задач и VK session status;
- кнопку reauth, если browser session invalid/needs auth;
- account-lane capacity, `schedule_generation_id` и время пересборки;
- таблицы `groups`, `posts`, `products`, `services`, `addresses`;
- next/last check, slot index, status, disabled reason и result per row;
- force-post run status;
- rate-probe actions.

`Обновить расписание` создает `api_groups_sync` job. Worker после успешного
sync обновляет VK group list, архивирует missing groups и пересобирает
`api_schedule_steps`.

### `/admin/group-pool`

Глобальный API group pool и fleet pass.

Используется для:

- синхронизации pool rows из CSV через maintenance;
- fleet pass старт/стоп/пауза/резюме/freeze;
- отключения/cooldown аккаунтов или service token;
- наблюдения за pool state вне конкретного account groups list.

### `/admin/accounts-vnc`

Legacy видимые account lanes и операции. Production держит это за
`legacy-vnc` profile; основной путь для массовых быстрых проверок -
`fast_screen_pool`.

### `/admin/processing`

Операционный экран обработки:

- status deep OCR queue и `ocr_sidecar`;
- запуск publication teacher run/cycle;
- список teacher runs/results;
- переход к processing logs.

### `/admin/results`

Canonical publication output:

- `materials`: активные/архивные publication materials;
- `posts`: active/superseded publication decisions;
- `groups`: группы с количеством canonical materials/posts.

Этот экран является основным источником готовой публикационной выдачи. Legacy
`content_pipeline_items` остаются evidence/review слоем.

### `/admin/logs`

Runtime events, file list and archive batch overview from DB-backed logs and
file log helpers.

### `/admin/file-logs`

Вкладки:

- `Процессы и файлы`: live stream фоновых задач, файловые логи и artifacts;
- `Статистика сбора`: история collection/admin jobs, crawl counters, pipeline,
  OCR и итоговые ошибки.

Поддерживает list/read/download/delete и SSE stream.

### `/admin/groups`

Список групп выбранного аккаунта.

Важно:

- `Удалить` означает архивирование account binding, а не удаление community;
- missing-after-`api_groups_sync` binding получает `is_archived=true` и
  `is_excluded_from_future_crawls=true`;
- archived/excluded группы игнорируются API schedule, pipeline, labels и market
  analysis до ручного `Учитывать`.

### `/admin/groups/{id}?tab=overview|posts|market|profile`

Единая source-centric карточка группы:

- refresh профиль/UI/API;
- refresh posts;
- refresh market/services;
- clear profile info;
- delete posts;
- raw/profile JSON;
- posts, market/services, API state and pipeline funnel;
- inline monitor активной задачи.

### `/admin/market`

Единая market-витрина продуктов и сервисов.

Контракт:

- `kind=all|product|service`;
- фильтры по поиску, городу, категории анализа, статусу анализа и score;
- ссылки в group market tab.

### `/admin/pipeline`

Legacy/current pipeline evidence surface:

- `view=posts&state=candidates|rejected`: local filter/OCR post rows;
- `view=items&state=selected|active|archive`: normalized legacy items;
- `view=groups`: групповые counters по posts/OCR/items/review.

Canonical publication output должен читаться из `/admin/results`, но pipeline
остается важным для анализа расхождений и ручной диагностики.

### `/admin/pipeline/posts/{id}` и `/admin/pipeline/items/{id}`

Detail pages для pipeline post/item: source post, OCR/Paddle/LLM payloads, raw
evidence, media, labels and manual review fields.

### `/admin/posts/{id}` и `/admin/posts/{id}/local-check`

Raw post card and local single-post processing check. Используется для
диагностики конкретного source post.

### `/admin/labels`

Единая поверхность разметки:

- `scope=all|posts|events`;
- фильтры по аккаунту, дате, городу, категории, теме, признаку, уверенности и
  сортировке;
- generic AJAX endpoints для autolabel/review.

## UI stack

- FastAPI;
- Jinja templates under `apps/web/templates/admin`;
- Bootstrap 5;
- small static JS helpers under `apps/web/static`;
- server-rendered pages first, AJAX only where it reduces operator friction.

## Operational contract

Collection and processing start through admin jobs or explicit CLI commands.

`docker compose up` must not automatically:

- crawl VK groups;
- run full processing over existing posts;
- reauthorize accounts;
- apply teacher labels;
- archive stale content.

## Telegram bot

Telegram bot lives in the separate private repository
`komaroffsergei/wtg-telegram-bot`. The WTG admin remains responsible for
collection, canonical publication output and review. The bot reads ready data
from the same PostgreSQL database and owns only bot-specific tables.

## Compatibility redirects

- `/review/*` redirects to `/admin/schedules`.
- `/admin/api-log*` redirects to schedule pages.
- Removed duplicate admin pages are not part of the contract and may return
  normal 404.
