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

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

Это продвинутый курс «со звёздочкой» для тех, кто уже прошёл базовую программу. Ты
поднимаешь у себя живой стенд (Kafka + ClickHouse + Airflow + мониторинг + BI) и
проходишь по нему основные паттерны инженерии данных. Курс самодостаточный — он
рассчитан на то, что ты идёшь по нему сам: каждый урок объясняет, зачем нужен паттерн,
даёт потрогать его руками и проверить себя в конце.

Курс — блок «со звёздочкой» открытого роадмапа Data Engineer
([de.dementev.space](https://de.dementev.space/), он же
[на GitHub](https://github.com/dementev-dev/de-roadmap)).

> **Пройти можно самому — а можно с ментором.** В одиночку реально — курс для того и
> сделан. С ментором — быстрее, понятнее и чаще с лучшим результатом:
> персональный план под твою ситуацию, разбор затыков на еженедельном созвоне, код-ревью
> твоих правок и проверка, что ты понял тему вглубь, а не просто прокликал. Хочешь так —
> напиши в Telegram [@dementev_dev](https://t.me/dementev_dev).

## Что нужно до старта

- **База пройдена:** SQL, моделирование данных, Python, Git, Docker, Airflow. ClickHouse
  знать заранее не нужно — это и есть тема курса.
- **Обзорное видео по Kafka из роадмапа** — посмотри перед уроком 0. Оттуда ты возьмёшь
  словарь («топик», «партиция», «offset», «consumer-группа», «lag»), а урок 0 свяжет эти
  слова с живым стендом.
- **Железо:** стек тяжёлый — Kafka, ClickHouse, Airflow, Superset, Prometheus и Grafana
  поднимаются одновременно. Нужна машина, которая это потянет.
- **Инструменты:** `Docker` с `docker compose`, `make`, `bash`, `curl`, `git` и `uv`.
  `uv` нужен для локальных Python-проверок и команд разработки.
- **Подними стенд и создай стартовую историю** (из корня репозитория) — этого хватит,
  чтобы начать, и прогон быстрый:

  ```bash
  make generated-history-analytics
  make up
  ```

  Эта команда проводит штатный путь стенда: готовый источник данных создаёт стартовую
  историю, события попадают в Kafka, затем в STG, ODS, DDS, DM и Superset. Файлы
  `data/*.jsonl` пока остаются только кладовкой готовых значений для генератора
  (браузеры, страны, устройства, UTM), а не источником аналитического контура. `make up`
  после неё поднимает остальные UI-сервисы курса: Kafka UI, Airflow, Prometheus и Grafana.

  Дальше каждый урок в секции «Руки» сам напоминает, что перезапустить.
  Точные шаги, параметры и troubleshooting — в [`docs/OPERATIONS.md`](../OPERATIONS.md).

## Уроки

Проходи по порядку — уроки 0→4 повторяют сам пайплайн (Kafka → STG → ODS → DDS →
оркестрация), а 5 и 6 надстраиваются поверх готовых данных. В колонке «режим»:
**наблюдение** — только смотрим, **руки** — запускаешь и меняешь сам.

| # | Урок | Режим | О чём |
|---|------|-------|-------|
| 0 | [Вводный по Kafka](./lessons/00_kafka_intro.md) | наблюдение | Ходим по Kafka UI: где лежат события, кто их читает, как Kafka помнит, докуда дочитано |
| 1 | [Kafka → ClickHouse (STG)](./lessons/01_kafka_to_clickhouse.md) | руки | Как сообщение из топика становится строкой ClickHouse через Kafka engine и Materialized View |
| 2 | [STG → ODS: типизация и DQ-split](./lessons/02_stg_to_ods.md) | руки | Приводим сырьё к типам и разводим чистое и битое по разным таблицам |
| 3 | [ODS → DDS: сборка сущностей](./lessons/03_ods_to_dds.md) | руки | Собираем `click` и `event` из кусочков (argMax, JOIN) и встречаем «сирот» |
| 4 | [Оркестрация в Airflow](./lessons/04_airflow_orchestration.md) | руки | Всю цепочку — в один DAG с зависимостями и честным гейтом целостности |
| 5 | [Мониторинг: Prometheus и Grafana](./lessons/05_monitoring.md) | наблюдение + мини-правка | Смотрим систему со стороны; гасим сервис — видим, как краснеет алерт |
| 6 | [BI-витрина в Superset](./lessons/06_superset_bi.md) | руки (опционально) | Дашборд поверх ClickHouse: KPI, динамика, воронка |

## Как проходить

- **По одному уроку за раз** — ожидаемый темп около дня на урок (уроки короткие и
  односоставные: один паттерн на урок).
- **Каждый урок устроен одинаково:** зачем паттерн нужен → что запустить и понаблюдать →
  чтение эталонного кода → одна управляемая правка с видимым результатом → самопроверка.
  Любая правка завершается шагом **«верни как было»**, чтобы стенд не остался сломанным.
- **Идёшь сам** — опорой служат секции «Проверь себя» в конце каждого урока: по ним
  видно, понял ты тему или только пробежал глазами.
- **Идёшь с ментором** — еженедельный созвон покрывает несколько уроков сразу: туда
  несёшь затыки и ответы «своими словами» из тех же секций «Проверь себя».

## Проверка чистого маршрута

Перед проверкой уроков 0, 1 и 5 подними стенд с нуля:

```bash
make generated-history-analytics
make up
```

Что должен подтвердить человек:

- урок 0: в Kafka UI видны четыре топика событий и понятны служебные топики
  генератора;
- урок 1: после `CLEAN_START=0 make generated-history-analytics` учебная колонка
  `kafka_msg_ts` не пропадает и заполняется;
- урок 5: Prometheus targets `clickhouse`, `kafka`, `airflow` находятся в `UP`,
  а `Kafka No Messages Produced` трактуется с учётом того, запущен live-генератор
  или только стартовая история.

## Границы

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

---

## Под капотом курса (для автора и любопытных)

Эти документы менти для прохождения не нужны — они объясняют, как курс устроен и почему
именно так. Открывай, если ведёшь курс или хочешь заглянуть в его «исходники».

| Файл | Что это |
|------|---------|
| [`PRD.md`](./PRD.md) | Рамка: зачем курс, цели, аудитория, скоуп, критерии успеха (замороженный документ) |
| [`LEARNING_PLAN.md`](./LEARNING_PLAN.md) | План обучения: карта уроков, маршрут, аудит эталонных путей |
| [`LESSON_STANDARD.md`](./LESSON_STANDARD.md) | Стандарт уроков: шаблон, качество кода, самопроверка — рабочий чеклист при написании |