analytics_service¶

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

analytics_service собирает веб-аналитику первой стороны (first-party): просмотры страниц SPA, сессии, API-запросы с фронтенда, клиентские ошибки, согласие на cookie/аналитику.

Агрегаты для админ-панели (/admin/analytics, вкладки «Трафик», «Страницы», …) отдаёт admin_service — он читает те же таблицы через cross-import моделей analytics_app.

Связанные документы:

Веб-аналитика: эксплуатация и разработка
Руководство для разработчиков (согласие, ПДн)
admin_service: dashboard web API (раздел «Веб-аналитика»)

2. Порт и префикс¶

Параметр	Значение
Host-порт (dev)	`8008:8000`
API-префикс	`/api/analytics/`
Docker-сервис	`analytics_service`

3. API ingest (публичный)¶

Все ingest-endpoint'ы: AllowAny, rate limit (AnalyticsBatchThrottle), CSRF exempt (beacon/fetch без cookie).

Метод	Путь	Назначение
POST	`/api/analytics/events/batch/`	Пакет до `ANALYTICS_BATCH_MAX_EVENTS` (по умолчанию 20)
POST	`/api/analytics/consent/`	Запись `consent_granted` / `consent_denied`

Тело batch¶

{
  "visitor_id": "uuid",
  "session_id": "uuid",
  "consent_version": "1.0",
  "events": [
    {
      "event_type": "page_view",
      "path": "/products",
      "occurred_at": "2026-05-17T10:00:00Z",
      "is_admin_area": false
    }
  ]
}

Ответ 201: { "stored": <int>, "visitor_id": "<uuid>" }.

Типы событий (`event_type`)¶

Значение	Источник
`page_view`	SPA route change
`page_leave`	Смена route / `visibilitychange`
`click`	Элемент с `[data-analytics]`
`api_request`	Axios interceptors в `frontend/src/services/api.js`
`client_error`	`window.onerror`, `unhandledrejection`
`performance`	Navigation Timing (раз на сессию)
`consent_granted` / `consent_denied`	Баннер или API consent

4. Модель данных¶

`AnalyticsSession`¶

Агрегат визита: один session_id, обновляется при каждом ingest события.

Ключевые поля: visitor_id, user (FK, nullable), started_at, last_seen_at, duration_sec, entry_path, exit_path, page_views_count, is_bounce, UTM, referrer_host, device_type, browser, os_name, ip_hash (SHA-256, не сырой IP), locale, screen_class, is_admin_area.

`AnalyticsEvent`¶

Append-only сырые события. Индексы по occurred_at, event_type, path, session_id, api_service.

`AnalyticsDailyRollup`¶

Зарезервировано для фоновых rollup (MVP: агрегации в admin_service на лету).

5. Приватность и согласие¶

Правило	Реализация
Сбор только после согласия	`webAnalyticsTracker.js` проверяет `localStorage.konstructorium_analytics_consent === granted`
IP не хранится в открытом виде	`ANALYTICS_IP_HASH_SALT` + SHA-256 в `ingest.py`
Тексты ошибок	`error_message_hash`, не полный текст в БД
Срок хранения сырых событий	`ANALYTICS_EVENT_RETENTION_DAYS` (90), команда `purge_old_analytics_events`

Баннер: frontend/src/components/AnalyticsConsentBanner.jsx (см. frontend).

6. Диаграмма потока¶

sequenceDiagram
  participant U as Browser
  participant F as SPA_tracker
  participant A as analytics_service
  participant ADM as admin_service
  participant UI as AdminAnalytics

  U->>F: Accept cookies
  F->>A: POST /consent/ granted
  U->>F: Navigate /products
  F->>A: POST /events/batch page_view
  A->>A: AnalyticsEvent + AnalyticsSession upsert

  Note over ADM,UI: Staff only
  UI->>ADM: GET /api/admin/dashboard/web/overview/
  ADM->>ADM: ORM aggregate on analytics_app
  ADM-->>UI: KPI + charts data

7. Конфигурация (env)¶

Переменная	Назначение	По умолчанию
`DATABASE_URL`	PostgreSQL	—
`SECRET_KEY`	Django	—
`ANALYTICS_IP_HASH_SALT`	Соль для IP hash	`konstructorium-analytics-salt`
`ANALYTICS_BATCH_MAX_EVENTS`	Лимит batch	`20`
`ANALYTICS_EVENT_RETENTION_DAYS`	Retention purge	`90`
`ANALYTICS_THROTTLE_RATE`	Общий anon throttle	`120/min`
`ANALYTICS_BATCH_THROTTLE_RATE`	Throttle batch	`60/min`

Frontend:

Переменная	Назначение
`VITE_PRIVACY_POLICY_URL`	Ссылка в баннере (например `/legal/privacy`)

8. Локальная разработка¶

# В составе стека
docker compose -f docker-compose.services.yml up -d analytics_service

# Миграции
cd analytics_service && python manage.py migrate

# Purge старых событий
python manage.py purge_old_analytics_events

Vite proxy: /api/analytics → http://localhost:8008 (см. frontend/vite.config.js).

9. Тесты¶

pytest tests/analytics_service/test_smoke.py
cd frontend && npm test -- --run src/test/webAnalyticsTracker.test.js

10. Исходники (карта файлов)¶

Путь	Роль
`analytics_app/models.py`	Модели
`analytics_app/views.py`	Ingest API
`analytics_app/serializers.py`	Валидация batch/consent
`analytics_app/services/ingest.py`	Persist + session upsert
`analytics_app/management/commands/purge_old_analytics_events.py`	Retention
`admin_app/web_analytics_views.py`	Read API (в `admin_service`)

11. Ограничения MVP¶

Нет: вебвизора, heatmap, гео по городам, A/B. Есть: страницы, сессии, referrers, UTM, устройства, JS/API ошибки, realtime, CSV в админке.