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

Стандарт уроков курса «Кликстрим на 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 и увидеть, как топик читается заново. Менти меняет — видит эффект — объясняет. Верни как было — каждая правка завершается явным шагом отката к чистому состоянию (откатить изменение либо make clean/up/ddl/data/transform), чтобы самостоятельный менти не застрял со сломанным стендом без ментора. (Урок 0 — без этого шага, только наблюдение.)
5. Проверь себя — самопроверка (раздел 3).
6. Принеси на сессию — конкретный артефакт плюс вопросы: скрин видимого результата правки (например, красный DAG или +1 в таблице ошибок), один абзац «своими словами» про паттерн урока или запрос, который пришлось написать. Артефакт делает самопроверку проверяемой, а сверку — предметной (критерий успеха PRD §5).

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 для сброса и повтора.

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