From 068d96ff0ecf6d92577e3965f98d3009a115553d Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Wed, 22 Jul 2026 19:10:16 +0300 Subject: [PATCH] =?UTF-8?q?docs(realism):=20=D0=B3=D1=80=D0=B0=D0=BD=D0=B8?= =?UTF-8?q?=D1=86=D1=8B=20=D0=BF=D1=80=D0=B8=D0=BC=D0=B5=D0=BD=D0=B8=D0=BC?= =?UTF-8?q?=D0=BE=D1=81=D1=82=D0=B8=20=D0=B3=D0=B5=D0=BD=D0=B5=D1=80=D0=B0?= =?UTF-8?q?=D1=82=D0=BE=D1=80=D0=B0=20=D0=BA=D0=BB=D0=B8=D0=BA=D1=81=D1=82?= =?UTF-8?q?=D1=80=D0=B8=D0=BC=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - менти должен понимать, какой опыт со стенда переносится на бой напрямую, а какой требует поправки на учебные упрощения (тикет «Реализм генератора» карты боевого реализма, issue #11). - Что: - docs/generator-realism.md: что честно как в бою (схема, воронка, сессии, суточная волна, обвязка) и что упрощено (четыре топика, только pageview, клонированные пользователи, нет «грязи», масштаб); - ссылка на документ в списке документации README. - Проверка: - make test (210 + 31) зелёный. Co-Authored-By: Claude Fable 5 --- README.md | 2 + docs/generator-realism.md | 78 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 80 insertions(+) create mode 100644 docs/generator-realism.md diff --git a/README.md b/README.md index e88b0d4..b32e929 100644 --- a/README.md +++ b/README.md @@ -164,6 +164,8 @@ flowchart LR - [Runbook стартовой истории](./docs/runbooks/startup-history.md) — экспорт, импорт эталонного мира из Git по умолчанию и live-продолжение. - [Карта репозитория](./docs/REPO_MAP.md) — где какие файлы и что менять. +- [Реализм генератора](./docs/generator-realism.md) — что в потоке как в бою, + а что учебная условность. - [Курс «Кликстрим на ClickHouse»](./docs/course/README.md) — учебная программа на этом стенде. - [DE-task.md](./docs/DE-task.md) — задание, из которого вырос стенд. diff --git a/docs/generator-realism.md b/docs/generator-realism.md new file mode 100644 index 0000000..ac96d43 --- /dev/null +++ b/docs/generator-realism.md @@ -0,0 +1,78 @@ +# Насколько генератор похож на настоящий кликстрим + +Стенд генерирует поток событий интернет-магазина. Этот документ честно +отвечает: что здесь как в бою, а что — учебная условность. Он нужен, +чтобы менти понимал, какой опыт со стенда переносится на реальную +работу напрямую, а какой требует поправки на упрощение. + +Дата оценки: 2026-07-22 (по коду `generator/src/clickstream_generator/`). + +## Что близко к бою + +**Схема событий.** Поля узнаваемы для любого продуктового трекера: +идентификаторы события и визита (`event_id`, `click_id`), страница и +UTM-атрибуция (`utm_source/medium/campaign/content`, `referer_medium`), +браузер и user agent, устройство и ОС, гео с координатами и IP, +идентификатор пользователя. Разговоры об атрибуции, сессиях и +размерностях по этому опыту — честные. + +**Воронка.** Путь `/home → /product → /cart → /payment → /confirmation` +задан матрицей переходов с реалистичными недоходами и возвратами: +в корзину уходит ~27% с товара, из корзины до оплаты — 42%. Конверсию +и отвал по шагам менти считает на данных, которые ведут себя как живые. + +**Сессии.** Визит — в среднем ~10 событий; паузы между событиями +случайны (логнормальное распределение, медиана ~20 секунд) с потолком +29 минут — фактически классический 30-минутный таймаут сессии из +веб-аналитики. + +**Суточная волна.** Интенсивность зависит от часа: рабочие часы ×1.2, +ночь ×0.7, поверх — случайный разброс. Сравнение «день к дню» и +разговор о сезонности внутри суток — по-настоящему. + +**Инженерная обвязка.** JSON-события в Kafka, слои STG/ODS/DDS/DM, +«грязные» записи не валят пайплайн (уходят в таблицы ошибок ODS), +manifest с контрольными суммами и воспроизводимый эталонный мир. +Это боевые практики, а не учебные упрощения. + +## Что упрощено + +**Четыре топика вместо одного события.** Реальные трекеры (Snowplow, +Segment, Amplitude) отдают одно широкое событие со всеми атрибутами. +Здесь событие разрезано на четыре потока (browser, location, device, +geo), которые надо склеивать по ключам. Как модель доставки кликстрима +это условность; как упражнение — честная интеграция нескольких +источников, обычная работа дата-инженера. + +**Только просмотры страниц.** Нет событий `add_to_cart` и `purchase` +с суммой заказа — воронка выводится из URL. Поэтому нет выручки и +GMV-метрик, которые в бою спрашивают в первую очередь. + +**Пользователи клонируются из словаря.** Новые визиты собираются из +небольшого набора заготовок: количество разных пользователей, устройств +и гео ограничено. У каждого визита есть email пользователя — в бою +большинство трафика анонимно, и склейка идентичностей (identity +stitching) — отдельная большая задача, которой стенд не показывает. + +**Нет «грязи» реального мира.** Ни ботов, ни дублей событий, ни +опоздавших мобильных батчей, ни расхождения часов клиента и коллектора +(в бою у события минимум две метки времени). Чистка и дедупликация — +только в теории. + +**Масштаб демо.** Объёмы на порядки меньше боевых: вопросы +партиционирования под нагрузкой, ретеншена и стоимости хранения стенд +не поднимает. + +## Что это значит для обучения + +Можно честно говорить «делал руками»: приём потока из Kafka в +ClickHouse, слоистое DWH, сессии и воронка, UTM-атрибуция, сверка +контрольных чисел, воспроизводимость мира, инкрементальность против +полной перезагрузки. + +Требует теории поверх стенда: формат доставки у реальных трекеров, +выручка и GMV, identity stitching, боты и дедупликация, поведение +под боевой нагрузкой. + +Развитие стенда в сторону боевого реализма обсуждается в трекере — +карта «Боевой реализм стенда».