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 написан и
  синхронизирован с реальным дашбордом; остаётся опциональным (обязательные уроки не
  блокирует).

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

- Переиспользование: после **первого реального прогона менти** — ретроспектива и
  обобщение материала под других менти. Это валидация уже собранного курса, а не
  часть его подготовки.