feat(generator): каркас проекта и контракт схемы события #44
Assignees
ddmitry (Dmitry Dementiev)
Clear assignees
ddmitry (Dmitry Dementiev)
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: ddmitry/clickstream-data-platform#44
Reference in New Issue
Block a user
Closes #36
Зачем
Этап 2 начинается с формы: контракт схемы — источник истины и для генерации
событий, и для DDL хранилища. Имена пакета и модулей задают границы всем
следующим тикетам этапа.
Что
generator/(pyproject.tomlиuv.lockв git; numpy,pytest, ruff), пакет
clickstream_generator.schema.py— контракт: чистые данные о 47 колонках выгрузки (имя Метрики,тип ClickHouse, тип numpy, нормализованное snake_case-имя, группа).
Порядок несёт сам кортеж
COLUMNS.schema_doc.pyсобирает из контракта описание выгрузкиdocs/formats/clickstream-event.md— по нему пишется сторона хранилища(#37, #43). Документ руками не правится.
сторожатся: правка контракта всплывает диффом пересобранного документа.
make lint,make test,make docs; README, AGENTS.md и CONTEXT.mdдополнены.
Ревью
Три линии: две Клодом (стандарты и постановка) и одна слепая Кодексом
(свежий тред, high) — все находки закрыты, перепроверка ревьюером
ALL_CLOSED. Приёмка владельца сняла с контракта лишние гвозди: имена для
DDS — не его решение.
Спека генератора (раздел 3) уточнена тем же PR: нормализованное имя — имя
источника в нашем стиле, а не имя атрибута в модели данных.
Проверка
make test— 248 тестов;make lint,make config-test;make docs, затемgit diff --exit-code docs/— пусто.- Зачем: - этап 2 начинается с формы: контракт схемы — источник истины и для генерации событий, и для DDL хранилища, а имена пакета и модулей задают границы всем следующим тикетам этапа. - Что: - заведён uv-проект generator/ (pyproject.toml и uv.lock в git; numpy, pytest и ruff), пакет clickstream_generator. - schema.py — контракт: чистые данные о 47 колонках выгрузки (имя Метрики, тип ClickHouse, тип numpy, имя для DDS, группа); порядок несёт сам кортеж COLUMNS, отдельного поля с номером нет намеренно. - schema_doc.py собирает из контракта описание выгрузки docs/formats/clickstream-event.md — по нему пишется сторона хранилища; документ руками не правится. - тесты: инварианты контракта (состав, уникальность, заполненность, согласие типов и порядок групп) и свежесть описания выгрузки. - цели make lint, make test и make docs; README, AGENTS.md и CONTEXT.md дополнены генератором, форматами и словарной статьёй. - Проверка: - make test (248 тестов), make lint, make config-test; - make docs, затем git diff --exit-code docs/ — пусто. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>- Зачем: - линия постановки: тест инвариантов обещал ловить дрейф колонок, но переименование Referer или перенос колонки в другую группу проходили все проверки; линия стандартов: докстринг говорил о contract-тесте как о существующем и не нёс следа сверки API через Context7. - Что: - тест состава по разделу 1.2 мастер-спеки: группа, имя и тип всех 47 колонок записаны независимо от контракта, поэтому молчаливое переименование или перестановка краснеют — проверено правкой Referer → Referrer. - контракт: contract-тест переведён в будущее время со ссылкой на спеку; записана сверка записи типов ClickHouse (Context7 и запрос к узлу стенда 26.3.17.56 — параметры входят в имя типа целиком). - описание выгрузки самодостаточнее: расшифрованы коды DeviceCategory, домен LastTrafficSource честно назван неполным, «идентификатор» сведён к «id» ради одного слова на одну вещь. - schema_doc: убраны неиспользуемые параметры render и main, row → table_row; тест строки сверяет свойство, а не форму. - Проверка: - make test (249 тестов), make lint; - make docs, затем git diff --exit-code docs/ — пусто. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>- Зачем: - слепая линия Кодекса (свежий тред, high) нашла три места, где обещание контракта не подкреплено: имена для DDS не сверялись ни с чем, порядок строк документа держался только на нумерации, а комментарий рекламировал торговые события, которые мастер-спека прямо исключила. - Что: - имена для DDS записаны независимо и сверяются целиком: они не выводятся правилом из имён Метрики, значит осмысленно неверное имя иначе молча уезжает в опубликованное описание (проверено подменой referer). - строки документа сверяются парами «номер, колонка»: рендер в другом порядке больше не проходит зелёным (проверено перевёрнутым рендером). - productEventType: detail и remove убраны из комментария — раздел 10 мастер-спеки отказался от полного словаря торговых событий Метрики; стенд шлёт add и purchase. - Проверка: - make test (250 тестов), make lint; - make docs, затем git diff --exit-code docs/ — пусто; - обе новые проверки проверены мутациями: каждая краснеет своим тестом. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>- Зачем: - контракт вёл себя как хозяин чужого слоя: поле называлось dds_name, в описании стоял столбец «Имя в DDS», а два теста прибивали имена гвоздями. Спека же задала вид имени (snake_case), а не список: имена атрибутов складывает модель данных DDS, и решать это не трекеру. - Что: - поле контракта и столбец описания стали нормализованным именем: имя источника в нашем стиле. В описании и в докстринге сказано прямо, что слой DDS называет атрибуты по своей модели. - сняты оба теста на имена — копия имён DDS и конспект состава по мастер-спеке. Они не проверяли верность имени, только неизменность, а неизменность и так сторожит пересборка описания: молчаливой правки контракта не бывает, она всплывает диффом документа. - остались проверки формы: 47 колонок, уникальность, стили имён, заполненность, согласие типов numpy и ClickHouse, порядок групп. - спека генератора (раздел 3) и CONTEXT.md согласованы тем же коммитом: уточнение внесено как расхождение, найденное при исполнении. - Проверка: - make test (248 тестов), make lint, make config-test; - make docs, затем git diff --exit-code docs/ — пусто. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>- Зачем: - запрет был лишним: dds.v_event по разделу 7 мастер-спеки эти имена и берёт, так что синоним не всегда ошибка. - Что: - в статье «Нормализованное имя» снята строка _Избегать_; различие с именем атрибута в модели данных осталось в теле статьи. - Проверка: - вычитка. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>