feat(generator): добавлен артефакт стартовой истории

- Зачем: - чистый стенд должен восстанавливать стартовую историю без повторной генерации. - Что: - добавлены export/import артефакта через Kafka и compact-топики. - добавлена manifest-aware сверка ClickHouse и защита от смешения state. - добавлен runbook использования стартовой истории. - Проверка: - uv run --with-requirements generator/requirements.txt pytest generator/tests -q. - bash -n scripts/check_startup_history_manifest.sh scripts/export_startup_history_artifact.sh scripts/import_startup_history_artifact.sh. - git diff --check.
2026-07-04 18:23:54 +03:00
parent ee4c9f5857
commit 3c38465d89
16 changed files with 1746 additions and 177 deletions
@@ -0,0 +1,91 @@
+# 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`.