docs(course): переведены уроки на стартовую историю

- Зачем:
  - учебный путь должен идти через генерацию и штатный пайплайн, а не через архивный сид.
- Что:
  - обновлены уроки 00-06 и стандарт урока под startup-history/backfill.
  - объяснено, что data/*.jsonl остаются кладовкой значений генератора.
  - тест-план переведён на новый штатный запуск и HITL-приёмку.
- Проверка:
  - rg -n \"make clean/up/ddl/data/transform|make data|kafka_load|LIMIT=|2022-11-28|26 из 50\" docs/course docs/TEST_PLAN.md.
  - git diff --cached --check.
This commit is contained in:
2026-07-04 22:22:36 +03:00
parent de938edb06
commit d76c03655b
10 changed files with 192 additions and 201 deletions
+22 -12
View File
@@ -7,7 +7,7 @@
> Эталонный путь: сам Kafka UI на `http://localhost:8082`.
>
> Поток данных одной строкой:
> `make data → топики Kafka (партиции, offset'ы) → consumer-группа ClickHouse вычитывает`
> `готовый источник данных стенда → топики Kafka (партиции, offset'ы) → consumer-группа ClickHouse вычитывает`
>
> О чём урок простыми словами: ходим по Kafka UI и разглядываем поток — где лежат события,
> кто их читает и как Kafka помнит, до какого места уже дочитано.
@@ -22,11 +22,15 @@
consumer читает в своём темпе, не трогая producer'а. Если читатель отстал или прилёг —
события не теряются, они лежат в топике и ждут.
На нашем стенде роли уже расставлены: `make data` играет роль трекера и заливает события
в топики, а ClickHouse — это consumer, который их вычитывает. В этом уроке мы не запускаем
пайплайн и ничего не меняем — мы открываем Kafka UI и **узнаём в живом кластере** те самые
понятия из видео. Это разминка: в уроке 1 ты уже руками увидишь, как эти же сообщения
доезжают до таблиц ClickHouse.
На нашем стенде роли уже расставлены: готовый источник данных стенда играет роль трекера
и пишет события в топики, а ClickHouse — это consumer, который их вычитывает. Для курса нам
важно не устройство источника, а сам путь данных: Kafka → STG → ODS → DDS → DM → Superset.
Файлы `data/*.jsonl` здесь не источник аналитики; пока это только кладовка готовых значений
для источника данных стенда.
В этом уроке мы не запускаем пайплайн и ничего не меняем — мы открываем Kafka UI и
**узнаём в живом кластере** те самые понятия из видео. Это разминка: в уроке 1 ты уже руками
увидишь, как эти же сообщения доезжают до таблиц ClickHouse.
> **В проде так же, только крупнее.** Здесь один брокер и крошечный срез данных. В бою
> брокеров несколько, топик разбит на много партиций, читателей в группе — тоже несколько,
@@ -37,8 +41,14 @@ consumer читает в своём темпе, не трогая producer'а.
## 2. Наблюдай: открой Kafka UI
Стенд уже должен быть поднят (`make up`) и в топиках должны лежать события
(`LIMIT=50 make data` из урока 1 — или любой прошлый прогон). Открой Kafka UI:
Стенд уже должен быть поднят, а в топиках должны лежать события после стартовой истории:
```bash
make generated-history-analytics
make up
```
Открой Kafka UI:
`http://localhost:8082`. Ходи по нему свободно — это режим чтения, сломать тут ничего нельзя.
Пройди по трём экранам и просто посмотри.
@@ -54,20 +64,20 @@ consumer читает в своём темпе, не трогая producer'а.
топиков) — его Kafka использует сама, мы его не трогаем. У каждого нашего топика в колонке
с партициями стоит **1**: топик маленький, делить не на что.
**Сообщения в топике.** Открой `browser_events` → вкладку *Messages*. Это и есть события,
которые залил `make data`. У каждого сообщения видно:
**Сообщения в топике.** Открой `browser_events` → вкладку *Messages*. Это и есть события
стенда. У каждого сообщения видно:
- **Offset** — порядковый номер сообщения в партиции (0, 1, 2, …);
- **Timestamp** — когда сообщение легло в Kafka (время *доставки*, не время самого события);
- **Value** — тело: JSON события целиком, например:
```json
{"event_id": "8cca1c7d-...", "event_timestamp": "2022-11-28 20:51:05.627882",
{"event_id": "8cca1c7d-...", "event_timestamp": "2026-01-01 00:01:00.000000",
"event_type": "pageview", "browser_name": "Chrome", "browser_language": "sat_IN"}
```
Загляни внутрь Value: у события есть своё `event_timestamp` (когда оно случилось,
здесь — 2022 год), и оно отличается от Kafka-Timestamp (когда оно попало в топик — при заливке стенда).
модельное время стенда), и оно отличается от Kafka-Timestamp (когда оно попало в топик).
Два разных времени у одной записи — запомни этот момент, в уроке 1 он всплывёт уже на
стороне ClickHouse.