202 lines
7.9 KiB
Markdown
202 lines
7.9 KiB
Markdown
# 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.
|
||
|
||
Поддержанные события:
|
||
|
||
- новый пользователь;
|
||
- первое авто пользователя;
|
||
- первая запись пользователя;
|
||
- новая заявка СТО;
|
||
- обновление документов или повторная отправка заявки СТО;
|
||
- изменение статуса заявки СТО;
|
||
- одобрение, блокировка и разблокировка СТО;
|
||
- новая запись в СТО, отмена записи СТО;
|
||
- создание, завершение и отклонение заказ-наряда;
|
||
- запрос и решение коррекции заказ-наряда;
|
||
- низкая оценка СТО;
|
||
- OCR/upload/rate-limit события;
|
||
- security/system события через общий admin notification service.
|
||
|
||
Idempotency key защищает от дублей. Telegram-сообщение содержит кнопку открытия соответствующего раздела админки.
|
||
|
||
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`
|
||
- `ocr_results`
|
||
- `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 или сетевых сбоях.
|