ddmitry/clickstream-ch-kafka-superset-demo

Files

T

ddadminandClaude Fable 5 85f076e205 docs(generator): проведён триаж бэклога фичи, задачи 01-06 закрыты

- Зачем:
  - follow-up задачи после ревью 2026-06-14 лежали без триажа; решения по
    артефакту, громкому отказу и интерфейсу приняты 2026-07-04 и должны
    попасть в задачи до передачи исполнителю.
- Что:
  - задачи 07 (миграция курса) и 08 (артефакт) поменяны местами — номера
    отражают порядок; ссылки обновлены.
  - 07 (артефакт + runbook) дооформлен: импорт строго через Kafka (напрямую
    в ClickHouse не пишет), громкий отказ при несовместимом state с правкой
    спеки, граница runbook «использование, не устройство»; ready-for-agent.
  - 08 дооформлен: устройство генератора вне пути менти, реальный объём
    (make data во всех уроках 00-05), демо вне скоупа; ready-for-agent.
  - новые задачи: 11 глаголы/длительность/профили (после 07, до 12),
    12 Airflow-DAG как пульт (приоритет поднят), 13 доливка (после 09).
  - задачи 01-06 переведены в done (стояли ошибочные ready-for-human);
    PRD фичи дополнен списком задач 7-13 с порядком и зависимостями.
- Проверка:
  - head -1 .scratch/generator-model-time-startup-history/issues/*.md;
    grep по старым именам файлов ничего не находит вне handoff.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-04 16:39:40 +03:00

10 KiB

Raw Blame History

Status: ready-for-agent

Портативный артефакт стартовой истории и runbook по стенду

Parent

.scratch/generator-model-time-startup-history/PRD.md

Why

Сейчас стартовая история персистится только в Kafka compact-топиках (generator_state, generator_startup_history_manifest) и в ClickHouse. Чистая пересборка стенда (make generated-history-analytics делает down -v) каждый раз заново генерирует backfill. Портативного файла-артефакта, который можно сгенерировать один раз и быстро восстановить на чистом стенде без запуска генератора, нет.

Из-за этого неудобно: мгновенно сбросить стенд, держать длинную стартовую историю (2+ суток, чтобы суточная волна повторялась на графике) без повторной генерации. Сейчас «дёшево» только live-возобновление из слепка и перезапуск без down -v; полный сброс требует регенерации.

Этот пункт работает на главную цель: если стенд поднимается одной командой и есть короткий runbook, генератор остаётся скрытой инфраструктурой и менти не нужно знать его устройство. Развилка курса «урок про генератор vs скрытая инфраструктура» уже закрыта в пользу скрытой инфраструктуры (docs/course/PRD.md §7, 2026-07-04) — эта задача обеспечивает решению опору.

What to build

Экспорт стартовой истории в портативный файл-артефакт: события (в формате сообщений топиков) плюс слепок состояния плюс манифест — один связный набор, чтобы не смешать GEN_SEED, T0, T_end и настройки генерации.
Импорт (решение 2026-07-04): воспроизвести события артефакта в Kafka-топики и вернуть слепок с манифестом в служебные compact-топики. Напрямую в ClickHouse импорт не пишет ничего: стенд наполняется штатным путём (Kafka engine + MV -> STG, батч-ETL -> витрины). Так не появляется обходного пути данных, каждый импорт заодно прогоняет весь пайплайн, а менти видит, как пустой стенд наполняется изучаемыми механизмами. Live продолжает с T_end.
Громкий отказ при несовместимом state (решение 2026-07-04, пересмотр правила спеки). Различать два случая. Нет состояния или оно повреждено -> чистый старт с предупреждением (как сейчас, оставить). Состояние есть и читается, но настройки несовместимы при GEN_STATE_RESET=false (оператор намерен продолжить) -> жёсткое падение с указанием разошедшихся полей (seed/T0/timezone/speed) и подсказкой выставить GEN_STATE_RESET=true, если новый мир нужен осознанно. Текущее тихое поведение — service.py:217-220. Правка идёт вместе с обновлением docs/specs/2026-06-14-generator-model-time-and-startup-history.md.
Runbook «как пользоваться стендом на генерации»: как сгенерировать, сохранить, восстановить, выбрать длительность стартовой истории; что дёшево (live-возобновление, перезапуск без чистки), а что требует регенерации.
Новые команды экспорта/импорта делать в стиле глаголов (явное действие одной командой), а не новыми комбинациями env-переменных.

Acceptance criteria

Есть команда экспорта: стартовая история -> портативный файл-артефакт (события + слепок + манифест) одним связным набором.
Есть команда импорта: на чистом стенде артефакт воспроизводится в Kafka (события + служебные compact-топики) без запуска генерации; напрямую в ClickHouse импорт не пишет. После штатного ETL контрольные числа в ClickHouse совпадают с манифестом и исходной генерацией.
После импорта live продолжает с T_end: без дублей на границе и без смешения миров.
Сохранено антисмешивание: импорт отвергает артефакт, несовместимый по манифесту (GEN_SEED, T0, T_end, настройки генерации, версия state).
Громкий отказ: живое читаемое состояние + несовместимые настройки при намерении продолжить -> падение с перечислением разошедшихся полей и подсказкой; нет состояния или повреждено -> чистый старт с предупреждением (как сейчас). Спека обновлена в этом же изменении.
Runbook описывает генерацию один раз, дешёвое восстановление, выбор длительности и то, что переживает перезапуск, а что требует регенерации.
Runbook — про использование, устройство генератора в нём не объясняется; за конструкцией он отсылает к generator/README.md и docs/specs/.
Документы запуска (README.md, docs/OPERATIONS.md, generator/README.md) ссылаются на runbook.

Notes

Опирается на спеку docs/specs/2026-06-14-generator-model-time-and-startup-history.md, разделы «Манифест стартовой истории» и «Повторяемая проверка в ClickHouse».
Спека уже упоминала будущий runbook «проверка генератора на стенде» — этот issue его и закрывает, расширяя до полного цикла «генерация — сохранение — восстановление».
Откуда экспорту брать события — решить при реализации и зафиксировать в спеке/runbook. Кандидаты: писать файл артефакта прямо при backfill (вторая копия рядом с публикацией в Kafka), вычитать топики событий (учесть retention) или выгрузить из STG (следить за точностью формата сообщений). Критерий выбора: артефакт должен байт в байт воспроизводить сообщения топиков.
Рекомендуемый режим ревью по coordinator-loop: гейт (state, сериализация, формат данных, правка спеки — всё из порогов риска).
Связано с 08-migrate-course-from-archive-seed.md: миграция уроков идёт после этой задачи и будет ссылаться на runbook отсюда (номера отражают порядок, переставлены 2026-07-04).

Идеи интерфейса — решения (2026-07-04)

Бывший раздел «на будущее, не решено» разобран с пользователем. Судьба идей:

Громкий отказ при несовместимом state — включён в эту задачу (см. What to build и критерии).
Глаголы / длительность / профили — отдельная задача 11-generator-launch-verbs-and-profiles.md, делать после этой и до DAG-пульта: чистый интерфейс «под капотом» делает DAG тонкой обёрткой с простыми и понятными параметрами.
Airflow-DAG как пульт генератора — приоритет поднят (пользователь, 2026-07-04): это будущий основной человеческий интерфейс стенда — «слишком сложно» лечится формой в веб-UI, а не только runbook'ом. Отдельная задача 12-generator-control-dag.md, делать после задачи 11.
Доливка прошлого кусочком — отдельная задача 13-backfill-top-up-from-snapshot.md, без приоритета.

Blocked by

.scratch/generator-model-time-startup-history/issues/05-startup-history-backfill-to-clickhouse.md
.scratch/generator-model-time-startup-history/issues/06-generated-history-as-analytics-source.md

10 KiB Raw Blame History Unescape Escape