clickstream-ch-kafka-superset-demo/.scratch/handoffs/20260705-2212-generator-cross-review-fixes.md

Handoff: fixes after generator cross-line review

Дата: 2026-07-05 22:12. Жанр: handoff по ADR-0003 после coordinator-loop 15 -> 16 -> 17 -> 18.

Что закрыто

• 15: граница миров после обновления, clean/reset и host-запусков. Коммиты: 080d5ae, 108053b.
• 16: свежий стенд и generator_control без неявных ручных шагов. Коммиты: 27947ce, 9804d0b.
• 17: доверенные проверки startup-history и Superset. Коммиты: 00c97eb, 6731349.
• 18: курс 00/01/05 проходит по startup-history на чистом стенде. Коммиты: 77e4fb6, 6d64f39.
• Follow-up 19: отдельная задача на единые make test и make lint. Коммит: 2778eae.
• Финальный review fix: документация больше не советует обычный make generated-history-check после backfill-only пути. Коммит: 8e1c733.
• Issue 19 закрыта после внешнего Claude review: единые make test и make lint, подключение корневых контрактных тестов и усиление проверок startup-history. Коммит: 9b0b063.

Ключевые стыки реализации

• generator/src/clickstream_generator/stand_clean.py — общий guard чистого стенда для Airflow и host-путей.
• scripts/assert_stand_clean.sh — host-проверка перед backfill/import/continue.
• airflow/dags/generator_control_dag.py — pause-check etl_pipeline до мутирующих веток.
• scripts/check_generated_analytics.sh — manifest boundary, fail-closed live seam, непустой ODS и fail-closed проверка DM-витрин.
• scripts/run_generated_history_runtime_check.sh — bounded runtime gate для daily-wave + live seam.
• scripts/run_generator.sh — reset теперь проходит clean-stand guard до запуска live-генератора.
• Makefile — make test, make lint, contract-test; обычный pytest-вывод тихий, подробность можно включить через PYTEST_ARGS.
• generator/src/clickstream_generator/state.py — любая версия state не 3.0 даёт громкий UnsupportedStateVersionError; from_dict_safe больше не глотает ошибку старой/неизвестной версии.
• generator/src/clickstream_generator/airflow_control.py — target_dag_trigger_error() покрывает три ветки pause-check без импорта Airflow.
• superset/create_dashboard.py — sync ограничен чартами целевого dashboard.
• docs/course/lessons/00_kafka_intro.md, docs/course/lessons/01_kafka_to_clickhouse.md, docs/course/lessons/05_monitoring.md — курс согласован с startup-history, no-live default и consumer lag.

Проверки

• Issue 15: make generator-test, docker compose config --quiet, py_compile, bash -n.
• Issue 16: make generator-test, docker compose config --quiet, py_compile, make clean, make up, make ddl.
• Issue 17: Docker target tests, make generator-test, py_compile, bash -n, make generated-history-runtime-check.
• Issue 18: doc rg, git diff --check, make generated-history-analytics, make up.
• Issue 19 / commit 9b0b063: make contract-test — 16 passed; make generator-test — 190 passed; make lint — passed; make test — 190 generator tests, 16 contract tests, docker compose config --quiet.
• Финальный chain review Gibbs: initial CHANGES_REQUESTED, narrow rerun APPROVED.

Происхождение ревью

• 15: gate; task reviewer Ptolemy high, code reviewer Linnaeus high; оба rerun APPROVED.
• 16: code reviewer Laplace high; primary review found paused-DAG order bug, later reruns APPROVED.
• 17: code reviewer Bacon high; found Superset ownership and live-seam defaults; bounded runtime gate rerun APPROVED.
• 18: docs/code reviewer Hume high; found Prometheus scrape-count drift; rerun APPROVED.
• Финал: chain reviewer Gibbs xhigh; found docs drift around generated-history-check; rerun APPROVED.
• После 9b0b063: внешний Claude review подтвердил закрытие всех девяти находок и дал APPROVED. Reviewer не перезапускал Docker-проверки сам, но сверил код, тесты и документы; фактические прогоны были выполнены координатором.

Отклонения процесса

• Локальный uv run ... pytest у координатора падал до pytest из-за snap-confine / cap_dac_override. Для координаторского gate целевые тесты запускались через Docker-образ generator:test. Это вынесено в issue 19.
• Первичный runtime gate issue 17 через полный daily-wave был остановлен: прогон был активным, но слишком долгим для коммит-гейта. После этого добавлен bounded make generated-history-runtime-check.
• Несколько стендовых проверок чистили Docker volumes. Это ожидаемо для issue 16-18 и зафиксировано в журнале.

Что вручную проверить дальше

• Чистый ручной путь через Airflow UI: make up, make ddl или ddl_init, airflow dags unpause etl_pipeline, затем generator_control backfill.
• Backfill-only путь: make generated-history-analytics, затем CHECK_LIVE_SEAM=0 make generated-history-check.
• Стык backfill/live: make generated-history-runtime-check.
• Superset: после готового DM открыть dashboard и сверить, что чарты созданы и Top Countries by Events читается.
• Kafka UI: в уроке 00 должны быть понятны четыре data-топика и служебные generator_state, generator_startup_history_manifest, generator_batch_history.

Suggested skills

• triage — если продолжать issue 13: он всё ещё needs-triage.
• brainstorm-with-docs — если перед issue 13 нужно заново согласовать модель доливки истории от слепка.
• coordinator-loop — только после перевода issue 13 в ready-for-agent.
• code-review — для внешнего прохода по коммитам после ручной проверки.

Открытые риски

• Ручная HITL-проверка после 9b0b063 ещё не выполнена пользователем.
• Issue 13 остаётся needs-triage: доливка истории от слепка должна опираться на закрытые инварианты 15 и 17.