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

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

Статус: прообраз PRD. Дата: 2026-06-01. Поправка 2026-06-03 (разморозка по делу): середина пайплайна расщеплена — ODS и DDS теперь разные уроки (принцип «один паттерн на урок»), витрины DM демотированы в поверхность потребления. Обязательных уроков стало 0–5, опциональный Superset — урок 6. Затронуты §4 (скоуп) и §3/§5 (ожидаемый такт — ~день на урок). Это изменение рамки, а не план реализации. Поправка 2026-06-03 (терминология): режим сопровождения — еженедельный созвон, а не «сессия»; менти проходит материал сам и ничего «не приносит», а на созвоне ментор разбирает затыки и проверяет глубину понимания. Затронуты §1, §3, §5. Назначение документа: зафиксировать для будущих сессий, что это за курс, зачем он, что входит в скоуп работ, а что нет. Это договорная рамка, а не план реализации и не стандарт уроков (см. раздел «Связанные документы»).

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

---

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

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

data/*.jsonl → Kafka → ClickHouse (Kafka engine + MV → STG) → Airflow ETL (STG→ODS→DDS→DM) → Superset
                                                              ↘ Prometheus / Grafana (мониторинг)

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

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

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).

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

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

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

4. Скоуп

Входит

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

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

Опционально

• Урок 6: Superset (BI-витрина). Делаем, если останется ресурс; обязательные уроки он не блокирует.

Не входит

• Переписывание всего стенда: полируем только эталонные пути обязательных уроков, остальной код стенда остаётся под капотом.
• 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-06-14). Устройство генератора вышло сложным (марковская модель, нетривиальный Python), а цель менти — быстро потренироваться в ClickHouse/Kafka. Вопрос: делать ли отдельный урок про генератор (возможный «урок 7») или оставить генератор скрытой инфраструктурой и адаптировать существующие уроки, не вводя марковские цепи и сложный Python в путь менти. Решение зависит от удобства стенда: если он поднимается одной командой и есть короткий runbook (см. бэклог фичи генератора, .scratch/generator-model-time-startup-history/issues/08-startup-history-portable-artifact-and-usage-docs.md), отдельный урок, скорее всего, не нужен.