Files

T

ddadminandClaude Opus 5 722dbe22b7 feat(generator): торговые события — корзина, покупка, сырой ecommerce

- Зачем:
  - клиентская сторона мира становится целой: без add_to_cart и purchase
    в данных нет ни таксономии событий, ни вложенного JSON, ни денег,
    а метка «покупатель» из плана состава ни на что не влияла (#40).
- Что:
  - добавлен модуль commerce: корзина шире заказа, номер заказа вида
    ГГГГММДД-NNNN, промокод без скидки в сумме, сырой ecommerce через orjson;
  - метка покупателя получила два рычага — долгую жизнь куки в плане и
    свою воронку в дне; CART_PERCENT опущен с 8 до 6, чтобы конверсия
    мира осталась около 2%;
  - часть цен каталога получила копейки: productPrice округляется форматом,
    purchaseRevenue несёт точную сумму — расхождение живёт внутри события;
  - граница суток забирает страницу подтверждения вместе с её покупкой:
    потерь на клиентской стороне этот этап не заводит;
  - решения и перемеренные числа мира записаны в спеку генератора, §9.
- Проверка:
  - make lint && make typecheck && make test — 383 passed (было 353).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-02 19:13:30 +03:00

7.1 KiB

Raw Blame History

Генератор кликстрима

Клиентская сторона стенда: отсюда берётся поток событий — широкое событие по образцу облачной выгрузки Яндекс Метрики. Устройство и принятые решения — спека «Генератор (этап 2)».

События уже есть: день-функция отдаёт по паре (зерно, D) упорядоченный поток трёх видов — просмотр страницы, корзина, покупка. Клиентская сторона на этом целая; заказы бэкенда и запуск снаружи — за следующими тикетами.

Как это работает

Раздел черновой. По сути он верен, но на понятность читателем со стороны не выверен: пишет его тот, кто держит устройство генератора в голове, а это худший судья понятности. Выверка — вместе с путеводителем, тикет #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/ids.py — номера событий: неповторяющиеся и ниже 2^53. Обещание одно на обе половины дня, поэтому и живёт отдельно.
src/clickstream_generator/schema.py — контракт схемы: чистые данные о колонках выгрузки. Собственность генератора; из него выводятся сам генератор, его валидация и описание выгрузки в доках.
src/clickstream_generator/schema_doc.py — сборка «описания выгрузки» (docs/formats/clickstream-event.md) из контракта. Документ руками не правят — пересобирают.
tests/ — инварианты контракта, свежесть описания и обещания мира: чистота от зерна, приток, гарантия двухкуковых пар, форма суточной волны и сборка визитов по задокументированным правилам.

Команды

Из корня репозитория:

make test — тесты генератора;
make lint — ruff: проверка и формат;
make typecheck — ty: проверка типов;
make docs — пересобрать описание выгрузки.

Python и зависимости — через uv, версии закреплены в uv.lock: на этом держится обещание побайтовой воспроизводимости (спека, раздел 2).

7.1 KiB Raw Blame History Unescape Escape

Генератор кликстрима

Как это работает

Что где лежит

Команды

7.1 KiB

Raw Blame History