From dc0e6f9452312c2a0c685f899ca52adf9d7c12e5 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Mon, 1 Jun 2026 22:28:14 +0300 Subject: [PATCH] =?UTF-8?q?docs(course):=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2?= =?UTF-8?q?=D0=BB=D0=B5=D0=BD=20=D0=BF=D1=80=D0=BE=D0=B4=D0=B2=D0=B8=D0=BD?= =?UTF-8?q?=D1=83=D1=82=D1=8B=D0=B9=20=D0=BA=D1=83=D1=80=D1=81=20=C2=AB?= =?UTF-8?q?=D0=9A=D0=BB=D0=B8=D0=BA=D1=81=D1=82=D1=80=D0=B8=D0=BC=20=D0=BD?= =?UTF-8?q?=D0=B0=20ClickHouse=C2=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - превратить стенд в самостоятельный учебный материал (трек «со звёздочкой») для продвинутых менти. - Что: - docs/course/: PRD, LEARNING_PLAN, LESSON_STANDARD и README-индекс. - AGENTS.md: ссылка на курс в разделе навигации. - CLAUDE.md: @-include AGENTS.md для контекста агента. - Проверка: - открыть docs/course/README.md и пройти по ссылкам на PRD/план/стандарт. --- AGENTS.md | 1 + CLAUDE.md | 1 + docs/course/LEARNING_PLAN.md | 57 ++++++++++++++++ docs/course/LESSON_STANDARD.md | 65 ++++++++++++++++++ docs/course/PRD.md | 120 +++++++++++++++++++++++++++++++++ docs/course/README.md | 25 +++++++ 6 files changed, 269 insertions(+) create mode 100644 CLAUDE.md create mode 100644 docs/course/LEARNING_PLAN.md create mode 100644 docs/course/LESSON_STANDARD.md create mode 100644 docs/course/PRD.md create mode 100644 docs/course/README.md diff --git a/AGENTS.md b/AGENTS.md index f071ffc..2d366f5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,6 +34,7 @@ - [docs/OPERATIONS.md](./docs/OPERATIONS.md) — запуск, DAG-параметры, проверки и troubleshooting. - [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) — детали по слоям STG/ODS/DDS/DM. - [docs/COMMIT_RULES.md](./docs/COMMIT_RULES.md) — правила оформления коммитов. +- [docs/course/](./docs/course/) — продвинутый учебный курс «со звёздочкой» на базе стенда (PRD, план обучения, стандарт уроков); начинать с [docs/course/README.md](./docs/course/README.md). - [plans/](./plans/) — legacy-планы (использовать как исторический контекст, не как источник истины). ## Ограничения по структуре diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/docs/course/LEARNING_PLAN.md b/docs/course/LEARNING_PLAN.md new file mode 100644 index 0000000..7349f04 --- /dev/null +++ b/docs/course/LEARNING_PLAN.md @@ -0,0 +1,57 @@ +# План обучения: курс «Кликстрим на ClickHouse» + +> Статус: черновик (скелет). Дата: 2026-06-01. +> Назначение: высокоуровневый маршрут менти по курсу — карта уроков, порядок, +> результаты аудита эталонных путей. Рамка курса (зачем/что/скоуп) — в `PRD.md`; +> как устроен отдельный урок — в `LESSON_STANDARD.md`. +> +> Этот файл — стартовый скелет. Детальный аудит путей и финальные вердикты +> дописываются перед стартом уроков. + +--- + +## 1. Маршрут + +Порядок линейный — уроки 0→4 идут цепочкой, повторяя сам пайплайн. Мониторинг (4) +и Superset (5) более самостоятельны и работают как надстройки. + +**Что нужно знать заранее по Kafka:** перед уроком 0 менти смотрит обзорное видео по +Kafka из роадмапа — оно даёт словарь терминов. Урок 0 связывает этот словарь с тем, +что менти сразу видит в живом стенде. + +## 2. Карта уроков + +| # | Урок | Эталонный путь (файлы стенда) | Статус | Режим | +|---|------|-------------------------------|--------|-------| +| 0 | Вводный урок по Kafka | Kafka UI: топики, партиции, offset'ы, consumer-группы, отставание (lag) | обязательный | наблюдение | +| 1 | Заземление Kafka → ClickHouse | `sql/ddl/stg/10_stg.sql` (Kafka engine → MV → MergeTree) | обязательный | руки | +| 2 | Слоёный ETL: где MV, а где батч | `sql/ods/*`, `sql/dds/*`, `sql/dm/*` (батч поверх стримингового STG) | обязательный | руки | +| 3 | Оркестрация в Airflow | `airflow/dags/etl_pipeline_dag.py` (зависимости, проверки, остановка при нарушениях) | обязательный | руки | +| 4 | Мониторинг | Prometheus + Grafana + экспортёры | обязательный | наблюдение | +| 5 | BI-витрина | Superset поверх ClickHouse | опциональный | руки | + +Урок 0 — обязательная разминка (без правок кода, только наблюдение); уроки 1–3 — +с управляемыми правками; урок 4 ближе к наблюдению (глубину уточняем, см. +«Открытые вопросы» в `PRD.md`). + +## 3. Аудит эталонных путей + +Вердикт по каждому пути — один из трёх: **годно как есть / точечно править / +переписать** (критерии «учебного качества» — в `LESSON_STANDARD.md`). + +Предварительная оценка (до детального аудита): + +| Путь | Файлы | Вердикт (предв.) | Заметки | +|------|-------|------------------|---------| +| STG (Kafka→CH) | `sql/ddl/stg/10_stg.sql` | годно как есть | внятные русские комментарии, метаданные доставки, обработка ошибок, партиционирование | +| ETL слои | `sql/ods/*`, `sql/dds/*`, `sql/dm/*` | точечно править | логика и комментарии крепкие; проверить «тест одного прохода» | +| Airflow DAG | `airflow/dags/etl_pipeline_dag.py` | под вопросом | нужен детальный аудит | +| Мониторинг | `configs/*`, экспортёры | под вопросом | нужен детальный аудит | + +Финальные вердикты и список конкретных правок — дописать перед стартом уроков. + +## 4. Что дальше + +После согласования этого плана — пишем уроки по одному, по шаблону из +`LESSON_STANDARD.md`, начиная с урока 1 (Kafka→CH). Урок 0 (разминка на Kafka UI) +можно готовить параллельно — он не зависит от полировки кода. diff --git a/docs/course/LESSON_STANDARD.md b/docs/course/LESSON_STANDARD.md new file mode 100644 index 0000000..e10721f --- /dev/null +++ b/docs/course/LESSON_STANDARD.md @@ -0,0 +1,65 @@ +# Стандарт уроков курса «Кликстрим на ClickHouse» + +> Статус: черновик. Дата: 2026-06-01. +> Назначение: рабочий чеклист, по которому пишется **каждый** урок. Открывается при +> создании урока. Рамка курса (зачем/что/скоуп) — в `PRD.md`; карта уроков и +> маршрут — в `LEARNING_PLAN.md`. + +--- + +## 1. Шаблон урока + +Каждый урок строится по единому шаблону: + +1. **Зачем и где в проде** — что за паттерн и где он встречается в обычной + кликстрим-аналитике (без привязки к конкретной компании). +2. **Руки** — что запустить и что понаблюдать (Kafka UI / ClickHouse / Grafana). +3. **Загляни внутрь** — чтение отполированного эталонного кода с пояснениями. +4. **Управляемая правка** — одно-два маленьких изменения с **видимым результатом**. + Например: добавить поле в Materialized View и увидеть его в `*_raw`; «сломать» + запись и увидеть `+1` в таблице ошибок `parse_errors`; сменить `kafka_group_name` + и увидеть, как топик читается заново. Менти меняет — видит эффект — объясняет. + (Урок 0 — без этого шага, только наблюдение.) +5. **Проверь себя** — самопроверка (раздел 3). +6. **Принеси на сессию** — что доложить ментору и какие вопросы задать. + +## 2. Стандарт качества эталонного кода + +Эталонные пути полируем до **учебного качества**; остальной код стенда остаётся под +капотом — его не трогаем. + +**Чеклист (минимум).** Файл доведён, если: +1. комментарии на русском объясняют **зачем**, а не пересказывают код; +2. шаги явные и названы своими именами, без неочевидных трюков; +3. в начале файла — поток данных одной строкой (как в STG: + `Kafka → kafka_*_raw → MV → *_raw`); +4. ошибки и проверки качества данных видны — понятно, куда смотреть; +5. нет мусора: мёртвого кода, закомментированных экспериментов, разнобоя в именах. + +**Тест одного прохода (главный критерий и защита от громоздкости).** +> Менти читает файл один раз сверху вниз и может пересказать своими словами, +> *что* происходит и *зачем* — не прыгая по файлу, не гугля, не расшифровывая трюки. + +Если тест не проходит — правим строго одним из трёх способов: (1) упростить код; +(2) добавить ровно одну строку «зачем» там, где код честно неочевиден; (3) убрать +лишнее под капот или в короткую пометку. **Добавить ещё комментариев — не способ.** + +**Две защиты от раздувания:** +- комментируем только неочевидное «зачем» (очевидную строку комментировать нельзя — + лишний текст сам по себе мешает понимать); +- «близко к проду» ≠ «вся прод-сложность прямо в коде урока»: один прод-паттерн на + урок показываем чисто, остальные прод-заботы — короткой пометкой «в проде иначе: …». + +Вердикты аудита по конкретным путям — в `LEARNING_PLAN.md`. + +## 3. Самопроверка (по-простому) + +Отдельный тест-фреймворк не строим. Опираемся на то, что в стенде уже есть: +- штатные быстрые проверки (smoke) из `docs/TEST_PLAN.md`; +- встроенные проверки в `etl_pipeline_dag.py` (DAG падает на пустой витрине или + нарушении целостности); +- `make clean/up/ddl/data/transform` для сброса и повтора. + +В каждом уроке — маленькая табличка самопроверки в формате +**действие → где смотреть → что ожидать**, а для управляемой правки — какой +видимый результат должен появиться. diff --git a/docs/course/PRD.md b/docs/course/PRD.md new file mode 100644 index 0000000..cf5c573 --- /dev/null +++ b/docs/course/PRD.md @@ -0,0 +1,120 @@ +# PRD: продвинутый курс «Кликстрим на ClickHouse» (со звёздочкой) + +> Статус: черновик (прообраз PRD). Дата: 2026-06-01. +> Назначение документа: зафиксировать для будущих сессий, что это за курс, зачем +> он, что входит в скоуп работ, а что нет. Это договорная **рамка**, а не план +> реализации и не стандарт уроков (см. раздел «Связанные документы»). +> +> Язык документа: уровни называем единообразно — **курс** (вся программа) состоит +> из **уроков**. Соседние программы (например, 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–4 (обязательные):** вводный урок по Kafka, заземление Kafka→CH, слоёный + ETL (где Materialized View, а где батч), Airflow, мониторинг. +- **Аудит и точечная полировка эталонных путей** этих уроков до учебного качества + (стандарт — в `LESSON_STANDARD.md`). +- Учебная часть вокруг каждого эталонного пути по единому шаблону урока. + +Подробная карта уроков (файлы стенда, статус, режим, вердикты аудита) — в плане +обучения `LEARNING_PLAN.md`. + +### Опционально +- **Урок 5: Superset (BI-витрина).** Делаем, если останется ресурс; обязательные + уроки он не блокирует. + +### Не входит +- Переписывание всего стенда: полируем только эталонные пути обязательных уроков, + остальной код стенда остаётся под капотом. +- Lakehouse (Spark / Iceberg / Trino) — отдельный стенд, отдельный курс. +- Подготовка к трудоустройству: резюме, легенда, мок-собесы, привязка к конкретному + работодателю. Любые материалы под конкретного менти — вне этого репозитория + (репозиторий публичный; приватное — в менторской базе). +- Доведение стенда до промышленной надёжности (отказоустойчивость, безопасность, + масштабирование) — кроме коротких пометок «в проде иначе». + +## 5. Критерии успеха + +- Менти проходит урок за неделю **сам**, без построчного разбора с ментором. +- Может своими словами объяснить паттерн урока и привязать его к обычной + кликстрим-аналитике. +- На сессии приносит осмысленные вопросы по сути, а не «застрял на запуске». +- Эталонный код проходит «тест одного прохода» (см. `LESSON_STANDARD.md`). + +## 6. Связанные документы и порядок работ + +Порядок создания артефактов: + +1. **`PRD.md`** (этот документ) — рамка: что, зачем, скоуп. **Замороженный** документ. +2. **`LEARNING_PLAN.md`** — высокоуровневый план обучения: карта уроков, маршрут + менти, результаты аудита путей. Пишется после согласования PRD. +3. **`LESSON_STANDARD.md`** — стандарт уроков: шаблон урока, стандарт качества кода, + самопроверка. Рабочий чеклист, открывается при написании каждого урока. +4. **Уроки** — по одному, по шаблону из `LESSON_STANDARD.md`, начиная с урока 1 + (Kafka→CH). + +Навигация по всем файлам курса — в `docs/course/README.md`. + +Материалы под конкретного менти (под кого первый прогон, привязка к работодателю, +подготовка к собесам) — **вне этого репозитория**, в приватной менторской базе. + +## 7. Открытые вопросы / на будущее + +- Глубина урока 4 (мониторинг): сколько внутреннего устройства показывать против + «просто наблюдай дашборд». +- Нужна ли BI-витрина (Superset) уже в первой версии или переносим на следующую. +- Переиспользование: после первого прогона — ретроспектива и обобщение материала + под других менти. diff --git a/docs/course/README.md b/docs/course/README.md new file mode 100644 index 0000000..2dde4a1 --- /dev/null +++ b/docs/course/README.md @@ -0,0 +1,25 @@ +# Курс «Кликстрим на ClickHouse» (со звёздочкой) + +Продвинутый курс для менти, уже прошедших базовую программу: ключевые паттерны +инженерии данных на стенде Kafka + ClickHouse + Airflow + мониторинг. Самостоятельный +учебный материал; ментор подключается на еженедельной сессии-сверке. + +## Что где искать + +| Файл | Что это | Когда открывать | +|------|---------|-----------------| +| [`PRD.md`](./PRD.md) | Рамка: зачем курс, цели, аудитория, скоуп, критерии успеха | Чтобы понять «что и зачем». Замороженный документ | +| [`LEARNING_PLAN.md`](./LEARNING_PLAN.md) | План обучения: карта уроков, маршрут, аудит эталонных путей | Чтобы понять «в каком порядке и из чего» | +| [`LESSON_STANDARD.md`](./LESSON_STANDARD.md) | Стандарт уроков: шаблон урока, качество кода, самопроверка | Рабочий чеклист при написании каждого урока | +| `lessons/` *(будет)* | Сами уроки, по одному файлу | Прохождение курса менти | + +## Порядок чтения + +1. Новому участнику (или будущей сессии): начать с `PRD.md`, затем `LEARNING_PLAN.md`. +2. Перед написанием урока: держать открытым `LESSON_STANDARD.md`. + +## Границы + +Материалы под конкретного менти (привязка к работодателю, легенда, подготовка к +собесам) в этот репозиторий **не кладём** — репозиторий публичный, приватное живёт +в менторской базе.