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>
6.2 KiB
Стандарт уроков курса «Кликстрим на ClickHouse»
Статус: черновик. Дата: 2026-06-01. Назначение: рабочий чеклист, по которому пишется каждый урок. Открывается при создании урока. Рамка курса (зачем/что/скоуп) — в
PRD.md; карта уроков и маршрут — вLEARNING_PLAN.md.
1. Шаблон урока
Каждый урок строится по единому шаблону:
- Зачем и где в проде — что за паттерн и где он встречается в обычной кликстрим-аналитике (без привязки к конкретной компании).
- Руки — что запустить и что понаблюдать (Kafka UI / ClickHouse / Grafana).
- Загляни внутрь — чтение отполированного эталонного кода с пояснениями.
- Управляемая правка — одно-два маленьких изменения с видимым результатом.
Например: добавить поле в Materialized View и увидеть его в
*_raw; «сломать» запись и увидеть+1в таблице ошибокparse_errors; сменитьkafka_group_nameи увидеть, как топик читается заново. Менти меняет — видит эффект — объясняет. Верни как было — каждая правка завершается явным шагом отката к чистому состоянию (откатить изменение либоmake clean/up/ddl/data/transform), чтобы самостоятельный менти не застрял со сломанным стендом без ментора. (Урок 0 — без этого шага, только наблюдение.) - Проверь себя — самопроверка (раздел 3).
- Что должно получиться — конкретный видимый результат, который менти проверяет
сам: скрин эффекта правки (например, красный DAG или
+1в таблице ошибок) плюс один абзац «своими словами» про паттерн урока или запрос, который пришлось написать. Это и есть самопроверка (раздел 3); те же вопросы «своими словами» менти разбирает с ментором на еженедельном созвоне. (Урок 0 — без правки, поэтому результат здесь — что менти увидел при наблюдении.)
2. Стандарт качества эталонного кода
Эталонные пути полируем до учебного качества; остальной код стенда остаётся под капотом — его не трогаем.
Чеклист (минимум). Файл доведён, если:
- комментарии на русском объясняют зачем, а не пересказывают код;
- шаги явные и названы своими именами, без неочевидных трюков;
- в начале файла — поток данных одной строкой (как в STG:
Kafka → kafka_*_raw → MV → *_raw); - ошибки и проверки качества данных видны — понятно, куда смотреть;
- нет мусора: мёртвого кода, закомментированных экспериментов, разнобоя в именах.
Тест одного прохода (главный критерий и защита от громоздкости).
Менти читает файл один раз сверху вниз и может пересказать своими словами, что происходит и зачем — не прыгая по файлу, не гугля, не расшифровывая трюки.
Если тест не проходит — правим строго одним из трёх способов: (1) упростить код; (2) добавить ровно одну строку «зачем» там, где код честно неочевиден; (3) убрать лишнее под капот или в короткую пометку. Добавить ещё комментариев — не способ.
Две защиты от раздувания:
- комментируем только неочевидное «зачем» (очевидную строку комментировать нельзя — лишний текст сам по себе мешает понимать);
- «близко к проду» ≠ «вся прод-сложность прямо в коде урока»: один прод-паттерн на урок показываем чисто, остальные прод-заботы — короткой пометкой «в проде иначе: …».
Вердикты аудита по конкретным путям — в LEARNING_PLAN.md.
3. Самопроверка (по-простому)
Отдельный тест-фреймворк не строим. Опираемся на то, что в стенде уже есть:
- штатные быстрые проверки (smoke) из
docs/TEST_PLAN.md; - встроенные проверки в
etl_pipeline_dag.py(DAG падает на пустой витрине или нарушении целостности); make clean/up/ddl/data/transformдля сброса и повтора.
В каждом уроке — маленькая табличка самопроверки в формате действие → где смотреть → что ожидать, а для управляемой правки — какой видимый результат должен появиться.