- Зачем:
- половина справочника была про один дашборд «Данные», а этап приносит ещё
два дашборда и правила оповещения: описание самой зоны утонуло бы.
- Что:
- заведён набор docs/architecture/monitoring/ по ADR 0011: README.md — зона
и каталог дашбордов, data.md — устройство дашборда «Данные».
- обе входящие ссылки перенацелены: README.md репозитория и ADR 0002.
- Проверка:
- make config-test; ссылки из README.md и ADR 0002 открываются.
- Зачем:
- две линии ревью нашли, что колонки панели брака читаются как
непересекающиеся кучи, «вовремя ли» из ADR 0002 не считается вовсе, а
отказ от ряда «против вчерашнего» нигде не записан рядом с решением.
- Что:
- в панели брака столбец назван «Из них в брак»: брак — часть приехавшего,
а не соседняя куча.
- панель слепка считает паузу после прошлого слепка — это и есть «вовремя
ли» из ADR 0002; пустая пауза у самого раннего слепка держится
обнуляемым типом.
- отказ от ряда «против вчерашнего» записан в ADR 0002 и в monitoring.md с
доводом: сдвиг на модельные сутки прописал бы ускорение мира в JSON.
- в monitoring.md сказано, почему свежесть читает физическую _dist, а не
ods.*_v, и почему панель слепка не знает окна; довод про сломанный JSON
оставлен у кода, а не задвоен в доке.
- README больше не утверждает, что панелей нет.
- у разбора дашбордов убран флаг -e: он обещал утверждение, которого нет.
- Проверка:
- make config-test (краснеет на нарочно сломанном JSON дашборда), make lint,
make smoke 21/21, make check-clickhouse 10/10; все шесть панелей отвечают
через /api/ds/query. Опыты приёмки и их следы — monitoring.md,
«Что проверено».
- Зачем:
- главный дашборд ADR 0002 отвечает на вопрос «с потоком всё в порядке?»;
три его вопроса — свежесть, брак и сходимость — у предшественника не
заданы вовсе, и в этом весь смысл экрана.
- Что:
- добавлен infra/grafana/provisioning/dashboards/data.json: свежесть, поток,
брак, сходимость, отставание чтения из Kafka и дневной слепок заказов;
порогов и цветовых вердиктов на панелях нет.
- в monitoring.md записано устройство дашборда: почему слои у панелей разные
и как считается сходимость — с доводом и двумя отвергнутыми способами.
- make config-test разбирает JSON дашбордов тем же доводом, что и файлы
дагов: сломанный файл Grafana молча оставляет прежнюю версию.
- Проверка:
- make config-test; на живом стенде make smoke 21/21 и make check-clickhouse
10/10; все шесть панелей отвечают через /api/ds/query.
- Зачем:
- подготовлен пол мониторинга для SQL-панелей и метрик отставания Kafka.
- Что:
- добавлены отдельная роль ClickHouse, источник Grafana и Kafka exporter.
- образ Grafana собирается с закреплённым плагином вне тома данных.
- Prometheus, смоук и документация обновлены под четыре цели.
- Проверка:
- make config-test; make lint.
- make smoke; make check-clickhouse; make check-services.
- make -C generator lint typecheck test.
- Зачем:
- дашборды нужны точками наблюдения на приёмке этапов 4-8, а зависимость
у них формально только от этапа 1: «в хвосте» было выбором, не
необходимостью.
- Что:
- раздел 9: дашборды строятся параллельно этапам 4-8, состав не меняется.
- назван хвост этапа: runbook keeper/DDL, system.text_log, правила
оповещения, урок «посмотрели - сломали - вернули».
- записано правило: панели порогов и цветовых вердиктов не несут, красное
и зелёное живёт в проверках.
- Проверка:
- тикеты этапа нарезаны по этому раскрою: #114-#117 под #11.
- Зачем:
- локальные уточнения документации нужно опубликовать без потери слитых изменений #96 и #109.
- Что:
- актуальный `origin/main` объединён с двумя локальными коммитами документации.
- сохранены уточнения применения настроек ClickHouse и границ проектирования заказов.
- Проверка:
- `make config-test`.
- `make lint`.
- Зачем:
- ODS должен показывать сущность заказа, а не способ её доставки слепком.
- Что:
- физические таблицы и представление переведены на имена `order_*`.
- SQL загрузки, DAG и документация приведены к тому же словарю.
- Проверка:
- `make config-test`, `make lint`.
- `make clean && make up`, `make smoke`, `make check-clickhouse`, `make check-services`.
- Зачем:
- свежий стенд должен показывать отставание ночной выгрузки заказов от кликстрима.
- Что:
- после событий генератор отправляет семь слепков дней 0…6 в общий топик orders.
- make up запускает orders_ingest, ограниченно ждёт его завершения и оставляет день 7 первому ходу мира.
- README и карта проверок описывают второй источник и измеренную цену подъёма.
- Проверка:
- make clean && make up; make smoke; make check-clickhouse; make check-services.
- cd generator && make lint && make typecheck && make test.
- Зачем:
- состав полей DDS определяется вместе с моделью, поэтому отдельная задача заранее не нужна.
- Что:
- удалена задача #85 из списка открытых решений по заказам.
- убран устаревший указатель на неё из описания приёма.
- Проверка:
- выполнен `git diff --cached --check`.
- Зачем:
- перезапуск мог оставить прежнее окружение и старый inode файла, а документы обещали неподдерживаемое живое применение.
- Что:
- в README записано пересоздание нод с ожиданием их здоровья.
- ADR 0007 отделяет решение от процедуры и очищен от устаревших обещаний.
- Проверка:
- make config-test.
- git diff --cached --check.
- Зачем:
- слепок D7 содержал отрицательный итог заказа и попадал в брак ODS.
- Что:
- скидка пересчитана от корзины после удаления отсутствующей позиции.
- сериализатор отклоняет отрицательные деньги через ValueError.
- добавлены проверки восьми стартовых дней и обновлена опись мира.
- Проверка:
- make lint, make typecheck и make test в generator/.
- живой world_next_day: 1694 строки приняты, таблица ошибок пуста.
Зачем: ревью в три линии нашло настоящий дефект. Девятая проверка кластера
звала dictGet('dds.products', …) — объекта после переноса не существует, и
make check-clickhouse падал. Промах вырос из недосчёта: упоминания dds.products
я искал с фильтром по расширениям, .sh туда не попал, и в ADR уехало «четыре
упоминания» вместо семи.
Что: проверка переведена на dic.products и сверяет цену, умножив её обратно на
сто, — так утверждается ещё и точность приведения к Decimal. Раздел 3
мастер-спеки и список пользователей README догнали перенос: оба описывали
отменённое устройство. В ADR 0012 добавлено условие пересмотра для дома — для
него его не было, хотя ради дома тикет и заводился; недосчёт записан в
«Что проверено» как урок. Разнобой обозначений сведён: карта таблиц в доке
хранилища перешла на имена баз строчными, таблица мастер-спеки — на заголовок
«Где», зону всюду зовут зоной, а не слоем. Термин «Справочник» переписан без
метафоры и уложен в формат глоссария. Вычтено лишнее: комментарии DDL
сократились вдвое, из ADR 0006 и 0007 убраны самооправдание и дублирующие
абзацы, отраслевой образец получил честную оговорку о непроверяемости.
Проверка: make config-test, make lint, make smoke и make check-clickhouse —
все зелёные, десять проверок кластера из десяти.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Зачем: горячее ревью поймало ошибку в трёх местах сразу. Было записано, что
после правки каталога ноды расходятся до тридцати секунд — число взято из
ширины окна LIFETIME(MIN 60 MAX 90). Ширина тут ни при чём: каждая нода ждёт
правки от нуля до верхней границы окна, фазы у них независимы, поэтому
расходиться они могут почти на все полторы минуты.
Что: исправлены ADR 0012, опорная точка мастер-спеки и комментарий DDL. Заодно
уточнено, что LIFETIME(0) неатомарность не предотвращал, а сжимал до разброса
исполнения SYSTEM RELOAD DICTIONARY ON CLUSTER, и что витрина выручки пока
спроектирована, а не построена.
Проверка: рассуждением, замером не подтверждалось — прежнее число тоже было
выведено, а не измерено. Замер в ADR (116 секунд на окне MIN 60 MAX 120)
относится к другому утверждению: что словарь обновляется сам.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Зачем: каждое утверждение о словаре было записано трижды — в доке хранилища, в
комментариях DDL и в ADR 0012. Правка поведения стоила бы трёх согласованных
правок, а расхождение между копиями обнаружилось бы не сразу. Дока хранилища —
карта, а не пересказ реализации.
Что: раздел «Справочники» сведён к своему уровню — правило принадлежности зоны,
топология на кластере, единицы денег и указатели. Механика (движок, форма пути,
пользователь, окно обновления) осталась только в sql/ddl/05-dic-catalog.sql,
рядом с кодом, который она объясняет. Блок «Что проверено» отправлен к замерам
ADR 0012 вместо их пересказа — так же, как он уже поступает с ADR 0005.
Проверка: минус 30 строк; ссылок на убранный подзаголовок в репозитории нет,
три относительные ссылки нового текста разрешаются в существующие файлы.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Зачем: место словаря в dds было унаследовано от первого объекта, а не решено.
Справочник читают несколько слоёв, а производит его в хранилище ни один —
прописка внутри одного из потребителей приписывала DDS владение, которого у
него нет.
Что: заведена база dic вне цепочки STG → ODS → DDS → DM, dds.products переехал
в dic.products. Под словарём появилась подложка dic.products_file на движке
File — намеренное усложнение ради урока: в бою источник словаря приезжает
процессом, а не лежит файлом у сервера. Источник объявлен формой query и
приводит цену из целых копеек каталога в Decimal(18, 2), как у денег бэкенда.
Обновление — окном LIFETIME(MIN 60 MAX 90) вместо ручной перезагрузки, ценой
заявленной неатомарности между нодами. У словаря свой беспарольный
пользователь dict с единственным правом на чтение dic. Суффикс _file добавлен
в конвенцию имён ADR 0006. Решение, отвергнутые варианты и условия пересмотра
— ADR 0012.
Проверка: make clean && make up на собранном заново стенде — зелено, make smoke
20 проверок и 0 ошибок, make lint чисто. Словарь LOADED со 180 строками, цена
Decimal(18, 2) и точна на копейках: 188990 → 1889.90. Пользователь bi читает
словарь dictGet-ом со второй ноды, analyst — подложку соединением, база dds
пуста. Минимальное право на движок замерено тремя пользователями: достаточно
GRANT FILE ON *.*, хотя отказ называет TABLE ENGINE ON File.
Closes#105
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Зачем:
- витринам нужен общий с генератором каталог, а менти — пример штатного обновления словаря.
- Что:
- каталог смонтирован read-only в обе ноды и создан как dds.products ON CLUSTER.
- роли получили dictGet, а check-clickhouse сверяет ответ под etl с исходным CSV.
- источник, раскладка и явная политика обновления записаны в документации.
- Проверка:
- make up с чистыми томами; make lint; make config-test; make smoke; make check-clickhouse.
- в generator: make lint typecheck test — 427 тестов прошли.
- Зачем:
- преобразования хранилища должны читаться рядом с целевым слоем, а DAG должен показывать оркестрацию.
- Что:
- запросы забора и разбора заказов разложены по каталогам STG и ODS.
- общий контракт провода подключён в обе ветви штатным шаблонизатором Airflow.
- SQL смонтирован во все службы Airflow, а правило раскладки записано в архитектуре.
- Проверка:
- make lint config-test smoke check-services.
- airflow tasks render для pull_batch и parse_batch; airflow tasks test для parse_batch.
- Зачем:
- менти должен различать версию заказа, наблюдение источника и запуск загрузки.
- Что:
- добавлены таблицы версий и брака заказов, а также представление ods.order_v.
- даг orders_ingest дополнен строгим переходом одного среза STG в две цели ODS.
- результаты опытов записаны в документации, дефект генератора вынесен в #102.
- Проверка:
- make lint config-test smoke check-clickhouse check-services.
Зачем:
- связать проигрывание модельных дней с пакетным приёмом заказов
- показать на одном стенде различие потокового push и пакетного pull
Что:
- добавлен топик, Kafka-чтец и реплицированное сырьё заказов
- добавлен даг orders_ingest с одним прямым чтением и идентификатором загрузки
- работники мира отправляют слепок, ждут приём и только затем двигают позицию
- решения, границы отказа и проверки отражены в ADR и архитектурных документах
Проверка:
- make lint
- make config-test
- make smoke
- make check-clickhouse
- make check-services
- Зачем:
- issue #91 требует решать исход и расхождение заказа в день его рождения.
- Что:
- добавлены три исхода, моменты оплаты и отмены и дельта одной позиции.
- обновлены проверки повторяемости и архитектурное описание заказов.
- Проверка:
- cd generator && make lint && make typecheck && make test (418 passed).
- Зачем:
- тикет #90: второй источник должен смотреть на торговую половину дня
глазами бэкенда — заказ есть проекция покупки, а не второе порождение;
учебный результат — два источника согласованы по построению, а не
сверкой.
- Что:
- `commerce` отдаёт вторым выходом покупки дня: номер заказа, корзину,
выручку клиента, промокод и человека за кукой; новых бросков в
подпоток `COMMERCE` не добавилось, события дня не сдвинулись.
- заведена заказная сторона: подпоток `ORDERS` на позиции 2 дерева зерна
(прежнее мёртвое имя `DISCREPANCIES`), ветвление — по дню рождения
заказа; `LATECOMERS` не тронут, его наполнит этап 6.
- новый модуль `orders.py`: деньги заказа целыми копейками —
`items_total` из корзины, `discount` по таблице «код → скидка»
(округление вниз), `delivery` броском по таблице весов на полную длину
дня, `total` = `items_total` − `discount` + `delivery`.
- план состава завёл `person_id` — последним броском когорты, после
паспортов: вторая кука пары повторяет ID своего человека, заказ
показывает его как `user_id`, в событие Метрики он не попадает.
- `world`: окно изменяемости `ORDER_WINDOW_DAYS` = 7 рядом с D0 и поясом,
черновая таблица стоимости доставки.
- слепок дня в тестах сторожит обе половины: заказы сравниваются наравне
с потоком событий.
- доки: имя подпотока заказной стороны и состав денег заказа записаны в
`docs/architecture/orders`, README генератора знает про новый модуль.
- Проверка:
- из `generator/`: make lint, make typecheck, make test (417 тестов);
в корне — make lint.
- опись мира не покраснела: байты восьми дней те же, заказная сторона
события не сдвинула.
Closes#90
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Зачем:
- потребителю ODS нужна точная актуальная версия события без знания о FINAL.
- Что:
- создано ods.event_v над распределённой таблицей событий с FINAL.
- сверка стартового мира переведена на новое представление.
- документация различает физические версии ODS и бизнес-представление DDS.
- Проверка:
- make config-test.
- make check-clickhouse.
Зачем: черновик этапов держал DDS заказа в этапе 3, а принятый набор
docs/architecture/orders/ оставляет модель DDS проектированию этапа 4
(ingestion.md «Не входит», тикет #85 перевешен на #6) — расхождение
всплыло на холодном ревью нарезки этапа (#89).
Что: в разделе 9 этап 3 сужен до STG/ODS и дага приёма, модель DDS
заказа названа работой этапа 4.
Проверка: чтение; нарезка этапа 3 (#90–#96) согласована с этой строкой.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Зачем: датированная спека — событие истории, а устройство компонента — живой
документ; большое полотно плохо грузится и агентом, и человеком (ADR 0011).
Что: вычитание #84 слито с переустройством формы: набор
docs/architecture/orders/ — индекс README и семь файлов по частям устройства
(нарезка по правилу «семь плюс-минус два»); датированные файлы удалены,
ссылки перенацелены, AGENTS.md дополнен правилом подпапки. Приёмка
владельцем #88 пройдена, черновой статус снят из README.
Проверка: холодная сверка миграции свежим тредом — потерь решений нет;
обход относительных ссылок набора — битых нет.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Зачем: решения развилок #70–#74, #80, #81 карты #69 разошлись по резолюциям
тикетов — цельная картина второго источника нужна в одном месте.
Что: черновик спеки заказов docs/specs/2026-08-16-orders.md и спека приёма
docs/specs/2026-08-16-order-ingestion.md; согласующие правки соседних
документов; правки горячего ревью и двух слепых холодных линий — дефекты
сборки закрыты, назван порядок строк внутри слепка.
Проверка: перепроверка находок теми же ревьюерами — ALL_CLOSED.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- документация не должна обещать постоянные числа для движущегося мира.
- Что:
- уточнено появление опоздавших заказов в слепках.
- опись ограничена неизменяемым выходом и счётчиками с читателем.
- счётчик пар оставлен плану, но исключён из описи.
- Проверка:
- CONTEXT.md перечитан целиком; git diff --check.
Зачем: взгляд владельца на генератор жил только в разговорах, и каждый
следующий агент восстанавливал его заново или не восстанавливал вовсе.
Без него решения по генератору принимаются не по тому критерию: внутренняя
стройность вместо правдоподобия данных на выходе.
Что: новый раздел «Чем меряется генератор» сразу после «Зачем» — пять
утверждений рамки. Генератор меряется выходом, а не устройством; менти
внутрь не смотрит, поэтому конструкция оправдана только наблюдаемым
эффектом; повторимы эффекты, а не числа, и хеши описи обещают видимость
сдвига, а не постоянство чисел; цена ошибки мала, поэтому оборона дороже
ошибки не заводится; сложность изолирована службой ради дешевизны правки.
Рамка шире этапа 2, поэтому спеки следующих этапов ссылаются на неё, а не
копируют.
Проверка: правка только текстовая, кода не касается.
Co-Authored-By: Claude Opus 5 (1M context) <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.
- Зачем:
- менти должен увидеть разделение доступа без состояния в томах.
- Что:
- пользователи и роли объявлены файлом с паролями из окружения.
- межшардовые запросы передают пользователя через общий секрет.
- четыре допущения реализации подтверждены в 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>
- Зачем:
- фраза «Date не участвует вовсе» выводила тип из-под общего правила:
про объявление это правда, про употребление — нет. Считая время по
EventDate без имени пояса, легко получить часы вне диапазона.
- Что:
- фраза заменена на две: Date хранит только номер дня, пояс при счёте
времени называют руками, промах виден по часам за границами 0–23.
- Проверка:
- замерено на стенде: без имени пояса часы от начала суток идут -4…19,
отрицательных 15 843 события; с названным поясом — 0…23
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>
ddadmin
