Untitled

# Полный сценарий использования A/B Платформы (Walkthrough)

Этот документ описывает полный жизненный цикл работы с вашим API: от регистрации пользователей с разными ролями до заведения эксперимента, его аппрува, получения пользователем варианта (А или Б) и просмотра финальной аналитики.

---

## 🎭 Шаг 1: Настройка ролей (Администратор, Экспериментатор, Аппрувер)

Чтобы запустить эксперимент, нам нужны три человека:
1. **Экспериментатор** (Product Manager) — тот, кто придумывает гипотезу и настраивает эксперимент.
2. **Аппрувер** (Tech Lead / QA) — тот, кто проверяет эксперимент и дает "Добро" на его запуск.
3. **Администратор** — настраивает права в системе.

**1.1. Регистрация всех троих**
Отправляем POST-запросы на `/api/v1/auth/register`:
* `{"username": "admin", "password": "123", "role": "admin"}`
* `{"username": "pm_ivan", "password": "123", "role": "experimenter"}`
* `{"username": "qa_anna", "password": "123", "role": "approver"}`

**1.2. Авторизация**
Каждый отправляет POST на `/api/v1/auth/login` и сохраняет себе JWT-токен. Все дальнейшие запросы они будут отправлять с заголовком:
`Authorization: Bearer <их_токен>`

**1.3. Привязка аппрувера (Делает Администратор)**
Админ отправляет POST на `/api/v1/experimenter-configs/upsert`:
```json
{
  "experimenter_id": 2, // ID pm_ivan
  "min_approvals": 1,
  "approver_ids": [3] // ID qa_anna
}
```
*Теперь система знает, что эксперименты от Ивана должна проверять Анна.*

---

## 🛠 Шаг 2: Подготовка к эксперименту (Делает Экспериментатор)

Иван хочет проверить гипотезу: "Купят ли подписку чаще, если кнопка будет Красной, а не Синей".

**2.1. Создание Feature Flag (Флага фичи)**
Иван регистрирует новую "ручку управления" через POST `/api/v1/feature-flags`:
```json
{
  "key": "button_color",
  "default_value": "blue", // По умолчанию у всех старая синяя кнопка
  "description": "Цвет кнопки покупки подписки"
}
```

**2.2. Заведение Метрик**
Как мы поймем, что кнопка сработала лучше? Мы заводим два события:
* Просмотр экрана подписки (`view_paywall`)
* Успешная покупка (`purchase_success`)

Иван создает новую метрику через POST `/api/v1/metrics`:
```json
{
  "name": "Конверсия в покупку (CR)",
  "type": "conversion",
  "event_type_numerator": "purchase_success",
  "event_type_denominator": "view_paywall",
  "time_window_seconds": 86400, // Конверсия в течение 24 часов
  "is_higher_better": true
}
```
*Мы получаем ID этой метрики (пусть будет `metric_1`).*

---

## 🚀 Шаг 3: Создание и запуск эксперимента (Иван + Анна)

**3.1. Создание черновика эксперимента (DRAFT)**
Иван отправляет POST на `/api/v1/experiments/`:
```json
{
  "name": "Тест красной кнопки на пейволе",
  "feature_flag_id": 1, // Привязываем к нашему button_color
  "traffic_percentage": 50, // Эксперимент сработает только у половины пользователей
  "variants": [
    {"name": "Control", "value": "blue", "weight": 50, "is_control": true},
    {"name": "Test", "value": "red", "weight": 50, "is_control": false}
  ],
  "targeting_rules": [{"attribute": "country", "operator": "eq", "value": "RU"}], // Запускаем только в РФ
  "metric_ids": [1] // Отслеживаем созданную метрику
}
```

**3.2. Отправка на ревью**
Иван отправляет POST на `/api/v1/experiments/{id}/review` с командой `submit`. Статус эксперимента меняется на `IN_REVIEW`.

**3.3. Аппрув (Делает Анна)**
Анна (под своим токеном) проверяет настройки и отправляет POST на `/api/v1/experiments/{id}/review`:
```json
{
  "decision": "approved",
  "comment": "Выглядит ок, запускай"
}
```
*Статус эксперимента меняется на `APPROVED`.*

**3.4. Запуск (Делает Иван)**
Иван отправляет POST на `/api/v1/experiments/{id}/start`, статус меняется на `RUNNING`. Всё, эксперимент начался!

---

## 🎲 Шаг 4: Клиентское устройство (Decide API и Events API)

Теперь в приложение заходит реальный пользователь с телефона (без авторизации, просто с уникальным ID устройства `device_001`).

**4.1. Запрос цвета кнопки (Decide)**
Клиент (например, iOS-приложение) отправляет POST на `/api/v1/decide` БЕЗ всяких токенов:
```json
{
  "subject_id": "device_001",
  "feature_keys": ["button_color"],
  "user_context": {
    "country": "RU",  // Попадает под наши правила таргетинга!
    "os": "ios"
  }
}
```
**Платформа отвечает:**
```json
{
  "features": {
    "button_color": {
      "value": "red", // Клиенту выпал Тестовый вариант
      "source": "experiment",
      "experiment_id": 1,
      "variant_name": "Test",
      "decision_id": "123e4567-e89b-12d3..."
    }
  }
}
```
*На телефоне рисуется красная кнопка.*

**4.2. Пользователь видит экран (Событие 1)**
Телефон отправляет "сырые" события в нашу аналитику: POST `/api/v1/events`:
```json
{
  "event_type": "view_paywall",
  "subject_id": "device_001",
  "properties": {"screen": "main_paywall"}
}
```

**4.3. Пользователь покупает (Событие 2)**
Телефон отправляет еще один POST `/api/v1/events`:
```json
{
  "event_type": "purchase_success",
  "subject_id": "device_001",
  "properties": {"amount": 990}
}
```

*Система складирует события в ClickHouse/PostgreSQL. Благодаря тому что мы знаем, кто и в какой группе (`Decide`) произвел эти события (`Events`), система позже сможет их связать.*

---

## 📊 Шаг 5: Анализ результатов (Делает Иван через сутки)

**5.1. Получение отчета**
Иван заходит в платформу и дергает GET `/api/v1/reports/experiment/1`:
Платформа внутри себя (в модуле `infra/analytics/calculator.py`) джойнит таблицы `decisions` (кто был в какой группе) и `events` (кто что сделал). Высчитывает конверсии (CR - Conversion Rate).

Ответ:
```json
{
  "metrics": {
    "1": {
      "results": [
        {
          "variant_id": 1, // Control (Синие)
          "unique_subjects": 1000,
          "conversions": 100,
          "value": 0.1 // 10%
        },
        {
          "variant_id": 2, // Test (Красные)
          "unique_subjects": 1000,
          "conversions": 150,
          "value": 0.15 // 15%
        }
      ],
      "statistical_significance": true,
      "p_value": 0.04
    }
  }
}
```

**5.2. Остановка эксперимента с выводами**
Иван видит, что красная кнопка работает на 50% лучше и разница статистически значимая. 
Он отправляет POST `/api/v1/experiments/{id}/stop`:
```json
{
  "completion_mode": "rollout", // Покатить победителя на всех
  "winner_variant_id": 2, // Красная кнопка
  "learning": { // Сохраняем выводы для будущих команд
    "hypothesis": "Красная кнопка повысит CR",
    "result_summary": "CR вырос с 10% до 15%",
    "details": "Стат значимость достигнута за сутки. Красный цвет работает лучше на RU аудитории."
  }
}
```

### Конец цикла
Теперь, если любой другой клиент спросит `/api/v1/decide` для `button_color`, платформа посмотрит, что этот эксперимент "Раскатан" (`rollout`), и **всем** всегда будет отдавать `"red"` как новый дефолт. А в библиотеке знаний (`/api/v1/learnings`) навсегда сохранится запись об этом удачном эксперименте.