docs(readme): корневой README пересобран по четырем блокам
Зачем: README был складом сведений, осевших там, где писались. По раскладке резолюции #211 он становится лицом репозитория: промо-блок, «куда я попал», типовые действия, ссылки. Слово «менти» уходит из README и путеводителя, хвосты #212 и #214 закрываются. Что: промо-цитата со ссылкой на план обучения и ментора; шапка с нейтральной адресацией и одной фразой о составе и пути данных; «Быстрый старт» сжат до двух команд по решению владельца — проверки остаются роботам, в README одна ссылка на карту проверок; разделы «Адреса и пароли», «Сдвинуть мир вперед», «Вернуть мир к началу», «Выключить или сбросить целиком», «Подключиться из DBeaver»; «Документация» называет все семь справочников вложенным списком. Умерли «Статус», «Что здесь будет», «Чем отличается от предшественника» и три заголовка-якоря. В world.md снята устаревшая фраза о «даге этапа 5», stand.md и ADR 0007 ведут на новый раздел «Адреса и пароли», в путеводителе снято слово «менти». Проверка: скрипт ссылок пуст, grep «менти» по README и путеводителю пуст, make config-test зеленый. Саморевью Sol 1/1; слепое ревью Opus — 0 блокеров, 2 minor, 3 nit, все закрыты; вычитка прозы ai-text-lint и оптикой литературного русского — 15 находок, 9 внесены, 6 отклонены как слова владельца и термины. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
1 parent
e56b23816e
commit
7108cd4af3
5 files changed
+72
-91
No files matched your search
@@ -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/) — описания форматов источников: по ним
|
||||
|
||||
Reference in new issue
Block a user