# CarPass Admin Control Center

Admin Control Center дает администраторам закрытого пилота безопасный доступ к событиям сервиса, модерации СТО, просмотру данных и экспорту без прямого SQL.

## Доступ

Админка открывается в Mini App по `/admin.html` или командой бота `/admin`.

Роли:

- `super_admin`: полный доступ к пользователям, СТО, заявкам, заказ-нарядам, расходам, audit, export и системным настройкам.
- `admin`: пользователи, СТО, модерация, заказ-наряды, базовая аналитика и экспорт без секретов.
- `moderator`: заявки СТО, отзывы, блокировки и комментарии модерации.
- `support`: поиск пользователя, авто, история действий и помощь без расширенных финансовых агрегатов.
- `analyst`: агрегированная аналитика и обезличенные выгрузки без персональных данных.

Все чувствительные admin actions пишутся в `AuditLog`.

## Уведомления

Система создает `AdminNotification` в БД и best-effort отправляет Telegram-сообщение администраторам. Ошибка Telegram не ломает бизнес-flow.

Поддержанные события:

- новый пользователь;
- первое авто пользователя;
- новая заявка СТО;
- изменение статуса заявки СТО;
- одобрение, блокировка и разблокировка СТО;
- security/system события через общий admin notification service.

Idempotency key защищает от дублей.

Env:

```env
ADMIN_TELEGRAM_IDS=123,456
ADMIN_NOTIFICATION_CHAT_ID=
ADMIN_NOTIFY_NEW_USERS=true
ADMIN_NOTIFY_STO_APPLICATIONS=true
ADMIN_NOTIFY_SECURITY_EVENTS=true
ADMIN_NOTIFY_SYSTEM_ERRORS=true
```

## Admin API

Dashboard:

- `GET /api/admin/dashboard`

Notifications:

- `GET /api/admin/notifications`
- `POST /api/admin/notifications/{id}/read`
- `POST /api/admin/notifications/read-all`
- `POST /api/admin/notifications/retry`
- `POST /api/admin/notifications/{id}/dismiss`

Data Explorer:

- `GET /api/admin/data/sources`
- `POST /api/admin/data/query`
- `PATCH /api/admin/data/{source}/{id}`
- `DELETE /api/admin/data/{source}/{id}`
- `POST /api/admin/data/export`

Users:

- `GET /api/admin/users`
- `GET /api/admin/users/{id}`
- `GET /api/admin/users/{id}/activity`
- `POST /api/admin/users/{id}/note`
- `POST /api/admin/users/{id}/block`
- `POST /api/admin/users/{id}/unblock`

СТО:

- `GET /api/admin/sto`
- `GET /api/admin/sto/{id}`
- `GET /api/admin/sto-applications`
- `POST /api/admin/sto-applications/{id}/approve`
- `POST /api/admin/sto-applications/{id}/reject`
- `POST /api/admin/sto-applications/{id}/request-changes`
- `POST /api/admin/sto/{id}/suspend`
- `POST /api/admin/sto/{id}/unsuspend`

Audit and exports:

- `GET /api/admin/audit-log`
- `GET /api/admin/exports`
- `GET /api/admin/exports/{id}`

## Data Explorer

Data Explorer работает только по whitelist источников и полей. Произвольный SQL из UI не принимается.

Источники:

- `users`
- `vehicles`
- `fuel_entries`
- `service_entries`
- `expense_entries`
- `sto_profiles`
- `sto_applications`
- `sto_employees`
- `vehicle_sto_links`
- `appointments`
- `work_orders`
- `work_order_items`
- `work_order_products`
- `reviews`
- `notifications`
- `admin_notifications`
- `audit_logs`
- `imports_exports`

Поддержаны фильтры по дате, статусу, пользователю, Telegram ID, авто, СТО, городу, роли, категории, сумме, ошибкам и текстовому поиску. Каждый запрос ограничен `limit` до 500 строк и пишет audit log.

Редактирование и удаление из Data Explorer:

- доступно только `admin` и `super_admin`;
- работает только по whitelist полей, который возвращает `GET /api/admin/data/sources`;
- требует `reason` минимум 5 символов;
- пишет `AuditLog` с old/new values;
- для пользователей, СТО, заявок, записей и уведомлений используется soft-delete/status change;
- hard-delete разрешен только для ограниченных журналов записей, где это явно включено;
- удаление автомобиля требует `super_admin`.

## Privacy

По умолчанию маскируются Telegram ID, VIN, госномер, телефон и регистрационные данные СТО.

Полный просмотр sensitive data:

- доступен только `admin` и `super_admin`;
- требует `reason`;
- пишет audit log;
- не раскрывает bot token, env, internal token, secret fields.

`analyst` видит только обезличенные или замаскированные персональные данные.

## Модерация СТО

Очередь заявок доступна в `/admin.html?section=sto-applications`.

Действия:

- approve;
- reject with reason;
- request changes with reason;
- suspend;
- unsuspend.

При изменении статуса создаются audit log, admin notification и уведомление владельцу СТО.

## Bot Commands

Админские команды бота:

- `/admin`
- `/admin_stats`
- `/admin_users`
- `/admin_sto`
- `/admin_pending_sto`
- `/admin_alerts`

API дополнительно проверяет роль пользователя, поэтому команда не дает доступа без admin-role в БД.

## Deploy Reports

Для временного rsync-деплоя есть `scripts/rsync_deploy.sh`. Скрипт:

- запускает локальные `ruff` и `pytest`;
- отправляет Telegram progress/failure/success отчеты;
- делает remote code backup без `.env`;
- синхронизирует код через `rsync`;
- собирает Docker images;
- применяет Alembic migrations;
- поднимает `api` и `bot`;
- проверяет `/health`, `/ready`, `/metrics`, `/admin.html`, `/sto.html`, `/work_order.html`.

Утилита `scripts/send_telegram_report.py` берет получателей из `ADMIN_NOTIFICATION_CHAT_ID`, `ADMIN_TELEGRAM_IDS` и, если env пустой, из пользователей БД с ролями `admin`, `super_admin`, `moderator`, `support`.

## Load Check

Быстрая проверка одновременных соединений:

```bash
python scripts/load_check.py --base-url http://127.0.0.1:8000 --requests 200 --concurrency 25
```

Скрипт проверяет `/health`, `/ready`, `/`, `/admin.html`, `/sto.html`, считает RPS, avg/p95/max latency и завершится с ошибкой при 5xx или сетевых сбоях.