REST API (108 endpoints)¶

FastAPI REST API обслуживает React SPA и предоставляет 108 endpoints через 16 роутеров. Swagger доступен по /api/docs (только для admin).

Модель авторизации¶

Параметр	Значение
Тип	Session-cookie auth (opaque token + scrypt hash)
Публичные	`/api/health/`, `/api/auth/` (кроме `/api/auth/me`), `/api/ui-config` (GET)
Authenticated	`/api/dashboard`, `/api/conversations`, `/api/operator`, `/api/clients`
Admin-only	Все остальные + Swagger `/api/docs`

flowchart LR
    REQ[Запрос] --> AUTH{Cookie?}
    AUTH -->|нет| PUB{Публичный endpoint?}
    PUB -->|да| OK[200]
    PUB -->|нет| DENY[401]
    AUTH -->|да| ROLE{Роль?}
    ROLE -->|admin| ADMIN[Полный доступ]
    ROLE -->|operator| OP[Ограниченный доступ]

RBAC¶

Роль	Доступные маршруты
`operator`	`/dashboard`, `/conversations`, `/operator`, `/clients`
`admin`	Все operator-маршруты + `/accounts`, `/departments`, `/workflows`, `/rag`, `/company`, `/settings`, `/proxies`, `/warming`, `/search`, `/employees`, `/portal-admin`

Сводная таблица API¶

Группа	Prefix	Access	Endpoints	Назначение
Health	`/api/health`	public	3	live, ready, legacy probes
Auth	`/api/auth`	mixed	10	register, login, logout, password reset, invite, me
Dashboard	`/api/dashboard`	authenticated	3	KPI, tables, communication economics
Conversations	`/api/conversations`	authenticated	3	Список, детали (500 msg), takeover
Clients	`/api/clients`	authenticated	11	CRUD, import/export, backups, memory
Operator	`/api/operator`	authenticated	12	Workspace, send, mode, suggestions, memory
Accounts	`/api/accounts`	admin	3	Список, детали, обновление
Departments	`/api/departments`	admin	10	Промпты, секции, preview, reference
Companies	`/api/companies`	admin	7	CRUD + activate
Settings	`/api/settings`	admin	7	Env-переменные, конфигурация
Infrastructure	`/api/*`	admin	6	Proxies, GoIP SIMs, warming
Workflows	`/api/workflows`	admin	17	Config, versions, publish/rollback/diff
Search	`/api/search`	admin	2	Semantic search stats + query
RAG	`/api/rag`	admin	6	Status, graph, branches, traces, reload
Users	`/api/users`	admin	4	Сотрудники, invite, resend, update
UI Config	`/api/ui-config`	mixed	4	GET (public), PUT/reset/defaults (admin)

Ключевые endpoints¶

Health¶

Method	Path	Назначение
GET	`/api/health/live`	Liveness probe
GET	`/api/health/ready`	Readiness probe (DB + Redis + commit consistency)
GET	`/api/health`	Legacy health check

Auth¶

Method	Path	Назначение
GET	`/api/auth/bootstrap`	Проверка: есть ли хотя бы один пользователь
POST	`/api/auth/register`	Регистрация первого администратора
POST	`/api/auth/login`	Логин (email + password --> session cookie)
POST	`/api/auth/logout`	Логаут (очистка cookie)
GET	`/api/auth/me`	Текущий пользователь + `available_routes`
POST	`/api/auth/forgot-password`	Запрос сброса пароля
POST	`/api/auth/reset-password`	Установка нового пароля по токену
POST	`/api/auth/verify-email`	Подтверждение email кодом
POST	`/api/auth/invite`	Приглашение сотрудника
POST	`/api/auth/accept-invite`	Принятие приглашения

Dashboard¶

Method	Path	Назначение	Cache
GET	`/api/dashboard/stats`	KPI: аккаунты, клиенты, диалоги, warming 24h	30s
GET	`/api/dashboard/tables`	Attention queue, department/account health	--
GET	`/api/dashboard/communications`	AI spend, token volume, message mix	30s

Communications Analytics

Параметр window принимает значения 24h, 7d, 30d. Возвращает coverage, summary, series, breakdowns (по source, campaign, model).

Operator Workspace¶

Method	Path	Назначение
GET	`/api/operator/summary`	Общая сводка workspace
GET	`/api/operator/conversations`	Очередь handoff
GET	`/api/operator/conversations/{id}/messages`	Сообщения с delta-polling (`after_id`, `include_state`)
POST	`/api/operator/conversations/{id}/send`	Отправка сообщения от оператора
POST	`/api/operator/conversations/{id}/claim`	Взять диалог в работу
POST	`/api/operator/conversations/{id}/mode`	Переключить режим (auto/assisted/manual)
GET	`/api/operator/conversations/{id}/suggestions`	AI suggestions (cache-first + Celery fallback)
GET	`/api/operator/conversations/{id}/suggestions/stream`	Streaming suggestions
POST	`/api/operator/validate`	Валидация текста оператора
POST	`/api/operator/reassign`	Переназначение диалога
POST	`/api/operator/remember`	Запись в память клиента

Split-topology fallback

Remote API не имеет Claude CLI/SDK. При генерации AI suggestions диспатчится Celery task на локальный воркер. Источник "fallback_pending" (30s TTL) возвращается до появления AI-результата (600s TTL).

Clients¶

Method	Path	Назначение
GET	`/api/clients`	Список с фильтрами по 7 статусам
GET	`/api/clients/{id}`	Карточка клиента
GET	`/api/clients/{id}/memory`	JSON-память клиента
POST	`/api/clients/import`	Импорт из Excel
GET	`/api/clients/export`	Экспорт
GET	`/api/clients/backups`	Список бэкапов
POST	`/api/clients`	Создание клиента
PATCH	`/api/clients/{id}`	Обновление
DELETE	`/api/clients/{id}`	Удаление
DELETE	`/api/clients/{id}/memory`	Очистка памяти
POST	`/api/clients/clear`	Массовая очистка

Departments¶

Method	Path	Назначение
GET	`/api/departments`	Список отделов
GET	`/api/departments/{name}`	Детали отдела
PUT	`/api/departments/{name}`	Обновление (hot-reload через Redis pub/sub)
GET	`/api/departments/{name}/base-prompt`	Базовый промпт
GET	`/api/departments/{name}/default-prompt`	Промпт по умолчанию
DELETE	`/api/departments/{name}`	Удаление
GET	`/api/departments/sections`	28 промпт-секций из section_catalog
GET	`/api/departments/{name}/sections`	Override-секции отдела
PUT	`/api/departments/{name}/sections`	Обновление секций
POST	`/api/departments/{name}/preview`	Preview промпта по call_type

Workflows¶

Method	Path	Назначение
GET	`/api/workflows/types`	4 типа workflow
GET	`/api/workflows/{type}`	Определение workflow
GET	`/api/workflows/{type}/config`	Параметры (с department overrides)
PUT	`/api/workflows/{type}/config`	Обновление параметров
GET	`/api/workflows/{type}/stats`	Live-статистика
GET	`/api/workflows/{type}/versions`	Список версий
GET	`/api/workflows/{type}/versions/{id}`	Детали версии
POST	`/api/workflows/{type}/versions`	Создание draft
PUT	`/api/workflows/{type}/versions/{id}`	Обновление draft
DELETE	`/api/workflows/{type}/versions/{id}`	Удаление draft
POST	`/api/workflows/{type}/versions/{id}/publish`	Публикация (hot-reload)
POST	`/api/workflows/{type}/versions/{id}/rollback`	Откат
GET	`/api/workflows/{type}/versions/{id}/diff`	Diff между версиями

Hot-Reload без перезапуска¶

Что меняем	Endpoint	Механизм
UI Config	`PUT /api/ui-config`	In-memory cache + ETag
Department prompts	`PUT /api/departments/{name}`	Redis pub/sub --> AIEngine
Company profile	`PUT /api/companies/{id}`	Redis pub/sub --> AIEngine
Workflow params	`POST .../publish`	Redis pub/sub --> WorkflowResolver
Embedding model	`POST /api/rag/reload-model`	`RAGEngine.reload_model()`

Требуют перезапуска

Большинство .env переменных (AI model, tokens, database URLs, working hours) требуют перезапуска контейнера после изменения через PUT /api/settings.

Source of Truth¶

Что	Файл
Маршруты фронтенда	`web/src/App.tsx`
Монтаж API	`api/main.py`
Auth flow	`api/routes/auth.py`, `api/security.py`
Role ACL	`api/security.py::ROLE_ALLOWED_ROUTES`
OpenAPI spec	`/api/openapi.json`