Зерновой мир: мини-манифест и заливка при make up #42

New Issue

2026-08-01T21:19:42+03:00

ddmitry commented

2026-08-01 21:19:42 +03:00

Part of #4.

Цель

Зафиксировать «зерновой» мир конца этапа 2 — маленький срез эталонной оси
для стабильных приёмок следующих этапов — и замкнуть этап: заливка при
make up и проверка на настоящих данных.

Что войдёт

Каноническое зерно уже константа репозитория (seeds.py, CANONICAL_SEED,
заведено в #38) — здесь оно только попадает в паспорт мини-манифеста.
Мини-манифест зернового мира: паспорт (зерно, версия генератора),
счётчики, хеши по дням. Форма решается здесь — с прицелом на полный
манифест этапа 7: мини-манифест — его младший брат, не вторая правда.
Срез решён владельцем при нарезке (2026-08-01): первые 8 модельных
дней оси, понедельник–понедельник. Полная неделя с выходными плюс
первый замкнутый цикл окна K = 7: день D0 успевает замёрзнуть — этапам
3–4 есть на чём принимать и «дыхание» выручки, и заморозку. Полный
снимок 14 дней — этап 7.
make up заливает зерновой мир через Kafka пакетным режимом
проигрывателя; счётчики против мини-манифеста идут отдельной проверкой
в make check-clickhouse. В смоук их класть не надо: разметка целей
решена в #54, ось — кого спрашивают, а счётчики в ods.event считает сам
сервер и отвечает сразу. Смоук остаётся быстрой проверкой «стенд собран».
Эти счётчики — единственный постоянный сторож цепочки
Kafka → STG → ODS. #43 закрыл свои три утверждения разовыми опытами и
назвал сторожем цепочки именно их (решение владельца 7 августа 2026 года).
Отсюда требование к форме: они обязаны ловить поломку разбора — сломалась
матвью, события уехали в брак, счёт разошёлся, — а значит смотрят и на
ods.event, и на *_errors, и при расхождении показывают, где именно оно.
Считать одни события мало: брак так и останется невидимым.
Чек-скрипт «пересгенерируй день N — сравни хеш с манифестом».

Что приходит готовым из #41

Тикет идёт третьим: #41 → #43 → #42, оба предшественника влиты. К его старту
на стенде стоят проигрыватель, настоящие события в топике и типизированный ODS.
Готовым приходит генератор в собственном образе, разовая служба compose на нём,
цели make generate-batch / generate-live, ограниченная пачка с печатью числа
отправленного, способ проиграть несколько дней подряд одним запуском и CLI без
состояния — всё это видно в compose.yaml и Makefile.

Отсюда работа этого тикета, которую больше некому сделать:

Включить службу в make up — она приходит под профилем generator и
в make up не входит. Снять её из-под профиля и дать ей зависимого с
service_completed_successfully. Без зависимого up --wait считает успешно
отработавшую разовую службу упавшей; предупреждение об этом уже стоит в
compose.yaml у clickhouse-init, и цепочка kafka-init →
clickhouse-init → airflow-init держится ровно на нём. Заливка идёт
последней в цепи, поэтому зависимого ей придётся назначить осознанно.
Проверить, что заливка встаёт после того, как ODS готов принимать:
порядок применения DDL решён нумерацией файлов, и последней по построению
создаётся матвью приёма (sql/ddl/40-stg-views.sql) — она включает чтение
топика, и всё доехавшее до появления разбора (30) минует ODS молча.
Нумерацию не «выправлять»: пропуск намеренный, объяснение — в шапке файла.
Дождаться доезда, а не завершения заливки. up --wait дожидается
службы, а приём асинхронный: Kafka-движок копит блок и отдаёт его по
размеру либо по stream_flush_interval_ms (умолчание 7,5 с), а зерновой
мир — это около 400 тыс. сообщений. Ждать ограниченным циклом опроса с
таймаутом, а не sleep наугад; образцы циклов — в
scripts/stand-services.sh.

Решить и внести в спеку генератора (раздел 9) тем же PR

Форма мини-манифеста зернового мира. Вместе с ней закрывается и второй
оставшийся за этим тикетом пункт раздела 9 — хеш каталога в паспорте
мира: правка цены или уровня спроса в CSV сейчас меняет мир молча.
Третий открытый пункт, интерфейс запуска, закрывает #41. После этого
раздел закрыть: подзаголовок «Остаётся открытым, за тикетами:» (раздел 9
спеки) переписать решениями или удалить.

Перф-порог снят

Решение владельца 7 августа 2026 года: автоматического порога не будет.
Спека назначила «день ≤ 30 с» до того, как генератор написали; замер 7 августа
на машине стенда — 1,7 секунды на день в 50 626 событий, в восемнадцать раз
ниже порога. Как здесь говорят о времени, решила карта целей: цена — замеренное
число с датой, а не назначенный предел (docs/architecture/testing.md).
Наблюдаемость остаётся: проигрыватель печатает тайминги генерации и доставки
раздельно, а make up после этого тикета гоняет генератор по восемь дней при
каждом подъёме стенда.

Снятие доводится до спеки тем же PR, иначе она продолжит обещать проверку,
которой нет: раздел 5 (абзац «Автоматический порог один…» целиком) и строка
в разделе «Числа». Соседний абзац раздела 5 — «Остальное — наблюдаемость без
порогов» — остаётся и становится всем ответом; вместо порога туда идёт
замеренное число с датой.

Критерии приёмки

make clean && make up с нуля приводит стенд к данным зернового
мира в ods.event; make check-clickhouse зелёный и сверяет
счётчики с мини-манифестом. Счёт обрамляется по EventDate
зернового мира: мир растёт — менти переиграет день, этап 5 добавит
следующий, — и голый счёт по таблице разойдётся с манифестом законно,
без всякой поломки.
Счётчики видят поломку разбора: при расхождении названо, где именно —
в событиях или в браке.
Хеш дня, пересчитанный чек-скриптом, сходится с манифестом в git;
мини-манифест в git, снимок в git не попадает. Внутрипрогонный повтор
проверять не надо — побайтовое совпадение двух прогонов уже держит
generator/tests/test_player.py::test_two_runs_give_the_same_file.
Порог 30 с снят из спеки генератора в обоих местах; на его месте —
замеренное число с датой.
Цена make up перезамерена и записана в карту целей
(docs/architecture/testing.md): заливка зернового мира её меняет, а
цена там — замер с датой.
Документация обновлена тем же PR: быстрый старт и описание
зернового мира.
Раздел 9 спеки генератора закрыт: открытых вопросов «решается при
нарезке» не осталось.
Словарь CONTEXT.md пополнен: «зерновой мир», «мини-манифест».

Границы

Полный эталонный мир (14 дней), пересборка манифеста, CI-генерация на
amd64/arm64 — этап 7 (#9).
Числа объёмов решены спекой — не переоткрывать.
Корректность процессов хранилища проверяют отдельные даги DQ (планы
владельца по следующим уровням хранилища), а не проверки стенда. Находку
«это стоило бы проверять регулярно» нести туда, а не в
make check-clickhouse.

Сначала прочитать

docs/specs/2026-08-01-generator.md — разделы 2, 5, 9.
docs/specs/2026-07-30-stand-v2-realism.md — раздел 8.
#54 и docs/architecture/testing.md — разметка целей проверки: что
утверждает каждая и куда класть новую; там же правило про цену как замер.
#41 целиком, с комментариями: там решения про размещение генератора,
профиль разовой службы и интерфейс запуска, на которых стоит раздел «Что
приходит готовым».
#43 с комментариями: асинхронность приёма, дисциплина ожидания
ограниченным циклом и довод, по которому постоянных проверок цепочки там
не осталось ни одной.

Проверка

make clean && make up && make check-clickhouse && make smoke
чек-скрипт хеша дня против манифеста

Part of #4. ## Цель Зафиксировать «зерновой» мир конца этапа 2 — маленький срез эталонной оси для стабильных приёмок следующих этапов — и замкнуть этап: заливка при `make up` и проверка на настоящих данных. ## Что войдёт - Каноническое зерно уже константа репозитория (`seeds.py`, `CANONICAL_SEED`, заведено в #38) — здесь оно только попадает в паспорт мини-манифеста. - Мини-манифест зернового мира: паспорт (зерно, версия генератора), счётчики, хеши по дням. Форма решается здесь — с прицелом на полный манифест этапа 7: мини-манифест — его младший брат, не вторая правда. Срез решён владельцем при нарезке (2026-08-01): **первые 8 модельных дней оси**, понедельник–понедельник. Полная неделя с выходными плюс первый замкнутый цикл окна K = 7: день D0 успевает замёрзнуть — этапам 3–4 есть на чём принимать и «дыхание» выручки, и заморозку. Полный снимок 14 дней — этап 7. - `make up` заливает зерновой мир через Kafka пакетным режимом проигрывателя; счётчики против мини-манифеста идут отдельной проверкой в `make check-clickhouse`. В смоук их класть не надо: разметка целей решена в #54, ось — кого спрашивают, а счётчики в `ods.event` считает сам сервер и отвечает сразу. Смоук остаётся быстрой проверкой «стенд собран». - **Эти счётчики — единственный постоянный сторож цепочки `Kafka → STG → ODS`.** #43 закрыл свои три утверждения разовыми опытами и назвал сторожем цепочки именно их (решение владельца 7 августа 2026 года). Отсюда требование к форме: они обязаны ловить поломку разбора — сломалась матвью, события уехали в брак, счёт разошёлся, — а значит смотрят и на `ods.event`, и на `*_errors`, и при расхождении показывают, где именно оно. Считать одни события мало: брак так и останется невидимым. - Чек-скрипт «пересгенерируй день N — сравни хеш с манифестом». ## Что приходит готовым из #41 Тикет идёт третьим: #41 → #43 → #42, оба предшественника влиты. К его старту на стенде стоят проигрыватель, настоящие события в топике и типизированный ODS. Готовым приходит генератор в собственном образе, разовая служба compose на нём, цели `make generate-batch` / `generate-live`, ограниченная пачка с печатью числа отправленного, способ проиграть несколько дней подряд одним запуском и CLI без состояния — всё это видно в `compose.yaml` и `Makefile`. Отсюда работа этого тикета, которую больше некому сделать: - **Включить службу в `make up`** — она приходит **под профилем** `generator` и в `make up` не входит. Снять её из-под профиля и **дать ей зависимого** с `service_completed_successfully`. Без зависимого `up --wait` считает успешно отработавшую разовую службу упавшей; предупреждение об этом уже стоит в `compose.yaml` у `clickhouse-init`, и цепочка `kafka-init` → `clickhouse-init` → `airflow-init` держится ровно на нём. Заливка идёт последней в цепи, поэтому зависимого ей придётся назначить осознанно. - Проверить, что заливка встаёт **после того, как ODS готов принимать**: порядок применения DDL решён нумерацией файлов, и последней по построению создаётся матвью приёма (`sql/ddl/40-stg-views.sql`) — она включает чтение топика, и всё доехавшее до появления разбора (30) минует ODS молча. Нумерацию не «выправлять»: пропуск намеренный, объяснение — в шапке файла. - **Дождаться доезда, а не завершения заливки.** `up --wait` дожидается службы, а приём асинхронный: Kafka-движок копит блок и отдаёт его по размеру либо по `stream_flush_interval_ms` (умолчание 7,5 с), а зерновой мир — это около 400 тыс. сообщений. Ждать ограниченным циклом опроса с таймаутом, а не `sleep` наугад; образцы циклов — в `scripts/stand-services.sh`. ## Решить и внести в спеку генератора (раздел 9) тем же PR - Форма мини-манифеста зернового мира. Вместе с ней закрывается и второй оставшийся за этим тикетом пункт раздела 9 — **хеш каталога в паспорте мира**: правка цены или уровня спроса в CSV сейчас меняет мир молча. Третий открытый пункт, интерфейс запуска, закрывает #41. После этого раздел закрыть: подзаголовок «Остаётся открытым, за тикетами:» (раздел 9 спеки) переписать решениями или удалить. ## Перф-порог снят **Решение владельца 7 августа 2026 года: автоматического порога не будет.** Спека назначила «день ≤ 30 с» до того, как генератор написали; замер 7 августа на машине стенда — **1,7 секунды** на день в 50 626 событий, в восемнадцать раз ниже порога. Как здесь говорят о времени, решила карта целей: цена — замеренное число с датой, а не назначенный предел (`docs/architecture/testing.md`). Наблюдаемость остаётся: проигрыватель печатает тайминги генерации и доставки раздельно, а `make up` после этого тикета гоняет генератор по восемь дней при каждом подъёме стенда. Снятие доводится до спеки тем же PR, иначе она продолжит обещать проверку, которой нет: раздел 5 (абзац «Автоматический порог один…» целиком) и строка в разделе «Числа». Соседний абзац раздела 5 — «Остальное — наблюдаемость без порогов» — остаётся и становится всем ответом; вместо порога туда идёт замеренное число с датой. ## Критерии приёмки - [x] `make clean && make up` с нуля приводит стенд к данным зернового мира в `ods.event`; `make check-clickhouse` зелёный и сверяет счётчики с мини-манифестом. **Счёт обрамляется по `EventDate` зернового мира**: мир растёт — менти переиграет день, этап 5 добавит следующий, — и голый счёт по таблице разойдётся с манифестом законно, без всякой поломки. - [x] Счётчики видят поломку разбора: при расхождении названо, где именно — в событиях или в браке. - [x] Хеш дня, пересчитанный чек-скриптом, сходится с манифестом в git; мини-манифест в git, снимок в git не попадает. Внутрипрогонный повтор проверять не надо — побайтовое совпадение двух прогонов уже держит `generator/tests/test_player.py::test_two_runs_give_the_same_file`. - [x] Порог 30 с снят из спеки генератора в обоих местах; на его месте — замеренное число с датой. - [x] Цена `make up` перезамерена и записана в карту целей (`docs/architecture/testing.md`): заливка зернового мира её меняет, а цена там — замер с датой. - [x] Документация обновлена тем же PR: быстрый старт и описание зернового мира. - [x] Раздел 9 спеки генератора закрыт: открытых вопросов «решается при нарезке» не осталось. - [x] Словарь CONTEXT.md пополнен: «зерновой мир», «мини-манифест». ## Границы - Полный эталонный мир (14 дней), пересборка манифеста, CI-генерация на amd64/arm64 — этап 7 (#9). - Числа объёмов решены спекой — не переоткрывать. - Корректность процессов хранилища проверяют отдельные даги DQ (планы владельца по следующим уровням хранилища), а не проверки стенда. Находку «это стоило бы проверять регулярно» нести туда, а не в `make check-clickhouse`. ## Сначала прочитать - docs/specs/2026-08-01-generator.md — разделы 2, 5, 9. - docs/specs/2026-07-30-stand-v2-realism.md — раздел 8. - #54 и `docs/architecture/testing.md` — разметка целей проверки: что утверждает каждая и куда класть новую; там же правило про цену как замер. - #41 целиком, **с комментариями**: там решения про размещение генератора, профиль разовой службы и интерфейс запуска, на которых стоит раздел «Что приходит готовым». - #43 **с комментариями**: асинхронность приёма, дисциплина ожидания ограниченным циклом и довод, по которому постоянных проверок цепочки там не осталось ни одной. ## Проверка - `make clean && make up && make check-clickhouse && make smoke` - чек-скрипт хеша дня против манифеста

ddmitry added the ready-for-agent label 2026-08-01 21:20:04 +03:00

ddmitry added a new dependency 2026-08-01 21:20:07 +03:00

#41 Сериализатор, приёмники и проигрыватель с CLI