From 525bd8cabf8efc518218c429b6bea0b9c331d34a Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Sun, 5 Jul 2026 00:51:22 +0300 Subject: [PATCH] =?UTF-8?q?docs(issues):=20=D0=BE=D1=84=D0=BE=D1=80=D0=BC?= =?UTF-8?q?=D0=BB=D0=B5=D0=BD=D1=8B=20=D0=B7=D0=B0=D0=B4=D0=B0=D1=87=D0=B8?= =?UTF-8?q?=20=D0=BA=D1=80=D0=BE=D1=81=D1=81-=D1=80=D0=B5=D0=B2=D1=8C?= =?UTF-8?q?=D1=8E=20=D0=B3=D0=B5=D0=BD=D0=B5=D1=80=D0=B0=D1=82=D0=BE=D1=80?= =?UTF-8?q?=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - нужен готовый набор задач для закрытия находок кросс-линейного ревью. - Что: - добавлены issue 15-18 по границе миров, свежему стенду, проверкам и курсу. - обновлены навигация PRD и блокировка будущей доливки истории. - уточнены риски fallback, Superset sync и простоя daily-wave. - Проверка: - git diff --cached --check. --- .../PRD.md | 23 +++++++-- .../13-backfill-top-up-from-snapshot.md | 14 +++++- .../15-world-boundary-after-cross-review.md | 46 +++++++++++++++++ .../16-fresh-stand-generator-control.md | 50 +++++++++++++++++++ ...trusted-checks-startup-history-superset.md | 48 ++++++++++++++++++ .../18-course-clean-stand-startup-history.md | 50 +++++++++++++++++++ 6 files changed, 226 insertions(+), 5 deletions(-) create mode 100644 .scratch/generator-model-time-startup-history/issues/15-world-boundary-after-cross-review.md create mode 100644 .scratch/generator-model-time-startup-history/issues/16-fresh-stand-generator-control.md create mode 100644 .scratch/generator-model-time-startup-history/issues/17-trusted-checks-startup-history-superset.md create mode 100644 .scratch/generator-model-time-startup-history/issues/18-course-clean-stand-startup-history.md diff --git a/.scratch/generator-model-time-startup-history/PRD.md b/.scratch/generator-model-time-startup-history/PRD.md index 266f185..e962727 100644 --- a/.scratch/generator-model-time-startup-history/PRD.md +++ b/.scratch/generator-model-time-startup-history/PRD.md @@ -90,9 +90,21 @@ Status: Implemented Дальнейшая задача вне текущей очереди: -- После фикса 09: `issues/13-...` (доливка истории от слепка; без приоритета, - `needs-triage` — доливка тиражирует стыки восстановления, дооформлять после - фикса). +- `issues/13-...` — доливка истории от слепка; без приоритета, + `needs-triage`. После кросс-линейного ревью 2026-07-05 блокируется + задачами 15 и 17: доливка тиражирует стыки мира и должна опираться на + доверенную проверку фактической границы. + +Доработки по кросс-линейному ревью 2026-07-05: + +- `issues/15-world-boundary-after-cross-review.md` — граница миров после + обновления, сброса и консольных запусков. +- `issues/16-fresh-stand-generator-control.md` — свежий стенд и Airflow-пульт + без неявных ручных шагов. +- `issues/17-trusted-checks-startup-history-superset.md` — доверенные проверки + startup-history и Superset export. +- `issues/18-course-clean-stand-startup-history.md` — курс на чистом стенде по + startup-history. ```mermaid flowchart LR @@ -103,6 +115,11 @@ flowchart LR i14["14 быстрый профиль"] --> i08 i09["09 фикс стыка"] --> i13["13 доливка"] i10["10 гео-карта"] + i15["15 граница миров"] --> i18["18 курс на чистом стенде"] + i16["16 свежий стенд"] --> i18 + i17["17 доверенные проверки"] --> i18 + i15 --> i13 + i17 --> i13 ``` ## Контрольные точки diff --git a/.scratch/generator-model-time-startup-history/issues/13-backfill-top-up-from-snapshot.md b/.scratch/generator-model-time-startup-history/issues/13-backfill-top-up-from-snapshot.md index 1c9fee7..7bcc35b 100644 --- a/.scratch/generator-model-time-startup-history/issues/13-backfill-top-up-from-snapshot.md +++ b/.scratch/generator-model-time-startup-history/issues/13-backfill-top-up-from-snapshot.md @@ -30,8 +30,18 @@ Status: needs-triage `09-seam-browser-fixture-not-preserved.md`: доливка создаёт новые стыки, тот же механизм восстановления. - [ ] Манифест после доливки отражает новый `T_end'`; антисмешивание работает. +- [ ] До реализации доливки принято решение по fallback-ветке восстановления + визита: либо свойство донорского сида закреплено проверкой, либо длина визита + ограничена так, чтобы fallback не менял фактуру на стыке. ## Blocked by -- `09-seam-browser-fixture-not-preserved.md` — доливка тиражирует стыки - восстановления; сначала починить фактуру на стыке, иначе дефект размножится. +- `15-world-boundary-after-cross-review.md` — доливка продолжает мир от слепка; + сначала нужен закрытый инвариант «старый state и консольные пути не создают + второй мир». +- `17-trusted-checks-startup-history-superset.md` — доливка создаёт новые + стыки; сначала нужна доверенная проверка фактической границы по манифесту. + +Исторический контекст: `09-seam-browser-fixture-not-preserved.md` закрыла +фактуру визита на стыке восстановления, но кросс-линейное ревью 2026-07-05 +нашло более широкие риски вокруг границы мира и проверки стыка. diff --git a/.scratch/generator-model-time-startup-history/issues/15-world-boundary-after-cross-review.md b/.scratch/generator-model-time-startup-history/issues/15-world-boundary-after-cross-review.md new file mode 100644 index 0000000..0eecf77 --- /dev/null +++ b/.scratch/generator-model-time-startup-history/issues/15-world-boundary-after-cross-review.md @@ -0,0 +1,46 @@ +Status: ready-for-agent + +# Граница миров после кросс-ревью + +## Parent + +`.scratch/generator-model-time-startup-history/PRD.md` + +## What to build + +Закрыть семейство находок кросс-линейного ревью про «смешение миров»: после +обновления кода, сброса стенда или консольного запуска старое состояние и старый +live-генератор не должны тихо писать события в новый мир данных. + +Источник: `.scratch/handoffs/20260705-0002-cross-review-generator-chain.md`, +разделы `Issue 12/14` и `Issue 09`. + +Связанные старые issue: `09-seam-browser-fixture-not-preserved.md`, +`12-generator-control-dag.md`, частично `14-fast-teaching-profile.md`. + +## Acceptance criteria + +- [ ] Известная старая версия state при `GEN_STATE_RESET=false` даёт громкий + отказ с понятным сообщением, а не тихий чистый старт поверх существующей + истории. +- [ ] Сброс и остановка стенда убирают ручной live-генератор из compose-профиля; + он не переживает `down`/`clean` и не воскресает после перезагрузки хоста. +- [ ] Консольные пути backfill/import/continue используют ту же идею + предпроверки чистого стенда, что Airflow-пульт, но реализованы способом, + пригодным для запуска с хоста. +- [ ] Документация объясняет миграционный случай: почему старый state может + теперь дать громкий отказ и что делать оператору или менти. +- [ ] Есть проверка, которая доказывает каждый из трёх путей смешения миров: + старая версия state, compose-профиль live-генератора, консольный запуск на + грязном стенде. + +## Blocked by + +Нет — можно начинать сразу. + +## Notes + +- Рекомендуемый режим `coordinator-loop`: гейт. Worker `high`, ревью задачи + `high`, ревью кода `high`. +- Не чинить здесь ложнозелёные проверки и курс целиком: это отдельные задачи + 17 и 18. Здесь только граница миров и доказательства именно этой границы. diff --git a/.scratch/generator-model-time-startup-history/issues/16-fresh-stand-generator-control.md b/.scratch/generator-model-time-startup-history/issues/16-fresh-stand-generator-control.md new file mode 100644 index 0000000..57d8356 --- /dev/null +++ b/.scratch/generator-model-time-startup-history/issues/16-fresh-stand-generator-control.md @@ -0,0 +1,50 @@ +Status: ready-for-agent + +# Свежий стенд и Airflow-пульт без догадок + +## Parent + +`.scratch/generator-model-time-startup-history/PRD.md` + +## What to build + +Сделать так, чтобы человек на свежем клоне мог пройти быстрый старт до +`generator_control` без неявных шагов, сырых ошибок и зависаний Airflow. + +Источник: `.scratch/handoffs/20260705-0002-cross-review-generator-chain.md`, +разделы `Issue 12/14` и `Issue 08`. + +Связанные старые issue: `12-generator-control-dag.md`, +`14-fast-teaching-profile.md`. + +## Acceptance criteria + +- [ ] Quick start и курс явно называют `uv` и остальные обязательные + пререквизиты до первой команды, которая их требует. +- [ ] Быстрый старт на чистом стенде подготавливает DDL до проверок генератора; + отсутствие таблиц не падает сырым `UNKNOWN_TABLE`. +- [ ] После обновления репозитория Airflow получает новые зависимости и DAG-и + без ручных догадок: через пересборку, явную команду или ясно описанный шаг. +- [ ] `generator_control` не висит навсегда, если зависимый `etl_pipeline` + стоит на паузе: оператор получает понятный отказ или инструкцию до запуска + долгого ожидания. +- [ ] Решение по Airflow API, проверенное через Context7 для текущей версии, + зафиксировано в коде или документации кратко и рядом с местом выбора. +- [ ] Runbook предупреждает, что долгий простой `daily-wave` на скорости 60 + создаёт большую дыру в модельном времени, и советует reset или повторный + импорт стартовой истории. + +## Blocked by + +- `.scratch/generator-model-time-startup-history/issues/15-world-boundary-after-cross-review.md` + +## Notes + +- Рекомендуемый режим `coordinator-loop`: обычный issue, worker `medium`, ревью + кода `high`. Если правка уйдёт в устройство DAG-зависимостей шире + предпроверки паузы, эскалировать до гейта. +- Формальная зависимость от 15 нужна из-за общего участка предпроверки чистого + стенда: свежий стенд должен опираться на уже выбранный способ отказа и + диагностики грязного мира. +- Не включать сюда учебные тексты уроков 00/01/05, кроме пререквизитов и + quick start: основной проход курса закрывает задача 18. diff --git a/.scratch/generator-model-time-startup-history/issues/17-trusted-checks-startup-history-superset.md b/.scratch/generator-model-time-startup-history/issues/17-trusted-checks-startup-history-superset.md new file mode 100644 index 0000000..1a367c8 --- /dev/null +++ b/.scratch/generator-model-time-startup-history/issues/17-trusted-checks-startup-history-superset.md @@ -0,0 +1,48 @@ +Status: ready-for-agent + +# Проверки startup-history и Superset без ложного зелёного + +## Parent + +`.scratch/generator-model-time-startup-history/PRD.md` + +## What to build + +Сделать проверки доверенными: зелёный результат должен означать, что проверен +фактический стык стартовой истории и живого продолжения, а Superset export +соответствует ожидаемому контракту чарта. + +Источник: `.scratch/handoffs/20260705-0002-cross-review-generator-chain.md`, +разделы `Issue 09`, `Issue 10` и `Issue 08`. + +Связанные старые issue: `09-seam-browser-fixture-not-preserved.md`, +`10-dashboard-geo-map-readability.md`, частично `14-fast-teaching-profile.md`. + +## Acceptance criteria + +- [ ] Проверка startup-history берёт границу стыка из манифеста фактического + прогона, а не из значения окружения по умолчанию. +- [ ] ODS-часть проверки не проходит на пустом ODS: отсутствие строк считается + ошибкой проверки, а не успешным результатом. +- [ ] Профиль запуска доходит до проверки: сценарий с `daily-wave` проверяет + именно мир `daily-wave`, а не диапазон `ci`. +- [ ] Ожидание live-строк доказывает, что живое продолжение реально успело + записать данные; короткое ожидание не должно превращать проверку стыка в + пропущенную проверку. +- [ ] Тест Superset сравнивает полный существенный контракт `params` между + конфигурацией и export, а не только небольшой набор полей. +- [ ] Сортировка top countries задана явно по числу событий, чтобы порядок не + зависел от случайной формы ответа после pivot. +- [ ] Повторная синхронизация Superset не удаляет одноимённые чарты вне целевого + источника данных или dashboard; деструктивность sync задокументирована. + +## Blocked by + +Нет — можно начинать сразу. + +## Notes + +- Рекомендуемый режим `coordinator-loop`: обычный issue, worker `medium`, + ревью кода `high`. +- Не смешивать с правками курса: задача 18 должна пользоваться уже доверенными + проверками, но текст уроков не является частью этой задачи. diff --git a/.scratch/generator-model-time-startup-history/issues/18-course-clean-stand-startup-history.md b/.scratch/generator-model-time-startup-history/issues/18-course-clean-stand-startup-history.md new file mode 100644 index 0000000..5823913 --- /dev/null +++ b/.scratch/generator-model-time-startup-history/issues/18-course-clean-stand-startup-history.md @@ -0,0 +1,50 @@ +Status: ready-for-agent + +# Курс проходит по startup-history на чистом стенде + +## Parent + +`.scratch/generator-model-time-startup-history/PRD.md` + +## What to build + +Довести учебный путь до воспроизводимого прохода на чистом стенде: уроки должны +работать с `startup-history`, не опираться на архивный сид и не обещать live-поток +там, где он больше не запускается по умолчанию. + +Источник: `.scratch/handoffs/20260705-0002-cross-review-generator-chain.md`, +раздел `Issue 08`. + +Связанные старые issue: `08-migrate-course-from-archive-seed.md`, частично +`12-generator-control-dag.md` и `14-fast-teaching-profile.md`. + +## Acceptance criteria + +- [ ] Упражнение урока 01 с добавлением `kafka_msg_ts` воспроизводимо на стенде: + повторная заливка данных не сбрасывает схему, которую только что изменил + менти. +- [ ] Урок 00 объясняет служебные топики генератора настолько, чтобы список + топиков не выглядел как набор неожиданных артефактов. +- [ ] Уроки 00 и 05 не противоречат друг другу в описании видимости consumer lag; + утверждение проверено на текущем стенде. +- [ ] Урок мониторинга согласован с no-live default: либо явно запускает live, + либо не обещает, что алерт отсутствия сообщений будет тихим на здоровом + стенде без live. +- [ ] Операционная документация не ведёт учебный путь первым делом к архивному + `make data`; startup-history остаётся основным источником аналитики. +- [ ] Проход уроков 00, 01 и 05 на чистом стенде проверен командно или вынесен + в явный HITL-пункт с точной инструкцией, что должен подтвердить человек. + +## Blocked by + +- `.scratch/generator-model-time-startup-history/issues/15-world-boundary-after-cross-review.md` +- `.scratch/generator-model-time-startup-history/issues/16-fresh-stand-generator-control.md` +- `.scratch/generator-model-time-startup-history/issues/17-trusted-checks-startup-history-superset.md` + +## Notes + +- Рекомендуемый режим `coordinator-loop`: обычный issue, worker `medium`, ревью + кода и документов `high`. +- Если по ходу окажется, что упражнение 01 требует нового поддержанного режима + перезаливки, не прятать это в тексте урока: оформить как явное решение и + покрыть проверкой.