ddadmin
f56166181b
- Зачем:
- на уроке 2 решили писать разжёванным языком; уроки 0–1 и шапки курса
остались в сжатом регистре, а слово «черновик»/«Режим: руки» путало менти.
- Что:
- урок 1: расшифрованы staging, MergeTree-дедуп, Materialized View и
виртуальные колонки; секция «Загляни внутрь» разбита на ###-подзаголовки;
плотные абзацы разбиты на пункты; добавлен зачин «О чём урок простыми словами».
- урок 0: добавлен зачин «О чём урок простыми словами» (лёгкая полировка).
- шапки всех уроков: «Статус: черновик. Режим: руки/наблюдение» заменены на
понятное «Формат: практика/наблюдение — …».
- PRD/LEARNING_PLAN/LESSON_STANDARD: убрано слово «черновик» из статуса.
- Проверка:
- grep -rn "черновик" docs/course/ — пусто;
- прочитать урок 1 сверху вниз: термины раскрыты на первом употреблении.
74 lines
6.2 KiB
Markdown
74 lines
6.2 KiB
Markdown
# Стандарт уроков курса «Кликстрим на 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` в таблице ошибок) плюс один
|
|
абзац «своими словами» про паттерн урока или запрос, который пришлось написать. Это и
|
|
есть самопроверка (раздел 3); те же вопросы «своими словами» менти разбирает с ментором
|
|
на еженедельном созвоне. (Урок 0 — без правки, поэтому результат здесь — что менти
|
|
увидел при наблюдении.)
|
|
|
|
## 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` для сброса и повтора.
|
|
|
|
В каждом уроке — маленькая табличка самопроверки в формате
|
|
**действие → где смотреть → что ожидать**, а для управляемой правки — какой
|
|
видимый результат должен появиться.
|