clickstream-data-platform/generator/README.md

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

Клиентская сторона стенда: отсюда берётся поток событий — широкое событие по
образцу облачной выгрузки Яндекс Метрики. Устройство и принятые решения —
спека [«Генератор (этап 2)»](../docs/specs/2026-08-01-generator.md).

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

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

Корневое зерно ветвится на подпотоки, из них складываются когорты, аудитория
дня, визиты, строки событий и заказы. План поднимает состав мира по требованию,
а день-функция проживает один день без накопленного состояния. Код этой
цепочки, ее схема и запуск D0 собраны в
[путеводителе](../docs/architecture/generator/README.md).

## Что где лежит

- `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/` — инварианты контракта, свежесть описания и обещания мира:
  чистота от зерна, приток, гарантия двухкуковых пар, форма суточной волны
  и сборка визитов по задокументированным правилам. Там же побайтовое
  обещание, доведённое до диска: два прогона дня в файл дают тот же файл, а
  строк в нём ровно столько, сколько событий.

## Команды

Проиграть день — раздел [«Как запустить
генератор»](../docs/architecture/world.md#как-запустить-генератор)
справочника мира и `--help`.

Из этого каталога — цели генератора живут здесь, а не в корне:

- `make test` — тесты генератора;
- `make lint` — ruff: проверка и формат;
- `make typecheck` — ty: проверка типов;
- `make demo` — пройти стадии канонического D0 на одном экране;
- `make docs` — пересобрать описание выгрузки;
- `make inventory` — пересобрать паспорт мира.

В корне репозитория `make lint` тоже есть, но он про код стенда — даги и
Superset. Одноимённые цели за разными дверями охватывают разное:
[карта проверок](../docs/architecture/testing.md).

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