clickstream-ch-kafka-superset-demo/docs/course/PRD.md

PRD: продвинутый курс «Кликстрим на ClickHouse» (со звёздочкой)

Статус: прообраз PRD. Дата: 2026-06-01. Поправка 2026-06-03 (разморозка по делу): середина пайплайна расщеплена — ODS и DDS теперь разные уроки (принцип «один паттерн на урок»), витрины DM демотированы в поверхность потребления. Superset вынесен в урок 6. Затронуты §4 (скоуп) и §3/§5 (ожидаемый такт — ~день на урок). Это изменение рамки, а не план реализации. Поправка 2026-06-03 (терминология): режим сопровождения — еженедельный созвон, а не «сессия»; менти проходит материал сам и ничего «не приносит», а на созвоне ментор разбирает затыки и проверяет глубину понимания. Затронуты §1, §3, §5. Поправка 2026-07-04 (целеполагание): §1 расширен — зафиксировано место стенда в экосистеме менторской программы (теория и лабы по ClickHouse живут в других местах, здесь — интеграции «как в жизни») и иерархия целей вплоть до генератора. Демо-материалы (шпаргалки 5 и 10–15 минут) устарели и удалены: демо выросло в отдельный проект и целью стенда больше не является. Схема потока в §1 обновлена под генератор (источник данных сменился, см. ADR-0006). В §7 закрыта развилка про урок о генераторе и добавлена развилка про кластерную конфигурацию. Поправка 2026-07-23 (маршрут курса): зафиксированы три режима работы с миром — импорт эталонной базы, пакетная дозаливка следующего дня и живое продолжение. Урок 6 стал обязательным, после него добавлены обязательные лабы 07–08. Затронуты §1–4 и §7. Назначение документа: зафиксировать для будущих сессий, что это за курс, зачем он, что входит в скоуп работ, а что нет. Это договорная рамка, а не план реализации и не стандарт уроков (см. раздел «Связанные документы»).

Язык документа: уровни называем единообразно — курс (вся программа) состоит из уроков. Соседние программы (например, Lakehouse) — отдельные курсы.

---

1. Контекст и назначение

Репозиторий — рабочий сквозной стенд кликстрим-DWH:

generator (импорт / живой поток) → Kafka → ClickHouse (Kafka engine + MV → STG) → Airflow ETL (STG→ODS→DDS→DM) → Superset
                                                                           ↘ Prometheus / Grafana (мониторинг)

Стенд близок к продакшену и показывает несколько паттернов инженерии данных на связке Kafka + ClickHouse + Airflow + мониторинг. ClickHouse не входит в базовую программу обучения — это продвинутый курс «со звёздочкой» для менти, уже прошедших базу (SQL, моделирование, Python, Git, Docker, Airflow).

Место стенда в менторской программе (2026-07-04)

Трек ClickHouse для продвинутых менти состоит из трёх частей, и у каждой своя роль:

• Теория — внешние курсы (бесплатный курс Яндекса или запись курса Отус). Здесь теорию не пересказываем.
• Лабы по самому ClickHouse — отдельный стенд clickhouse-learning-cluster: полноценный кластер, но без внешних интеграций.
• Этот стенд — то, чего нет в первых двух: ClickHouse в окружении «как в жизни». Интеграции (Kafka, Airflow), мониторинг и BI поверх. Ниша стенда — не сам ClickHouse, а инженерия данных вокруг него.

Иерархия целей внутри репозитория:

1. Курс — главная цель. Всё остальное — средства.
2. Стенд — носитель курса. Должен подниматься одной командой, давать правдоподобные данные (пирамида «пользователи < визиты < события», суточная волна, возвраты) и быстро воспроизводиться.
3. Генератор — скрытая инфраструктура стенда. Его задача — живые данные: стартовая история плюс живое продолжение. Учебным предметом не является (решение — §7); пользовательская граница — «как пользоваться», не «как устроен».

Демо-употребление стенда (шпаргалки на 5 и 10–15 минут) устарело: демо выросло в отдельный проект и целью этого репозитория больше не является (2026-07-04, материалы удалены).

Цель курса — превратить стенд в самостоятельный учебный материал, по которому продвинутый менти проходит ключевые паттерны сам, а ментор подключается на обычном еженедельном созвоне (что получилось / что нет / вопросы / план на неделю). Долгий разбор кода вживую форматом не предусмотрен — поэтому материал обязан быть самодостаточным.

2. Цели (чему учим)

К концу курса менти умеет:

1. Заземлять поток из Kafka в ClickHouse через Kafka engine и Materialized View (ClickHouse сам забирает сообщения из топика), понимая роль топиков, партиций, offset'ов и consumer-групп.
2. Строить слоёный ETL (STG → ODS → DDS → DM) и объяснять, где уместен Materialized View (стриминговое приземление данных), а где батч (так удобнее управлять и наблюдать за пересчётом).
3. Читать и объяснять оркестрацию в Airflow: DAG, зависимости задач, проверки качества данных, остановку пайплайна при нарушениях.
4. Понимать, как устроен мониторинг пайплайна (метрики, экспортёры, дашборды).
5. Подключать BI-витрину поверх ClickHouse (Superset).
6. Различать пакетную дозаливку дня и живой поток, понимать границы времени и свежесть данных.

Сквозная цель — не «посмотреть, как работает», а уметь пересказать паттерн своими словами и привязать его к обычной кликстрим-аналитике (трекер событий → Kafka → ClickHouse → BI).

3. Аудитория и режим

• Аудитория: продвинутые менти, прошедшие базовую программу. Пишем обобщённо, но затачиваем под реальный первый прогон, а не под гипотетических будущих менти.
• Режим: самостоятельный, асинхронный. Менти клонирует репозиторий, готовит стенд по канонической инструкции и идёт по урокам из docs/course/ рядом с кодом. Уроки короткие и односоставные — ожидаемый срок прохождения одного около дня.
• Роль ментора: еженедельный созвон-сверка (покрывает несколько уроков), без построчного разбора кода.
• Железо: стек тяжёлый (Kafka + ClickHouse + Airflow + Superset + Prometheus + Grafana одновременно). Считаем наличие подходящего железа данностью; стек не режем на части — это усложнило бы жизнь и менти, и автору материала.

4. Скоуп

Входит

• Уроки 0–6 (обязательные): вводный урок по Kafka, заземление Kafka→CH, STG→ODS (типизация + DQ), ODS→DDS (сборка сущностей), Airflow, мониторинг. Принцип нарезки — один прод-паттерн на урок; контраст «где Materialized View, а где батч» проходит мостом уроков 1→2. Урок 6 закрывает BI-слой в Superset.
• Лабы 07–08 (обязательные): пакетная дозаливка следующего дня, затем живое продолжение потока.
• Витрины DM — не отдельный урок: их показываем в деле там, где их потребляют (мониторинг и BI). См. LEARNING_PLAN.md §1–2.
• Аудит и точечная полировка эталонных путей этих уроков до учебного качества (стандарт — в LESSON_STANDARD.md).
• Учебная часть вокруг каждого эталонного пути по единому шаблону урока.

Подробная карта уроков (файлы стенда, статус, режим, вердикты аудита) — в плане обучения LEARNING_PLAN.md.

Не входит

• Переписывание всего стенда: полируем только эталонные пути обязательных уроков, остальной код стенда остаётся под капотом.
• Lakehouse (Spark / Iceberg / Trino) — отдельный стенд, отдельный курс.
• Подготовка к трудоустройству: резюме, легенда, мок-собесы, привязка к конкретному работодателю. Любые материалы под конкретного менти — вне этого репозитория (репозиторий публичный; приватное — в менторской базе).
• Доведение стенда до промышленной надёжности (отказоустойчивость, безопасность, масштабирование) — кроме коротких пометок «в проде иначе».

5. Критерии успеха

• Менти проходит урок сам, без построчного разбора с ментором (ожидаемый срок — около дня на урок: уроки короткие и односоставные).
• Может своими словами объяснить паттерн урока и привязать его к обычной кликстрим-аналитике.
• На созвоне задаёт осмысленные вопросы по сути, а не «застрял на запуске».
• Эталонный код проходит «тест одного прохода» (см. LESSON_STANDARD.md).

6. Связанные документы и порядок работ

Порядок создания артефактов:

1. PRD.md (этот документ) — рамка: что, зачем, скоуп. По умолчанию заморожен; меняется только осознанной поправкой с датой и причиной в шапке (как 2026-06-03).
2. LEARNING_PLAN.md — высокоуровневый план обучения: карта уроков, маршрут менти, результаты аудита путей. Пишется после согласования PRD.
3. LESSON_STANDARD.md — стандарт уроков: шаблон урока, стандарт качества кода, самопроверка. Рабочий чеклист, открывается при написании каждого урока.
4. Уроки — по одному, по шаблону из LESSON_STANDARD.md, начиная с урока 1 (Kafka→CH).

Навигация по всем файлам курса — в docs/course/README.md.

Материалы под конкретного менти (под кого первый прогон, привязка к работодателю, подготовка к собесам) — вне этого репозитория, в приватной менторской базе.

7. Открытые вопросы / на будущее

Закрыто при написании уроков (2026-06-06):

• Глубина урока 5 (мониторинг): сколько устройства показывать против «просто наблюдай дашборд». Решено: взяли мини-правку «погаси сервис → алерт краснеет» (зеркало урока 4) — урок 5 даёт «сломал-увидел», а не чистое наблюдение. См. LEARNING_PLAN.md §3.1.
• Нужна ли BI-витрина (Superset) уже в первой версии. Решено: урок 6 написан и синхронизирован с реальным дашбордом. С 2026-07-23 он входит в обязательный маршрут.

Закрыто позже:

• Генератор как инфраструктура против отдельного урока (открыто, 2026-06-14). Решено (2026-07-04): отдельного урока про генератор не будет — генератор остаётся скрытой инфраструктурой. Причина: устройство генератора (марковская модель, нетривиальный Python) — это разработка бэкенда и математика, а не инженерия данных; такой урок не попадает в цели курса, и менти его не ожидает. Существующие уроки адаптируем без ввода марковских цепей и сложного Python в путь менти (задача — .scratch/generator-model-time-startup-history/issues/08-migrate-course-from-archive-seed.md). Удобство стенда (одна команда + короткий runbook) остаётся отдельной задачей (.scratch/generator-model-time-startup-history/issues/07-startup-history-portable-artifact-and-usage-docs.md) и делает адаптацию уроков проще, но решение от неё больше не зависит.

Остаётся на будущее:

• Переиспользование: после первого реального прогона менти — ретроспектива и обобщение материала под других менти. Это валидация уже собранного курса, а не часть его подготовки.
• Кластерная конфигурация ClickHouse (открыто, 2026-07-04). Сейчас стенд — одноузловой ClickHouse; кластер живёт в соседнем clickhouse-learning-cluster. Развилка: оставить разделение «здесь интеграции, там кластер» или доработать этот стенд до кластера — «всё в одном» удобнее и ближе к промышленной системе, но ощутимо утяжеляет стенд (ресурсы, конфигурация, сложность уроков) и размывает нишу learning-cluster. Решение не принято.