ddadminandClaude Opus 5
61bc156d6a
Зачем: модельный день прогоняется только руками, и владельцу нечем проверять процессы стенда вживую. Этап 3 без дага не существует вовсе (ADR 0008), поэтому форму пульта и способ вызова генератора надо решить раньше кода. Что: ADR 0009 — работники без расписания (`world_next_day` пачкой, `world_live_day` в темпе) и выключатель `world_live` без своей работы, ждущий дочерний прогон триггером, а не сенсором; генератор зовётся `DockerOperator` в каноническом контейнере, потому что в образе Airflow ему не жить (Python 3.14 против 3.13); позиция ставится как «последний сыгранный + 1» — правило вместо сторожа, и его мягкий худший исход назван. Плата за сокет докера снята замером: доступ открывается добавлением GID в контейнер, правка прав на хосте не нужна, а сам GID — локальная настройка в `.env`. Пакетная автоматика отложена, не отвергнута. Расхождения внесены в спеку генератора: позицию ставит сыгравший, у живого дня появился выключатель. В словарь добавлен «пульт мира». Проверка: `make config-test` зелёный; API Airflow 3.3 (пауза и ручной запуск, ожидание триггера по идентификатору прогона, привязка сенсора к логической дате, `DockerOperator`) сверено через MCP Context7; версия Python в образе и права сокета — замером. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
173 lines
12 KiB
Markdown
173 lines
12 KiB
Markdown
# Кликстрим-платформа (стенд v2)
|
||
|
||
Словарь понятий проекта: одни и те же слова для одних и тех же вещей —
|
||
у владельца, кода, документов и агентов. Только язык, никаких решений.
|
||
|
||
## Язык
|
||
|
||
**Хранилище**:
|
||
Аналитическая база стенда — кластер ClickHouse со слоями STG/ODS/DDS/DM.
|
||
Принимающая сторона границы «трекер | хранилище»: нормализует имена и стили
|
||
источников, строится по их документации.
|
||
_Избегать_: склад, склад данных
|
||
|
||
**Состав мира**:
|
||
Постоянная часть мира генератора — популяция посетителей, их привычки,
|
||
двухкуковые пары. По дням его выдаёт план состава.
|
||
_Избегать_: состояние мира
|
||
|
||
**План состава**:
|
||
Способ спросить состав мира: функция зерна, выдающая его по дням —
|
||
когорту новых кук, их возвраты, назначенные заказы двухкуковых пар.
|
||
|
||
**Подпоток**:
|
||
Ветвь дерева случайности генератора: своё зерно у состава мира, у каждого
|
||
дня и у каждого компонента дня. Подпоток задан позицией в дереве, а не
|
||
порядком вычислений.
|
||
|
||
**Конфигурация мира**:
|
||
Модуль чистых данных со всеми числами мира: приток, профили возвратов, доли
|
||
покупателей, D0. Правка модуля — смена мира. Модуль-близнец контракта схемы:
|
||
там колонки, здесь числа.
|
||
|
||
**Когорта дня**:
|
||
Люди, впервые пришедшие в мир в один день, со всеми их куками и днями
|
||
активности. Единица плана состава: когорта — функция зерна и номера дня.
|
||
|
||
**Приток**:
|
||
Появление новых кук на всём протяжении оси модельного времени; единица —
|
||
кука (`ClientID`). Из-за притока накопленная аудитория растёт с
|
||
горизонтом и не совпадает с дневной.
|
||
|
||
**Хвост возвратов**:
|
||
Окно активности, отсчитанное от первого дня человека и общее на обе
|
||
его куки; дольше окна кука не возвращается.
|
||
|
||
**Предыстория**:
|
||
Когорты плана с первым днём активности до D0; событий не порождают.
|
||
|
||
**День активности**:
|
||
День, в который кука хоть раз появилась в мире: день её рождения или день
|
||
возврата. Единица плана состава: за день он у куки один, а визитов внутри
|
||
него бывает несколько.
|
||
_Избегать_: визит (визит — про сессию)
|
||
|
||
**Визит**:
|
||
Подряд идущие события одной куки без пауз длиннее 30 минут, не пересекающие
|
||
границу суток. Поле `VisitID` — эталон для лабы сессий. «Сессия» — то же
|
||
понятие словами аналитики: в данных и в коде оно зовётся визитом, но имена
|
||
вроде «лаба сессий» и «сборка сессий» остаются.
|
||
|
||
**Паспорт куки**:
|
||
Устройство и город, приписанные куке на всю жизнь: кука — это браузер на
|
||
устройстве. Держит их план состава, разворачивает в поля события
|
||
день-функция; у двухкуковой пары город один на две куки, устройства разные.
|
||
|
||
**Покупатель**:
|
||
Человек, которого план состава пометил склонным покупать. Метка значима:
|
||
помеченный доходит до заказа заметно чаще прочих, но и непомеченный иногда
|
||
покупает. Из покупателей отбираются двухкуковые пары.
|
||
_Избегать_: «покупатель» про того, кто купил в конкретный день — это визит
|
||
с заказом.
|
||
|
||
**День-функция**:
|
||
Функция (зерно, номер дня), выдающая упорядоченный поток событий этих
|
||
модельных суток. Состояния между днями нет: день D не зависит от того,
|
||
прожиты ли дни до него.
|
||
|
||
**Торговое событие**:
|
||
Событие корзины или покупки — отдельная строка потока, а не просмотр
|
||
страницы. Садится на ту страницу, где случилось: корзина — на карточку
|
||
товара, покупка — на страницу подтверждения заказа.
|
||
|
||
**Каталог товаров**:
|
||
`data/catalog/products.csv` — общий справочник генератора и словаря
|
||
ClickHouse. Форма файла решена, длина — нет: строки дописываются.
|
||
|
||
**Уровень спроса**:
|
||
Свойство товара в каталоге: как часто открытую карточку кладут в корзину.
|
||
Три значения — магнит, обычный, залёживается. Постоянная часть мира, а не
|
||
поведение дня: он и делает конверсию «просмотр → корзина» по товарам и
|
||
брендам различимой.
|
||
|
||
**Ось модельного времени**:
|
||
Собственный календарь мира генератора. Дни считаются от фиксированного
|
||
первого дня D0; реальный календарь в модели не участвует. Между прогонами
|
||
живут только зерно и позиция на оси.
|
||
|
||
**Стартовый мир**:
|
||
Первые восемь дней оси (понедельник по понедельник), которыми стенд
|
||
наполняется при каждом `make up`. Маленький кусок эталонного мира, всегда
|
||
один и тот же: на нём принимаются следующие этапы.
|
||
_Избегать_: зерновой мир
|
||
|
||
**Опись мира**:
|
||
`data/world-inventory.json` — единственное, что о мире хранится в git:
|
||
паспорт (зерно, версия генератора, хеш каталога) и по строке на день с
|
||
датой, числом событий и хешем его байтов. Сам мир в git не лежит — он
|
||
пересчитывается. Опись отвечает на один вопрос: тот ли это мир.
|
||
_Избегать_: манифест, мини-манифест
|
||
|
||
**Пошаговый режим**:
|
||
Базовый способ движения по оси модельного времени: «прожить следующий
|
||
день» — явное действие.
|
||
|
||
**Живой день**:
|
||
Проигрывание текущего модельного дня в реальном времени с ускорением;
|
||
включается по требованию, не постоянный фон.
|
||
|
||
**Пакетный режим**:
|
||
Проигрывание готового дня пачкой, без темпа: заливка снимка при старте
|
||
стенда, пересборки и проверки.
|
||
|
||
**Пульт мира**:
|
||
Даги Airflow, которыми двигают ось модельного времени: работники играют день —
|
||
пачкой или в темпе, — а выключатель держит стенд живущим, пока включён.
|
||
_Избегать_: управляющие даги
|
||
|
||
**Граница суток**:
|
||
Единственный структурный шов модели: сессии режутся по ней, слепок заказов
|
||
снимается на ней, день проживается только целиком.
|
||
|
||
**Контракт схемы**:
|
||
Python-модуль с описателями колонок события — собственность генератора.
|
||
Из него выводятся генератор, валидация и документация формата; хранилище
|
||
строится по документации, не по модулю.
|
||
|
||
**Нормализованное имя**:
|
||
Имя колонки источника, приведённое к нашему стилю (snake_case). Живёт в
|
||
контракте схемы и в описании выгрузки. Не то же, что имя атрибута в модели
|
||
данных: слой DDS складывает модель и называет атрибуты по ней.
|
||
|
||
**Описание выгрузки**:
|
||
Публичная документация формата события: таблица колонок, собранная из
|
||
контракта схемы. По ней пишется сторона хранилища — как в бою по документации
|
||
источника. Правится только контракт, документ пересобирается.
|
||
_Избегать_: описание схемы, документация контракта
|
||
|
||
**Канонический сериализатор**:
|
||
Единственное место, где событие превращается в байты. Фиксированный порядок
|
||
ключей и строк — основа побайтовой воспроизводимости.
|
||
|
||
**Проигрыватель**:
|
||
Компонент доставки готового потока дня в приёмник. Два режима: пакетный
|
||
(пачкой, без темпа) и живой день.
|
||
|
||
**Слепок**:
|
||
Полная выгрузка заказов окна изменяемости, снятая бэкендом на границе суток:
|
||
состояние заказов на этот момент, а не поток их изменений. Один заказ
|
||
приезжает в стольких слепках, сколько дней окна он прожил.
|
||
|
||
**Окно изменяемости**:
|
||
Сколько модельных дней заказ ещё может измениться и потому продолжает ездить
|
||
в слепках. Константа мира: семь дней. За окном заказ замёрз, выручка дня
|
||
перестала «дышать».
|
||
|
||
**Пакетный забор**:
|
||
Способ приёма топика, при котором данные тянет запрос по команде, а не
|
||
матвью непрерывно. Так стенд принимает заказы: у слепка есть начало и конец,
|
||
и забирать его уместно тогда, когда он собран целиком. Противоположность —
|
||
потоковый приём событий.
|
||
_Избегать_: путать с приёмником и пакетным режимом — те про сторону
|
||
генератора, про отправку; забор — про сторону хранилища, про чтение.
|