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

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

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

Курс — блок «со звёздочкой» открытого роадмапа Data Engineer (de.dementev.space, он же на GitHub).

Пройти можно самому — а можно с ментором. В одиночку реально — курс для того и сделан. С ментором — быстрее, понятнее и чаще с лучшим результатом: персональный план под твою ситуацию, разбор затыков на еженедельном созвоне, код-ревью твоих правок и проверка, что ты понял тему вглубь, а не просто прокликал. Хочешь так — напиши в Telegram @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-проверок и команд разработки.

Подготовка и канонический сброс

Первый запуск и возврат к чистому эталонному миру идут одним путём. При первом запуске пропусти make clean; для полного сброса выполни все три шага:

1. Выполни make clean. Команда удалит данные стенда и метаданные Superset: сохранённые в нём настройки и дашборды тоже придётся создать заново.
2. Выполни make up и открой Airflow на http://localhost:8080 (admin/admin). На свежем стенде DAG-и стоят на паузе. Подготовь и запусти их по порядку:
   • ddl_init — сними паузу и запусти с пустой формой;
   • etl_pipeline — только сними паузу: его вызовет следующий DAG;
   • world_init — сними паузу и запусти с пустой формой после успешного ddl_init.
3. Когда world_init завершится успешно и витрины DM будут готовы, выполни make superset-init.

Так события из эталонного мира попадут в Kafka, затем в STG, ODS, DDS и DM, а Superset получит готовые наборы данных и дашборд. Файлы data/*.jsonl остаются только кладовкой готовых значений для генератора (браузеры, страны, устройства, UTM), а не источником аналитического контура.

Точные параметры и разбор ошибок — в docs/OPERATIONS.md.

Уроки

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

#	Урок	Режим	О чём
0	Вводный по Kafka	наблюдение	Ходим по Kafka UI: где лежат события, кто их читает, как Kafka помнит, докуда дочитано
1	Kafka → ClickHouse (STG)	руки	Как сообщение из топика становится строкой ClickHouse через Kafka engine и Materialized View
2	STG → ODS: типизация и DQ-split	руки	Приводим сырьё к типам и разводим чистое и битое по разным таблицам
3	ODS → DDS: сборка сущностей	руки	Собираем click и event из кусочков (argMax, JOIN) и встречаем «сирот»
4	Оркестрация в Airflow	руки	Всю цепочку — в один DAG с зависимостями и честным гейтом целостности
5	Мониторинг: Prometheus и Grafana	наблюдение + мини-правка	Смотрим систему со стороны; гасим сервис — видим, как краснеет алерт
6	BI-витрина в Superset	руки	Дашборд поверх ClickHouse: KPI, динамика, воронка
7	Лаба: следующий день	руки	Пакетный инкремент дня и границы времени
8	Лаба: живое продолжение	руки	Живой поток и свежесть данных

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

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

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

Перед проверкой уроков 0, 1 и 5 пройди канонический сброс.

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

• урок 0: в Kafka UI видны четыре топика событий и понятны служебные топики генератора;
• урок 1: после запуска world_next_day учебная колонка kafka_msg_ts не пропадает и заполняется;
• урок 5: Prometheus targets clickhouse, kafka, airflow находятся в UP, а Kafka No Messages Produced трактуется с учётом того, включён живой поток или стенд работает на импортированной базе.

Границы

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

---

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

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

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