ddadminandClaude Opus 5
35dc933d29
Зачем: модельный день прогонялся только руками, и владельцу нечем было проверять процессы стенда вживую. Пульт нужен раньше этапа 3 и независимо от него: он обкатывает то, что приёму заказов понадобится готовым — вызов генератора из задачи Airflow. Что: `dags/world_control.py` — три дага по ADR 0009. Работники `world_next_day` (день пачкой, «сколько дней» параметром) и `world_live_day` (день в темпе) живут без расписания и без паузы; выключатель `world_live` создаётся на паузе, тикает раз в 25 минут и дёргает работника живого дня с ожиданием конца. Генератор зовётся `DockerOperator` в каноническом контейнере: сокет докера отдан планировщику, потому что при LocalExecutor задачи исполняет он, а GID группы `docker` уехал в `.env` как локальная настройка. Позицию на оси ведёт переменная `world_position` — её ставит сыгравший день работник и только по успеху. Факты стенда — образ, сеть, брокер, топик, размер стартового мира — даги получают окружением от compose; внутри compose они названы по разу якорями, иначе разошлись бы с разовой службой генератора. README получил раздел про пульт с названной вслух платой за сокет. Проверка: `make lint`, `make config-test`, `make smoke` (20/0), `make check-services` (7/0), `make check-clickhouse` (9/9) — зелёные. На чистом стенде: два прогона `world_next_day` подряд двигают позицию на два дня, «дней = 3» — на три, все пять дней доехали в ODS; обрыв контейнера позицию не двигает, повторный запуск играет тот же день с тем же счётом событий. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
12 KiB
Кликстрим-платформа (стенд 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 складывает модель и называет атрибуты по ней.
Описание выгрузки: Публичная документация формата события: таблица колонок, собранная из контракта схемы. По ней пишется сторона хранилища — как в бою по документации источника. Правится только контракт, документ пересобирается. Избегать: описание схемы, документация контракта
Канонический сериализатор: Единственное место, где событие превращается в байты. Фиксированный порядок ключей и строк — основа побайтовой воспроизводимости.
Проигрыватель: Компонент доставки готового потока дня в приёмник. Два режима: пакетный (пачкой, без темпа) и живой день.
Слепок: Полная выгрузка заказов окна изменяемости, снятая бэкендом на границе суток: состояние заказов на этот момент, а не поток их изменений. Один заказ приезжает в стольких слепках, сколько дней окна он прожил.
Окно изменяемости: Сколько модельных дней заказ ещё может измениться и потому продолжает ездить в слепках. Константа мира: семь дней. За окном заказ замёрз, выручка дня перестала «дышать».
Пакетный забор: Способ приёма топика, при котором данные тянет запрос по команде, а не матвью непрерывно. Так стенд принимает заказы: у слепка есть начало и конец, и забирать его уместно тогда, когда он собран целиком. Противоположность — потоковый приём событий. Избегать: путать с приёмником и пакетным режимом — те про сторону генератора, про отправку; забор — про сторону хранилища, про чтение.