Задокументирован модуль Metrics и вынесен сбор метрик в сервис

Author: Toksi86

docs/modules/metrics.md

@@ -1,3 +1,97 @@
 # Metrics
 
-TODO
+## Назначение
+
+Metrics отвечает за внутренний admin-only endpoint с базовыми счетчиками
+сервиса.
+
+Модуль нужен для быстрой технической сводки: сколько в системе пользователей,
+ролевых профилей, проектов, вакансий и сколько пользователей сейчас считаются
+online через websocket-чаты.
+
+## Статус модуля
+
+Модуль рабочий и подключен в корень API через `GET /`.
+
+Endpoint доступен только staff-пользователям. Для anonymous и обычных
+authenticated пользователей доступ закрыт.
+
+## Основные возможности
+
+- подсчет общего количества пользователей;
+- подсчет количества ролевых профилей пользователей;
+- подсчет количества проектов;
+- подсчет количества вакансий;
+- подсчет текущих online-пользователей по cache-ключу websocket-чата.
+
+## Архитектура
+
+- `metrics/views.py` - HTTP endpoint метрик.
+- `metrics/services.py` - сбор response payload.
+- `metrics/urls.py` - route модуля.
+- `metrics/tests/` - regression-тесты и helpers модуля.
+
+## API
+
+- `GET /` - получить внутренние метрики сервиса.
+
+Response содержит поля:
+
+- `total_CustomUser_count` - количество пользователей;
+- `total_Expert_count` - количество экспертных профилей;
+- `total_Investor_count` - количество профилей инвесторов;
+- `total_Member_count` - количество профилей участников;
+- `total_Mentor_count` - количество профилей менторов;
+- `total_Project_count` - количество проектов;
+- `total_Vacancy_count` - количество вакансий;
+- `current_online_users` - количество пользователей online по данным cache.
+
+## Основные сценарии
+
+### Staff открывает внутреннюю сводку
+
+Staff-пользователь отправляет `GET /` и получает текущие счетчики.
+
+Счетчики `total_*_count` считаются через `objects.count()` соответствующих
+моделей.
+
+### Подсчет online-пользователей
+
+`current_online_users` считается по cache-ключу `online_users`.
+
+Этот ключ наполняется модулем `chats`: при подключении пользователя к
+websocket-чату пользователь добавляется в set online-пользователей, при
+отключении удаляется.
+
+## Связи с другими модулями
+
+- `users` - счетчики пользователей и ролевых профилей.
+- `projects` - счетчик проектов.
+- `vacancy` - счетчик вакансий.
+- `chats` - источник данных для `current_online_users`.
+- `core` - cache helpers для online-ключей.
+
+## Ограничения и риски
+
+- Endpoint подключен к корню API: `GET /`. Это текущий контракт, но он
+  неочевиден для отдельного модуля метрик.
+- `current_online_users` показывает только пользователей, которые считаются
+  online через websocket-чаты. Пользователь, который делает только HTTP-запросы,
+  в этот счетчик не попадет.
+- Online-счетчик зависит от cache. После очистки cache значение будет `0`, пока
+  пользователи снова не подключатся к websocket.
+- Поля response имеют технические имена моделей и сохранены для совместимости.
+
+## Тесты
+
+Текущие тесты лежат в `metrics/tests/`.
+
+Проверяется:
+
+- anonymous пользователь не получает доступ к метрикам;
+- обычный authenticated пользователь не получает доступ к метрикам;
+- staff-пользователь получает payload метрик;
+- service считает пользователей, ролевые профили, проекты, вакансии и
+  online-пользователей;
+- пустой online-cache возвращает `current_online_users = 0`;
+- helper подсчета модели сохраняет уже собранный payload.

metrics/services.py

@@ -0,0 +1,32 @@
+from django.contrib.auth import get_user_model
+from django.core.cache import cache
+
+from core.utils import get_users_online_cache_key
+from projects.models import Project
+from users.models import Expert, Investor, Member, Mentor
+from vacancy.models import Vacancy
+
+User = get_user_model()
+
+METRIC_MODELS = (User, Expert, Investor, Member, Mentor, Project, Vacancy)
+
+
+def add_total_count(data: dict[str, int], model) -> dict[str, int]:
+    new_data = dict(data)
+    new_data[f"total_{model.__name__}_count"] = model.objects.count()
+    return new_data
+
+
+def get_current_online_users_count() -> int:
+    users_online_list_key = get_users_online_cache_key()
+    return len(cache.get_or_set(users_online_list_key, set()))
+
+
+def collect_metrics_payload() -> dict[str, int]:
+    data = {}
+
+    for model in METRIC_MODELS:
+        data = add_total_count(data, model)
+
+    data["current_online_users"] = get_current_online_users_count()
+    return data

metrics/tests.py metrics/tests/__init__.pymetrics/tests.py renamed to metrics/tests/__init__.py

@@ -0,0 +1,47 @@
+from datetime import date
+from uuid import uuid4
+
+from projects.models import Project
+from users.models import CustomUser
+from vacancy.models import Vacancy
+
+
+def unique_suffix() -> str:
+    return uuid4().hex[:8]
+
+
+def create_user(
+    *,
+    prefix: str = "metrics-user",
+    is_staff: bool = False,
+    is_superuser: bool = False,
+    user_type: int = CustomUser.MEMBER,
+) -> CustomUser:
+    return CustomUser.objects.create_user(
+        email=f"{prefix}-{unique_suffix()}@example.com",
+        password="test_password_123",
+        first_name="Иван",
+        last_name="Иванов",
+        birthday=date(2000, 1, 1),
+        user_type=user_type,
+        is_active=True,
+        is_staff=is_staff or is_superuser,
+        is_superuser=is_superuser,
+    )
+
+
+def create_project(*, leader: CustomUser | None = None) -> Project:
+    return Project.objects.create(
+        leader=leader or create_user(prefix="metrics-leader"),
+        name=f"Metrics project {unique_suffix()}",
+        description="Проект для метрик",
+        draft=False,
+    )
+
+
+def create_vacancy(*, project: Project | None = None) -> Vacancy:
+    return Vacancy.objects.create(
+        project=project or create_project(),
+        role=f"Metrics vacancy {unique_suffix()}",
+        description="Вакансия для метрик",
+    )

metrics/tests/helpers.py

@@ -0,0 +1,41 @@
+from django.core.cache import cache
+from django.test import TestCase
+from rest_framework.test import APIClient
+
+from core.utils import get_users_online_cache_key
+from metrics.tests.helpers import create_project, create_user, create_vacancy
+
+
+class MetricsAPITests(TestCase):
+    def setUp(self):
+        self.client = APIClient()
+        cache.clear()
+
+    def test_anonymous_user_cannot_access_metrics(self):
+        response = self.client.get("/")
+
+        self.assertEqual(response.status_code, 401)
+
+    def test_staff_user_can_get_metrics_payload(self):
+        staff = create_user(prefix="metrics-staff", is_staff=True)
+        user = create_user(prefix="metrics-regular")
+        project = create_project(leader=user)
+        create_vacancy(project=project)
+        cache.set(get_users_online_cache_key(), {staff.id, user.id})
+        self.client.force_authenticate(staff)
+
+        response = self.client.get("/")
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.data["total_CustomUser_count"], 2)
+        self.assertEqual(response.data["total_Project_count"], 1)
+        self.assertEqual(response.data["total_Vacancy_count"], 1)
+        self.assertEqual(response.data["current_online_users"], 2)
+
+    def test_non_staff_user_cannot_access_metrics(self):
+        user = create_user(prefix="metrics-regular")
+        self.client.force_authenticate(user)
+
+        response = self.client.get("/")
+
+        self.assertEqual(response.status_code, 403)

metrics/tests/test_metrics_api.py

@@ -0,0 +1,53 @@
+from django.core.cache import cache
+from django.test import TestCase
+
+from core.utils import get_users_online_cache_key
+from metrics.services import add_total_count, collect_metrics_payload
+from metrics.tests.helpers import create_project, create_user, create_vacancy
+from users.models import CustomUser
+
+
+class MetricsServiceTests(TestCase):
+    def setUp(self):
+        cache.clear()
+
+    def test_collect_metrics_payload_counts_supported_models_and_online_users(self):
+        online_user = create_user(
+            prefix="metrics-online",
+            user_type=CustomUser.ADMIN,
+        )
+        create_user(prefix="metrics-member")
+        create_user(prefix="metrics-mentor", user_type=CustomUser.MENTOR)
+        create_user(prefix="metrics-expert", user_type=CustomUser.EXPERT)
+        create_user(prefix="metrics-investor", user_type=CustomUser.INVESTOR)
+        leader = create_user(
+            prefix="metrics-leader",
+            user_type=CustomUser.ADMIN,
+        )
+        project = create_project(leader=leader)
+        create_vacancy(project=project)
+        cache.set(get_users_online_cache_key(), {online_user.id, leader.id})
+
+        payload = collect_metrics_payload()
+
+        self.assertEqual(payload["total_CustomUser_count"], 6)
+        self.assertEqual(payload["total_Member_count"], 1)
+        self.assertEqual(payload["total_Mentor_count"], 1)
+        self.assertEqual(payload["total_Expert_count"], 1)
+        self.assertEqual(payload["total_Investor_count"], 1)
+        self.assertEqual(payload["total_Project_count"], 1)
+        self.assertEqual(payload["total_Vacancy_count"], 1)
+        self.assertEqual(payload["current_online_users"], 2)
+
+    def test_collect_metrics_payload_returns_zero_online_users_for_empty_cache(self):
+        payload = collect_metrics_payload()
+
+        self.assertEqual(payload["current_online_users"], 0)
+
+    def test_add_total_count_preserves_existing_payload(self):
+        create_user(prefix="metrics-counted")
+
+        payload = add_total_count({"existing": 1}, CustomUser)
+
+        self.assertEqual(payload["existing"], 1)
+        self.assertEqual(payload["total_CustomUser_count"], 1)

metrics/tests/test_metrics_services.py

@@ -1,14 +1,8 @@
-from django.contrib.auth import get_user_model
-from core.utils import get_users_online_cache_key
-from projects.models import Project
 from rest_framework import permissions
 from rest_framework.response import Response
 from rest_framework.views import APIView
-from users.models import Expert, Investor, Member, Mentor
-from vacancy.models import Vacancy
-from django.core.cache import cache
 
-User = get_user_model()
+from metrics.services import collect_metrics_payload
 
 
 class MetricsView(APIView):
@@ -21,36 +15,4 @@ class MetricsView(APIView):
     permission_classes = [permissions.IsAdminUser]
 
     def get(self, request, format=None):
-        data = {}
-
-        models = [User, Expert, Investor, Member, Mentor, Project, Vacancy]
-
-        for model in models:
-            data = self._update_total_counts(data, model)
-
-        users_online_list_key = get_users_online_cache_key()
-        data["current_online_users"] = len(cache.get_or_set(users_online_list_key, set()))
-
-        return Response(data)
-
-    def _update_total_counts(self, data, model) -> dict[str, int]:
-        """
-        Updates the total counts of the given model.
-
-        Args:
-            data: dict with data.
-            model: model to get count from.
-
-        Returns:
-            dict: A dictionary with the updated data.
-
-        For example:
-            {
-                "total_Investor_count": 3,
-            }
-        """
-
-        new_data = dict(data)
-        new_data[f"total_{model.__name__}_count"] = model.objects.count()
-
-        return new_data
+        return Response(collect_metrics_payload())