From 8e1c7330e19d310d23554fde1990a0a5aba6f252 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Sun, 5 Jul 2026 22:12:09 +0300 Subject: [PATCH] =?UTF-8?q?docs(generator):=20=D1=83=D1=82=D0=BE=D1=87?= =?UTF-8?q?=D0=BD=D0=B5=D0=BD=D1=8B=20=D0=BF=D1=80=D0=BE=D0=B2=D0=B5=D1=80?= =?UTF-8?q?=D0=BA=D0=B8=20startup-history=20=D0=BF=D0=BE=D1=81=D0=BB=D0=B5?= =?UTF-8?q?=20review?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - backfill-only сценарии не должны советовать проверку, которая требует live seam. - Что: - для backfill/import-only путей указан CHECK_LIVE_SEAM=0. - live-проверка вынесена в generated-history-runtime-check или явно описанный live-путь. - журнал дополнен финальным review и rerun. - Проверка: - финальный chain review rerun APPROVED; git diff --check. --- .../coordinator-journal.md | 18 +++++++++++++++ README.md | 10 +++++++-- docs/OPERATIONS.md | 22 +++++++++++++------ docs/runbooks/startup-history.md | 6 ++++- 4 files changed, 46 insertions(+), 10 deletions(-) diff --git a/.scratch/generator-model-time-startup-history/coordinator-journal.md b/.scratch/generator-model-time-startup-history/coordinator-journal.md index 3026e09..7603fe2 100644 --- a/.scratch/generator-model-time-startup-history/coordinator-journal.md +++ b/.scratch/generator-model-time-startup-history/coordinator-journal.md @@ -555,3 +555,21 @@ - 22:02 Перед финальным review: добавлен follow-up issue 19 про единые `make test`/`make lint`; PRD обновлён: 15-18 закрыты, открытыми остаются 13 (`needs-triage`) и 19 (`ready-for-agent`). +- 22:04 Финальное chain review запущено координатором: свежий + observer-субагент `Gibbs`, reasoning_effort=`xhigh`, без правок репозитория + и среды; цель — проверить цепочку 15-18 и PRD/трекер против замысла. +- 22:08 Финальное chain review `Gibbs`: `CHANGES_REQUESTED`. Finding: + docs still recommend plain `make generated-history-check` after backfill-only + `make generated-history-analytics`, but issue 17 changed default check to + require live seam. Affected docs: OPERATIONS, README, startup-history runbook. + Fixer-субагент запускается для проектных документов. +- 22:10 Final-review fixer `Peirce`: исправил README, OPERATIONS и + startup-history runbook: backfill/import-only пути используют + `CHECK_LIVE_SEAM=0`, live-проверка вынесена в + `make generated-history-runtime-check` или описана после `generator-continue` + + `make transform`. Checks: targeted `rg` PASS; `git diff --check` PASS. +- 22:10 Финальное chain review narrow rerun отправлено `Gibbs`: проверить + закрытие finding по `generated-history-check` docs drift и новый локальный + drift рядом. +- 22:11 Финальное chain review narrow rerun `Gibbs`: `APPROVED`. Findings: + нет. Chain-level решение: финальный review закрыт, собрать handoff. diff --git a/README.md b/README.md index 070534f..5bed3e4 100644 --- a/README.md +++ b/README.md @@ -70,10 +70,16 @@ PROFILE=daily-wave make generated-history-analytics GEN_HISTORY_DURATION=2d make generated-history-analytics ``` -Повторить только техническую проверку после уже выполненного прогона: +Повторить техническую проверку после такого прогона только стартовой истории: ```bash -make generated-history-check +CHECK_LIVE_SEAM=0 make generated-history-check +``` + +Стык backfill/live проверяйте отдельным коротким сценарием: + +```bash +make generated-history-runtime-check ``` Сохранить стартовую историю в файл и восстановить её без новой генерации можно diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md index 5a985c3..85c4203 100644 --- a/docs/OPERATIONS.md +++ b/docs/OPERATIONS.md @@ -11,8 +11,9 @@ - `make clean` (полная очистка: `down -v --remove-orphans`) - `make generated-history-analytics` (штатный чистый прогон: стартовая история генератора -> Kafka/STG -> ODS -> DDS -> DM -> Superset) -- `make generated-history-check` (повторяемая проверка ClickHouse и Superset - после прогона стартовой истории) +- `CHECK_LIVE_SEAM=0 make generated-history-check` (повторяемая проверка + ClickHouse и Superset после прогона только стартовой истории) +- `make generated-history-runtime-check` (короткая проверка стыка backfill/live) - `make ddl` (применяет SQL из `sql/ddl/00_databases.sql` и `sql/ddl/*/*.sql` в ClickHouse) - `make data` (архивный путь: заливает `data/*.jsonl` в Kafka; не основной источник аналитики) - `make transform` (запускает batch-процесс ODS -> DDS -> DM) @@ -183,16 +184,16 @@ make generated-history-analytics Она выполняет полный сброс volumes, поднимает ClickHouse и Kafka, применяет DDL, выполняет глагол `backfill`, прогоняет batch STG -> ODS -> DDS -> DM, инициализирует Superset и запускает техническую проверку. Для координатора или -CI короткая повторная проверка после уже готового стенда: +CI короткая повторная проверка такого готового стенда: ```bash -make generated-history-check +CHECK_LIVE_SEAM=0 make generated-history-check ``` По умолчанию команда требует live-строки после `T_end` и проверяет стык backfill/live. Чистый `make generated-history-analytics` отключает эту часть явно, потому что внутри него live-продолжение не запускается. Для ручной -backfill-only проверки используйте: +проверки только стартовой истории используйте: ```bash CHECK_LIVE_SEAM=0 make generated-history-check @@ -623,10 +624,17 @@ docker compose restart grafana # Полный чистый путь: генерация -> STG -> ODS -> DDS -> DM -> Superset make generated-history-analytics -# Повторная техническая проверка без пересоздания данных -make generated-history-check +# Повторная проверка данных стартовой истории без пересоздания +CHECK_LIVE_SEAM=0 make generated-history-check + +# Проверка стыка backfill/live +make generated-history-runtime-check ``` +Обычный `make generated-history-check` корректен только после +`make generator-continue` и повторного `make transform`, когда в витринах уже +есть строки после `T_end`. + ## Быстрые проверки - Kafka ingest: наличие данных генератора в `stg.*` и типизированных строк в `ods.*`. diff --git a/docs/runbooks/startup-history.md b/docs/runbooks/startup-history.md index 8ac8d29..00d839c 100644 --- a/docs/runbooks/startup-history.md +++ b/docs/runbooks/startup-history.md @@ -109,9 +109,13 @@ ARTIFACT=/tmp/clickstream-startup-history.json make startup-history-import sleep 10 make transform ARTIFACT=/tmp/clickstream-startup-history.json make startup-history-check -make generated-history-check +CHECK_LIVE_SEAM=0 make generated-history-check ``` +Это путь только импорта: live-строк после `T_end` ещё нет. Стык backfill/live +проверяйте через `make generated-history-runtime-check` или после +`make generator-continue` и повторного `make transform`. + Импорт не пишет напрямую в ClickHouse. Он воспроизводит события и служебные compact-топики в Kafka. ClickHouse читает данные через свои Kafka-таблицы и Materialized View, затем batch строит ODS, DDS и DM.