clickstream-ch-kafka-superset-demo/docs/specs/2026-07-23-course-labs-redesign.md

Редизайн лаб курса под три режима менти

Статус: принято, в работе (ветка feature/course-labs-redesign). Источник: issue #7; аудит курса против стенда и штурм педагогики лаб с пользователем 2026-07-23. Опирается на спеку редизайна пути менти (реализована, issue #9 закрыт) и термины из CONTEXT.md (три режима менти, эталонный мир, модельное время).

Проблема

Курс в docs/course/ (7 уроков + 4 метадокумента) целиком построен на старом пути make generated-history-analytics && make up: ни один документ не знает про world_init, import, эталонный мир и make superset-init. После редизайна пути менти курс в текущем виде не заработает.

При этом педагогическое ядро уроков цело: SQL, DAG'и, мониторинг и Superset актуальны — ломаются только блоки подготовки стенда и обвязка. А два новых режима роста мира (next-day, continue) вообще не имеют уроков, хотя спека пути менти прямо называет их «разные педагогики и разные лабы».

Цели

• Менти проходит курс по новому пути: make up → Airflow UI (ddl_init → world_init с пустой формой) → make superset-init.
• Оба режима роста мира получают по обязательному уроку-лабе с собственным учебным паттерном.
• Числа в уроках совпадают у всех менти число-в-число (следствие import эталонного мира) и сверены с живым стендом.
• Смешанных состояний не бывает: вся перестройка — один PR.

Целевая модель

Маршрут курса

Маршрут остаётся линейным, все уроки — обязательные:

• Урок 6 (Superset) становится обязательным. Его опциональность родом из PRD («делаем, если останется ресурс») — экономия ресурса на написание, а урок давно написан; причина истекла. Ожидания работодателей к дата-инженеру теперь включают витринно-BI-слой.
• Две новые лабы после урока 6, обе обязательные: 07_lab_next_day.md, затем 08_lab_continue.md. Порядок осознанный: next-day детерминирована (числа сойдутся у всех — можно печатать точные ожидания), continue — живая и недетерминированная, «второй шаг свободы».
• Обе лабы строятся по шаблону LESSON_STANDARD.md (шапка + 6 секций).

Новая семантика сброса

Для лаб «верни как было» — это не откат правки в git: мир вырос. Канонический сброс — тот же путь, что и первый вход, и описывается он в одном месте (README курса), уроки ссылаются:

1. make clean (сносит и данные, и Superset — это надо назвать явно);
2. make up → Airflow UI: ddl_init → world_init с пустой формой;
3. make superset-init.

Идём UI-путём менти, а не мейнтейнерским make startup-history-import. Старая команда сброса make generated-history-analytics && make up уходит из учебных текстов (остаётся мейнтейнеру и CI).

Лаба 07 — next-day

Паттерн одной фразой: пакетный инкремент дня и его границы (прод-аналог — «ночью приехал вчерашний день»).

• Руки: триггер беспараметрного world_next_day → день 4 в витринах; сверка чисел manifest (точные ожидаемые значения); make generated-history-chain-check на стыке; день-к-дню на дашборде.
• Центральное открытие — переходящие визиты: менти SQL-запросом находит визиты, чьи события лежат по обе стороны полуночи, и осознаёт, почему суточная нарезка режет живые сессии — откуда берутся проверки стыков, late data и пересчёт вчерашнего хвоста. Этого нет ни в одном уроке 0–6. Важно для текста лабы: запрос идёт в dds.event напрямую (GROUP BY click_id + HAVING toDate(min(event_ts)) <> toDate(max(event_ts))) — витрина dm.v_session_overview не годится, она группирует по event_date и режет переходящий визит на две строки. Это новый приём, который лаба сама и учит (уроки давали argMax/JOIN, но не агрегацию визита целиком). Годится любой стык дней: стыки 1→2 и 2→3 внутри эталонного мира есть точно; живы ли визиты на стыке 3→4 (заморозка мира могла закрыть открытые сессии) — проверяется на стенде при реализации. Здесь же — короткая врезка про соответствие терминов: «визит» из manifest = click_id в SQL (в схеме нет таблицы «визитов», есть dds.click).
• Управляемая правка: включить расписание world_next_day в Airflow UI → день 5 приезжает сам → выключить обратно. Спека пути менти прямо проектировала paused-расписание под этот шаг лабы; заодно менти трогает paused/catchup.
• Цена роста — коротким наблюдением: в длительностях задач Airflow генерация дня ~постоянна (инкрементальные счётчики manifest, issue #5), а full_refresh ETL растёт с миром — осознанный долг, ссылка на #8.
• Самопроверка — крючок про идемпотентность: «триггерни дважды — что будет? почему прод-джобы за день устроены иначе?».
• Эталонный путь: airflow/dags/world_next_day_dag.py.

Лаба 08 — continue

Паттерн одной фразой: живой поток и свежесть данных.

• Ядро — потоковый приём ≠ потоковая обработка: Kafka и STG пополняются сами (MV урока 1), витрины DM стоят до прогона etl_pipeline; запустил — догнали и снова отстают. Свежесть данных как явное понятие: «какую свежесть обещаем потребителю?».
• Руки: make generator-continue → мониторинг урока 5 оживает (target генератора в UP, алерт Kafka No Messages Produced гаснет, events/min шевелится, офсеты урока 0 растут) → наблюдение расслоения свежести → догон через etl_pipeline.
• Управляемая правка — останови поток и продолжи: make generator-down → алерт срабатывает, потребитель дочитывает лаг до нуля; make generator-continue → мир продолжается с места остановки (популяция и модельные часы пережили рестарт). Это суть режима continue и рабочий паттерн устойчивости. По шаблону LESSON_STANDARD лаба всё равно завершается явным шагом «верни как было» — канонический сброс (см. выше): мир после continue недетерминирован, и к следующему прохождению стенд возвращается к эталону.
• Финальное наблюдение — «мир расходится»: после continue числа менти перестают совпадать с эталонными, и это правильно; возвраты пользователей вживую разводят users < sessions (на статике было невозможно — см. CONTEXT.md).
• Модельное время — только врезкой: «стенд ускорен в 60 раз, чтобы сутки потока уложились в ~полчаса; "сейчас" дашборда может обгонять настенные часы», ручка GEN_MODEL_TIME_SPEED — одной строкой. Это механизм тренажёра, не рабочий паттерн — секционного веса не даём. Висячую ссылку CONTEXT.md про «урок 7» поправить на эту врезку.

Симметрия курса: 07 — про границы времени в пакетном мире, 08 — про свежесть в потоковом; обе лабы растят один и тот же импортированный мир двумя способами.

Существующие уроки и метадокументы

По вердиктам аудита:

• Все уроки 0–6: блок подготовки в §2 заменить на новый путь (import); сам блок вынести в одно каноническое место (README курса), уроки ссылаются на него.
• Все цифры уроков 0–6 недействительны. Старые значения считались на старом мире (другой профиль, другой объём); с переходом на эталонный мир каждое цитируемое число каждого урока пересчитывается заново. Это полноправный этап работы, а не финальная галочка — даже в уроках, где правки текста минимальны.
• Урок 1: управляемая правка «добавь колонку и получи свежие сообщения» переводится с перегенерации backfill на дозаливку через world_next_day (детерминированно). Известная цена: прогон DAG'а занимает минуты — урок называет её честно; сам DAG подаётся кнопкой- анонсом без разбора («подробно — в лабе 07»), чтобы не красть у лабы её материал.
• Урок 4: добавить лесенку ddl_init → world_init → world_next_day как контекст оркестрации (менти уже прошёл её руками).
• Урок 5: словарь «backfill-only стенд» заменить на «база import / живой поток»; сценарий алерта Kafka No Messages Produced переписать в этих терминах.
• Урок 6: снять пометку «опционально»; цифры сверить с эталонным миром.
• README курса: переписать блоки подготовки и «Проверка чистого маршрута»; таблицу уроков дополнить лабами.
• PRD: не переписывать — одна датированная поправка по его же конвенции (три режима менти, урок 6 обязателен, лабы 07–08).
• LEARNING_PLAN: переписать маршрут и статус, сохранить таблицу аудита эталонных путей; дополнить её world_next_day_dag.py.
• LESSON_STANDARD: заменить команду сброса на import-путь.

Чего здесь не делаем

• Не трогаем код стенда: DAG'и, SQL, генератор, инфраструктура — вне скоупа; работа только с документами курса, README курса и CONTEXT.md (одна ссылка).
• Не чиним рост стоимости full_refresh (issue #8) — в лабе 07 он только показывается.
• Не пишем урок про модельное время — понижено до врезки в лабе 08.
• Не переносим приватные менторские материалы — граница из README курса остаётся.
• Не переделываем эталонный код уроков 0–6 сверх замены обвязки: аудит подтвердил, что ядро актуально.

Проверка

• Чистый стенд: менти проходит весь курс 0–8 по текстам уроков, ни разу не встретив generated-history-analytics и backfill.
• Каждая цитируемая цифра уроков и лаб сверена с живым стендом после import эталонного мира (обязательный финальный шаг реализации).
• Лаба 07: после world_next_day числа manifest совпадают с напечатанными в лабе; make generated-history-chain-check зелёный; SQL-запрос из лабы находит хотя бы один переходящий визит (на любом стыке дней).
• Детерминизм инкремента подтверждён до печати чисел: два независимых прогона world_next_day от свежего import дают одинаковые числа manifest и контрольную сумму.
• Лаба 08: сценарий стоп/продолжение проходит без потерь (лаг стекает к нулю, после продолжения числа согласованы с manifest).
• Все внутренние ссылки курса живы; make test / make lint зелёные (доки код не трогают — проверка от регрессий по касанию).

Решения и отклонённые варианты

• Лабы — секциями внутри уроков 4/5 — отклонено: уроки распухают, лабы теряют самостоятельность; выбраны отдельные файлы.
• Урок 6 оставить опциональным, финал лабы 07 — только SQL — отклонено: причина опциональности истекла, рынок ждёт BI-навыков; урок 6 становится обязательным, лабы опираются на дашборд.
• Модельное время как секция или отдельный урок — отклонено: механизм тренажёра, не рабочий паттерн; врезка.
• Управляемая правка лабы 08 через ручку ×K — отклонено по той же причине; выбран стоп/продолжение потока.
• Дробить работу на несколько PR — отклонено: половинчатый курс (часть уроков про import, часть про backfill) хуже любого из крайних состояний; этапность — коммитами внутри одной ветки.
• Цифры «ориентировочно», без сверки со стендом — отклонено: воспроизводимость число-в-число — главный козырь эталонного мира.

Влияние на документацию

Вся работа и есть документация: docs/course/** (7 уроков + 2 лабы + 4 метадокумента), одна ссылка в CONTEXT.md. Корневой README.md и docs/OPERATIONS.md уже описывают новый путь — не трогаем. Issue #7 ссылается на эту спеку и ведёт чек-лист шагов.