PROD.2026/Lotty
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Lotty/RUNBOOK.md
T
ITQ d3731e78df chore(): final fixes before deadline 
- added images of notification feature working
- added seed data script
- race condition fix for notifications worker
- small improvements
2026-02-24 23:22:31 +03:00

8.8 KiB
Raw Permalink 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

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

3.5 Seed демо-данных через HTTP API

Скрипт создаёт следующие сущности:

  • test flags;
  • experiments + variants + lifecycle до running;
  • event types (exposure, click);
  • metrics (ctr, exposure_count, click_count) и привязку к эксперименту;
  • telegram notification channel + rules;
  • smtp notification channel + rules (опционально);
  • conflict domain с включёнными экспериментами;
  • два learning (для color/copy), чтобы проверить похожие;
  • guardrail (pause) c порогом, который не срабатывает сразу;
  • subjects + decide + события (show+click, show-only, click-only, out-of-order).

Команда:

BACKEND_BASE_URL='http://127.0.0.1' \
TG_BOT_TOKEN='6196898691:AAGbCxOf7-iXWKkKeOr9GrgHKcw6G7Ou1zU' \
TG_CHAT_ID='826812483' \
./infrastructure/http/seed-demo-data.sh

Команда c SMTP:

BACKEND_BASE_URL='http://127.0.0.1' \
TG_BOT_TOKEN='6196898691:AAGbCxOf7-iXWKkKeOr9GrgHKcw6G7Ou1zU' \
TG_CHAT_ID='826812483' \
SMTP_ENABLED=true \
SMTP_RECIPIENT='itq.dev@ya.ru' \
SMTP_FROM_EMAIL='mikrotik@itqdev.xyz' \
SMTP_HOST='smtp.office365.com' \
SMTP_PORT=587 \
SMTP_USERNAME='mikrotik@itqdev.xyz' \
SMTP_PASSWORD='5x9NqfIO4tVMg0B' \
SMTP_USE_TLS=true \
SMTP_USE_SSL=false \
SMTP_TIMEOUT=15 \
./infrastructure/http/seed-demo-data.sh

Что получаем:

  • скрипт печатает ключевые ID прямо в stdout;
  • артефакты в artifacts/http-seed/<RUN_ID>/;
  • сводка в artifacts/http-seed/<RUN_ID>/summary.json.

3.6 Что проверяем в Swagger (localhost/api/v1/docs)

  1. Открыть http://127.0.0.1/api/v1/docs.
  2. Получить токен через POST /api/v1/auth/login (admin/experimenter/approver).
  3. Нажать Authorize и вставить Bearer <access_token>.
  4. Проверить GET /api/v1/reports/{experiment_id} для experiment_color_id из seed-вывода:
  • по вариантам есть exposures, click_count, exposure_count, ctr.
  1. Проверить POST /api/v1/experiments/{experiment_id}/guardrails/check:
  • triggered=0.
  1. Проверить GET /api/v1/conflicts/domains/{domain_id}/experiments:
  • видно оба running эксперимента в домене.
  1. Проверить POST /api/v1/decide для color_flag_key:
  • reason=experiment_assigned.
  1. Проверить POST /api/v1/decide для copy_flag_key тем же subject:
  • reason=domain_conflict.
  1. Проверить GET /api/v1/notification-channels, GET /api/v1/notification-rules, GET /api/v1/notification-logs:
  • есть telegram channel/rules и, если SMTP_ENABLED=true, smtp channel/rules.
  1. Проверить GET /api/v1/learnings:
  • есть как минимум 2 seeded learning.
  1. Проверить GET /api/v1/experiments/{experiment_id}/similar-learnings для experiment_color_id:
  • ответ непустой;
  • в выдаче есть learning_copy_id и similarity_score.

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

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

docker compose -f compose.yaml down

Полный стек:

docker compose -f compose.prod.yaml --profile observability down

С удалением томов:

docker compose -f compose.yaml down -v
# или
docker compose -f compose.prod.yaml --profile observability down -v
Reference in New Issue View Git Blame Copy Permalink