Lotty/RUNBOOK.md

# 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
```