docs(handbook): интерактивная карта слоев хранилища
Зачем: путеводитель рассказывает путь данных через слои словами, а карта дает его увидеть и потрогать: у одного смысла в каждом слое свое имя и своя поверхность, а переносят данные три разных механизма — матвью непрерывно, даг пачкой, представление без копии. Постановка — тикет #222, форма — резолюция #208 (один самодостаточный HTML, исходники рядом). Что: docs/handbook/architecture-map.html — готовая карта; исходники в docs/handbook/architecture-map/ (map.yaml — слои, узлы, стрелки, карточки; template.html — разметка, стили, скрипт; render.py — сборка и --check; README.md). Щелчок по узлу открывает карточку и подсвечивает путь, щелчок по стрелке — кто и каким SQL переносит данные; переключатель потока приглушает чужую часть карты. Ссылки карточек ведут в справочники и DDL на Gitea. Путеводитель и глава о хранилище ведут на карту; make lint проверяет ruff для сборщика и свежесть рендера; testing.md и AGENTS.md обновлены. Проверка: uv run docs/handbook/architecture-map/render.py --check и make lint зеленые; внешних запросов в HTML нет; ссылки и якоря карточек сверены с Gitea; карта прощелкана в headless Chromium на ширинах 1280–1920: подсветка пути, фильтр, Esc, карточки узлов и стрелок. Ревью: постановка — Opus; реализация — Codex (Sol), два слепых ревью Opus (уместность и код), вычитка прозы Sol.
This commit is contained in:
1 parent
4995628f2a
commit
466acafce6
10 files changed
+2720
-8
No files matched your search
@@ -36,13 +36,13 @@
|
||||
Стенд нужен трём целям из восьми. Цена — замер, см. «Что проверено».
|
||||
`make smoke` и `make check-services` перемерены 28 августа 2026 года,
|
||||
`make config-test` — 21 августа, `make check-clickhouse` — 19 августа,
|
||||
корневой `make lint` — 9 августа, `make test` — 30 августа; остальные стоят с
|
||||
корневой `make lint` — 3 сентября, `make test` — 30 августа; остальные стоят с
|
||||
замера 6 августа.
|
||||
|
||||
| Цель | Откуда | Что утверждает | Стенд | Цена |
|
||||
|---|---|---|---|---|
|
||||
| `make config-test` | корень | Compose разбирается, файлы DAG и дашборды Grafana синтаксически целы, в diff нет пробельных ошибок. О работоспособности не говорит ничего | не нужен | 1 с |
|
||||
| `make lint` | корень | Код стенда — `dags/` и `infra/superset/` — отформатирован и проходит ruff | не нужен | 0,4 с |
|
||||
| `make lint` | корень | Код стенда и сборщик карты отформатированы и проходят ruff; готовый HTML карты соответствует исходникам | не нужен | 0,8 с |
|
||||
| `make smoke` | корень | Стенд **собран**: службы живы, порты отвечают, подключения настроены друг на друга. Вширь и по касательной к каждой службе. Единственная цель, которая здесь правда смоук | нужен | 25 с |
|
||||
| `make check-clickhouse` | корень | Всё, что спрашивают **у ClickHouse** и он отвечает сам: макросы, шарды, реплики, путь в keeper, ключ шардирования, очередь распределённых DDL, ответ словаря товаров, счёт событий стартового мира против паспорта | нужен | 24 с |
|
||||
| `make check-services` | корень | **Службы работают**: DAG запускается и доходит, топик создаётся и удаляется, Superset логинится и ходит в базу | нужен | 71 с |
|
||||
@@ -128,7 +128,7 @@ ClickHouse отвечает сразу.
|
||||
|
||||
Правки генератора добавляют к этому `make lint`, `make typecheck` и `make test`
|
||||
из каталога `generator/`: стенд им не нужен, а `make test` из них самая
|
||||
дорогая. Правки дагов и Superset — корневой `make lint`.
|
||||
дорогая. Правки дагов, Superset и карты — корневой `make lint`.
|
||||
|
||||
Двадцать секунд из ее ста семидесяти шести — пересборка восьми модельных дней
|
||||
для сверки с паспортом мира (20,5 с из 176,5). Дешевле хеши не сравнить: чтобы
|
||||
@@ -286,6 +286,10 @@ Kafka по той же причине спрашивают снаружи. Её
|
||||
|
||||
## Что проверено
|
||||
|
||||
**Перезамер 3 сентября 2026 года при исполнении #222.** `make lint` прошел за
|
||||
0,768 секунды; в таблице 0,8 с. `ruff format --check` проверил 13 файлов стенда,
|
||||
включая исходники карты, а затем проверка рендера подтвердила свежесть HTML.
|
||||
|
||||
**Калибровка заказной стороны 30 августа 2026 года при исполнении #194.**
|
||||
Пересборки эталонного мира не будет (#192), поэтому доли заказной стороны
|
||||
сверены замером внутренностей генератора — окно 28 модельных дней,
|
||||
@@ -474,11 +478,11 @@ shell-версия узкой пересборки за 2 м 25 с пересо
|
||||
24 секунды. Это цена всей цели, а не одной новой строки.
|
||||
|
||||
**Замер 9 августа 2026 года при появлении корневого `lint` (#65).** Три прогона
|
||||
подряд — 0,39, 0,36 и 0,39 секунды на трёх файлах стенда; в таблице 0,4 с. На
|
||||
подряд — 0,39, 0,36 и 0,39 секунды на трех файлах стенда, которые тогда входили в проверку; в таблице 0,4 с. На
|
||||
машине с непрогретым кешем первый прогон дороже: `uvx` сначала скачивает ruff.
|
||||
|
||||
Тогда же снято, что двери не перекрываются: `ruff check --show-files` из корня
|
||||
перечисляет ровно три файла стенда, из `generator/` — только файлы генератора.
|
||||
перечислял ровно три файла стенда, из `generator/` — только файлы генератора.
|
||||
Корневой конфиг правила генератору не подменяет: конфиг ищется вверх по дереву
|
||||
от файла, и ближний выигрывает.
|
||||
|
||||
|
||||
Reference in new issue
Block a user