drivers_bot/ADMIN.md

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:

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

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

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 или сетевых сбоях.