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.

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

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

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

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/{id}/dismiss

Data Explorer:

• GET /api/admin/data/sources
• POST /api/admin/data/query
• 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.

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 в БД.