PROD.2026/Lotty

Files

T

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

repository map

zavoz

2026-02-24 17:53:14 +03:00

5.7 KiB

Raw Blame History

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 Выбор стека

Базовый стек:

docker compose -f compose.yaml up -d

Полный стек (с observability):

docker compose -f compose.prod.yaml --profile observability up -d

3.2 Проверка, что сервисы поднялись

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):

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):

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 Просмотр логов

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-подтверждение:

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-зависимости):

cd src/backend
just --list
just test
just test-coverage
just show-coverage
just lint
just format

Точечные наборы:

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:

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

uv run python manage.py test apps.notifications.tests.test_notifications api.v1.notifications.tests.test_notifications_api

FX: Learnings

uv run python manage.py test apps.learnings.tests.test_learnings api.v1.learnings.tests.test_learnings_api

FX: Conflicts

uv run python manage.py test apps.conflicts.tests.test_conflicts api.v1.conflicts.tests.test_conflicts_api

Объединённый прогон:

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. Остановка и очистка