Merge pull request 'docs(readme): корневой README пересобран по четырем блокам' (#217) from 216-readme-rebuild into main

Reviewed-on: #217
2026-09-02 22:44:54 +03:00
commit 354b8abe56
@@ -1,29 +1,21 @@
 # Учебная дата-платформа кликстрима

-Этот стенд — для менти, который видит такую систему впервые и хочет
-проследить весь путь данных: от кликстрима и заказов до витрин, проверок и
-графиков. Преемник учебного стенда
+> Этим стендом можно пользоваться самостоятельно. Он также входит в
+> [план обучения Data Engineering Roadmap](https://de.dementev.space) как
+> курсовая работа. Если вам нужна помощь, обратитесь к автору материалов —
+> ментору [@dementev_dev](https://t.me/dementev_dev).
+
+Этот стенд — для изучения и экспериментов с кликстримом и ClickHouse. Здесь
+можно проследить весь путь данных: от кликстрима и заказов до витрин, проверок
+и графиков. Это преемник учебного стенда
 [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).
-
-## Статус
-
-Репозиторий строится по спеке
-[«Боевой реализм стенда (v2)»](docs/specs/2026-07-30-stand-v2-realism.md).
-Сейчас работают кластер ClickHouse из двух шардов, отдельный
-clickhouse-keeper, односерверная Kafka в режиме KRaft, Airflow 3.3, Superset,
-Prometheus, Grafana, экспортёр метрик Kafka и общая база Postgres для
-метаданных. Генератор кликстрима в [`generator/`](generator/) собран
-целиком со стороны клиента: у него есть контракт схемы события, из которого
-собрано [описание выгрузки](docs/formats/clickstream-event.md), модельный мир и
-проигрыватель, отправляющий дни в Kafka или в файл. События доезжают до
-типизированного `ods.event`, а `dds.event_v` отдаёт их на языке бизнес-модели
-без копии данных. `make up` наполняет стенд стартовым миром — первой неделей
-модельного времени.
+В стенде подняты кластер ClickHouse из двух шардов, отдельный keeper, Kafka,
+Airflow, Superset, Prometheus и Grafana; события кликстрима и заказы бэкенда
+приезжают из генератора и идут по слоям STG → ODS → DDS → DM. `make up`
+наполняет стенд стартовым миром — первой неделей модельного времени. Чтобы
+разобраться в устройстве, начните с [путеводителя](docs/handbook/README.md), а
+учиться — с [уроков](docs/labs/README.md).

 ## Быстрый старт

@@ -35,27 +27,21 @@ Prometheus, Grafana, экспортёр метрик Kafka и общая баз
 пользователя Windows; после правки нужен `wsl --shutdown`. Если своей машины не
 хватает, стенд одинаково хорошо живёт на недорогом VPS.

-Проверкам на поднятом стенде также нужны `curl`, `jq`, `awk`, `grep`, `sed`,
-`tail`, `sleep` и `timeout`. `jq` нужен и самому `make up`: им читается паспорт
-мира, по которому он ждёт заливки. По умолчанию должны быть свободны порты
-`23000`, `28080`, `28088`, `28123`, `28124`, `29000`, `29001`, `29090` и
-`29092`. Проверкам без стенда — `make config-test` и `make lint` в корне, всем
-целям генератора в `generator/` — нужен `uv`.
+`make up` нужны `curl` и `jq`: первым он ходит в Airflow, вторым читает
+паспорт мира, по которому ждет заливки. По умолчанию должны быть свободны
+порты `23000`, `28080`, `28088`, `28123`, `28124`, `29000`, `29001`, `29090`
+и `29092`. Всем целям генератора в `generator/` нужен `uv`.

 Сначала скопируйте настройки стенда:

 ```bash
 cp .env.example .env
 make up
-make smoke
-make check-clickhouse
-make check-services
 ```

-Первому знакомству нужны все три проверки на стенде: `make smoke` говорит, что
-стенд собран, `make check-clickhouse` — что кластер работает кластером, а
-`make check-services` — что Airflow запускает DAG, а Superset ходит в базу.
-Дальше, в рабочей петле, обычно хватает `make smoke`.
+`make up` сам ждет заливки стартового мира; что он делает по шагам и какие
+проверки есть у стенда, описано в [карте
+проверок](docs/architecture/testing.md).

 `.env.example` — образец обязательной локальной настройки. В нём живут имя
 экземпляра, внешние порты, учебные учётные данные и ключи. Одно значение образца
@@ -72,38 +58,7 @@ make check-services
 все локальные данные стенда, а следующий `make up` создаст их с новыми
 значениями.

-Что делает `make up`, кого спрашивает каждая проверка и как устроен смоук,
-описано в [карте проверок](docs/architecture/testing.md).
-
-Обычный рабочий цикл — `make config-test` и `make smoke`; остальные цели гоняют
-тогда, когда правка их касается. Что утверждает каждая проверка, нужен ли ей
-поднятый стенд, сколько стоит прогон и куда класть новую — в
-[карте проверок](docs/architecture/testing.md).
-
-Остановить контейнеры без удаления данных можно командой `make down`. Если нужно
-вернуть прикладной мир к началу, `make rebuild-storage` запустит в Airflow его
-явную пересборку: удалит прикладные базы ClickHouse, топики и позиции
-потребителей Kafka, затем создаст схему и данные заново. Службы и их тома
-останутся на месте. `make clean` удаляет весь стенд вместе с именованными томами
-и для обычной разработки не нужен. Перед пересборкой поставьте `world_live` на
-паузу и дайте уже начатому шаговому дагу закончить день.
-
-## Стартовый мир
-
-Стартовый мир и его паспорт описаны в [справочнике
-мира](docs/architecture/world.md).
-
-## Как позвать генератор
-
-Режимы и команды запуска генератора описаны в
-[справочнике мира](docs/architecture/world.md#как-запустить-генератор).
-
-### Даги модельного времени
-
-Даги времени, позиция мира и форма запуска описаны в [справочнике
-мира](docs/architecture/world.md#даги-модельного-времени).
-
-## Состав и доступ
+## Адреса и пароли

 С настройками из `.env.example` порты доступны только с локальной машины:

@@ -118,21 +73,37 @@ make check-services
 Службы, пользователи и роли, применение настроек и результаты сверки
 конфигурации описаны в [справочнике стенда](docs/architecture/stand.md).

-## Что здесь будет
+## Сдвинуть мир вперед

- одно широкое событие кликстрима по образцу выгрузки Яндекс Метрики вместо
-  четырёх топиков;
- второй источник — заказы бэкенда, ежедневным слепком в ту же Kafka;
- сверка клиентской покупки с заказом бэкенда: деньги считаем по бэкенду,
-  поведение и атрибуцию — по трекеру;
- анонимный кликстрим и склейка кука↔пользователь через покупки;
- ClickHouse кластером как единственным режимом.
+В Airflow запустите даг `world_next_day`: по умолчанию он сыграет один день, а
+в форме запуска можно задать другое число дней. Снимите с паузы `world_live`,
+и мир поедет сам в темпе модельного времени. Подробности — в [справочнике
+мира](docs/architecture/world.md#даги-модельного-времени).

-## Чем отличается от предшественника
+## Вернуть мир к началу

-Предшественник остаётся стабильным учебным стендом и заморожен для новых фич:
-там событие разрезано на четыре топика, есть только просмотры страниц,
-посетители опознаны по email, ClickHouse — одна нода. Развитие идёт здесь.
+`make rebuild-storage` запустит в Airflow явную пересборку: удалит прикладные
+базы ClickHouse, топики и позиции потребителей Kafka, затем создаст схему
+и данные заново. Службы и их тома останутся на месте. Перед пересборкой
+поставьте `world_live` на паузу и дайте уже начатому шаговому дагу закончить
+день.
+
+## Выключить или сбросить целиком
+
+`make down` остановит контейнеры без удаления данных. `make clean` удалит весь
+стенд вместе с именованными томами и для обычной работы не нужен.
+
+## Подключиться из DBeaver
+
+Драйвер ClickHouse в DBeaver подключается по JDBC через HTTP-порт. Укажите хост
+`127.0.0.1`, порт `28123`, пользователя `analyst` и пароль из переменной
+`CLICKHOUSE_ANALYST_PASSWORD` в `.env`; в образце это `analyst-26-reader`.
+Ко второй ноде — порт `28124`.
+
+Пользователь `analyst` читает все слои и справочники. Нативные порты `29000` и
+`29001` нужны `clickhouse-client`, но не DBeaver. Остальные пользователи и роли
+описаны в [справочнике
+стенда](docs/architecture/stand.md#пользователи-и-роли-clickhouse).

 ## Документация

@@ -143,10 +114,20 @@ make check-services
 - [docs/adr/](docs/adr/) — принятые решения с доводами и отвергнутыми
  вариантами: почему сделано так, а не иначе.
 - [docs/architecture/](docs/architecture/) — рабочие справочники по зонам
-  ответственности: [хранилище](docs/architecture/storage.md) — конвенции имён,
-  раскладка по шардам, приём событий, карта таблиц;
-  [проверки](docs/architecture/testing.md) — что утверждает каждая цель `make`
-  и куда класть новую проверку.
+  ответственности:
+  - [хранилище](docs/architecture/storage.md) — конвенции имён, раскладка по
+    шардам, приём событий, карта таблиц.
+  - [конвейер](docs/architecture/etl.md) — движение данных между слоями и
+    работа дагов.
+  - [мир и модельное время](docs/architecture/world.md) — начальные данные,
+    ход дней и управление генератором.
+  - [стенд](docs/architecture/stand.md) — службы, доступ и настройка.
+  - [проверки](docs/architecture/testing.md) — что утверждает каждая цель
+    `make` и куда класть новую проверку.
+  - [мониторинг](docs/architecture/monitoring/README.md) — сбор метрик и
+    устройство дашборда.
+  - [Superset](docs/architecture/superset.md) — подключения, наборы данных и
+    граница автоматической настройки.
 - [docs/research/](docs/research/) — исследования; сейчас это формат
  кликстрима Яндекса, по которому строится модель события.
 - [docs/formats/](docs/formats/) — описания форматов источников: по ним
@@ -43,7 +43,7 @@
 Сетевых ограничений на `default` нет: порты стенда и так открыты только на
 `127.0.0.1`, а внутри сети Compose дверь заперта паролем.

-Раздел README «Состав и доступ» описывает, кто каким пользователем ходит и где
+Раздел README «Адреса и пароли» описывает, кто каким пользователем ходит и где
 живут пароли; здесь остаются решение и доводы. Отдельного справочника по
 доступу в `docs/architecture/` нет: точные права видны в `access.xml`, конвенция
 чтения через `_v` описана в доке хранилища.
@@ -107,7 +107,7 @@
 источник истины — файл в git. Стенд считает `access.xml` и переданные через
 `.env` значения настройкой при создании контейнера; отдельного способа
 применять их на живом стенде нет, потому что уроки не меняют базовую модель
-доступа. Порядок применения изменений — в разделе README «Состав и доступ».
+доступа. Порядок применения изменений — в разделе README «Адреса и пароли».
 Оба варианта с SQL — локальное хранилище доступа с `ON CLUSTER` и
 реплицированное в keeper — делают пользователей состоянием тома: `.env` на
 них больше не влияет, и появляется расхождение того же сорта, которое README
@@ -4,7 +4,7 @@
 настройки доходят до контейнеров. Состав каркаса обоснован в
 [ADR 0001](../adr/0001-stand-services.md), доступ к ClickHouse — в
 [ADR 0007](../adr/0007-clickhouse-access.md). Адреса и пароли интерфейсов
-остаются в [корневом README](../../README.md#состав-и-доступ).
+остаются в [корневом README](../../README.md#адреса-и-пароли).

 ## Службы

@@ -111,8 +111,8 @@ uv run --project generator python -m clickstream_generator batch \
 ```

 За один запуск можно проиграть несколько дней подряд: `--days 8`. Всё, что
-принимается флагами, принимается и переменными окружения — так генератор позовёт
-даг этапа 5; полный список у `--help`.
+принимается флагами, принимается и переменными окружения — так генератор
+запускают даги модельного времени; полный список у `--help`.

 **Значения по умолчанию есть не у всех параметров, и это сделано специально.**
 Зерно, число дней и темп живого дня описывают модель мира — их генератор знает
@@ -43,7 +43,7 @@

 ### Генератор: откуда берутся данные

-Для менти генератор здесь — источник данных. Глава в общих чертах объяснит,
-откуда берутся события и заказы и в каком виде их получает хранилище. Пока
-главы нет, смотрите [`generator/`](../../generator/) и
+Здесь генератор — источник данных, а не предмет изучения. Глава в общих
+чертах объяснит, откуда берутся события и заказы и в каком виде их получает
+хранилище. Пока главы нет, смотрите [`generator/`](../../generator/) и
 [описание события кликстрима](../formats/clickstream-event.md).