clickstream-data-platform/CONTEXT.md

# Кликстрим-платформа (стенд v2)

Словарь понятий проекта: одни и те же слова для одних и тех же вещей —
у владельца, кода, документов и агентов. Только язык, никаких решений.

## Язык

**Хранилище**:
Аналитическая база стенда — кластер ClickHouse со слоями STG/ODS/DDS/DM.
Принимающая сторона границы «трекер | хранилище»: нормализует имена и стили
источников, строится по их документации.
_Избегать_: склад, склад данных

**Состав мира**:
Постоянная часть мира генератора — популяция посетителей, их привычки,
двухкуковые пары. По дням его выдаёт план состава.
_Избегать_: состояние мира

**План состава**:
Способ спросить состав мира: функция зерна, выдающая его по дням —
когорту новых кук, их возвраты, назначенные заказы двухкуковых пар.

**Подпоток**:
Ветвь дерева случайности генератора: своё зерно у состава мира, у каждого
дня и у каждого компонента дня. Подпоток задан позицией в дереве, а не
порядком вычислений.

**Конфигурация мира**:
Модуль чистых данных со всеми числами мира: приток, профили возвратов, доли
покупателей, D0. Правка модуля — смена мира. Модуль-близнец контракта схемы:
там колонки, здесь числа.

**Когорта дня**:
Люди, впервые пришедшие в мир в один день, со всеми их куками и днями
активности. Единица плана состава: когорта — функция зерна и номера дня.

**Человек**:
Устойчивая личность в составе мира, которой принадлежат одна или две куки.
Не поле источника: кликстрим видит куку, а заказ — пользователя магазина.

**Посетитель**:
Кука, наблюдаемая в кликстриме и обозначенная `ClientID`; единица
`uniq(ClientID)`. Один человек может быть представлен несколькими посетителями.
_Избегать_: «посетитель» про человека после склейки

**Пользователь магазина**:
Представление человека со стороны заказов; в записи заказа обозначается
`user_id`. Через заказы связывает разные куки человека, в кликстрим напрямую
не попадает.

**Приток**:
Появление новых кук на всём протяжении оси модельного времени; единица —
кука (`ClientID`). Из-за притока накопленная аудитория растёт с
горизонтом и не совпадает с дневной.

**Хвост возвратов**:
Окно активности, отсчитанное от первого дня человека и общее на обе
его куки; дольше окна кука не возвращается.

**Предыстория**:
Когорты плана с первым днём активности до D0; событий не порождают.

**День активности**:
День, в который кука хоть раз появилась в мире: день её рождения или день
возврата. Единица плана состава: за день он у куки один, а визитов внутри
него бывает несколько.
_Избегать_: визит (визит — про сессию)

**Визит**:
Подряд идущие события одной куки без пауз длиннее 30 минут, не пересекающие
границу суток. Поле `VisitID` — эталон для лабы сессий. «Сессия» — то же
понятие словами аналитики: в данных и в коде оно зовётся визитом, но имена
вроде «лаба сессий» и «сборка сессий» остаются.

**Паспорт куки**:
Устройство и город, приписанные куке на всю жизнь: кука — это браузер на
устройстве. Держит их план состава, разворачивает в поля события
день-функция; у двухкуковой пары город один на две куки, устройства разные.

**Покупатель**:
Человек, которого план состава пометил склонным покупать. Метка значима:
помеченный доходит до заказа заметно чаще прочих, но и непомеченный иногда
покупает. Из покупателей отбираются двухкуковые пары.
_Избегать_: «покупатель» про того, кто купил в конкретный день — это визит
с заказом.

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

**Торговое событие**:
Событие корзины или покупки — отдельная строка потока, а не просмотр
страницы. Садится на ту страницу, где случилось: корзина — на карточку
товара, покупка — на страницу подтверждения заказа.

**Каталог товаров**:
`data/catalog/products.csv` — общий справочник генератора и словаря
ClickHouse. Форма файла решена, длина — нет: строки дописываются.

**Уровень спроса**:
Свойство товара в каталоге: как часто открытую карточку кладут в корзину.
Три значения — магнит, обычный, залёживается. Постоянная часть мира, а не
поведение дня: он и делает конверсию «просмотр → корзина» по товарам и
брендам различимой.

**Ось модельного времени**:
Собственный календарь мира генератора. Дни считаются от фиксированного
первого дня D0; реальный календарь в модели не участвует. Между прогонами
живут только зерно и позиция на оси.

**Стартовый мир**:
Первые восемь дней оси (понедельник по понедельник), которыми стенд
наполняется при каждом `make up`. Маленький кусок эталонного мира, всегда
один и тот же: на нём принимаются следующие этапы.
_Избегать_: зерновой мир

**Опись мира**:
`data/world-inventory.json` — единственное, что о мире хранится в git:
паспорт (зерно, версия генератора, хеш каталога) и по строке на день с
датой, числом событий и хешем его байтов. Сам мир в git не лежит — он
пересчитывается. Опись отвечает на один вопрос: тот ли это мир.
_Избегать_: манифест, мини-манифест

**Пошаговый режим**:
Базовый способ движения по оси модельного времени: «прожить следующий
день» — явное действие.

**Живой день**:
Проигрывание текущего модельного дня в реальном времени с ускорением;
включается по требованию — постоянным фоном идёт, только пока включён
выключатель пульта.

**Пакетный режим**:
Проигрывание готового дня пачкой, без темпа: заливка снимка при старте
стенда, пересборки и проверки.

**Пульт мира**:
Даги Airflow, которыми двигают ось модельного времени: работники играют день —
пачкой или в темпе, — а выключатель держит стенд живущим, пока включён.
_Избегать_: управляющие даги

**Граница суток**:
Единственный структурный шов модели: сессии режутся по ней, слепок заказов
снимается на ней, день проживается только целиком.

**Контракт схемы**:
Python-модуль с описателями колонок события — собственность генератора.
Из него выводятся генератор, валидация и документация формата; хранилище
строится по документации, не по модулю.

**Нормализованное имя**:
Имя колонки источника, приведённое к нашему стилю (snake_case). Живёт в
контракте схемы и в описании выгрузки. Не то же, что имя атрибута в модели
данных: слой DDS складывает модель и называет атрибуты по ней.

**Описание выгрузки**:
Публичная документация формата события: таблица колонок, собранная из
контракта схемы. По ней пишется сторона хранилища — как в бою по документации
источника. Правится только контракт, документ пересобирается.
_Избегать_: описание схемы, документация контракта

**Канонический сериализатор**:
Единственное место, где событие превращается в байты. Фиксированный порядок
ключей и строк — основа побайтовой воспроизводимости.

**Проигрыватель**:
Компонент доставки готового потока дня в приёмник. Два режима: пакетный
(пачкой, без темпа) и живой день.

**Слепок**:
Полная выгрузка заказов окна изменяемости, снятая бэкендом на границе суток:
состояние заказов на этот момент, а не поток их изменений. Один заказ
приезжает в стольких слепках, сколько дней окна он прожил.

**Окно изменяемости**:
Сколько модельных дней заказ ещё может измениться и потому продолжает ездить
в слепках. Константа мира: семь дней. За окном заказ замёрз, выручка дня
перестала «дышать».

**Пакетный забор**:
Способ приёма топика, при котором данные тянет запрос по команде, а не
матвью непрерывно. Так стенд принимает заказы: у слепка есть начало и конец,
и забирать его уместно тогда, когда он собран целиком. Противоположность —
потоковый приём событий.
_Избегать_: путать с приёмником и пакетным режимом — те про сторону
генератора, про отправку; забор — про сторону хранилища, про чтение.