# 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_MODEL_T_END`).
- Другой `GEN_SEED`, `GEN_MODEL_T0`, часовой пояс, скорость или настройки
  генерации.
- Осознанный новый мир после несовместимого state: сначала сбросьте state через
  `GEN_STATE_RESET=true` или чистые volumes.

## Экспорт

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

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

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

Суточная история:

```bash
ARTIFACT=/tmp/clickstream-startup-history-1d.json \
GEN_MODEL_T_END=2026-01-02T00:00:00+00:00 \
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.

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

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

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

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

```bash
GEN_STATE_RESET=false \
GEN_SEED=4242 \
GEN_MODEL_T0=2026-01-01T00:00:00+00:00 \
GEN_MODEL_T_END=2026-01-01T06:00:00+00:00 \
GEN_MODEL_TIMEZONE=UTC \
GEN_MODEL_TIME_SPEED=1 \
docker compose up -d generator
```

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