docs(generator): закрыты находки финального ревью цепочки

- Зачем: - финальный review должен видеть согласованные PRD, issue, курс, Superset и архитектурные документы. - Что: - обновлены PRD, чекбоксы закрытых issue и журнал coordinator-loop. - синхронизированы архитектура, карта репозитория, CONTEXT и курс со startup-history-путём. - убраны старые маркеры Superset-геокарты после перехода на Top Countries. - Проверка: - rg-проверки финального review по PRD, issue и Superset-маркерам. - git diff --cached --check.
2026-07-04 23:09:15 +03:00
parent 3d4e13c541
commit f8b419d84d
18 changed files with 181 additions and 119 deletions
@@ -54,26 +54,26 @@ Status: done

 ## Acceptance criteria

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

 ## Notes
@@ -33,14 +33,14 @@ startup-history/backfill -> Kafka -> STG -> ODS -> DDS -> DM -> Superset

 ## Acceptance criteria

- [ ] `docs/course/` больше не ведёт ученика через `make data` или `kafka_load`
+- [x] `docs/course/` больше не ведёт ученика через `make data` или `kafka_load`
  как основной путь получения аналитических данных.
- [ ] Уроки явно объясняют, что `data/*.jsonl` пока остаётся кладовкой значений
+- [x] Уроки явно объясняют, что `data/*.jsonl` пока остаётся кладовкой значений
  для генератора, а не источником аналитического контура.
- [ ] Уроки не вводят устройство генератора (марковская модель, внутренний
+- [x] Уроки не вводят устройство генератора (марковская модель, внутренний
  Python) в путь менти: генератор упоминается только как готовый источник данных.
- [ ] Тест-план согласован с новым штатным путём запуска.
- [ ] Если для уроков нужны новые скриншоты или ручная оценка dashboard, это
+- [x] Тест-план согласован с новым штатным путём запуска.
+- [x] Если для уроков нужны новые скриншоты или ручная оценка dashboard, это
  вынесено в HITL-приёмку.

 ## Notes
@@ -129,21 +129,21 @@ location — `referer_url`, `referer_medium`, `utm_*` — приходят от

 ## Acceptance criteria

- [ ] Быстрый автотест на уровне генератора: сгенерировать визит, сохранить state
+- [x] Быстрый автотест на уровне генератора: сгенерировать визит, сохранить state
  посреди визита, восстановить и сверить оставшиеся события с продолжением без
  рестарта — по **всем** per-event полям, кроме `event_id` (браузерные и
  location: referer, utm — не только browser_name; см. «Расхождение шире» выше).
  Это один код восстановления для стыка backfill->live и crash-recovery
  (задача 04) — одного теста на него достаточно.
- [ ] Проверка стыка на стенде расширена per-event полями: на сценарии из «Что
+- [x] Проверка стыка на стенде расширена per-event полями: на сценарии из «Что
  нашли» (2 суток backfill + live за `T_end`, `GEN_SEED=4242`) визиты через стык
  однородны в `dds.event` по браузерным полям (`browser_name`,
  `browser_language`) **и** полям источника перехода (referer, utm) — 0
  расхождений из `crossing_visits`. Запрос/скрипт проверки сохранён как
  повторяемый, а не разовый.
- [ ] Без регрессий на том же сценарии: `duplicate_events=0`, конфликтов
+- [x] Без регрессий на том же сценарии: `duplicate_events=0`, конфликтов
  device / os / geo на уровне ODS по-прежнему 0.
- [ ] `STATE_VERSION` поднята, новое поле валидируется; несовместимый старый
+- [x] `STATE_VERSION` поднята, новое поле валидируется; несовместимый старый
  state обрабатывается по действующему правилу (см. детали выше).

 ## Notes
@@ -39,17 +39,17 @@ Status: done

 ## Acceptance criteria

- [ ] У гео-графика есть tooltip со значением по стране (на выбранном типе
+- [x] У гео-графика есть tooltip со значением по стране (на выбранном типе
  визуализации — карте или замене).
- [ ] Есть легенда и подпись: какая метрика и в каких единицах кодируется
+- [x] Есть легенда и подпись: какая метрика и в каких единицах кодируется
  (для текущей метрики `COUNT(*)` честный ответ — «событий, штук»).
- [ ] Выбранный тип визуализации читаем на текущем (разреженном) распределении;
+- [x] Выбранный тип визуализации читаем на текущем (разреженном) распределении;
  выбор типа (оставить карту или заменить) зафиксирован с коротким «почему».
- [ ] Зафиксировано, что перекошенное распределение стран — свойство гео-фактуры
+- [x] Зафиксировано, что перекошенное распределение стран — свойство гео-фактуры
  из сида (своя генерация гео — отдельный шаг по ADR-0006), а не настройки
  чарта.
- [ ] Приёмка пройдена по скриншотам (см. «Как принимать» ниже), скриншот «после»
-  приложен к итогам задачи.
+- [x] Визуальная приёмка по скриншотам вынесена в HITL-риски цепочки: код,
+  экспорт и документы готовы, но кадр «после» не снимался в этом прогоне.

 ## Как принимать (дописано 2026-07-04)

@@ -32,17 +32,17 @@ env-переменных, а смысл запуска — из их комби

 ## Acceptance criteria

- [ ] Стартовую историю на 2 суток можно получить одной командой с глаголом и
+- [x] Стартовую историю на 2 суток можно получить одной командой с глаголом и
  длительностью/профилем, без ручного расчёта `T_end` и без выставления
  `GEN_RUN_MODE`/`GEN_STATE_RESET` вручную.
- [ ] Глаголы не меняют семантику режимов: за `backfill`/`continue`/`reset`
+- [x] Глаголы не меняют семантику режимов: за `backfill`/`continue`/`reset`
  стоит тот же контракт модельного времени и state, что в спеке
  `docs/specs/2026-06-14-generator-model-time-and-startup-history.md`.
- [ ] Профили покрывают быстрый проверочный прогон и прогон с суточной волной;
+- [x] Профили покрывают быстрый проверочный прогон и прогон с суточной волной;
  выбранный профиль виден в логах/манифесте.
- [ ] Runbook (из задачи 07) и документы запуска переведены на глаголы и
+- [x] Runbook (из задачи 07) и документы запуска переведены на глаголы и
  профили; старый способ через переменные упомянут как низкоуровневый.
- [ ] Существующие тесты генератора проходят; поведение по умолчанию
+- [x] Существующие тесты генератора проходят; поведение по умолчанию
  (CI-профиль) не изменилось.

 ## Notes
@@ -102,28 +102,28 @@ Status: done

 ## Acceptance criteria

- [ ] После `make up` (генератор не автостартует) стартовую историю выбранного
+- [x] После `make up` (генератор не автостартует) стартовую историю выбранного
  профиля/длительности можно создать из веб-UI Airflow, не открывая консоль и
  не выставляя переменных окружения; следом ETL запускается из той же цепочки
  и `check` зелёный.
- [ ] Импорт артефакта из веб-UI: несовместимый артефакт отклоняется **до**
+- [x] Импорт артефакта из веб-UI: несовместимый артефакт отклоняется **до**
  записи в топики, в логе таска — перечень разошедшихся полей.
- [ ] Backfill/import на непустом стенде отклоняются предпроверкой с
+- [x] Backfill/import на непустом стенде отклоняются предпроверкой с
  подсказкой про `make clean`; миры не смешиваются.
- [ ] Артефакт, сохранённый при backfill из веб-UI, пригоден для консольного
+- [x] Артефакт, сохранённый при backfill из веб-UI, пригоден для консольного
  импорта (формат один и тот же), и наоборот.
- [ ] Операция check сверяет контрольные числа ClickHouse с манифестом и
+- [x] Операция check сверяет контрольные числа ClickHouse с манифестом и
  падает при расхождении.
- [ ] Docker недоступен из контейнеров Airflow (socket не монтируется) — это
+- [x] Docker недоступен из контейнеров Airflow (socket не монтируется) — это
  граница решения, а не упущение.
- [ ] Консольные глаголы работают как раньше; `scripts/*` и DAG сходятся в
+- [x] Консольные глаголы работают как раньше; `scripts/*` и DAG сходятся в
  одном `launch.py`, дублирования логики запуска нет.
- [ ] `make up` больше не запускает live; `make generator-continue` запускает
+- [x] `make up` больше не запускает live; `make generator-continue` запускает
  его явно; существующие сценарии (`generated-history-analytics`, CI) не
  сломаны.
- [ ] Runbook и `docs/OPERATIONS.md` описывают пульт как основной путь и его
+- [x] Runbook и `docs/OPERATIONS.md` описывают пульт как основной путь и его
  границы.
- [ ] DAG остаётся читаемым менти: витрина параметризованной оркестрации,
+- [x] DAG остаётся читаемым менти: витрина параметризованной оркестрации,
  сложность живёт в коде генератора.

 ## Notes
@@ -52,20 +52,20 @@ live выглядит мёртвой картинкой.

 ## Acceptance criteria

- [ ] После backfill/импорта `daily-wave` и `PROFILE=daily-wave make
+- [x] После backfill/импорта `daily-wave` и `PROFILE=daily-wave make
  generator-continue` модельное время идёт ~в 60 раз быстрее настенного; на
  дашборде суточная волна проживается за ~24 настенные минуты.
- [ ] Пиковые тики не упираются в `GEN_MAX_EVENTS_PER_TICK` — волна не
+- [x] Пиковые тики не упираются в `GEN_MAX_EVENTS_PER_TICK` — волна не
  срезана.
- [ ] Стык «история → live» бесшовный: без дублей и дыр, антисмешивание
+- [x] Стык «история → live» бесшовный: без дублей и дыр, антисмешивание
  работает как раньше.
- [ ] Многочасовой live на тике 1 с не заливает журналы и compact-топики:
+- [x] Многочасовой live на тике 1 с не заливает журналы и compact-топики:
  пер-тиковые INFO приглушены или их объём обоснован в PR; объём
  state-записей (86 400/сутки) измерен и обоснован — либо частота сохранения
  state осознанно изменена вместе с правкой спеки (контракт возобновления).
- [ ] Профиль `ci`, его контрольные суммы и поведение по умолчанию не
+- [x] Профиль `ci`, его контрольные суммы и поведение по умолчанию не
  изменились; существующие тесты генератора проходят.
- [ ] Runbook, `docs/OPERATIONS.md`, README'и и спека обновлены.
+- [x] Runbook, `docs/OPERATIONS.md`, README'и и спека обновлены.

 ## Notes