docs(generator): зафиксирован контракт модельного времени
- Зачем: - нужно закрепить принятое человеком HITL-решение до кодовых задач 02-06. - Что: - добавлен рабочий контракт настроек, хода часов, state, манифеста и ClickHouse-проверки. - выбран один живой ход часов через фиксированный модельный шаг без отдельной матрицы драйверов. - уточнена граница стартовой истории как [T0, T_end) и закрыт чек-лист issue 01. - Проверка: - git diff --cached --check.
This commit is contained in:
@@ -12,9 +12,9 @@
|
||||
[`06-state-v2-and-restart`](../../.scratch/feature-data-generator/issues/06-state-v2-and-restart.md)
|
||||
(сохранение состояния построено на настенных часах).
|
||||
|
||||
Уровень документа — **модель и правила**, как в мат-спеке. Код, имена настроек,
|
||||
формат конфигурации и сам способ управления ходом часов — за исполнителем, в
|
||||
рамках правил этой спеки (как условились в ADR-0005).
|
||||
Уровень документа — **модель и правила**, как в мат-спеке. Раздел «Рабочий
|
||||
контракт реализации» ниже фиксирует внешний интерфейс для задач 02–06. Внутренние
|
||||
классы, функции и разбиение кода остаются за исполнителем.
|
||||
|
||||
## Проблема
|
||||
|
||||
@@ -65,18 +65,144 @@ ADR-0005 решил отвязать время генератора от реа
|
||||
- **Не описываем здесь перестройку процесса** на новый сид (загрузка
|
||||
`kafka_load_dag`, витрины/Superset, уроки) — это решено в ADR-0006 и
|
||||
проектируется отдельно. Эта спека — только про сам генератор.
|
||||
- **Не фиксируем** имена настроек, формат конфигурации и сам алгоритм — это за
|
||||
исполнителем.
|
||||
- **Не фиксируем** внутренние имена классов и функций — это за исполнителем.
|
||||
- **Не добавляем** новые типы событий и инкрементальную загрузку ETL.
|
||||
|
||||
## Модель
|
||||
|
||||
### Рабочий контракт реализации
|
||||
|
||||
Этот раздел — источник истины для задач 02–06. Если кодовая задача меняет любое
|
||||
имя, формат state, манифест или правило проверки, сначала обновляется этот
|
||||
контракт.
|
||||
|
||||
#### Настройки
|
||||
|
||||
- `GEN_MODEL_T0` — стартовая модельная точка `T0`. Формат: ISO 8601 с часовым
|
||||
поясом, например `2026-01-01T00:00:00+00:00`. Внутри генератора метка
|
||||
нормализуется к UTC.
|
||||
- `GEN_MODEL_T_END` — граница стартовой истории `T_end`. Формат такой же, как у
|
||||
`GEN_MODEL_T0`. Обязательна только для режима `backfill`.
|
||||
- `GEN_MODEL_TIMEZONE` — часовой пояс модельных часов для дневного коэффициента.
|
||||
Формат: имя IANA, например `UTC` или `Europe/Moscow`. Значение по умолчанию —
|
||||
`UTC`.
|
||||
- `GEN_MODEL_TIME_SPEED` — скорость `K`: сколько модельных секунд проходит за
|
||||
одну настенную секунду. Формат: положительное число, по умолчанию `1`.
|
||||
- `GEN_RUN_MODE` — режим запуска: `live` или `backfill`. Значение по умолчанию —
|
||||
`live`.
|
||||
- `GEN_SEED`, `GEN_TICK_SECONDS` и остальные настройки генерации остаются частью
|
||||
контракта повторяемости. Если они отличаются, артефакт стартовой истории
|
||||
считается другим.
|
||||
|
||||
#### Ход часов
|
||||
|
||||
В живом режиме модельное время идёт фиксированным шагом. На чистом старте оно
|
||||
равно `GEN_MODEL_T0`. После каждого успешного тика оно сдвигается на
|
||||
`GEN_TICK_SECONDS * GEN_MODEL_TIME_SPEED`. Событийный бюджет считается по этой
|
||||
модельной длительности, а не по тому, сколько процесс реально спал.
|
||||
|
||||
При одинаковых `GEN_SEED`, `GEN_MODEL_T0`, `GEN_MODEL_TIME_SPEED`, настройках
|
||||
генерации и числе успешных тиков живой поток повторяется точно. Это выбранный
|
||||
путь для текущей цепочки: он ближе к учебной цели и не добавляет новую публичную
|
||||
матрицу режимов поверх ADR-0005.
|
||||
|
||||
`backfill` не спит и не измеряет настенные интервалы. Генератор детерминированно
|
||||
проматывает модельное время от `GEN_MODEL_T0` до `GEN_MODEL_T_END`. Артефакт
|
||||
повторяется точно при тех же настройках и чистом состоянии.
|
||||
|
||||
Измеренный настенный интервал между тиками не входит в текущий контракт живого
|
||||
режима. Если он понадобится позже, это отдельное изменение спеки или ADR, потому
|
||||
что оно меняет уровень повторяемости стенда.
|
||||
|
||||
#### Граница `T_end`
|
||||
|
||||
Стартовая история покрывает полуоткрытый отрезок `[T0, T_end)`: в неё попадают
|
||||
события с `event_timestamp >= T0` и `event_timestamp < T_end`. Слепок состояния
|
||||
сохраняется на модельной границе `T_end`.
|
||||
|
||||
Живое продолжение начинается из этого слепка с модельной точки `T_end`. Событие,
|
||||
которое запланировано ровно на `T_end`, не входит в стартовую историю и может
|
||||
быть выпущено первым живым тиком. Так на стыке нет дублей и дыр.
|
||||
|
||||
#### Модельные и настенные метки
|
||||
|
||||
Модельными считаются:
|
||||
|
||||
- `event_timestamp` во всех событиях;
|
||||
- метки внутри визитов и популяции: начало визита, запланированные смещения,
|
||||
`last_finished_at`;
|
||||
- `GEN_MODEL_T0`, `GEN_MODEL_T_END`, точка возобновления и метка слепка state.
|
||||
|
||||
Настенными остаются операционные метки: время записи логов, метрики здоровья,
|
||||
длительность тика, история отправки пачек, время сохранения state в Kafka и
|
||||
служебная метка `generated_at` в манифесте. Они помогают обслуживать сервис, но
|
||||
не должны менять `event_timestamp` и бизнес-логику визитов.
|
||||
|
||||
#### Восстановление после сбоя
|
||||
|
||||
Следующая версия state должна хранить связку:
|
||||
|
||||
- `model_timestamp` — модельная точка последнего сохранённого состояния;
|
||||
- `wall_timestamp` — настенная UTC-метка, когда это состояние было сохранено;
|
||||
- `model_time_speed`, `model_timezone` и `model_t0`.
|
||||
|
||||
При восстановлении живого режима после сбоя модельная точка считается так:
|
||||
|
||||
```text
|
||||
resume_model_at =
|
||||
state.model_timestamp
|
||||
+ max(0, wall_now_utc - state.wall_timestamp) * state.model_time_speed
|
||||
```
|
||||
|
||||
Для восстановления из стартовой истории эта формула не применяется:
|
||||
`resume_model_at = manifest.model_t_end`. Иначе долгий простой между созданием
|
||||
артефакта и запуском стенда искусственно оборвёт активные визиты.
|
||||
|
||||
Короткий или долгий простой считается только по модельному времени. При большом
|
||||
`GEN_MODEL_TIME_SPEED` короткая настенная пауза может стать долгой модельной
|
||||
паузой, и тогда просроченные активные визиты закрываются.
|
||||
|
||||
#### Манифест стартовой истории
|
||||
|
||||
Стартовая история состоит из трёх частей: события, слепок состояния и манифест.
|
||||
Манифест хранится как JSON и минимум содержит:
|
||||
|
||||
- `manifest_version`;
|
||||
- `generated_at` — настенная UTC-метка создания артефакта;
|
||||
- `gen_seed`;
|
||||
- `model_t0`, `model_t_end`, `model_timezone`;
|
||||
- `run_mode = "backfill"`;
|
||||
- настройки генерации, влияющие на поток;
|
||||
- `state_version` и ссылку на файл или запись слепка состояния;
|
||||
- контрольные числа по каждому топику: количество строк, минимум и максимум
|
||||
`event_timestamp`, контрольная сумма;
|
||||
- итоговые контрольные числа для проверки в ClickHouse: события, визиты,
|
||||
пользователи и диапазон модельного времени.
|
||||
|
||||
Нельзя смешивать события, state и манифест от разных `GEN_SEED`, `T0`, `T_end`
|
||||
или настроек генерации. Такое смешивание считается ошибкой запуска.
|
||||
|
||||
#### Повторяемая проверка в ClickHouse
|
||||
|
||||
Для этой цепочки выбираем чистый прогон, а не идемпотентную дозаливку. Перед
|
||||
повторной проверкой нужно сбросить:
|
||||
|
||||
- таблицы ClickHouse в слоях STG, ODS, DDS и DM, куда попадают события стенда;
|
||||
- Kafka-топики данных: `browser_events`, `location_events`, `device_events`,
|
||||
`geo_events`;
|
||||
- состояние генератора: compact topic `generator_state` или явный сброс
|
||||
состояния при старте, если он гарантированно не читает старую запись.
|
||||
|
||||
После такого сброса один и тот же артефакт стартовой истории должен давать те же
|
||||
контрольные числа в ClickHouse. Если проверка запускается без чистки, это уже
|
||||
другой сценарий и его нужно описывать отдельно.
|
||||
|
||||
### Точка отсчёта и скорость хода часов
|
||||
|
||||
У генератора своя точка отсчёта времени — **стартовая модельная точка `T0`**
|
||||
(задаётся в настройках). В метку события (`event_timestamp`) пишется это
|
||||
внутреннее время. Скорость, с которой оно идёт относительно реальных часов,
|
||||
переключается (в ADR-0005 — «драйвер часов»):
|
||||
задаётся режимами из ADR-0005:
|
||||
|
||||
- **×1** — как реальное время;
|
||||
- **×K** — в `K` раз быстрее;
|
||||
@@ -86,16 +212,15 @@ ADR-0005 решил отвязать время генератора от реа
|
||||
### Повторяемость
|
||||
|
||||
При одном и том же зерне `GEN_SEED`, одной и той же `T0` и одной скорости
|
||||
генератор каждый раз даёт **один и тот же поток**. Это убирает прежнюю оговорку
|
||||
мат-спеки «запуск в другой час даёт другой поток»: дневной коэффициент
|
||||
(день/ночь) теперь считается по внутреннему времени от `T0`, а не по реальным
|
||||
часам. Так раздел «Воспроизводимость» мат-спеки приводится в соответствие с
|
||||
модельным временем.
|
||||
генератор каждый раз даёт **один и тот же поток** в `backfill` и в живом режиме
|
||||
при одинаковом числе успешных тиков. Дневной коэффициент считается по модельному
|
||||
времени в `GEN_MODEL_TIMEZONE`, а не по реальным часам. Так раздел
|
||||
«Воспроизводимость» мат-спеки приводится в соответствие с модельным временем.
|
||||
|
||||
### Заливка прошлого и стартовая история
|
||||
|
||||
«Промотать» прошлое — значит прогнать время без пауз от `T0` до момента `T_end` и
|
||||
сгенерировать события этого отрезка. На выходе — события за `[T0, T_end]` и
|
||||
сгенерировать события этого отрезка. На выходе — события за `[T0, T_end)` и
|
||||
**слепок состояния** генератора на момент `T_end`.
|
||||
|
||||
События плюс слепок и есть **стартовая история** («стартовый сид» или «новый сид» —
|
||||
|
||||
Reference in New Issue
Block a user