docs: added repository map

2026-02-24 09:45:47 +03:00
parent 77218c53ca
commit 2829c4575f
1 changed files with 68 additions and 0 deletions
@@ -0,0 +1,68 @@
+# Карта репозитория
+
+## 1. Точки входа
+
+- Backend root: [src/backend](./src/backend)
+- Django settings: [src/backend/config/settings](./src/backend/config/settings)
+- URL root: [src/backend/config/urls.py](./src/backend/config/urls.py)
+- API wiring: [src/backend/api/urls.py](./src/backend/api/urls.py)
+- API v1 router: [src/backend/api/v1/router.py](./src/backend/api/v1/router.py)
+- Команды и проверки: [src/backend/justfile](./src/backend/justfile)
+
+## 2. Основные доменные модули ([src/backend/apps](./src/backend/apps))
+
+- [flags](./src/backend/apps/flags) - feature flags и типизация значений.
+- [experiments](./src/backend/apps/experiments) - жизненный цикл эксперимента, варианты.
+- [reviews](./src/backend/apps/reviews) - группы аппруверов, дефолтная политика апрува.
+- [decision](./src/backend/apps/decision) - логика выбора варианта для флага (детерминизм, таргетинг, лимиты участия, конфликт-домены).
+- [events](./src/backend/apps/events) - обработка эвентов: валидация, дедуп, атрибуция, pending events.
+- [metrics](./src/backend/apps/metrics) - каталог и правила вычисления метрик.
+- [reports](./src/backend/apps/reports) - отчёты по экспериментам в разрезе вариантов/периода.
+- [guardrails](./src/backend/apps/guardrails) - safety правила, триггеры, авто пауза/ролбек.
+- [conflicts](./src/backend/apps/conflicts) - домены конфликтов между экспериментами.
+- [notifications](./src/backend/apps/notifications) - enqueue/flush уведомлений по системным событиям.
+- [learnings](./src/backend/apps/learnings) - библиотека выводов/знаний по экспериментам.
+- [users](./src/backend/apps/users) - роли, auth, RBAC.
+- [core](./src/backend/apps/core) - базовые модели/общие вспомогательные элементы.
+
+## 3. API слой ([src/backend/api/v1](./src/backend/api/v1))
+
+- [src/backend/api/v1/decision/endpoints.py](./src/backend/api/v1/decision/endpoints.py) - `POST /api/v1/decide`
+- [src/backend/api/v1/events/endpoints.py](./src/backend/api/v1/events/endpoints.py) - `POST /api/v1/events`, CRUD event types
+- [src/backend/api/v1/reports/endpoints.py](./src/backend/api/v1/reports/endpoints.py) - `GET /api/v1/reports/{experiment_id}`
+- [src/backend/api/v1/guardrails/endpoints.py](./src/backend/api/v1/guardrails/endpoints.py) - check/list/create/update/delete guardrails
+- [src/backend/api/v1/experiments/endpoints.py](./src/backend/api/v1/experiments/endpoints.py) - lifecycle и CRUD экспериментов/вариантов
+- [src/backend/api/v1/reviews/endpoints.py](./src/backend/api/v1/reviews/endpoints.py) - review settings и approver groups
+- `flags`, `users`, `metrics`, `conflicts`, `notifications`, `learnings` - соответствующие доменные API
+
+## 4. Критичный поток
+
+1. Decide
+   - [src/backend/api/v1/decision/endpoints.py](./src/backend/api/v1/decision/endpoints.py)
+   - [src/backend/apps/decision/services.py](./src/backend/apps/decision/services.py)
+
+2. Events/Attribution
+   - [src/backend/api/v1/events/endpoints.py](./src/backend/api/v1/events/endpoints.py)
+   - [src/backend/apps/events/services.py](./src/backend/apps/events/services.py)
+   - [src/backend/apps/events/models.py](./src/backend/apps/events/models.py)
+
+3. Reports/Guardrails
+   - [src/backend/api/v1/reports/endpoints.py](./src/backend/api/v1/reports/endpoints.py)
+   - [src/backend/apps/reports/services.py](./src/backend/apps/reports/services.py)
+   - [src/backend/api/v1/guardrails/endpoints.py](./src/backend/api/v1/guardrails/endpoints.py)
+   - [src/backend/apps/guardrails/services.py](./src/backend/apps/guardrails/services.py)
+
+## 5. Интеграционные тесты
+
+- Happy path: [src/backend/tests/integration/test_happy_path.py](./src/backend/tests/integration/test_happy_path.py)
+- API contract flow: [src/backend/tests/integration/test_api_contract.py](./src/backend/tests/integration/test_api_contract.py)
+- Events edge-cases: [src/backend/tests/integration/test_events.py](./src/backend/tests/integration/test_events.py)
+- Guardrails e2e: [src/backend/tests/integration/test_guardrails.py](./src/backend/tests/integration/test_guardrails.py)
+- Негативные сценарии: [src/backend/tests/integration/test_negative.py](./src/backend/tests/integration/test_negative.py)
+
+## 6. Наблюдаемость и эксплуатация
+
+- Health/readiness endpoints: [src/backend/api/urls.py](./src/backend/api/urls.py)
+- Prometheus middleware/logging config: [src/backend/config/settings.py](./src/backend/config/settings.py)
+- Structured logs: [src/backend/config/settings.py](./src/backend/config/settings.py)
+- CI/CD config: [.gitlab-ci.yml](./.gitlab-ci.yml)