docs(generator): уточнены проверки startup-history после review

- Зачем:
  - 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.
This commit is contained in:
2026-07-05 22:12:09 +03:00
parent 2778eae9f0
commit 8e1c7330e1
4 changed files with 46 additions and 10 deletions
@@ -555,3 +555,21 @@
- 22:02 Перед финальным review: добавлен follow-up issue 19 про единые - 22:02 Перед финальным review: добавлен follow-up issue 19 про единые
`make test`/`make lint`; PRD обновлён: 15-18 закрыты, открытыми остаются `make test`/`make lint`; PRD обновлён: 15-18 закрыты, открытыми остаются
13 (`needs-triage`) и 19 (`ready-for-agent`). 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.
+8 -2
View File
@@ -70,10 +70,16 @@ PROFILE=daily-wave make generated-history-analytics
GEN_HISTORY_DURATION=2d make generated-history-analytics GEN_HISTORY_DURATION=2d make generated-history-analytics
``` ```
Повторить только техническую проверку после уже выполненного прогона: Повторить техническую проверку после такого прогона только стартовой истории:
```bash ```bash
make generated-history-check CHECK_LIVE_SEAM=0 make generated-history-check
```
Стык backfill/live проверяйте отдельным коротким сценарием:
```bash
make generated-history-runtime-check
``` ```
Сохранить стартовую историю в файл и восстановить её без новой генерации можно Сохранить стартовую историю в файл и восстановить её без новой генерации можно
+15 -7
View File
@@ -11,8 +11,9 @@
- `make clean` (полная очистка: `down -v --remove-orphans`) - `make clean` (полная очистка: `down -v --remove-orphans`)
- `make generated-history-analytics` (штатный чистый прогон: стартовая история - `make generated-history-analytics` (штатный чистый прогон: стартовая история
генератора -> Kafka/STG -> ODS -> DDS -> DM -> Superset) генератора -> 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 ddl` (применяет SQL из `sql/ddl/00_databases.sql` и `sql/ddl/*/*.sql` в ClickHouse)
- `make data` (архивный путь: заливает `data/*.jsonl` в Kafka; не основной источник аналитики) - `make data` (архивный путь: заливает `data/*.jsonl` в Kafka; не основной источник аналитики)
- `make transform` (запускает batch-процесс ODS -> DDS -> DM) - `make transform` (запускает batch-процесс ODS -> DDS -> DM)
@@ -183,16 +184,16 @@ make generated-history-analytics
Она выполняет полный сброс volumes, поднимает ClickHouse и Kafka, применяет DDL, Она выполняет полный сброс volumes, поднимает ClickHouse и Kafka, применяет DDL,
выполняет глагол `backfill`, прогоняет batch STG -> ODS -> DDS -> DM, выполняет глагол `backfill`, прогоняет batch STG -> ODS -> DDS -> DM,
инициализирует Superset и запускает техническую проверку. Для координатора или инициализирует Superset и запускает техническую проверку. Для координатора или
CI короткая повторная проверка после уже готового стенда: CI короткая повторная проверка такого готового стенда:
```bash ```bash
make generated-history-check CHECK_LIVE_SEAM=0 make generated-history-check
``` ```
По умолчанию команда требует live-строки после `T_end` и проверяет стык По умолчанию команда требует live-строки после `T_end` и проверяет стык
backfill/live. Чистый `make generated-history-analytics` отключает эту часть backfill/live. Чистый `make generated-history-analytics` отключает эту часть
явно, потому что внутри него live-продолжение не запускается. Для ручной явно, потому что внутри него live-продолжение не запускается. Для ручной
backfill-only проверки используйте: проверки только стартовой истории используйте:
```bash ```bash
CHECK_LIVE_SEAM=0 make generated-history-check CHECK_LIVE_SEAM=0 make generated-history-check
@@ -623,10 +624,17 @@ docker compose restart grafana
# Полный чистый путь: генерация -> STG -> ODS -> DDS -> DM -> Superset # Полный чистый путь: генерация -> STG -> ODS -> DDS -> DM -> Superset
make generated-history-analytics 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.*`. - Kafka ingest: наличие данных генератора в `stg.*` и типизированных строк в `ods.*`.
+5 -1
View File
@@ -109,9 +109,13 @@ ARTIFACT=/tmp/clickstream-startup-history.json make startup-history-import
sleep 10 sleep 10
make transform make transform
ARTIFACT=/tmp/clickstream-startup-history.json make startup-history-check 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. Он воспроизводит события и служебные Импорт не пишет напрямую в ClickHouse. Он воспроизводит события и служебные
compact-топики в Kafka. ClickHouse читает данные через свои Kafka-таблицы и compact-топики в Kafka. ClickHouse читает данные через свои Kafka-таблицы и
Materialized View, затем batch строит ODS, DDS и DM. Materialized View, затем batch строит ODS, DDS и DM.