docs(course): добавлен продвинутый курс «Кликстрим на ClickHouse»
- Зачем: - превратить стенд в самостоятельный учебный материал (трек «со звёздочкой») для продвинутых менти. - Что: - docs/course/: PRD, LEARNING_PLAN, LESSON_STANDARD и README-индекс. - AGENTS.md: ссылка на курс в разделе навигации. - CLAUDE.md: @-include AGENTS.md для контекста агента. - Проверка: - открыть docs/course/README.md и пройти по ссылкам на PRD/план/стандарт.
This commit is contained in:
@@ -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-планы (использовать как исторический контекст, не как источник истины).
|
||||
|
||||
## Ограничения по структуре
|
||||
|
||||
@@ -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)
|
||||
можно готовить параллельно — он не зависит от полировки кода.
|
||||
@@ -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` для сброса и повтора.
|
||||
|
||||
В каждом уроке — маленькая табличка самопроверки в формате
|
||||
**действие → где смотреть → что ожидать**, а для управляемой правки — какой
|
||||
видимый результат должен появиться.
|
||||
@@ -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) уже в первой версии или переносим на следующую.
|
||||
- Переиспользование: после первого прогона — ретроспектива и обобщение материала
|
||||
под других менти.
|
||||
@@ -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`.
|
||||
|
||||
## Границы
|
||||
|
||||
Материалы под конкретного менти (привязка к работодателю, легенда, подготовка к
|
||||
собесам) в этот репозиторий **не кладём** — репозиторий публичный, приватное живёт
|
||||
в менторской базе.
|
||||
Reference in New Issue
Block a user