# Стандарт уроков курса «Кликстрим на 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` для сброса и повтора.

В каждом уроке — маленькая табличка самопроверки в формате
**действие → где смотреть → что ожидать**, а для управляемой правки — какой
видимый результат должен появиться.