ddadminandClaude Fable 5
c28f724706
- Зачем:
- трекер стенда был полным, и правило «деньги — по бэкенду» держалось
на слове; классы B и D делают недосчет и пересчет трекера
наблюдаемыми (этап 6, #184).
- Что:
- подпоток BEACONS: точечная потеря purchase (~3%) и сюжетный дубль
(~2%) швом после _purchases, с гарантией моста идентичностей и
условием допуска дубля по паузе до следующего визита;
- опись считает пять классов по приоритету спеки; фильтр
classes_vs_inventory расширен, нулевой класс читается нулем;
- fate.md, seeds.md, dm.md и orders/README.md приведены к имени
BEACONS и строгому правилу допуска.
- Проверка:
- make lint, make typecheck, make test (433 passed) и make inventory
из generator/ — хеши слепков не изменились;
- на стенде: make smoke, make check-clickhouse, make check-services
зеленые; в dq_summary classes_vs_inventory и sessions_vs_reference
pass, витрина сверки показывает lost_event и duplicate_event.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Генератор кликстрима
Клиентская сторона стенда: отсюда берётся поток событий — широкое событие по образцу облачной выгрузки Яндекс Метрики. Устройство и принятые решения — спека «Генератор (этап 2)».
События уже есть и уже уезжают: день-функция отдаёт по паре (зерно, D) упорядоченный поток трёх видов — просмотр страницы, корзина, покупка, — канонический сериализатор превращает его в JSON, а проигрыватель гонит в файл или в Kafka. Клиентская сторона на этом целая. Второй источник строится: день отдаёт и заказы бэкенда — проекцию своих покупок с деньгами магазина, — а судьба заказа и отправка слепка идут следующими тикетами.
Как это работает
Корневое зерно ветвится на подпотоки, из них складываются когорты, аудитория дня, визиты, строки событий и заказы. План поднимает состав мира по требованию, а день-функция проживает один день без накопленного состояния. Код этой цепочки, ее схема и запуск D0 собраны в путеводителе.
Что где лежит
src/clickstream_generator/world.py— конфигурация мира: все его числа одним местом. Правка любого — смена мира; крутить их и предлагается.src/clickstream_generator/seeds.py— иерархия зёрен: кто из какого подпотока берёт случайность. На ней держится весь детерминизм.src/clickstream_generator/plan.py— план состава: кто есть в мире в день D. Когорты, приток, двухкуковые пары, паспорта кук, человек за кукой и счётчики — до генерации событий.src/clickstream_generator/weights.py— выбор по целым весам: один приём на весь генератор, чтобы дисциплина целочисленной случайности не жила копиями.src/clickstream_generator/reference.py— справочники: устройства, города, источники трафика, карта сайта. Таблицы-литералы: доля живёт в строке, которой принадлежит.src/clickstream_generator/catalog.py— каталог товаров изdata/catalog/products.csv, общего у генератора и словаря ClickHouse.src/clickstream_generator/day.py— день-функция: визиты, страницы, атрибуция, устройство и гео. Там же правила резки визитов и шов, на который садятся торговые события; прожитый день отдаёт обе половины — поток событий и заказы.src/clickstream_generator/commerce.py— торговые события: что легло в корзину, что из этого куплено, деньги, номера заказов и сыройecommerce. Своя случайность, поэтому правка торговли трафик не двигает.src/clickstream_generator/orders.py— заказы бэкенда: вторая проекция покупки. Личность покупателя и деньги магазина — скидка по промокоду, доставка, итог; своя случайность, ветвящаяся по дню рождения заказа.src/clickstream_generator/ids.py— номера событий: неповторяющиеся и ниже 2^53. Обещание одно на обе половины дня, поэтому и живёт отдельно.src/clickstream_generator/serialize.py— канонический сериализатор: единственное место, где событие целиком превращается в JSON. Порядок ключей, все 47 колонок всегда и форма на проводе — ISO-8601.src/clickstream_generator/sinks.py— приёмники: файл (одно событие — одна строка) и Kafka (одно событие — одно сообщение). Про содержимое они не знают; там же довод, почему у сообщения нет ключа.src/clickstream_generator/player.py— проигрыватель: гонит дни в приёмник пачкой или с темпом живого дня. Состояния не хранит.src/clickstream_generator/cli.py— интерфейс запуска: параметры аргументами или окружением, логи в стандартный вывод, итог кодом возврата.src/clickstream_generator/schema.py— контракт схемы: чистые данные о колонках выгрузки. Собственность генератора; из него выводятся сам генератор, его валидация и описание выгрузки в доках.src/clickstream_generator/schema_doc.py— сборка «описания выгрузки» (docs/formats/clickstream-event.md) из контракта. Документ руками не правят — пересобирают.src/clickstream_generator/inventory.py— сборка описи мира (data/world-inventory.json): паспорт мира и хеши восьми дней, которыми наполняется стенд, плюс счётчики классов расхождений по заказам для дней с закрытым окном. Руками не правят — пересобирают цельюmake inventory.tests/— инварианты контракта, свежесть описания и обещания мира: чистота от зерна, приток, гарантия двухкуковых пар, форма суточной волны и сборка визитов по задокументированным правилам. Там же побайтовое обещание, доведённое до диска: два прогона дня в файл дают тот же файл, а строк в нём ровно столько, сколько событий.
Команды
Проиграть день — быстрый старт и --help.
Из этого каталога — цели генератора живут здесь, а не в корне:
make test— тесты генератора;make lint— ruff: проверка и формат;make typecheck— ty: проверка типов;make demo— пройти стадии канонического D0 на одном экране;make docs— пересобрать описание выгрузки;make inventory— пересобрать опись мира.
В корне репозитория make lint тоже есть, но он про код стенда — даги и
Superset. Одноимённые цели за разными дверями охватывают разное:
карта проверок.
Python и зависимости — через uv, версии закреплены в uv.lock: на этом
держится обещание побайтовой воспроизводимости (спека, раздел 2).