admin_service¶

1. Назначение¶

admin_service предоставляет единый административный API для модерации и управления пользователями, товарами, заказами, отзывами, чатом и внутренними уведомлениями.

2. API-каталог¶

Базовый префикс: /api/admin/. Для большинства endpoint требуется is_staff.

Основные группы¶

/users/* — управление пользователями и ролями.
/products/* — модерация каталога.
/orders/* — админ-управление заказами и платежами.
/reviews/* — модерация отзывов.
/seller-status-requests/* — обработка заявок продавцов.
/notifications/* — работа с системными уведомлениями.
/chat/conversations/*, /chat/messages/* — админ-доступ к чату.
/dashboard/stats/, /dashboard/timeseries/, /dashboard/funnel/ — бизнес-аналитика (OLTP).
/dashboard/web/* — веб-аналитика (модели analytics_app, см. analytics_service).

Кастомные actions (выборка)¶

Метод	Путь	Назначение
POST	`/users/{id}/toggle_active/`	Активация/деактивация
POST	`/users/{id}/toggle_staff/`	Назначение staff
POST	`/users/{id}/update_role/`	Назначение роли
POST	`/products/{id}/update_status/`	Изменение статуса товара
POST	`/orders/{id}/update_status/`	Изменение статуса заказа
POST	`/orders/{id}/update_payment_status/`	Изменение статуса оплаты
POST	`/seller-status-requests/{id}/approve/`	Одобрение заявки
POST	`/seller-status-requests/{id}/reject/`	Отклонение заявки
POST	`/notifications/{id}/mark_read/`	Пометка уведомления
POST	`/notifications/mark_all_read/`	Пометка всех уведомлений
GET	`/notifications/unread_count/`	Счетчик непрочитанных

3. Локальные модели¶

SellerStatusRequest (pending|approved|rejected, reviewed metadata).
Notification (type, title, message, is_read, metadata, индексы).

4. Межсервисные зависимости¶

admin_service импортирует доменные модели из:

auth_service
user_service
product_service
order_service
review_service
chat_service
analytics_service (модели AnalyticsEvent, AnalyticsSession для dashboard web)

5. Бизнес-правила¶

Доступ только для staff пользователей.
update_role валидирует buyer|seller|both.
approve seller-заявки меняет роль и фиксирует reviewer метаданные.
Для payment_status=paid заказ может автоматически перейти в processing.

6. Риски¶

Сильная code-level и data-level связность с другими сервисами.
Нет детального разделения админ-ролей (moderator/admin/superadmin).
Недостаток транзакционной обертки в мульти-шаговых операциях.
Небезопасные дефолты settings для production.

7. Диаграмма workflow approve seller request¶

sequenceDiagram
  participant A as Admin
  participant S as admin_service
  participant U as user_profile_data
  participant N as notification_store

  A->>S: POST /seller-status-requests/{id}/approve
  S->>U: ensure user profile + role update
  S->>S: set request approved + reviewed_at/by
  S->>N: create notification
  S-->>A: 200 approved

8. Конфигурация¶

Внешний порт: 8006.
Основные env: DATABASE_URL, SECRET_KEY, DEBUG, PYTHONPATH.
В settings подключены внешние app через INSTALLED_APPS.

9. Дополнительная детализация внутренних функций (append-only)¶

9.1 Управление пользователями¶

`UserAdminViewSet.perform_create(self, serializer)`¶

Источник: admin_service/admin_app/views.py
Назначение: создать пользователя и синхронизировать ролевые профили.
Вход:
validated serializer data;
дополнительный role из request.data.
Выход:
созданный пользователь в стандартном DRF flow.
Side effects:
создание/обновление UserProfile;
создание SellerProfile/BuyerProfile в зависимости от роли;
best-effort создание уведомления.

`UserAdminViewSet.update_role(self, request, pk=None)`¶

Вход:
role в теле запроса (buyer|seller|both).
Выход:
200 с обновленным пользователем;
400 при невалидной роли;
500 при внутренних ошибках интеграции профилей.
Side effects:
изменение UserProfile.role;
создание недостающих role-specific профилей.

9.2 Управление товарами и заказами¶

`ProductAdminViewSet.update_status(self, request, pk=None)`¶

Источник: admin_service/admin_app/views.py
Вход:
status: draft|published|archived.
Выход:
200 с объектом товара;
400 при невалидном статусе.

`OrderAdminViewSet.update_status(self, request, pk=None)`¶

Вход:
status из Order.STATUS_CHOICES.
Выход:
200 с обновленным заказом;
400 при невалидном значении.
Примечание:
финальный список допустимых статусов берется из модели order-сервиса.

`OrderAdminViewSet.update_payment_status(self, request, pk=None)`¶

Вход:
payment_status из Order.PAYMENT_STATUS_CHOICES.
Выход:
200 с заказом;
400 при невалидном статусе оплаты.
Side effects:
бизнес-правило: при paid и pending статус заказа переводится в processing.

9.3 Модерация seller-заявок¶

`SellerStatusRequestViewSet.approve(self, request, pk=None)` / `reject(self, request, pk=None)`¶

Источник: admin_service/admin_app/views.py
Вход:
id заявки;
опционально notes.
Выход:
200 с данными обновленной заявки;
400/500 в ошибочных сценариях.
Side effects:
обновление статуса заявки и reviewer metadata;
при approve: изменение роли пользователя и создание seller-профиля;
отправка уведомления пользователю.

9.4 Веб-аналитика (dashboard web)¶

Staff-only endpoint'ы в admin_app/web_analytics_views.py (префикс /api/admin/dashboard/web/):

Метод	Путь	Назначение
GET	`/overview/`	KPI: визиты, посетители, просмотры, отказы, API success, JS-ошибки
GET	`/timeseries/`	Тренды visits, pageviews, errors, api_2xx/4xx/5xx
GET	`/pages/`	Топ страниц, входы/выходы
GET	`/sources/`	Referrers, UTM, каналы
GET	`/technology/`	Browser, OS, device
GET	`/errors/`	Client + API ошибки
GET	`/api/`	Статистика API по сервисам
GET	`/realtime/`	Активные сессии, последние события

Query: from, to (YYYY-MM-DD), interval=day|week (для timeseries).

UI: frontend/src/pages/AdminAnalytics.jsx + WebAnalyticsSection.jsx.

Регламент: Веб-аналитика.

9.5 Dashboard (бизнес) и уведомления¶

`dashboard_stats(request)`¶

Источник: admin_service/admin_app/views.py
Назначение: сбор агрегатов для dashboard.
Выход:
total/recent метрики и top-products.
Особенность:
часть подзапросов защищена локальными try/except, возможна частичная деградация без полного падения ответа.

`NotificationViewSet.mark_read`, `mark_all_read`, `unread_count`¶

Назначение: операции по состоянию прочитанности.
Side effects:
массовые update-операции по уведомлениям текущего админа.
Edge-cases:
при недоступной модели уведомлений часть endpoint может вернуть fallback (count=0) или 500 (в зависимости от метода).

9.6 Операционная CLI-логика¶

`create_admin` management command (`handle`, `get_password`)¶

Источник: admin_service/admin_app/management/commands/create_admin.py
Назначение: интерактивное создание staff/superuser из консоли.
Вход:
username/email/password через параметры или prompt.
Выход:
созданный пользователь либо аварийное завершение процесса.
Edge-cases:
sys.exit(1) при дубликатах, mismatch пароля или иных критичных ошибках.

10. Соответствие master-документации¶

Источник верхнего уровня: Master-документация проекта.

Контроль	Требование	Проверка	Артефакт
Governance sync	Изменения admin-процессов синхронизированы с governance/operations docs	ревью релизных и role-процедур	PR + docs diff
Permission model	Роли и доступы endpoint-ов документированы явно	проверка role/permission сценариев	API docs + QA checks
Contract stability	Админские действия согласованы с зависимыми сервисами	контрактная проверка смежных endpoint-ов	integration checks
Incident readiness	Критичные admin flow имеют операционные fallback	ревью инцидентных сценариев	operations docs