ddadminandClaude Opus 5
b2fcc7e593
- Зачем: - тикет #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>
115 lines
10 KiB
Markdown
115 lines
10 KiB
Markdown
# Генератор кликстрима
|
||
|
||
Клиентская сторона стенда: отсюда берётся поток событий — широкое событие по
|
||
образцу облачной выгрузки Яндекс Метрики. Устройство и принятые решения —
|
||
спека [«Генератор (этап 2)»](../docs/specs/2026-08-01-generator.md).
|
||
|
||
События уже есть и уже уезжают: день-функция отдаёт по паре (зерно, D)
|
||
упорядоченный поток трёх видов — просмотр страницы, корзина, покупка, —
|
||
канонический сериализатор превращает его в JSON, а проигрыватель гонит в файл
|
||
или в Kafka. Клиентская сторона на этом целая. Второй источник строится:
|
||
день отдаёт и заказы бэкенда — проекцию своих покупок с деньгами магазина, —
|
||
а судьба заказа и отправка слепка идут следующими тикетами.
|
||
|
||
## Как это работает
|
||
|
||
> Раздел черновой. По сути он верен, но на понятность читателем со стороны не
|
||
> выверен: пишет его тот, кто держит устройство генератора в голове, а это
|
||
> худший судья понятности. Выверка — вместе с путеводителем, тикет #48.
|
||
|
||
Цепочка одна и всегда та же: корневое зерно → подпотоки по позиции в дереве
|
||
→ когорта дня (кто впервые пришёл, сколько раз вернётся, чей паспорт какой)
|
||
→ аудитория дня, то есть когорта плюс возвраты когорт окна → визиты этих кук
|
||
→ строки событий. Мир при этом ленив: когорта считается по требованию, а до
|
||
D0 живёт предыстория, поэтому любой день собирается сам по себе — прожитая
|
||
история для него не нужна и на него не влияет.
|
||
|
||
Главное правило для того, кто придёт следующим: **внутри подпотока порядок
|
||
бросков — часть контракта.** Броски раздаёт один генератор подряд, и k-й
|
||
бросок достаётся тому, кто спросил k-м. Приписать новый бросок в конец
|
||
функции безопасно: у прежних он ничего не отнимает. Вставить в середину —
|
||
значит сдвинуть все броски после него, а с ними и весь мир: события того же
|
||
дня станут другими, счётчики канонического мира разойдутся с описью, и
|
||
поймается это не ошибкой, а красным чеком. Ровно поэтому паспорта кук в
|
||
`plan.cohort` брошены последними, а личность человека приписана уже за ними:
|
||
куки, пары и паспорта остались теми же до байта.
|
||
|
||
Случайность целочисленная — только диапазоны и выбор по целым весам: готовые
|
||
распределения numpy расходятся между версиями и архитектурами, а обещано
|
||
побайтовое совпадение (спека, раздел 2). Отсюда `weights.py` вместо
|
||
`rng.choice` с вероятностями.
|
||
|
||
## Что где лежит
|
||
|
||
- `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`](../docs/formats/clickstream-event.md))
|
||
из контракта. Документ руками не правят — пересобирают.
|
||
- `src/clickstream_generator/inventory.py` — сборка описи мира
|
||
([`data/world-inventory.json`](../data/world-inventory.json)): паспорт мира
|
||
и хеши восьми дней, которыми наполняется стенд. Руками не правят —
|
||
пересобирают целью `make inventory`.
|
||
- `tests/` — инварианты контракта, свежесть описания и обещания мира:
|
||
чистота от зерна, приток, гарантия двухкуковых пар, форма суточной волны
|
||
и сборка визитов по задокументированным правилам. Там же побайтовое
|
||
обещание, доведённое до диска: два прогона дня в файл дают тот же файл, а
|
||
строк в нём ровно столько, сколько событий.
|
||
|
||
## Команды
|
||
|
||
Проиграть день — [быстрый старт](../README.md#как-позвать-генератор) и `--help`.
|
||
|
||
Из этого каталога — цели генератора живут здесь, а не в корне:
|
||
|
||
- `make test` — тесты генератора;
|
||
- `make lint` — ruff: проверка и формат;
|
||
- `make typecheck` — ty: проверка типов;
|
||
- `make docs` — пересобрать описание выгрузки;
|
||
- `make inventory` — пересобрать опись мира.
|
||
|
||
В корне репозитория `make lint` тоже есть, но он про код стенда — даги и
|
||
Superset. Одноимённые цели за разными дверями охватывают разное:
|
||
[карта проверок](../docs/architecture/testing.md).
|
||
|
||
Python и зависимости — через `uv`, версии закреплены в `uv.lock`: на этом
|
||
держится обещание побайтовой воспроизводимости (спека, раздел 2).
|