# Runbook: стартовая история стенда

Этот runbook нужен, чтобы один раз создать стартовую историю генератора, сохранить
её в файл и быстро восстановить на чистом стенде.

За устройством генератора см. [`generator/README.md`](../../generator/README.md)
и [спеку модельного времени](../specs/2026-06-14-generator-model-time-and-startup-history.md).

## Что дёшево

- Перезапуск без очистки volumes: Kafka хранит `generator_state` и manifest.
- Live-продолжение после импорта: генератор стартует с `T_end`, если настройки
  совпадают.
- Восстановление чистого стенда из готового файла: события повторно пишутся в
  Kafka, ClickHouse наполняется штатным путём.

## Что требует нового артефакта

- Другая длительность истории или другой профиль запуска.
- Другой `GEN_SEED`, `GEN_MODEL_T0`, часовой пояс, скорость или настройки
  генерации.
- Осознанный новый мир после несовместимого state: сначала сбросьте state через
  `GEN_STATE_RESET=true` или чистые volumes.

## Профили запуска

Основной способ — глагол плюс профиль:

| Профиль | Для чего | Длительность |
|---------|----------|--------------|
| `ci` | Быстрая проверка и CI | `6h` |
| `daily-wave` | История с видимой суточной волной | `2d` |

Длительность можно переопределить через `GEN_HISTORY_DURATION`, например `2d`.
Команда сама считает `GEN_MODEL_T_END` от `GEN_MODEL_T0`.

## Экспорт

По умолчанию создаётся быстрый 6-часовой артефакт:

```bash
make startup-history-export
```

Файл по умолчанию: `/tmp/clickstream-startup-history.json`.

История на 2 суток с суточной волной:

```bash
ARTIFACT=/tmp/clickstream-startup-history-2d.json \
PROFILE=daily-wave \
make startup-history-export
```

Команда делает чистый backfill и пишет в файл один связный набор: события Kafka,
state и manifest.

## Импорт на чистый стенд

```bash
make clean
docker compose up -d clickhouse kafka
make ddl

ARTIFACT=/tmp/clickstream-startup-history.json make startup-history-import

sleep 10
make transform
ARTIFACT=/tmp/clickstream-startup-history.json make startup-history-check
make generated-history-check
```

Импорт не пишет напрямую в ClickHouse. Он воспроизводит события и служебные
compact-топики в Kafka. ClickHouse читает данные через свои Kafka-таблицы и
Materialized View, затем batch строит ODS, DDS и DM.

Если артефакт создан не профилем `ci`, импорт запускайте с тем же профилем:

```bash
PROFILE=daily-wave ARTIFACT=/tmp/clickstream-startup-history-2d.json \
make startup-history-import
```

`make startup-history-check` сверяет контрольные числа DM-витрины с manifest
артефакта: события, визиты, пользователей и диапазон `event_timestamp`. Если
data-топики Kafka уже непустые, импорт остановится до публикации событий.

В текущем стеке `kafka-python` не даёт транзакционный producer для нескольких
топиков. Поэтому импорт остаётся clean-stand операцией: при ошибке записи он
удаляет import-топики Kafka, чтобы повторный импорт не дописал дубли. Если
ClickHouse уже успел прочитать частичные сообщения, очистите стенд через
`make clean` и повторите импорт.

## Live-продолжение

После импорта запускайте live с тем же профилем, что был в артефакте:

```bash
PROFILE=ci make generator-continue
```

Если читаемый state есть, но настройки не совпадают, генератор падает с перечнем
полей. Это защита от смешения разных миров. Для намеренного нового мира
используйте `make generator-reset` или `make clean`.

Старые переменные `GEN_RUN_MODE`, `GEN_STATE_RESET` и `GEN_MODEL_T_END` остаются
низкоуровневым способом для отладки и прямого `docker compose run`.