docs(): added RUNBOOK, compliance matrix, ADR, refactored C4 and

repository map zavoz
2026-02-24 13:17:24 +03:00
parent 7bf3ccee5c
commit 740fd2d7bd
18 changed files with 542 additions and 10 deletions
@@ -0,0 +1,204 @@
+# Runbook
+
+Этот runbook задаёт основной сценарий проверки по критериям `B1..B10` и выбранным `FX`.
+
+## 1. Что проверяем
+
+Сквозной поток:
+- `decide` -> `events` -> `report`;
+- lifecycle/review/guardrails;
+- observability (`/health`, `/ready`, `/metrics`);
+- инженерная дисциплина (tests, lint, format);
+- выбранные FX: notifications, learnings, conflicts.
+
+Артефакты:
+- `compliance-matrix.md`
+- `ADR/*`
+- `MAP.md`
+- `assets/plantuml/raw/c4-context.puml`
+- `assets/plantuml/raw/c4-container.puml`
+- `assets/plantuml/raw/c4-component-critical-path.puml`
+
+## 2. Предусловия
+
+### 2.1 Основной сценарий (по умолчанию): Docker Compose
+
+Нужно:
+- Docker
+- Docker Compose
+
+Файлы:
+- `compose.yaml` - базовый стек
+- `compose.prod.yaml` - базовый стек + observability
+- Детали по compose-конфигурации: `README.md` -> `Setup with docker compose`.
+
+Порты по умолчанию (см. `.env.template`):
+- reverse proxy: `80`
+- backend direct: `14609`
+- static direct: `14610`
+
+### 2.2 Дополнительный локальный сценарий (для тестов/линтинга)
+
+Нужно:
+- Python `>=3.13,<3.15`
+- `uv`
+- `just`
+
+Рабочая директория:
+- `cd src/backend`
+
+## 3. Основной сценарий запуска (Docker Compose)
+
+### 3.1 Выбор стека
+
+Базовый стек:
+```bash
+docker compose -f compose.yaml up -d
+```
+
+Полный стек (с observability):
+```bash
+docker compose -f compose.prod.yaml --profile observability up -d
+```
+
+### 3.2 Проверка, что сервисы поднялись
+
+```bash
+docker compose -f compose.yaml ps
+# или
+docker compose -f compose.prod.yaml --profile observability ps
+```
+
+Ожидаем `running/healthy` для `postgresql`, `valkey`, `backend`, `backend-celery-worker`, `backend-celery-beat`.
+
+### 3.3 Runtime sanity-check
+
+Через reverse proxy (`80`):
+```bash
+curl -i http://127.0.0.1/health
+curl -i http://127.0.0.1/ready
+curl -s http://127.0.0.1/metrics | head -n 40
+```
+
+Альтернатива напрямую в backend (`14609`):
+```bash
+curl -i http://127.0.0.1:14609/health
+curl -i http://127.0.0.1:14609/ready
+curl -s http://127.0.0.1:14609/metrics | head -n 40
+```
+
+### 3.4 Просмотр логов
+
+```bash
+docker compose -f compose.yaml logs -f backend backend-celery-worker backend-celery-beat
+# или
+docker compose -f compose.prod.yaml --profile observability logs -f backend backend-celery-worker backend-celery-beat
+```
+
+## 4. Проверка критериев B1..B10
+
+### B1. Запуск и воспроизводимость
+
+Compose runtime-подтверждение:
+```bash
+docker compose -f compose.yaml up -d
+docker compose -f compose.yaml ps
+curl -i http://127.0.0.1/health
+curl -i http://127.0.0.1/ready
+```
+
+Показываем:
+- сервисы запускаются без ручных скрытых шагов;
+- backend жив и готов после зависимостей.
+
+### B2-B6, B8, B10. Функциональность, отчёты, тестирование и дисциплина
+
+Эти проверки выполняются локально из `src/backend` (dev-зависимости):
+```bash
+cd src/backend
+just --list
+just test
+just test-coverage
+just show-coverage
+just lint
+just format
+```
+
+Точечные наборы:
+```bash
+cd src/backend
+uv run python manage.py test apps.decision.tests.test_decide
+uv run python manage.py test apps.events.tests.test_services tests.integration.test_events
+uv run python manage.py test apps.reports.tests.test_reports apps.guardrails.tests.test_guardrails
+uv run python manage.py test apps.reviews.tests.test_reviews_policy apps.experiments.tests.test_services
+uv run python manage.py test tests.integration.test_negative tests.integration.test_happy_path tests.integration.test_api_contract
+```
+
+### B7. Архитектурные артефакты
+
+Проверяем:
+- `compliance-matrix.md`
+- `ADR/README.md`
+- `ADR/04-decisions.md`
+- `MAP.md`
+- `assets/plantuml/raw/c4-context.puml`
+- `assets/plantuml/raw/c4-container.puml`
+- `assets/plantuml/raw/c4-component-critical-path.puml`
+
+### B9. Эксплуатационная готовность и наблюдаемость
+
+Runtime через compose:
+```bash
+curl -i http://127.0.0.1/health
+curl -i http://127.0.0.1/ready
+curl -s http://127.0.0.1/metrics | head -n 40
+```
+
+## 5. Проверка выбранных допфич (FX)
+
+Локально из `src/backend`:
+
+FX: Notifications
+```bash
+uv run python manage.py test apps.notifications.tests.test_notifications api.v1.notifications.tests.test_notifications_api
+```
+
+FX: Learnings
+```bash
+uv run python manage.py test apps.learnings.tests.test_learnings api.v1.learnings.tests.test_learnings_api
+```
+
+FX: Conflicts
+```bash
+uv run python manage.py test apps.conflicts.tests.test_conflicts api.v1.conflicts.tests.test_conflicts_api
+```
+
+Объединённый прогон:
+```bash
+uv run python manage.py test \
+  apps.notifications.tests.test_notifications \
+  apps.learnings.tests.test_learnings \
+  apps.conflicts.tests.test_conflicts \
+  api.v1.notifications.tests.test_notifications_api \
+  api.v1.learnings.tests.test_learnings_api \
+  api.v1.conflicts.tests.test_conflicts_api
+```
+
+## 6. Остановка и очистка
+
+Базовый стек:
+```bash
+docker compose -f compose.yaml down
+```
+
+Полный стек:
+```bash
+docker compose -f compose.prod.yaml --profile observability down
+```
+
+С удалением томов:
+```bash
+docker compose -f compose.yaml down -v
+# или
+docker compose -f compose.prod.yaml --profile observability down -v
+```