ddadminandClaude Fable 5
7d54e5fc1f
- Зачем:
- целеполагание было размазано по обсуждениям: место стенда в менторской
программе и иерархия целей нигде не были записаны, а демо-употребление
стенда устарело (выросло в отдельный проект).
- Что:
- PRD курса §1: место стенда в треке ClickHouse (теория и лабы вне репо,
здесь — интеграции), иерархия целей курс -> стенд -> генератор;
схема потока обновлена на генератор как источник.
- PRD §7: закрыта развилка про урок о генераторе (урока не будет,
генератор — скрытая инфраструктура), добавлена открытая развилка про
кластерную конфигурацию.
- удалены DEMO_CHEATSHEET_5MIN.md и DEMO_SCRIPT_10_15MIN.md; ссылок на них
в репозитории не осталось.
- Проверка:
- grep -rn "DEMO_CHEATSHEET\|DEMO_SCRIPT" --include="*.md" . — только
исторический handoff.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
201 lines
17 KiB
Markdown
201 lines
17 KiB
Markdown
# PRD: продвинутый курс «Кликстрим на ClickHouse» (со звёздочкой)
|
||
|
||
> Статус: прообраз PRD. Дата: 2026-06-01.
|
||
> Поправка 2026-06-03 (разморозка по делу): середина пайплайна расщеплена — ODS и DDS
|
||
> теперь разные уроки (принцип «один паттерн на урок»), витрины DM демотированы в
|
||
> поверхность потребления. Обязательных уроков стало 0–5, опциональный Superset — урок 6.
|
||
> Затронуты §4 (скоуп) и §3/§5 (ожидаемый такт — ~день на урок). Это изменение рамки,
|
||
> а не план реализации.
|
||
> Поправка 2026-06-03 (терминология): режим сопровождения — еженедельный **созвон**, а не
|
||
> «сессия»; менти проходит материал сам и ничего «не приносит», а на созвоне ментор
|
||
> разбирает затыки и проверяет глубину понимания. Затронуты §1, §3, §5.
|
||
> Поправка 2026-07-04 (целеполагание): §1 расширен — зафиксировано место стенда в
|
||
> экосистеме менторской программы (теория и лабы по ClickHouse живут в других местах,
|
||
> здесь — интеграции «как в жизни») и иерархия целей вплоть до генератора. Демо-материалы
|
||
> (шпаргалки 5 и 10–15 минут) устарели и удалены: демо выросло в отдельный проект и целью
|
||
> стенда больше не является. Схема потока в §1 обновлена под генератор (источник данных
|
||
> сменился, см. ADR-0006). В §7 закрыта развилка про урок о генераторе и добавлена
|
||
> развилка про кластерную конфигурацию.
|
||
> Назначение документа: зафиксировать для будущих сессий, что это за курс, зачем
|
||
> он, что входит в скоуп работ, а что нет. Это договорная **рамка**, а не план
|
||
> реализации и не стандарт уроков (см. раздел «Связанные документы»).
|
||
>
|
||
> Язык документа: уровни называем единообразно — **курс** (вся программа) состоит
|
||
> из **уроков**. Соседние программы (например, Lakehouse) — отдельные **курсы**.
|
||
|
||
---
|
||
|
||
## 1. Контекст и назначение
|
||
|
||
Репозиторий — рабочий сквозной стенд кликстрим-DWH:
|
||
|
||
```
|
||
generator (backfill/live) → Kafka → ClickHouse (Kafka engine + MV → STG) → Airflow ETL (STG→ODS→DDS→DM) → Superset
|
||
↘ Prometheus / Grafana (мониторинг)
|
||
```
|
||
|
||
Стенд близок к продакшену и показывает несколько паттернов инженерии данных на
|
||
связке Kafka + ClickHouse + Airflow + мониторинг. ClickHouse не входит в базовую
|
||
программу обучения — это **продвинутый курс «со звёздочкой»** для менти, уже
|
||
прошедших базу (SQL, моделирование, Python, Git, Docker, Airflow).
|
||
|
||
### Место стенда в менторской программе (2026-07-04)
|
||
|
||
Трек ClickHouse для продвинутых менти состоит из трёх частей, и у каждой своя роль:
|
||
|
||
- **Теория** — внешние курсы (бесплатный курс Яндекса или запись курса Отус).
|
||
Здесь теорию не пересказываем.
|
||
- **Лабы по самому ClickHouse** — отдельный стенд
|
||
[clickhouse-learning-cluster](https://github.com/dementev-dev/clickhouse-learning-cluster):
|
||
полноценный кластер, но без внешних интеграций.
|
||
- **Этот стенд** — то, чего нет в первых двух: ClickHouse в окружении «как в жизни».
|
||
Интеграции (Kafka, Airflow), мониторинг и BI поверх. Ниша стенда — не сам
|
||
ClickHouse, а инженерия данных вокруг него.
|
||
|
||
Иерархия целей внутри репозитория:
|
||
|
||
1. **Курс — главная цель.** Всё остальное — средства.
|
||
2. **Стенд — носитель курса.** Должен подниматься одной командой, давать
|
||
правдоподобные данные (пирамида «пользователи < визиты < события», суточная
|
||
волна, возвраты) и быстро воспроизводиться.
|
||
3. **Генератор — скрытая инфраструктура стенда.** Его задача — живые данные:
|
||
стартовая история плюс живое продолжение. Учебным предметом не является
|
||
(решение — §7); пользовательская граница — «как пользоваться», не «как устроен».
|
||
|
||
Демо-употребление стенда (шпаргалки на 5 и 10–15 минут) **устарело**: демо выросло
|
||
в отдельный проект и целью этого репозитория больше не является (2026-07-04,
|
||
материалы удалены).
|
||
|
||
Цель курса — превратить стенд в **самостоятельный учебный материал**, по которому
|
||
продвинутый менти проходит ключевые паттерны сам, а ментор подключается на обычном
|
||
еженедельном созвоне (что получилось / что нет / вопросы / план на неделю). Долгий
|
||
разбор кода вживую форматом не предусмотрен — поэтому материал обязан быть
|
||
самодостаточным.
|
||
|
||
## 2. Цели (чему учим)
|
||
|
||
К концу курса менти умеет:
|
||
|
||
1. **Заземлять поток из Kafka в ClickHouse** через Kafka engine и Materialized View
|
||
(ClickHouse сам забирает сообщения из топика), понимая роль топиков, партиций,
|
||
offset'ов и consumer-групп.
|
||
2. Строить **слоёный ETL** (STG → ODS → DDS → DM) и объяснять, **где уместен
|
||
Materialized View** (стриминговое приземление данных), **а где батч** (так
|
||
удобнее управлять и наблюдать за пересчётом).
|
||
3. Читать и объяснять **оркестрацию в Airflow**: DAG, зависимости задач, проверки
|
||
качества данных, остановку пайплайна при нарушениях.
|
||
4. Понимать, **как устроен мониторинг** пайплайна (метрики, экспортёры, дашборды).
|
||
5. (Опционально) Подключать **BI-витрину** поверх ClickHouse (Superset).
|
||
|
||
Сквозная цель — не «посмотреть, как работает», а **уметь пересказать паттерн
|
||
своими словами и привязать его к обычной кликстрим-аналитике** (трекер событий →
|
||
Kafka → ClickHouse → BI).
|
||
|
||
## 3. Аудитория и режим
|
||
|
||
- **Аудитория:** продвинутые менти, прошедшие базовую программу. Пишем обобщённо,
|
||
но затачиваем под реальный первый прогон, а не под гипотетических будущих менти.
|
||
- **Режим:** самостоятельный, асинхронный. Менти клонирует репозиторий, поднимает
|
||
стенд у себя (`make up`) и идёт по урокам из `docs/course/` рядом с кодом.
|
||
Уроки короткие и односоставные — ожидаемый срок прохождения одного **около дня**.
|
||
- **Роль ментора:** еженедельный созвон-сверка (покрывает несколько уроков), без
|
||
построчного разбора кода.
|
||
- **Железо:** стек тяжёлый (Kafka + ClickHouse + Airflow + Superset + Prometheus +
|
||
Grafana одновременно). Считаем наличие подходящего железа данностью; стек не режем
|
||
на части — это усложнило бы жизнь и менти, и автору материала.
|
||
|
||
## 4. Скоуп
|
||
|
||
### Входит
|
||
- **Уроки 0–5 (обязательные):** вводный урок по Kafka, заземление Kafka→CH, STG→ODS
|
||
(типизация + DQ), ODS→DDS (сборка сущностей), Airflow, мониторинг. Принцип нарезки —
|
||
один прод-паттерн на урок; контраст «где Materialized View, а где батч» проходит
|
||
мостом уроков 1→2.
|
||
- Витрины **DM — не отдельный урок**: их показываем в деле там, где их потребляют
|
||
(мониторинг и BI). См. `LEARNING_PLAN.md` §1–2.
|
||
- **Аудит и точечная полировка эталонных путей** этих уроков до учебного качества
|
||
(стандарт — в `LESSON_STANDARD.md`).
|
||
- Учебная часть вокруг каждого эталонного пути по единому шаблону урока.
|
||
|
||
Подробная карта уроков (файлы стенда, статус, режим, вердикты аудита) — в плане
|
||
обучения `LEARNING_PLAN.md`.
|
||
|
||
### Опционально
|
||
- **Урок 6: Superset (BI-витрина).** Делаем, если останется ресурс; обязательные
|
||
уроки он не блокирует.
|
||
|
||
### Не входит
|
||
- Переписывание всего стенда: полируем только эталонные пути обязательных уроков,
|
||
остальной код стенда остаётся под капотом.
|
||
- Lakehouse (Spark / Iceberg / Trino) — отдельный стенд, отдельный курс.
|
||
- Подготовка к трудоустройству: резюме, легенда, мок-собесы, привязка к конкретному
|
||
работодателю. Любые материалы под конкретного менти — вне этого репозитория
|
||
(репозиторий публичный; приватное — в менторской базе).
|
||
- Доведение стенда до промышленной надёжности (отказоустойчивость, безопасность,
|
||
масштабирование) — кроме коротких пометок «в проде иначе».
|
||
|
||
## 5. Критерии успеха
|
||
|
||
- Менти проходит урок **сам**, без построчного разбора с ментором (ожидаемый срок —
|
||
около дня на урок: уроки короткие и односоставные).
|
||
- Может своими словами объяснить паттерн урока и привязать его к обычной
|
||
кликстрим-аналитике.
|
||
- На созвоне задаёт осмысленные вопросы по сути, а не «застрял на запуске».
|
||
- Эталонный код проходит «тест одного прохода» (см. `LESSON_STANDARD.md`).
|
||
|
||
## 6. Связанные документы и порядок работ
|
||
|
||
Порядок создания артефактов:
|
||
|
||
1. **`PRD.md`** (этот документ) — рамка: что, зачем, скоуп. По умолчанию **заморожен**;
|
||
меняется только осознанной поправкой с датой и причиной в шапке (как 2026-06-03).
|
||
2. **`LEARNING_PLAN.md`** — высокоуровневый план обучения: карта уроков, маршрут
|
||
менти, результаты аудита путей. Пишется после согласования PRD.
|
||
3. **`LESSON_STANDARD.md`** — стандарт уроков: шаблон урока, стандарт качества кода,
|
||
самопроверка. Рабочий чеклист, открывается при написании каждого урока.
|
||
4. **Уроки** — по одному, по шаблону из `LESSON_STANDARD.md`, начиная с урока 1
|
||
(Kafka→CH).
|
||
|
||
Навигация по всем файлам курса — в `docs/course/README.md`.
|
||
|
||
Материалы под конкретного менти (под кого первый прогон, привязка к работодателю,
|
||
подготовка к собесам) — **вне этого репозитория**, в приватной менторской базе.
|
||
|
||
## 7. Открытые вопросы / на будущее
|
||
|
||
Закрыто при написании уроков (2026-06-06):
|
||
|
||
- ~~Глубина урока 5 (мониторинг): сколько устройства показывать против «просто
|
||
наблюдай дашборд».~~ **Решено:** взяли мини-правку «погаси сервис → алерт краснеет»
|
||
(зеркало урока 4) — урок 5 даёт «сломал-увидел», а не чистое наблюдение. См.
|
||
`LEARNING_PLAN.md` §3.1.
|
||
- ~~Нужна ли BI-витрина (Superset) уже в первой версии.~~ **Решено:** урок 6 написан и
|
||
синхронизирован с реальным дашбордом; остаётся опциональным (обязательные уроки не
|
||
блокирует).
|
||
|
||
Закрыто позже:
|
||
|
||
- ~~Генератор как инфраструктура против отдельного урока (открыто, 2026-06-14).~~
|
||
**Решено (2026-07-04): отдельного урока про генератор не будет — генератор
|
||
остаётся скрытой инфраструктурой.** Причина: устройство генератора (марковская
|
||
модель, нетривиальный Python) — это разработка бэкенда и математика, а не
|
||
инженерия данных; такой урок не попадает в цели курса, и менти его не ожидает.
|
||
Существующие уроки адаптируем без ввода марковских цепей и сложного Python в
|
||
путь менти (задача — `.scratch/generator-model-time-startup-history/issues/08-migrate-course-from-archive-seed.md`).
|
||
Удобство стенда (одна команда + короткий runbook) остаётся отдельной задачей
|
||
(`.scratch/generator-model-time-startup-history/issues/07-startup-history-portable-artifact-and-usage-docs.md`)
|
||
и делает адаптацию уроков проще, но решение от неё больше не зависит.
|
||
|
||
Остаётся на будущее:
|
||
|
||
- Переиспользование: после **первого реального прогона менти** — ретроспектива и
|
||
обобщение материала под других менти. Это валидация уже собранного курса, а не
|
||
часть его подготовки.
|
||
- Кластерная конфигурация ClickHouse (открыто, 2026-07-04). Сейчас стенд —
|
||
одноузловой ClickHouse; кластер живёт в соседнем
|
||
[clickhouse-learning-cluster](https://github.com/dementev-dev/clickhouse-learning-cluster).
|
||
Развилка: оставить разделение «здесь интеграции, там кластер» или доработать этот
|
||
стенд до кластера — «всё в одном» удобнее и ближе к промышленной системе, но
|
||
ощутимо утяжеляет стенд (ресурсы, конфигурация, сложность уроков) и размывает
|
||
нишу learning-cluster. Решение не принято.
|