Веб-аналитика: эксплуатация и разработка¶

Единый регламент для разработчиков и контрибьюторов Konstructorium по сбору статистики посещений (уровень собственной Метрики, без сторонних SDK).

1. Краткий обзор¶

Слой	Компонент	Порт / путь
Запись событий	`analytics_service`	`:8008`, `POST /api/analytics/*`
Чтение отчётов	`admin_service`	`:8006`, `GET /api/admin/dashboard/web/*`
UI	`AdminAnalytics.jsx`	`/admin/analytics` (вкладки traffic … realtime)
Клиентский сбор	`webAnalyticsTracker.js` + баннер согласия	метрики — после `granted`; `user_error` — всегда

Подробная спецификация сервиса: analytics_service.

2. Обязательные правила для PR¶

Не отправлять события в analytics_service, пока пользователь не принял cookie (konstructorium_analytics_consent === granted).
Не подключать Google Analytics / Яндекс.Метрику / иные сторонние счётчики без обновления политики cookie и баннера.
Новые страницы SPA автоматически попадают в page_view через AnalyticsRouteTracker — отдельный код не нужен.
Новые вызовы API через api.js автоматически дают api_request — прямые fetch в обход axios в отчётах не видны.
При изменении полей событий — обновить serializer в analytics_service и при необходимости агрегаты в web_analytics_views.py.

Юридические требования: developer-guide.

3. localStorage и идентификаторы¶

Ключ	Значение
`konstructorium_analytics_consent`	`pending` \| `granted` \| `denied`
`konstructorium_analytics_visitor_id`	UUID посетителя
`konstructorium_analytics_session_id`	UUID сессии
`konstructorium_analytics_session_started_at`	timestamp для таймаута 30 мин

Новая сессия создаётся после 30 минут без активности (как в типичной веб-аналитике).

4. Что собирается¶

Категория	Примеры
Навигация	path, query keys (без значений), `page_leave` + duration
API	method, нормализованный path (`/api/users/:id`), status, latency, сервис
Ошибки	`client_error` (hash), `user_error` (incident_id, error_code, user_id)
Техника	browser, OS, device, screen bucket (из UA + viewport)
Источники	referrer host, UTM из URL
Зона	`is_admin_area` для `/admin/*`

Не собирается: сырой IP, полный stack trace в prod, значения query-параметров с PII.

5. Админ-панель: вкладки¶

В Аналитика (требуется is_staff):

Вкладка	API	Содержание
Трафик	`web/overview`, `web/timeseries`	KPI, визиты, API 2xx/4xx/5xx, ошибки
Страницы	`web/pages`	Топ URL, входы/выходы, CSV
Источники	`web/sources`	Referrers, UTM, каналы
Технологии	`web/technology`	Browser, OS, device
Ошибки	`web/errors`	JS + API ошибки, журнал `user_error` с `KON-*` и пользователем
API	`web/api`	По сервисам, медленные endpoint'ы
Онлайн	`web/realtime`	Активные сессии, лента (refresh 30 с)

Фильтры дат общие с бизнес-аналитикой (from, to, interval=day|week).

6. Запуск и проверка¶

Docker¶

docker compose -f docker-compose.services.yml up -d analytics_service admin_service frontend

Ручная проверка ingest¶

Открыть сайт, принять cookie в баннере.
DevTools → Network: POST /api/analytics/events/batch/ → 201.
Перейти на несколько страниц — в batch должны быть page_view.
Вызвать любой API (логин, каталог) — в batch появятся api_request.

Проверка админ-отчётов¶

Войти как staff → /admin/analytics → вкладка Трафик.
GET /api/admin/dashboard/web/overview/?from=YYYY-MM-DD&to=YYYY-MM-DD → 200.

Smoke-тесты¶

pytest tests/analytics_service/test_smoke.py
pytest tests/admin_service/test_smoke.py -k web

7. Прокси и production¶

Контур	Файл
Vite dev	`frontend/vite.config.js` → `:8008`
Frontend nginx (compose)	`frontend/nginx.conf` → `analytics_service:8000`
Edge nginx (prod)	Убедиться, что `/api/analytics/` проксируется на frontend или напрямую на `analytics_service`

Чеклист: ru-legal-production-checklist.

8. Retention и обслуживание¶

# В контейнере analytics_service
python manage.py purge_old_analytics_events
# или с переопределением
python manage.py purge_old_analytics_events --days 90

Рекомендуется cron на проде (раз в сутки).

9. Отладка типичных проблем¶

Симптом	Причина	Действие
Нет batch в Network	Consent не `granted`	Принять баннер или очистить `konstructorium_analytics_consent`
400 на batch	Невалидный JSON / пустой `events`	Проверить тело запроса
503 в админке web/*	`analytics_app` не в PYTHONPATH admin	Проверить volume/mount `analytics_service` в compose
Пустые графики	Нет данных за период	Сгенерировать трафик после consent
API не в отчётах	Вызов мимо axios	Перевести на `api.js` или server middleware (фаза 2)

10. Связь с `increment_views`¶

Счётчик product_service.increment_views для рекомендаций остаётся. Веб-аналитика дополнительно пишет page_view на ProductDetail — это нормально, цели разные.