From ab35560ece16251909a7b12615cc138e378a8c46 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Tue, 1 Sep 2026 14:15:25 -0400 Subject: [PATCH] =?UTF-8?q?docs(handbook):=20=D1=81=D0=BA=D0=B5=D0=BB?= =?UTF-8?q?=D0=B5=D1=82=20=D0=BF=D1=83=D1=82=D0=B5=D0=B2=D0=BE=D0=B4=D0=B8?= =?UTF-8?q?=D1=82=D0=B5=D0=BB=D1=8F=20=D0=B8=20=D1=87=D0=B5=D0=BB=D0=BE?= =?UTF-8?q?=D0=B2=D0=B5=D1=87=D0=B5=D1=81=D0=BA=D0=B0=D1=8F=20=D1=88=D0=B0?= =?UTF-8?q?=D0=BF=D0=BA=D0=B0=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - менти негде было понять с первого экрана, что перед ним и куда идти; тикет #209 карты #206 открывает учебную документацию стенда. - Что: - создан docs/handbook/README.md: тропа чтения и пять аннотированных будущих глав с временными ссылками на справочники. - шапка README.md переписана для менти: четыре действия и ссылки на путеводитель и уроки; в разделе «Документация» добавлены handbook и labs. - в AGENTS.md добавлено правило имен для docs/handbook/. - Проверка: - команда проверки ссылок из тикета #209 — пустой вывод; - git diff: операторские разделы README не тронуты. Co-Authored-By: Claude Fable 5 --- AGENTS.md | 4 ++++ README.md | 12 +++++++++- docs/handbook/README.md | 49 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 64 insertions(+), 1 deletion(-) create mode 100644 docs/handbook/README.md diff --git a/AGENTS.md b/AGENTS.md index 4c75c4b..0b73c53 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -161,6 +161,10 @@ Airflow) и названия из кода. Если для понятия ес (`top-pages-daily.md`), индекс папки — `README.md`. Здесь живут ТЗ учебных заданий. Ни даты, ни номера: задание — не событие истории, а живой документ, и правится он вместе с тем, о чем говорит. Слаг называет предмет задания. +- Имена файлов в `docs/handbook/` — слаг строчными латинскими буквами через + дефис, индекс папки — `README.md`. Здесь живет путеводитель по стенду: + учебные главы для менти. Ни дат, ни номеров: глава — живой документ и + правится вместе с тем, что описывает. - Имена файлов в `docs/adr/` — `NNNN-краткое-имя.md`: сквозной номер из четырёх цифр и слаг (`0001-stand-services.md`). Решения нумеруются подряд, дата в имени не нужна. diff --git a/README.md b/README.md index 1885271..53868a5 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,15 @@ # Учебная дата-платформа кликстрима -Стенд для работы с кликстримом. Преемник учебного стенда +Этот стенд — для менти, который видит такую систему впервые и хочет +проследить весь путь данных: от кликстрима и заказов до витрин, проверок и +графиков. Преемник учебного стенда [clickstream-ch-kafka-superset-demo](https://git.dementev.space/ddmitry/clickstream-ch-kafka-superset-demo). +Поднять стенд поможет [«Быстрый старт»](#быстрый-старт), выключить — +`make down`. Чтобы разобраться в устройстве, начните с +[путеводителя](docs/handbook/README.md), а учиться — с +[уроков](docs/labs/README.md). + ## Статус Репозиторий строится по спеке @@ -410,6 +417,9 @@ Superset закреплён на 6.1.0; драйвер `clickhouse-connect`, ф ## Документация +- [docs/handbook/](docs/handbook/) — путеводитель по стенду и порядок чтения. +- [docs/labs/](docs/labs/) — учебные задания с порядком прохождения и + самопроверкой. - [docs/specs/](docs/specs/) — спеки: источник истины о задуманном. - [docs/adr/](docs/adr/) — принятые решения с доводами и отвергнутыми вариантами: почему сделано так, а не иначе. diff --git a/docs/handbook/README.md b/docs/handbook/README.md new file mode 100644 index 0000000..e16c900 --- /dev/null +++ b/docs/handbook/README.md @@ -0,0 +1,49 @@ +# Путеводитель по стенду + +Если вы впервые видите стенд, начните отсюда. Путеводитель подскажет, на что +смотреть и в каком порядке, а за подробностями отправит в справочники. Так вы +разберетесь в устройстве, прежде чем браться за уроки. + +## Как читать + +Тропа такая: [словарь понятий](../../CONTEXT.md) → главы путеводителя → +[справочники `docs/architecture/`](../architecture/) → +[уроки](../labs/README.md). + +Словарь не надо читать подряд. Возвращайтесь к нему за незнакомым словом. +Первая статья объясняет хранилище. Следом идет несколько статей об устройстве +генератора; они понадобятся нескоро. + +## Будущие главы + +### Хранилище и его слои + +От события в Kafka до витрины: глава разберет путь через STG, ODS, DDS и DM +и покажет, за что отвечает каждый слой. Пока главы нет, смотрите +[справочник хранилища](../architecture/storage.md). + +### Потоки Airflow и пульт мира + +Пульт играет модельный день, а дневной конвейер раскладывает данные по слоям. +Глава поможет увидеть их связь и роль каждого дага. Пока главы нет, смотрите +[справочник конвейера](../architecture/etl.md) и +[раздел «Пульт мира» корневого README](../../README.md#пульт-мира). + +### Мониторинг: куда смотреть + +Свежесть и поток данных, брак и отставание собраны на дашборде «Данные». +Глава научит находить нужную панель и разбирать ее показания. Пока главы +нет, смотрите [устройство мониторинга](../architecture/monitoring/README.md). + +### Немного Superset + +Глава покажет, как витрина становится графиком и где проходит граница между +своими объектами и теми, которые поднимает стенд. Пока главы нет, смотрите +[справочник Superset](../architecture/superset.md). + +### Генератор: откуда берутся данные + +Для менти генератор здесь — источник данных. Глава в общих чертах объяснит, +откуда берутся события и заказы и в каком виде их получает хранилище. Пока +главы нет, смотрите [`generator/`](../../generator/) и +[описание события кликстрима](../formats/clickstream-event.md).