docs(course): каркас курса и переобвязка уроков 0–6 на путь import (#21)

Зачем: после редизайна пути менти курс ссылался на старый путь
generated-history-analytics/backfill и не проходился по новому стенду.

Что: в README курса — единый блок подготовки и канонического сброса
(make clean -> make up + ddl_init/world_init -> make superset-init),
таблица уроков дополнена лабами 07–08 («в работе»); LESSON_STANDARD и
уроки 0–6 ссылаются на канонический блок; урок 1 переведён на дозаливку
через world_next_day (кнопкой-анонсом, цена в минутах названа); урок 4 —
лесенка DAG-ов; урок 5 — словарь «база import / живой поток»; урок 6
обязателен; цифры старого мира помечены маркером «сверить-на-стенде».

Проверка: grep по generated-history-analytics/backfill в docs/course/
пуст; правки только в docs/course/; git diff --check чистый.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-07-23 13:22:41 +03:00
co-authored by Claude Opus 4.8
parent b57a4e2292
commit cc1cffe2f3
11 changed files with 142 additions and 171 deletions
+27 -26
View File
@@ -27,24 +27,27 @@
поднимаются одновременно. Нужна машина, которая это потянет.
- **Инструменты:** `Docker` с `docker compose`, `make`, `bash`, `curl`, `git` и `uv`.
`uv` нужен для локальных Python-проверок и команд разработки.
- **Подними стенд и создай стартовую историю** (из корня репозитория) — этого хватит,
чтобы начать, и прогон быстрый:
```bash
make generated-history-analytics
make up
```
## Подготовка и канонический сброс
Эта команда проводит штатный путь стенда: готовый источник данных создаёт стартовую
историю, события попадают в Kafka, затем в STG, ODS, DDS, DM и Superset. Это тот же
путь, что ручной вариант из README (Airflow UI и операция `backfill`), но одной
командой — выбери один из двух, оба ведут к одинаковому стенду. Файлы
`data/*.jsonl` пока остаются только кладовкой готовых значений для генератора
(браузеры, страны, устройства, UTM), а не источником аналитического контура. `make up`
после неё поднимает остальные UI-сервисы курса: Kafka UI, Airflow, Prometheus и Grafana.
Первый запуск и возврат к чистому эталонному миру идут одним путём. При первом запуске
пропусти `make clean`; для полного сброса выполни все три шага:
Дальше каждый урок в секции «Руки» сам напоминает, что перезапустить.
Точные шаги, параметры и troubleshooting — в [`docs/OPERATIONS.md`](../OPERATIONS.md).
1. Выполни `make clean`. Команда удалит данные стенда и метаданные Superset: сохранённые
в нём настройки и дашборды тоже придётся создать заново.
2. Выполни `make up`, открой Airflow на `http://localhost:8080` (`admin/admin`) и дождись
успешного завершения двух DAG-ов по порядку:
- `ddl_init` — запусти с пустой формой;
- `world_init` — после него запусти с пустой формой.
3. Когда `world_init` завершится успешно и витрины DM будут готовы, выполни
`make superset-init`.
Так события из эталонного мира попадут в Kafka, затем в STG, ODS, DDS и DM, а Superset
получит готовые наборы данных и дашборд. Файлы `data/*.jsonl` остаются только кладовкой
готовых значений для генератора (браузеры, страны, устройства, UTM), а не источником
аналитического контура.
Точные параметры и разбор ошибок — в [`docs/OPERATIONS.md`](../OPERATIONS.md).
## Уроки
@@ -60,7 +63,9 @@
| 3 | [ODS → DDS: сборка сущностей](./lessons/03_ods_to_dds.md) | руки | Собираем `click` и `event` из кусочков (argMax, JOIN) и встречаем «сирот» |
| 4 | [Оркестрация в Airflow](./lessons/04_airflow_orchestration.md) | руки | Всю цепочку — в один DAG с зависимостями и честным гейтом целостности |
| 5 | [Мониторинг: Prometheus и Grafana](./lessons/05_monitoring.md) | наблюдение + мини-правка | Смотрим систему со стороны; гасим сервис — видим, как краснеет алерт |
| 6 | [BI-витрина в Superset](./lessons/06_superset_bi.md) | руки (опционально) | Дашборд поверх ClickHouse: KPI, динамика, воронка |
| 6 | [BI-витрина в Superset](./lessons/06_superset_bi.md) | руки | Дашборд поверх ClickHouse: KPI, динамика, воронка |
| 7 | Лаба: следующий день | руки, в работе | Пакетный инкремент дня и границы времени |
| 8 | Лаба: живое продолжение | руки, в работе | Живой поток и свежесть данных |
## Как проходить
@@ -76,22 +81,18 @@
## Проверка чистого маршрута
Перед проверкой уроков 0, 1 и 5 подними стенд с нуля:
```bash
make generated-history-analytics
make up
```
Перед проверкой уроков 0, 1 и 5 пройди
[канонический сброс](#подготовка-и-канонический-сброс).
Что должен подтвердить человек:
- урок 0: в Kafka UI видны четыре топика событий и понятны служебные топики
генератора;
- урок 1: после `CLEAN_START=0 make generated-history-analytics` учебная колонка
`kafka_msg_ts` не пропадает и заполняется;
- урок 1: после запуска `world_next_day` учебная колонка `kafka_msg_ts` не пропадает
и заполняется;
- урок 5: Prometheus targets `clickhouse`, `kafka`, `airflow` находятся в `UP`,
а `Kafka No Messages Produced` трактуется с учётом того, запущен live-генератор
или только стартовая история.
а `Kafka No Messages Produced` трактуется с учётом того, включён живой поток
или стенд работает на импортированной базе.
## Границы