docs(realism): границы применимости генератора кликстрима

- Зачем:
  - менти должен понимать, какой опыт со стенда переносится на бой
    напрямую, а какой требует поправки на учебные упрощения
    (тикет «Реализм генератора» карты боевого реализма, issue #11).
- Что:
  - docs/generator-realism.md: что честно как в бою (схема, воронка,
    сессии, суточная волна, обвязка) и что упрощено (четыре топика,
    только pageview, клонированные пользователи, нет «грязи», масштаб);
  - ссылка на документ в списке документации README.
- Проверка:
  - make test (210 + 31) зелёный.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

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) — задание, из которого вырос стенд.

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, боты и дедупликация, поведение
+под боевой нагрузкой.
+
+Развитие стенда в сторону боевого реализма обсуждается в трекере —
+карта «Боевой реализм стенда».