ddmitry/clickstream-ch-kafka-superset-demo

Files

T

ddadminandClaude Opus 4.8 f4d3118a42 docs(course): добавлен урок 1 и выровнена рамка под созвоны

- Зачем:
  - нужен первый урок курса по эталонному пути STG, а рамка курса описывала сопровождение как «сессию-сверку», хотя по факту это самостоятельная работа + еженедельный созвон.
- Что:
  - добавлен docs/course/lessons/01_kafka_to_clickhouse.md (Kafka → ClickHouse, слой STG) по шаблону LESSON_STANDARD.
  - в sql/ddl/stg/10_stg.sql исправлен баг kafka_ts во всех 4 MV: toInt64(DateTime64) срезал миллисекунды, kafka_ts по всему стенду был 1970-01-21; теперь _timestamp_ms присваивается напрямую (downstream на kafka_ts не опирается).
  - урок 1 §3/§4 приведены к исправленному коду; врезка про рассинхрон MV↔таблица описывает реальное поведение (молчаливый сброс лишней колонки, не ошибка).
  - «сессия/сессия-сверка» → «созвон» в PRD (датированная поправка), LESSON_STANDARD §6 (секция «Что должно получиться») и README курса; добавлена ссылка на открытый DE-роадмап.
  - в LEARNING_PLAN исправлен вердикт аудита урока 1 (баг найден прогоном), war-story про toInt64(DateTime64) припаркована в урок 2.
- Проверка:
  - прогон на стенде: make up && make ddl && LIMIT=50 make data → kafka_ts = 2026-… с миллисекундами; правка §4 (ALTER + пересоздание MV + TRUNCATE + перезаливка) и откат отработали.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-03 23:03:24 +03:00

11 KiB

Raw Blame History

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. Цели (чему учим)

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

Заземлять поток из Kafka в ClickHouse через Kafka engine и Materialized View (ClickHouse сам забирает сообщения из топика), понимая роль топиков, партиций, offset'ов и consumer-групп.
Строить слоёный ETL (STG → ODS → DDS → DM) и объяснять, где уместен Materialized View (стриминговое приземление данных), а где батч (так удобнее управлять и наблюдать за пересчётом).
Читать и объяснять оркестрацию в Airflow: DAG, зависимости задач, проверки качества данных, остановку пайплайна при нарушениях.
Понимать, как устроен мониторинг пайплайна (метрики, экспортёры, дашборды).
(Опционально) Подключать 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. Связанные документы и порядок работ

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

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

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

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

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

Глубина урока 5 (мониторинг): сколько внутреннего устройства показывать против «просто наблюдай дашборд». Кандидат — мини-правка «погаси сервис → алерт краснеет» (зеркало урока 4), см. LEARNING_PLAN.md §3.1.
Нужна ли BI-витрина (Superset) уже в первой версии или переносим на следующую.
Переиспользование: после первого прогона — ретроспектива и обобщение материала под других менти.

11 KiB Raw Blame History Unescape Escape