Зачем: определение описи разошлось с файлом, который называет. Формула
«счётчики закрытых окон с названным читателем» не покрывает счёт событий по
дням, а он в описи лежит и сегодня, и читатель у него самый живой: make
check-clickhouse сверяет по нему приход в ods.event.
Что: счёт событий вернулся в определение строкой дня; «паспорт» снова
раскрыт скобкой — двумя термами выше стоит «Паспорт куки», и голое слово с
ним сталкивалось; вернулось «единственное, что о мире хранится в git» —
определяющее свойство описи, а не следствие. Строка про слепок и правило
«счётчик только с названным читателем» сохранены.
Проверка: определение сверено с data/world-inventory.json и с резолюцией
«Места заказов в стартовом мире» (#74).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- Зачем:
- документация не должна обещать постоянные числа для движущегося мира.
- Что:
- уточнено появление опоздавших заказов в слепках.
- опись ограничена неизменяемым выходом и счётчиками с читателем.
- счётчик пар оставлен плану, но исключён из описи.
- Проверка:
- CONTEXT.md перечитан целиком; git diff --check.
Зачем: взгляд владельца на генератор жил только в разговорах, и каждый
следующий агент восстанавливал его заново или не восстанавливал вовсе.
Без него решения по генератору принимаются не по тому критерию: внутренняя
стройность вместо правдоподобия данных на выходе.
Что: новый раздел «Чем меряется генератор» сразу после «Зачем» — пять
утверждений рамки. Генератор меряется выходом, а не устройством; менти
внутрь не смотрит, поэтому конструкция оправдана только наблюдаемым
эффектом; повторимы эффекты, а не числа, и хеши описи обещают видимость
сдвига, а не постоянство чисел; цена ошибки мала, поэтому оборона дороже
ошибки не заводится; сложность изолирована службой ради дешевизны правки.
Рамка шире этапа 2, поэтому спеки следующих этапов ссылаются на неё, а не
копируют.
Проверка: правка только текстовая, кода не касается.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- Зачем:
- генератору нужен единый язык для скрытой личности и наблюдаемых идентификаторов.
- Что:
- определены человек, посетитель и пользователь магазина.
- закреплена граница между ClientID кликстрима и user_id заказа.
- Проверка:
- документ перечитан целиком.
Зачем: линия дефектов нашла опору на дефект провайдера, линия постановки —
незаписанный ответ на вопрос ADR 0009 и переменную образца, чьё значение на
чужой машине неверно, а узнаёт об этом читатель через двести строк.
Что: `auto_remove` у прогона генератора переведён с `success` на `force`.
Значение `success` тоже убирало контейнер в любом исходе, но случайно —
удаление у провайдера 4.5.7 стоит в `finally` вопреки собственной
документации; `force` то же поведение называет прямо и переживёт починку.
У выключателя назван `catchup=False`: умолчание Airflow 3 то же самое, но
у дага с тиком в 25 минут и `start_date` в январе это первый вопрос
читателя. «Быстрый старт» предупреждает про `DOCKER_GID` — единственное
значение образца, неверное вне этой машины. В образе Airflow записано, что
провайдер docker приходит с базой (4.5.7 к 3.3.0), — это ответ на вопрос,
который ADR 0009 оставил тикету. Список томов планировщика получил ту же
пометку «правя одно, правьте второе», что стоит у числа дней. Проход на
вычитание срезал три комментария, пересказывавших ADR.
Проверка: `make lint`, `make config-test`, `make smoke` (20/0),
`make check-clickhouse` (9/9) — зелёные. Живой пульт на чистом стенде:
снятый с паузы `world_live` сыграл два дня подряд без нажатия (24 м 07 с и
24 м 06 с, пауза между ними 55 секунд), дочерний прогон виден ссылкой из
задачи выключателя; пауза остановила мир на границе суток — тик прошёл,
третьего прогона нет. Контейнер после прогона с `force` не остался.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Зачем: модельный день прогонялся только руками, и владельцу нечем было
проверять процессы стенда вживую. Пульт нужен раньше этапа 3 и независимо
от него: он обкатывает то, что приёму заказов понадобится готовым — вызов
генератора из задачи Airflow.
Что: `dags/world_control.py` — три дага по ADR 0009. Работники
`world_next_day` (день пачкой, «сколько дней» параметром) и `world_live_day`
(день в темпе) живут без расписания и без паузы; выключатель `world_live`
создаётся на паузе, тикает раз в 25 минут и дёргает работника живого дня
с ожиданием конца. Генератор зовётся `DockerOperator` в каноническом
контейнере: сокет докера отдан планировщику, потому что при LocalExecutor
задачи исполняет он, а GID группы `docker` уехал в `.env` как локальная
настройка. Позицию на оси ведёт переменная `world_position` — её ставит
сыгравший день работник и только по успеху. Факты стенда — образ, сеть,
брокер, топик, размер стартового мира — даги получают окружением от compose;
внутри compose они названы по разу якорями, иначе разошлись бы с разовой
службой генератора. README получил раздел про пульт с названной вслух платой
за сокет.
Проверка: `make lint`, `make config-test`, `make smoke` (20/0), `make
check-services` (7/0), `make check-clickhouse` (9/9) — зелёные. На чистом
стенде: два прогона `world_next_day` подряд двигают позицию на два дня,
«дней = 3» — на три, все пять дней доехали в ODS; обрыв контейнера позицию
не двигает, повторный запуск играет тот же день с тем же счётом событий.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Зачем: модельный день прогоняется только руками, и владельцу нечем
проверять процессы стенда вживую. Этап 3 без дага не существует вовсе
(ADR 0008), поэтому форму пульта и способ вызова генератора надо решить
раньше кода.
Что: ADR 0009 — работники без расписания (`world_next_day` пачкой,
`world_live_day` в темпе) и выключатель `world_live` без своей работы,
ждущий дочерний прогон триггером, а не сенсором; генератор зовётся
`DockerOperator` в каноническом контейнере, потому что в образе Airflow ему
не жить (Python 3.14 против 3.13); позиция ставится как «последний сыгранный
+ 1» — правило вместо сторожа, и его мягкий худший исход назван. Плата за
сокет докера снята замером: доступ открывается добавлением GID в контейнер,
правка прав на хосте не нужна, а сам GID — локальная настройка в `.env`.
Пакетная автоматика отложена, не отвергнута. Расхождения внесены в спеку
генератора: позицию ставит сыгравший, у живого дня появился выключатель.
В словарь добавлен «пульт мира».
Проверка: `make config-test` зелёный; API Airflow 3.3 (пауза и ручной
запуск, ожидание триггера по идентификатору прогона, привязка сенсора к
логической дате, `DockerOperator`) сверено через MCP Context7; версия
Python в образе и права сокета — замером.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Зачем:
- документация и конфигурация доступа должны говорить только подтверждённое.
- Что:
- ADR приведён к результату межшардового замера.
- объяснены служебный грант и учебный компромисс remote().
- удалены избыточные профили, README связан с ADR.
- Проверка:
- make config-test, make lint, make smoke, make check-clickhouse, make check-services.
- Зачем:
- читателю нужна честная граница между учебными ролями и боевой защитой.
- Что:
- README описывает пользователей, роли и место хранения паролей.
- мастер-спека явно откладывает эксплуатационные меры защиты.
- устаревшие комментарии Compose и пробника приведены к реализации.
- Проверка:
- make config-test, make lint.
- Зачем:
- default должен остаться только учёткой локальных служебных вызовов.
- Что:
- пароль default подставлен из окружения на обеих нодах.
- healthcheck и служебные скрипты передают его внутри контейнера.
- Проверка:
- make config-test, make up, make smoke, make check-clickhouse, make check-services.
- Зачем:
- DDL, Airflow и Superset не должны работать с правами default.
- Что:
- DDL и Airflow переведены на etl, включая явный доступ remote().
- Superset переведён на bi с паролем из окружения.
- etl получил право KAFKA, которое ClickHouse 26.3 требует для движка.
- Проверка:
- make config-test, make lint, make up, make smoke, make check-services.
- Зачем:
- менти должен увидеть разделение доступа без состояния в томах.
- Что:
- пользователи и роли объявлены файлом с паролями из окружения.
- межшардовые запросы передают пользователя через общий секрет.
- четыре допущения реализации подтверждены в ADR живыми замерами.
- Проверка:
- make config-test, make smoke, make check-clickhouse, make check-services.
Зачем: резолюции wayfinder-тикетов живут комментариями, и правка после
ревью идёт в них — а дока описывала только правку тела issue. Путь
неочевидный: без номера issue, по идентификатору из ленты.
Что: абзац в разделе про правку через API и строка в «Что проверено и
когда».
Проверка: снято живыми запросами при закрытии #72 — резолюция правилась
дважды этой командой.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Зачем:
- развилка этапа 3 стояла нерешённой прямо в разделе 7 мастер-спеки: нужен
ли слепку слой сырья и как заказы попадают из топика в хранилище (#70).
- Что:
- заведён ADR 0008 — байтовый чтец без матвью, слой сырья у заказов
остаётся, в ods.order_snapshot пишет шаг Airflow заменой партиции; топик
orders в одну партицию, чтец на clickhouse-01 без ON CLUSTER.
- мастер-спека приведена в соответствие, разделы 6, 7, 9, 11, 12: сравнение
двух приёмов переписано на «поток против слепка», сенсор дневного батча
снят, первый даг переехал с этапа 5 на этап 3.
- в CONTEXT.md заведены «слепок», «окно изменяемости», «пакетный забор».
- Проверка:
- решение сверено по документации ClickHouse через MCP Context7 12 августа
2026 года; что осталось замерить на стенде — списком в конце ADR 0008.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Зачем:
- до появления ETL и витрин надо выбрать границу боевого реализма в
доступе: один беспарольный default учит нулю, а полноценная защита
стоит эксплуатации, которой стенду не потянуть (#66).
- Что:
- принято четыре пользователя и три роли, объявленные файлами настройки,
без состояния в томах и без SQL-хранилища доступа.
- межнодовое доверие переведено на общий секрет кластера: учётные данные
по репликам подменяют права спросившего правами общей учётки.
- записаны отвергнутые варианты, отложенные меры защиты и четыре
проверки, которые закрывает тикет реализации.
- устройство модели отдано разделу README «Состав и доступ»: отдельный
справочник по доступу своего содержания сверх ADR сегодня не имеет.
- оговорено, что роль шире прав на слои — образ требует отдельных
разрешений на ON CLUSTER и на чтение системных таблиц (холодное
ревью #78).
- Проверка:
- реализации в этом коммите нет, менять нечему: make config-test.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Зачем:
- target-version по младшему образу (Superset, 3.10) занижал проверку для дагов: они бегут на 3.13, а ruff предлагал им идиомы старее их рантайма. На учебном стенде это вывернуто наизнанку — менти читает и правит именно даги.
- защита от Superset была верна не по устройству, а по сегодняшнему содержимому одного файла настройки.
- Что:
- target-version в корневом ruff.toml поднят до py313, комментарий переписан.
- две находки UP017 в дагах починены: datetime.timezone.utc заменён на datetime.UTC.
- из карты проверок убран пункт про разную строгость дверей — с равными версиями он потерял предмет.
- Проверка:
- make lint; make config-test — зелёные.
- make -C generator lint — зелёный; исходники генератора не менялись.
- находок ruff в дагах теперь ровно четыре, как обещал тикет: два переформата и два UP017.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Зачем:
- половина критерия приёмки стояла не там, где решено: предупреждение о ручном равенстве версий ruff адресовано тому, кто правит лок в generator/, а лежало в корневом Makefile.
- довод «генератор — отдельная сущность» был выписан трижды почти дословно.
- Что:
- равенство версий и охват корневой цели названы в карте проверок; три примечания к таблице собраны списком.
- названа цена занижения target-version: даги бегут на 3.13 и модернизаций не получают.
- шапка generator/Makefile вырезана, корневая сжата до строки, объяснение в ruff.toml укорочено.
- формулировки в AGENTS.md и README поправлены.
- Проверка:
- make lint; make config-test — зелёные.
- make -C generator lint; typecheck — зелёные; исходники генератора не менялись.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Зачем:
- корневые цели смешивали два уровня: пять из шестнадцати начинались с cd generator.
- цель, названная общерепозиторной, охватывала 31 файл Python из 34: даги и Superset не видел ни линт, ни типы.
- Что:
- lint, typecheck, test, docs и inventory переехали в новый generator/Makefile.
- корневой lint заведён по коду стенда — dags и infra/superset — с явными путями и закреплённой версией ruff.
- заведён корневой ruff.toml: тот же список правил, target-version по младшему Python в образах стенда.
- цели корня сгруппированы по использованию, осталось двенадцать.
- два файла дагов переформатированы под новую проверку.
- карта проверок, оба README, спека генератора и AGENTS.md приведены к двум дверям.
- Проверка:
- make lint; make config-test — зелёные.
- make -C generator lint; typecheck; test — зелёные, 407 тестов.
- ruff check --show-files: из корня ровно три файла стенда, из generator/ — только его.
- цена корневого lint замерена (0,4 с) и вписана в карту проверок.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Зачем:
- устранены дублирование значений и тихая подстановка неполной настройки.
- Что:
- версии образов и внутренняя топология закреплены рядом с местом использования.
- имя экземпляра, внешние порты, учётные данные и ключи сделаны обязательными настройками .env.
- быстрый старт, Dockerfile и статическая проверка приведены к новой границе.
- Проверка:
- make config-test.
- docker build для образов Airflow и Superset без аргументов.
- make up; make smoke; make check-clickhouse; make check-services.
- Зачем:
- фраза «Date не участвует вовсе» выводила тип из-под общего правила:
про объявление это правда, про употребление — нет. Считая время по
EventDate без имени пояса, легко получить часы вне диапазона.
- Что:
- фраза заменена на две: Date хранит только номер дня, пояс при счёте
времени называют руками, промах виден по часам за границами 0–23.
- Проверка:
- замерено на стенде: без имени пояса часы от начала суток идут -4…19,
отрицательных 15 843 события; с названным поясом — 0…23
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Зачем:
- константу COUNTER_TIMEZONE не читал ни один модуль, единственным её
читателем был тест про неё же; связь имени и смещения держится тем, что
они стоят в одной строке.
- Что:
- COUNTER_TIMEZONE снят, имя пояса ушло комментарием к
COUNTER_TIMEZONE_MINUTES.
- тест сходимости имени и смещения снят вместе с ним; test_world.py
вернулся к прежнему виду.
- Проверка:
- make lint, make typecheck, make test (407 тестов)
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Зачем:
- линия дефектов нашла три неверных утверждения и мёртвый замер, линия
уместности — три пересказа уже сказанного.
- Что:
- «тип колонки не решает, какое число ляжет» сужено до правды: разбор
отдаёт готовое число, а пояс приёмника решал бы судьбу строки.
- замер до правки типов помечен как неповторяемый на нынешнем стенде.
- правило о поясе сервера привязано к местам, где линза что-то решает:
матвью приёма пояс не называет, и это не нарушение.
- убраны: пересказ механики в ADR 0005, четыре строки учебного
комментария, утверждение о порядке файлов и «секунды от начала эпохи»
у миллисекундной метки.
- Проверка:
- make lint, make typecheck, make test (408 тестов)
- make clean && make up && make check-clickhouse — 9 из 9
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Зачем:
- конвенция #63 записана, а код её не достиг: колонки времени стояли без
пояса, и сходилось всё лишь потому, что пояс сервера — UTC.
- Что:
- UTCEventTime объявлен DateTime('UTC'), служебные метки _load_ts и
kafka_timestamp — DateTime64(3, 'UTC') в STG и ODS.
- parseDateTimeOrNull получил третьим аргументом 'UTC': маска сверяет
суффикс Z как букву, зоны из строки не берёт вовсе.
- контракт схемы и описание выгрузки несут тип с поясом; имя пояса
Europe/Samara встало рядом со смещением в world.py, сходимость сверяет
тест.
- учебный комментарий о линзе — у первой колонки с явным поясом.
- Проверка:
- make lint, make typecheck, make test (408 тестов)
- make clean && make up && make check-clickhouse — 9 из 9
- замер тикета повторён: под session_timezone='Europe/Samara' колонка
показана 2026-05-31 23:37:00, как и без настроек
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Зачем:
- раздел «Часовые пояса» прошёл два холодных ревью — по дефектам и по
уместности. Первое поймало ложный замер и три расхождения с живым
стендом, второе — материал не своей зоны и дубли (#63).
- Что:
- замер «расхождение живёт по HTTP» отозван: мерил toString(UTCEventTime)
в родном клиенте против голой колонки по HTTP, а это разные вещи.
Перемерено — клиенты ведут себя одинаково; записан верный факт: вывод
колонки идёт по поясу сессии, функция — по поясу типа.
- «по поясу сервера» заменено на «по поясу сессии, а тот по умолчанию
серверный» — в разделе и в ADR 0005; утверждение в ледгере переписано
под измеренный раскол вывода и типа.
- PARTITION BY toDate(_load_ts) больше не выдаётся за уже соблюдённое
правило: _load_ts сегодня DateTime64(3) без пояса.
- абзац ADR 0005 больше не спорит с цитатой вызова строкой выше.
- вырезано: веер отклонённых вариантов под заголовком (живые отказы
разложены прозой по своим абзацам, как принято в этом документе),
ссылка на несуществующую связку в world.py, осиротевшая строка про
Grafana, абзац про пояс показа — он уехал комментарием в #63.
- Проверка:
- make lint
- замеры повторены на живом стенде 8 августа 2026 года
- DDL к конвенции по-прежнему не приведён: документы описывают цель
- Зачем:
- пояс в стенде нигде не назван: числа верны только потому, что сервер
ClickHouse стоит в UTC, а правило понадобится в dds и витринах —
воронки, удержание, «покупки по дням» (#63).
- Что:
- раздел «Часовые пояса»: пояс — линза, называется в типе колонки либо в
вызове; какая именно — решает слой (ODS на языке выгрузки, DDS и витрины
на языке бизнеса); день берётся из EventDate.
- названы оба перехода, где пояс выбирается, включая разбор строки в
матвью — он берёт пояс у сервера и тип колонки этого не чинит.
- отвергнутые варианты прозой: умолчание сервера, TZ серверу, ODS в поясе
счётчика, хранение местного времени.
- три замера ушли в «Что проверено», сверка с документацией — от 8 августа.
- Проверка:
- make lint
- DDL к конвенции ещё не приведён: документ описывает цель, код идёт
следом тем же тикетом.
Зачем: формулировка в спеке дублировала строку карты проверок и делала это
хуже оригинала. «make up работает» следует из зелёных проверок и потому
пусто; настоящее условие — «с нуля» — в спеке не проговаривалось. Заодно
гигиеническая планка носила имя приёмки этапа, хотя про предмет этапа она
молчит: дашборд может быть не нарисован, а все три цели зелены. Тот же промах
разобран в ADR 0004 — там он случился с числовым порогом.
Что: раздел 9 спеки отсылает к карте проверок вместо своей формулировки и
называет вещь своим именем — гигиена, а не приёмка. Копия строки убрана из
семи карт этапов и карты #1 в трекере: одна вещь — одно место.
Проверка: правка документная. grep по docs, README и AGENTS — других копий
формулировки нет.
Зачем: этап 2 принят прогоном с нуля, и два его следа должны остаться в
доках — иначе решение «не проверяем» станет забытым долгом, а цена цели
разойдётся с замером.
Что:
- в спеке v2 раздел 11 больше не держит Kafka Engine на двух нодах: дубли и
раскладку партиций между прогонами решено не проверять — дубль возможен по
устройству движка, окно разобрано в доке хранилища, в ODS его схлопывает
ReplacingMergeTree. Половина, которую показал #37, названа;
- в карте проверок цена check-services 44 с -> 59 с и абзац с замерами
приёмки: clean+up 2 м 58 с, смоук 9 с, check-clickhouse 8 с, test 71 с.
Причина подорожания не выдумывается — названа неизвестной.
Проверка: make clean && make up, затем make smoke, make check-clickhouse,
make check-services, make lint, make typecheck, make test — всё зелёное
7 августа 2026 года.
Зачем
Холодное ревью нашло три места, где написанное сильнее сделанного.
Что
- Непустая таблица брака больше не выдаётся за доказательство сломанного
разбора. Модельного дня у брака нет, обрамить его нечем, и строки прежних
уроков лежат в нём месяц: после первого же урока с мусором проверка
давала бы неверный диагноз навсегда. Теперь она даёт признак, по которому
причину отличают, — сошлась недостача с числом брака или нет.
- Комментарий у world-init обещал, что расхождение числа дней с
STARTING_DAYS поймают счётчики. Это неправда в одну сторону: лишний день
ложится за рамкой дат описи. Обещание убрано, дыра названа.
- Довод «даг next_day этапа 5 продолжит ось» опирался на несуществующий
этап; заменён настоящей причиной — заливка замыкает цепь разовых служб.
- Потолок ожидания 300 с получил обоснование замером с кратностью, а сам
скрипт — честную оговорку: его обещание работает на пустом стенде, на
живом ждать нечего.
- Третья, пропущенная ссылка на снятый порог скорости дня убрана из спеки.
- Даты замеров в карте целей разведены: #42 менял три цели, а не шесть.
Проверка
Обе ветви диагноза сняты заново на живом стенде: без брака — «не доехали»,
с браком — признак различения. Стенд восстановлен, все 9 проверок зелёные,
брака 0. make lint, typecheck, config-test, test (407 тестов) зелёные.
Ссылка: #42
Зачем
Стенд поднимался пустым, и всякая приёмка следующих этапов начиналась с
ручной заливки данных. Теперь `make up` сам приводит стенд к одному и тому
же состоянию, а в git лежит то, чем это состояние проверяется.
Что
- Опись мира `data/world-inventory.json`: паспорт (зерно, версия
генератора, хеш каталога) и по строке на каждый из восьми дней — дата,
число событий, хеш байтов. Собирается `make inventory`, свежесть сторожит
`test_inventory.py` — тем же способом, что свежесть описания выгрузки.
- Разовая служба `world-init` вышла из-под профиля и играет в топик восемь
дней при каждом подъёме; зависимый у неё — `airflow-init`, иначе `--wait`
считает успешно отработавшую службу упавшей.
- `scripts/wait-for-world.sh` — вторая половина `make up`: приём
асинхронный, поэтому ждать надо доезда до `ods.event`, а не завершения
заливки. Ограниченный цикл опроса, не пауза наугад.
- Девятая проверка `make check-clickhouse`: подневный счёт событий против
описи, рамка по датам стартового мира, счёт через `FINAL`. При
расхождении называет, где искать, — в событиях или в браке.
- Порог «день ≤ 30 с» снят из спеки генератора в обоих местах: замер дал
1,7 с, порог был выше факта в восемнадцать раз. На его месте — замеры с
датой. Раздел 9 спеки закрыт: открытых вопросов не осталось.
- Слова: «манифест» стал описью мира, «зерновой мир» — стартовым миром
(решение владельца). Оба заведены в словарь CONTEXT.md.
Проверка
`make clean && make up` с нуля — 2 м 50 с, доехало ровно 401 185 событий.
`make check-clickhouse` зелёный (8 с), `make smoke` зелёный (9 с),
`make test` — 407 тестов за 71 с, `make lint`, `make typecheck`,
`make config-test` зелёные.
Что проверка умеет краснеть, снято двумя поломками: снос партиции
2026-06-03 дал диагноз «не доехали до ODS», негодная строка в сырье —
«сломан разбор». Строки опыта убраны, день переигран, счёт вернулся.
Тест свежести проверен молчаливой правкой цены в каталоге: покраснел.
Ссылка: #42
- Зачем:
- находка «это стоило бы проверять регулярно» решалась заново в каждом
тикете и каждый раз тянулась в make check-clickhouse. У неё есть
назначенный дом: даги качества данных, которые придут со следующими
уровнями хранилища.
- Что:
- добавлен раздел «Корректность процессов живёт в дагах DQ, а не в целях
make»: цели make отвечают «стенд собран», свойства данных — работа дага.
- назван фильтр: про полноту дня, свежесть слоя, сходимость витрины с
источником — это даг, а не цель.
- названа учебная сторона: даг идёт по расписанию, пишет историю проверок
и разбирается как обычная задача Airflow — так качество данных устроено
в бою.
- Проверка:
- make config-test
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Зачем: parseDateTimeBestEffort на непонятной строке не краснеет, а достраивает
недостающее — обрезанное «20:00:21» становится первым января текущего года.
Такое сообщение проходило строгий приём с тихо неверным временем, то есть с
той самой порчей, ради которой класс key_field_unparsed и заведён.
Что:
- В обеих матвью разбор метки идёт parseDateTimeOrNull по формату
'%Y-%m-%dT%H:%i:%SZ'. Форма на проводе одна и каноническая, поэтому широта
best-effort не нужна вовсе, а платится за неё отключённой проверкой.
- Замеры в ADR 0005: три записи, которые best-effort достраивает; проверка,
что настройка cast_string_to_date_time_mode не спасает JSONExtract; сверка
на настоящих данных — по всем 101 252 строкам сырья модельного дня точный
формат разобрал метку у каждой и ни на одной не разошёлся с best-effort.
- Записано наблюдение стенда: пересозданная на живом чтеце матвью пропускает
ближайшее сообщение мимо ODS, через минуту то же сообщение разбирается.
Воспроизведено дважды; на нём я сам споткнулся при проверке этой правки.
Проверка: опыт строгого приёма прогнан заново — три сообщения дали событие и
два key_field_unparsed, включая обрезанную метку, которая раньше проходила
годной. DDL применяется на живом кластере.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Зачем: холодное ревью по двум линиям нашло дыру в следе опытов и три места,
где текст утверждает не то, что построено.
Что:
- Опыт «_load_ts переносится из сырья» прогнан и записан: у двух тысяч
событий метка совпала с меткой одной из доставок, случаев «метки нет среди
доставок» ноль. Туда же — ответ про форму ключа ODS: вопрос раздела 11
спеки закрывался молча.
- Дока хранилища говорила, что предикат собран из функций, не возвращающих
NULL; построено иначе — обнуляемый разбор есть, но кончается IS NOT NULL.
- Записана гарантия на JSONType: на не-JSON и пустой строке она отдаёт Null и
не бросает, то есть годится в предикат. Раньше первый класс брака стоял на
замере соседней функции.
- ttl_only_drop_parts у таблицы ошибок назван в доке хранилища.
- Комментарий матвью ужат: три вопроса строгого приёма пересказывали ADR 0005
целиком. Осталось то, чего по коду не видно, — запрет трогать arraySort и
замер про ISO-8601. Убрано неверное «в полусотне строк» и упоминание имени
таблицы хранилища в докстринге контракта генератора.
Проверка: DDL применяется на живом кластере; make lint, typecheck, docs.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Зачем: цепочка Kafka → STG → ODS достраивается последним этажом. Сырьё уже
доезжает (#37), настоящие события в топике есть (#41), а типизированного слоя
не было — событие негде было прочитать колонками, а брак негде увидеть.
Что:
- sql/ddl/20-ods-tables.sql — ods.event_rep/_dist на ReplacingMergeTree с
версией _load_ts, партиция по EventDate, ключ по разделу 1.3 спеки,
шардирование cityHash64(ClientID); ods.event_errors_rep/_dist с классом
брака, своими ключами и сроком жизни в месяц.
- sql/ddl/30-ods-views.sql — две матвью над stg.hits_raw_dist. Годность
считает предикат из трёх частей, вторая матвью берёт его дословное
отрицание, класс брака пишется первым совпавшим из трёх.
- Метку времени разбирает parseDateTimeBestEffortOrNull, а не JSONExtract:
ISO-8601 с суффиксом Z JSONExtract не берёт вовсе. Спека генератора
обещала обратное — обещание поправлено, форма на проводе не менялась.
- Сверка объявлений (contract-тест) снята из документов и из докстрингов
schema.py: сверх строгого приёма она ловила только смену типа.
- Документация приведена в соответствие: ADR 0005, дока хранилища и обе
спеки; группа «сказано по памяти» в доке хранилища опустела.
Проверка: make up && make check-clickhouse (8 проверок, 7,5 с); make lint,
make typecheck, make test (406), make docs без диффа. Разовые опыты при
исполнении — в теле PR.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Зачем: имя файла осталось от прежней цели smoke-cluster, которой больше нет,
и читатель ищет проверку ClickHouse не там, где она лежит.
Что: git mv scripts/clickhouse-smoke.sh scripts/check-clickhouse.sh, тем же
коммитом — вызов в Makefile и строка в карте целей. Абзац-объяснение в
docs/architecture/testing.md снят: он обещал переименование, которое здесь и
случилось.
Проверка: make check-clickhouse.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Зачем:
- до сих пор генератор умел собирать день, но не умел его отдать: топик
hits наполнялся пробником, а не настоящими данными. Тикет #41 доводит
события до стенда и закрывает форму на проводе, на которую обопрётся
типизированный ODS (#43).
- сериализатор один по решению спеки: второе место, печатающее событие в
JSON, разошлось бы с первым молча.
- Что:
- serialize.py — канонический сериализатор на orjson: единственное место,
где событие целиком становится JSON; 47 ключей всегда, «пусто» это
пустое значение, даты ISO-8601, ecommerce строкой. Вложенный блок
ecommerce в commerce.py вторым сериализатором не считается — правило
про событие, а не про блок внутри него.
- sinks.py — приёмники: файл (одно событие — одна строка) и Kafka (одно
событие — одно сообщение). Ключа у сообщения нет: WatchID уникален,
ключом он был бы ключом лишь на вид.
- player.py, cli.py — проигрыватель и интерфейс запуска: режимы batch и
live (темп ×60), несколько дней одним запуском, ограниченная пачка,
раздельные тайминги генерации и доставки, лаг в логе.
- день на оси и имя топика умолчаний не имеют: параметр, описывающий
среду или позицию, приходит от зовущего, иначе отказ до генерации.
Умолчания зерна, числа дней и темпа остаются — они описывают мир.
- generator/Dockerfile — свой образ: зависимости из uv.lock, база
закреплена до патча, раскладка репозитория сохранена ради каталога
товаров. Образ Airflow не тронут.
- разовая служба compose под профилем, цели generate-batch и
generate-live, .dockerignore, tmp/ в .gitignore.
- решения внесены в спеку (разделы 4, 8, 9), быстрый старт — в README.
- Проверка:
- make test 406 passed, make lint, make typecheck, make config-test.
- побайтовый детерминизм: два прогона дня в независимых процессах дают
один sha256; день в контейнере совпадает с днём на машине.
- на стенде: пакетный день доехал до stg.hits_raw_dist, счёт по
Distributed сошёлся — отправлено 50626, в таблице 50626.
- топик прочитан обеими нодами: clickhouse-01 раздел 0 (26368),
clickhouse-02 раздел 1 (24258).
- живой день: модельное время 01:00 на 60-й секунде, 02:00 на 120-й —
темп ×60, лаг печатается.
- форма на проводе в колонке raw: даты читаются глазами, ecommerce лежит
строкой.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Зачем:
- у вопроса «чему на этом научится менти?» не хватало второй половины:
он отсеивал бесполезное, но не взвешивал цену полезного. Стенд
учебный, и чем он сложнее, тем хуже как учебный материал.
- прогон #41 показал механизм: две слепые линии ревью дали 15 находок,
саморевью ещё 7, и каждая по устройству триажа превратилась в правку.
Шага, на котором кто-нибудь вычитает, в конвейере не было ни разу —
только воронка. Проход на вычитание потом срезал 149 строк и 6 тестов,
и всё срезанное появилось после ревью, а не при замысле.
- Что:
- в раздел «Цель репозитория» добавлены три абзаца: внимание менти как
конечная валюта и вопрос «что он платит и что получает»; почему
оборонительный код дороже прочего и врёт про опасность; проход на
вычитание как обязательный шаг перед приёмкой заметной работы.
- записано частное правило, выведенное владельцем на двух резах подряд:
не сторожить ошибку, которую человек делает сам себе и тут же видит —
разбирательство с ней и есть урок.
- Проверка:
- правка текстовая, целей make не задевает; make config-test зелёный.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Зачем:
- проверка, которая кормит стенд данными, оставляет их в мире менти
навсегда: у ODS срока хранения нет, и события, которых мир не рождал,
неотличимы в лабах от настоящих. Решение принято при разборе постановок
#41 и #43, чтобы оно решалось по карте, а не заново в каждом тикете.
- Что:
- добавлен раздел «Интеграционная проверка постоянной целью не становится»:
такой прогон делается один раз при исполнении, след — запись в теле PR.
- названо требование прибираться за собой и дешёвый способ это сделать:
модельный день за границей оси мира и снос его партиции.
- названо, что стережёт цепочку постоянно вместо неё — проверки на
настоящих данных, которые стенд произвёл сам.
- Проверка:
- make config-test
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Зачем:
- проверка была сломана с рождения цели: bash -n со списком файлов
разбирает только первый, остальные уходят ему в аргументы. Из пяти
скриптов проверялся один, и за всё время этого никто не заметил.
- чинить незачем: скрипты стенда запускают с той же машины, и
синтаксическая ошибка вылезает при первом же запуске с номером строки.
Учебной ценности в проверке нет — из неё не узнаёшь ничего, кроме того,
что у bash есть ключ -n.
- держалась она не строчкой, а двенадцатью: обход репозитория, временный
файл со списком, mapfile и две ветки на пустой список.
- Что:
- из scripts/config-test.sh убраны разбор Bash и весь аппарат сбора
списка файлов; 53 строки стали 40.
- разбор файлов DAG остался и получил комментарий с основанием: их на
машине не запускает никто, обработчик разбирает их внутри контейнера, и
ошибка всплывает не сообщением, а молча пропавшим DAG.
- README и карта проверок больше не обещают проверку синтаксиса Bash.
- в карте записано, почему проверку не стоит заводить заново.
- Проверка:
- make config-test зелёный.
- оставшийся разбор DAG краснеет: незакрытая скобка в dags/test_kafka.py
роняет цель с SyntaxError и ненулевым кодом; файл восстановлен.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- Зачем:
- деление целей оставило дыру: про Airflow, Superset, Prometheus и Grafana
смоук стучится с машины в отображённый порт, а про Kafka после переезда
check_kafka_from_host знал только «контейнер здоров».
- вердикт этот приходит из healthcheck в compose.yaml, а тот спрашивает
брокер изнутри и по внутреннему слушателю: объявленный наружу адрес может
вести не туда, и Kafka всё равно останется здоровой.
- поломка популярная и показательная: клиент подключается, получает
метаданные и молча виснет на адресе, которого с его стороны нет. Менти
узнаёт, что у брокера два слушателя и зачем нужен advertised.listeners.
Генератор будет писать в Kafka именно с машины.
- Что:
- check_kafka_external_listener в make smoke: запрос списка топиков с машины
через отображённый порт, ответ приходит только если объявленный адрес ведёт
туда же. Комментарий у проверки объясняет, от чего она заведена.
- ожидание ответа ограничено 15 секундами при замеренных 2,6 — впятеро
больше, чем стоит зелёный прогон.
- README и карта проверок: новая проверка названа, доводы записаны, цена
смоука обновлена с 6 до 8 секунд.
- Проверка:
- make config-test, make smoke (20 проверок, 8 с), make check-clickhouse,
make check-services — зелёные.
- краснеет на своей поломке: брокеру объявлен адрес kafka-nowhere:29092 при
целом внутреннем слушателе — проверка состояния контейнера осталась
зелёной, смоук покраснел именно на этой строке. После проверки Kafka
возвращена в исходное состояние, посторонних контейнеров не осталось.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ddadminandClaude Opus 5
ddmitry