ddadminandClaude Opus 4.8
f4d3118a42
- Зачем: - нужен первый урок курса по эталонному пути STG, а рамка курса описывала сопровождение как «сессию-сверку», хотя по факту это самостоятельная работа + еженедельный созвон. - Что: - добавлен docs/course/lessons/01_kafka_to_clickhouse.md (Kafka → ClickHouse, слой STG) по шаблону LESSON_STANDARD. - в sql/ddl/stg/10_stg.sql исправлен баг kafka_ts во всех 4 MV: toInt64(DateTime64) срезал миллисекунды, kafka_ts по всему стенду был 1970-01-21; теперь _timestamp_ms присваивается напрямую (downstream на kafka_ts не опирается). - урок 1 §3/§4 приведены к исправленному коду; врезка про рассинхрон MV↔таблица описывает реальное поведение (молчаливый сброс лишней колонки, не ошибка). - «сессия/сессия-сверка» → «созвон» в PRD (датированная поправка), LESSON_STANDARD §6 (секция «Что должно получиться») и README курса; добавлена ссылка на открытый DE-роадмап. - в LEARNING_PLAN исправлен вердикт аудита урока 1 (баг найден прогоном), war-story про toInt64(DateTime64) припаркована в урок 2. - Проверка: - прогон на стенде: make up && make ddl && LIMIT=50 make data → kafka_ts = 2026-… с миллисекундами; правка §4 (ALTER + пересоздание MV + TRUNCATE + перезаливка) и откат отработали. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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` для сброса и повтора.
|
|
|
|
В каждом уроке — маленькая табличка самопроверки в формате
|
|
**действие → где смотреть → что ожидать**, а для управляемой правки — какой
|
|
видимый результат должен появиться.
|