From 7a3542d933e0f17c5c3dc456f0dbdacb4cd05711 Mon Sep 17 00:00:00 2001 From: Dmitry Dementiev Date: Tue, 1 Sep 2026 23:04:45 +0300 Subject: [PATCH] =?UTF-8?q?docs(architecture):=20=D0=BB=D0=B5=D0=B4=D0=B3?= =?UTF-8?q?=D0=B5=D1=80=20stand.md=20=D1=80=D0=B0=D0=B7=D0=B1=D0=B8=D1=82?= =?UTF-8?q?=20=D0=BF=D0=BE=20=D1=82=D0=B5=D0=BC=D0=B0=D0=BC,=20=D0=BA?= =?UTF-8?q?=D0=B0=D0=BB=D1=8C=D0=BA=D0=B8=20=D0=B2=20world.md=20=D1=81?= =?UTF-8?q?=D0=BD=D1=8F=D1=82=D1=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Зачем: ревью владельца по PR #213. Сверка конфигурации в stand.md приехала из README одним абзацем на двадцать строк, а Superset был приклеен к Airflow без пустой строки. Три места в world.md читались калькой с английского. Что: ледгер «Что проверено» разбит на записи по темам — ClickHouse, Kafka, метрики и Grafana, Airflow, Superset. В world.md заголовок «Как позвать генератор» стал «Как запустить генератор» (якоря в README и generator/README.md обновлены), переписаны абзацы про значения по умолчанию и про сокет Docker. Смысл не менялся. Словарь проекта («пульт мира», «опись мира», «работник», «сырье») не трогался: это термины CONTEXT.md и ADR, их пересмотр — отдельная развилка. Проверка: скрипт ссылок из тикета — пустой вывод; make config-test — ЗЕЛЁНО; старый якорь «как-позвать-генератор» в репозитории не встречается. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_014QBCtU38qSHg5DvgtnKXcW --- README.md | 2 +- docs/architecture/stand.md | 6 +++++- docs/architecture/world.md | 25 +++++++++++++------------ generator/README.md | 6 +++--- 4 files changed, 22 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index d6bb097..580eff9 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,7 @@ Airflow его явную пересборку: удалит прикладны ## Как позвать генератор Режимы и команды запуска генератора описаны в -[справочнике мира](docs/architecture/world.md#как-позвать-генератор). +[справочнике мира](docs/architecture/world.md#как-запустить-генератор). ### Пульт мира diff --git a/docs/architecture/stand.md b/docs/architecture/stand.md index 1abe354..85546cb 100644 --- a/docs/architecture/stand.md +++ b/docs/architecture/stand.md @@ -91,8 +91,11 @@ ClickHouse: создавал отдельный путь каждого шарда без вписанных вручную значений. Для образа зафиксирован точный текущий [LTS-выпуск 26.3.17.56](https://github.com/ClickHouse/ClickHouse/releases/tag/v26.3.17.56-lts); -серверы и keeper используют один образ. Настройки Kafka 4.3.1 сверены с +серверы и keeper используют один образ. + +Настройки Kafka 4.3.1 сверены с [примером односерверного KRaft](https://github.com/apache/kafka/blob/4.3.1/docker/examples/docker-compose-files/single-node/plaintext/docker-compose.yml). + Секция метрик взята из конфигурации закреплённого образа ClickHouse и проверена на серверах и keeper. Подготовка источников Grafana сверена с [официальным описанием автоматической настройки](https://grafana.com/docs/grafana/latest/administration/provisioning/) @@ -116,6 +119,7 @@ Airflow закреплён на 3.3.0. Состав обязательных п `clickhouse-connect`. Официальный провайдер Kafka сам использует `confluent-kafka`; отдельное подключение и его обёртки здесь не нужны, поэтому клиент Kafka добавлен в образ напрямую. + Superset закреплён на 6.1.0; драйвер `clickhouse-connect`, форма `clickhousedb://` и драйвер Postgres сверены с [документацией подключений Superset](https://superset.apache.org/user-docs/6.1.0/databases/) diff --git a/docs/architecture/world.md b/docs/architecture/world.md index 0a5aad9..63a9356 100644 --- a/docs/architecture/world.md +++ b/docs/architecture/world.md @@ -50,7 +50,7 @@ uv run --project generator python -m clickstream_generator batch \ sha256sum tmp/day0.jsonl ``` -## Как позвать генератор +## Как запустить генератор События производит генератор из [`generator/`](../../generator/). Модельный день — функция зерна и номера дня, поэтому один и тот же день всегда даёт те же @@ -112,11 +112,12 @@ uv run --project generator python -m clickstream_generator batch \ флагами, принимается и переменными окружения — так генератор позовёт даг этапа 5; полный список у `--help`. -**Умолчания есть не у всего, и это нарочно.** Зерно, число дней и темп живого -дня описывают модель мира — их генератор знает сам. День на оси, приёмник и имя -топика описывают стенд, на котором его запустили: не назвали — отказ и ненулевой -код возврата, ещё до первого события. Поэтому умолчание дня и живёт в -`Makefile`: день называет тот, кто запускает, а не тот, кого запускают. +**Значения по умолчанию есть не у всех параметров, и это сделано специально.** +Зерно, число дней и темп живого дня описывают модель мира — их генератор знает +сам. День на оси, приемник и имя топика описывают стенд, на котором генератор +запустили: если их не задать, он откажется работать и вернет ненулевой код еще +до первого события. Поэтому значение дня по умолчанию живет в `Makefile`: день +задает тот, кто запускает, а не тот, кого запускают. ## Пульт мира @@ -153,9 +154,9 @@ uv run --project generator python -m clickstream_generator batch \ встанет на границе модельных суток, доиграв начатый день. Форма пульта и доводы целиком — [ADR 0009](../adr/0009-world-control.md). -**Плата названа вслух: планировщику Airflow отдан сокет докера** — иначе -контейнер генератора ему не поднять. Доступ к сокету равен праву root на -машине; для локального учебного стенда размен принят, но знать о нём надо. -Открывает дверь не монтирование, а членство в группе: GID группы `docker` у -каждой машины свой, живёт в `.env` и подсматривается командой -`getent group docker`. +**У этого решения есть цена: планировщику Airflow отдан сокет Docker** — +иначе ему не поднять контейнер генератора. Доступ к сокету равен правам root +на машине; для локального учебного стенда это приемлемо, но знать об этом +нужно. Доступ дает не само монтирование сокета, а членство в группе `docker`: +у нее на каждой машине свой GID, он записан в `.env`, а узнать его можно +командой `getent group docker`. diff --git a/generator/README.md b/generator/README.md index c191572..ce419e2 100644 --- a/generator/README.md +++ b/generator/README.md @@ -77,9 +77,9 @@ ## Команды -Проиграть день — раздел [«Как позвать -генератор»](../docs/architecture/world.md#как-позвать-генератор) справочника -мира и `--help`. +Проиграть день — раздел [«Как запустить +генератор»](../docs/architecture/world.md#как-запустить-генератор) +справочника мира и `--help`. Из этого каталога — цели генератора живут здесь, а не в корне: