Интерактивная карта архитектуры: слои хранилища и путь данных #222
Assignees
ddmitry (Dmitry Dementiev)
Clear assignees
ddmitry (Dmitry Dementiev)
No Assignees
ddmitry
ddmitry
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: ddmitry/clickstream-data-platform#222
Reference in new issue
Block a user
Part of #206
Цель
Интерактивная карта архитектуры хранилища — один самодостаточный HTML-файл
docs/handbook/architecture-map.html. Читатель открывает его двойным щелчкомиз любой копии репозитория, без сети и сервера, и видит путь данных через
слои: топики Kafka → STG → ODS → DDS → DM, сбоку зона
dic. Щелчок по узлупоказывает карточку объекта: что это, какой поверхностью его читать, из чего
он физически состоит, какими ключами соединяется с соседями, кто и в каком
ритме его наполняет, ссылки в справочник и DDL. Щелчок по стрелке показывает,
кто переносит данные между узлами и каким SQL.
Охват первой версии — только слои хранилища и путь данных через них
(резолюция #208). Потоки Airflow как второй слой карты, читатели DM
(Superset, Grafana) и генератор в эту версию не входят.
Урок карты: у одного смысла в каждом слое свое имя и своя поверхность, а
данные между слоями переносят три разных механизма — матвью непрерывно, даг
пачкой, представление без копии. Глава «Хранилище и его слои» это
рассказывает, карта дает это увидеть и потрогать.
Файлы
docs/handbook/architecture-map.htmldocs/handbook/architecture-map/map.yamldocs/handbook/architecture-map/template.htmldocs/handbook/architecture-map/render.pymap.yaml, вкладывает его в шаблон как JSON, пишет HTML. Флаг--checkсравнивает свежий рендер с файлом в репозитории и падает при расхожденииdocs/handbook/architecture-map/README.mdrender.py— скриптuvс inline-метаданными (# /// script), единственнаязависимость —
pyyaml. Запуск:uv run docs/handbook/architecture-map/render.py.Рендер детерминирован: тот же
map.yamlиtemplate.htmlдают байт в байт тотже HTML (без времени сборки, без случайных id; ключи JSON — в порядке
map.yaml, не сортируются;ensure_ascii=False). Порядок полей карточкизадает шаблон, а не порядок ключей в данных.
Объем:
render.py— не длиннее 80 строк;template.html— не длиннее 450строк; готовый HTML — не тяжелее 80 КБ. Если форма и бюджет спорят,
побеждает форма: превышение назвать в отчете с причиной.
Содержание: слои, узлы, стрелки
Слои — колонки слева направо. У каждой колонки заголовок и подпись-вопрос из
главы о хранилище:
Зона
dic— не колонка, а отдельный узел под колонками DDS и DM с подписью«сбоку цепочки: справочники».
Узел — один логический объект; его физические формы (
_kafka,_rep,_dist,_mv,_stage_rep,_stage_dist,_v; таблицы ошибок*_errors_*— отдельные узлы, у них свои формы) живут внутри карточки, а не отдельными
узлами. Имя узла на карте — имя, которым читатель его читает: поверхность
_vтам, где представление есть; где его нет (STG, таблицы ошибок) —_dist;для словаря —
dic.products, для Kafka — имя топика.Состав узлов (проверить по DDL в
sql/ddl/и карте таблицdocs/architecture/storage.md#карта-таблиц; расхождение — исправить у себя иназвать в отчете):
hitsordersstg.hits_raw_diststg.orders_raw_distods.event_vods.event_errors_distods.order_vods.order_errors_distdds.event_vdds.session_vdds.order_vdds.identity_map_vdm.daily_traffic_vdm.revenue_daily_vdm.purchase_vs_orders_vdm.dq_summary_vdic.productsСтрелка — перенос данных из узла в узел. У каждой стрелки есть механизм, и
механизмов ровно три; они же — легенда карты:
orders_ingest) или на каждом прогоне конвейера (dds_transform,dm_transform,dq_check)Состав стрелок — гипотеза постановки; источники каждой проверить по SQL в
sql/stg/,sql/ods/,sql/dds/,sql/dm/и по дагам вdags/(sql/dq/стрелок не дает, см. ниже).
Стрелка, которой SQL не подтверждает, убирается; стрелка, которую SQL
показывает, а таблица нет, добавляется; и то и другое — в отчет.
hitsstg.hits_raw_diststg.hits_raw_kafka, матвьюstg.hits_raw_mvstg.hits_raw_distods.event_vods.event_mvstg.hits_raw_distods.event_errors_distods.event_errors_mvordersstg.orders_raw_distorders_ingest, задачаpull_batch, чтецstg.orders_raw_kafka,sql/stg/orders_raw_load.sqlstg.orders_raw_distods.order_vorders_ingest, задачаparse_batch,sql/ods/order_parse.sqlstg.orders_raw_distods.order_errors_distods.event_vdds.event_vsql/ddl/50-dds-views.sqldds.event_vdds.session_vdds_transform,sql/dds/session_*.sqlods.order_vdds.order_vdds_transform,sql/dds/order_*.sqldds.event_vdds.identity_map_vdds_transform,sql/dds/identity_map_rebuild.sqldds.order_vdds.identity_map_vdds.session_vdm.daily_traffic_vdm_transform,sql/dm/daily_traffic_rebuild.sqldds.identity_map_vdm.daily_traffic_vclient_iddds.order_vdm.revenue_daily_vdm_transform,sql/dm/revenue_daily_*.sqldic.productsdm.revenue_daily_vdictGetпоitem_skuзаказа, ключ словаряskudds.event_vdm.purchase_vs_orders_vdm_transform,sql/dm/purchase_vs_orders_*.sqldds.order_vdm.purchase_vs_orders_vУ
dm.dq_summary_vстрелок нет. Ее наполняет дагdq_check, но он непереносит данные, а сравнивает: витрины DM (в том числе те, что строятся на
уроках и в DDL стенда отсутствуют) с DDS, ODS, словарем и паспортом мира.
Рисовать это стрелками — значит утопить карту в линиях ради одного узла.
Узел остается в колонке DM, а его карточка в поле «Кто наполняет» объясняет
это своими словами и перечисляет пять проверок, которые запускает
dags/dq_check.py, с именами их SQL изsql/dq/.У
dic.productsвходящих стрелок тоже нет: словарь читает CSV-файл(
dic.products_file), это не путь данных через слои. Карточка называетисточник в поле «Из чего состоит».
Карточка узла
Поля, в этом порядке; пустое поле не показывается:
главы путеводителя; не пересказ справочника.
_v— публичныйдоговор;
_distу STG и ошибок — потому что представления там нет).stg.hits_raw_kafka— чтец топика;stg.hits_raw_rep— реплицируемаятаблица на шарде; и так далее. Имена — точно как в DDL.
тот же смысл называется у соседа. Основа — таблица «Сквозные ключи» главы о
хранилище; имена колонок сверить с DDL.
DDS и DM — правило обновления: замена партиции дня, полный пересчет новой
версией,
FINALв представлении.docs/architecture/, для DDS и DM —файл объекта в
docs/architecture/dds/или разделdm.md) и «DDL»(файл в
sql/ddl/). Ссылки абсолютные, на веткуmainGitea:https://git.dementev.space/ddmitry/clickstream-data-platform/src/branch/main/<путь>#<якорь>.Карта открывается из любого места, относительные ссылки там не живут.
Якорь — фактический id заголовка на странице Gitea, а не слаг по
догадке: у заголовков с обратными кавычками он другой (
dm.mdдает
dmrevenue_daily_v, неdm-revenue_daily_v). Снимать так:curl -sS <url файла> | grep -oE 'id="user-content-[^"]*"'.Обязательные поля: у каждого узла — «Что это», «Как читать», «Кто наполняет
и как часто», «Ссылки»; «Из чего состоит» — у всех узлов, кроме топиков
Kafka (у
dds.event_vполе состоит из одной фразы: только представление надods.event_v, своей таблицы нет); «Ключи» — у всех узлов ODS,DDS, DM и у словаря, кроме таблиц ошибок и
dm.dq_summary_v. В «Ссылках» уузлов хранилища обе ссылки — справочник и DDL; у топиков Kafka вместо DDL —
описание формата (
docs/formats/clickstream-event.mdдляhits,docs/architecture/orders/snapshot.mdдляorders).Карточка стрелки: заголовок «откуда → куда», механизм, ритм, кто именно
(даг и задача или матвью), ссылка на SQL и на раздел справочника
(
docs/architecture/etl.md,docs/architecture/orders/ingestion.md,docs/architecture/dds/*.md,docs/architecture/dm.md).Каждый факт карточек берется из DDL, SQL, справочников
docs/architecture/,CONTEXT.mdили глав путеводителя. Ничего не додумывается. Нашли расхождениесправочника с кодом — карточка следует коду, расхождение идет в отчет.
Взаимодействие
выделен, его входящий путь (все узлы и стрелки, из которых он собран, до
Kafka) и исходящий путь (все, что из него получается, до DM) подсвечены,
остальное приглушено. Повторный щелчок или Esc снимает выделение. У узлов
без стрелок (
dic.productsна входе,dm.dq_summary_vцеликом) путьпуст — это не ошибка, подсвечивается только сам узел.
узла выделены.
щелчке; уходит вместе с курсором.
стрелки не выбранного потока приглушаются, но остаются на месте: карта не
перестраивается.
это за карта, как ею пользоваться, ссылка на главу «Хранилище и его слои»
(абсолютная, на Gitea).
Раскладку считает скрипт в браузере из данных: колонка — по слою, строка —
по полю
orderузла внутри слоя, зонаdic— под колонками DDS и DM.Стрелки между колонками — кривые Безье от правого края узла к левому краю
следующего. Стрелки внутри одной колонки (три в DDS) выходят из правого
края источника, изгибаются в промежуток между колонками и входят в правый
край цели; порядок узлов в DDS —
dds.event_v,dds.session_v,dds.order_v,dds.identity_map_v, чтобы источник всегда стоял выше цели.Стрелка из
dicвыходит из верхнего края словаря. Карта — один SVG сviewBox, тянетсяпо ширине окна, при узком окне появляется горизонтальная прокрутка. Ни
масштабирования колесом, ни перетаскивания: карта помещается на экран.
Цвета: серые узлы и линии, один акцент для выделения, вторым тоном —
приглушение; потоки различаются не цветом, а фильтром. Шрифт системный.
Все тексты интерфейса — по-русски, обращение на «вы», тире «—» и
кавычки-елочки, без буквы «ё». Никаких внешних запросов: ни шрифтов, ни
скриптов, ни картинок по сети; файл работает по
file://.Где карта упоминается
docs/handbook/README.md: после раздела «Как читать» — раздел «Картахранилища» в четыре-пять строк: что это, ссылка на
architecture-map.html,совет открыть рядом с главой о хранилище. Gitea показывает файл как текст,
а не как страницу, поэтому раздел говорит прямо: откройте файл из своей
копии репозитория или скачайте его кнопкой «Raw» и откройте в браузере.
Остальной текст не меняется.
docs/handbook/storage-layers.md, раздел «Куда дальше»: одна фраза соссылкой на карту и той же оговоркой в двух словах — открывать из своей
копии репозитория. Остальной текст главы не меняется.
Makefile, цельlint: третья строкаuv run docs/handbook/architecture-map/render.py --check, а в две строкиruffдобавляется путьdocs/handbook/architecture-map. Комментарий надцелью дополняется одной фразой: почему проверка рендера живет здесь
(быстрая, стенд не нужен, ловит протухший рендер).
docs/architecture/testing.md: там, где описано, что утверждаетmake lint, — одна фраза про проверку рендера карты; длительность целии дата замера, которые там записаны, обновляются по фактическому прогону.
Больше ничего.
AGENTS.md, раздел «Структура», абзац проdocs/handbook/: после фразыпро индекс папки вставить ровно это предложение: «Исходники интерактивной
карты лежат подпапкой
architecture-map/, а ее рендер — файломarchitecture-map.htmlрядом с главами.» Больше ничего.render.pyобъявляетrequires-python = ">=3.13": такtarget-versionкорневого
ruff.tomlдля него верен, и самruff.tomlне трогается.Критерии приемки
uv run docs/handbook/architecture-map/render.pyсобираетdocs/handbook/architecture-map.html; повторный запуск не меняет файл;--checkзеленый на свежем рендере и красный, если в HTML изменитьодин символ.
file://без сети: ни одного внешнегоsrc,hrefна стили и скрипты,@import,url()на сетевые адреса.Ссылки на Gitea в карточках — обычные
<a target="_blank">.месте; каждый узел открывает карточку со всеми непустыми полями; каждая
стрелка открывает свою карточку.
работают так, как описано в «Взаимодействии». Браузера у исполнителя нет:
он проверяет скрипт чтением и, где возможно, прогоном чистых функций
раскладки и достижимости через
node -e; проверка в браузере — заоркестратором на приемке, исполнитель называет в отчете, что проверить
щелчками.
map.yamlсуществует в коде под этим именем.
main(
curl -sIотвечает 200) и на фактический id заголовка (снят командойиз раздела «Карточка узла», не угадан).
make lintзеленый;ruffв него теперь проверяет иrender.py.docs/handbook/README.md,storage-layers.md,Makefile,testing.mdизменены только в названных местах.README.mdкарты нет «ё», слов «менти»и «оператор», олицетворений («дашборд спрашивает», «заказ ездит»);
обращение на «вы».
карта упоминается», не создано и не изменено.
Границы
docs/architecture/(кроме названных правок вtesting.md),CONTEXT.md, корневойREADME.md,ruff.toml,AGENTS.md(кроме одногоназванного предложения), DDL, SQL, даги и код генератора не правятся. Расхождение справочника с кодом — в отчет, не в правку.
чистом JS, стили — на чистом CSS, оба внутри шаблона.
Сначала прочитать
docs/handbook/storage-layers.md— глава, которую карта дополняет;таблица «Сквозные ключи» и подписи слоев берутся отсюда.
docs/architecture/storage.md— разделы «Имена объектов», «Служебныеколонки», «Актуальные события», «Версии заказов», «Справочники», «Карта
таблиц».
sql/ddl/*.sql— имена и устройство всех объектов.sql/stg/,sql/ods/,sql/dds/,sql/dm/,sql/dq/— источникикаждой стрелки.
dags/— какая задача какого дага исполняет какой SQL; имена дагов изадач — отсюда.
docs/architecture/etl.md,docs/architecture/orders/ingestion.md,docs/architecture/dds/README.md,docs/architecture/dm.md— ритмы иправила обновления для карточек.
docs/handbook/README.md— куда встает раздел о карте.AGENTS.md, раздел «Язык».Команды проверки
Последние две команды должны молчать. Стенд для задачи не нужен.
Сделано, PR #223 (сливается с
Closes #222).Что получилось.
docs/handbook/architecture-map.html— один самодостаточный файл: пять колонок Kafka → STG → ODS → DDS → DM, зонаdicсбоку, 17 узлов и 17 стрелок. Щелчок по узлу открывает карточку (что это, как читать, из чего состоит, ключи, кто наполняет, ссылки в справочник и DDL на Gitea) и подсвечивает входящий и исходящий путь; щелчок по стрелке — механизм, ритм, даг и задача, SQL. Переключатель потока приглушает чужую часть карты, легенда трех механизмов всегда на виду. Исходники —docs/handbook/architecture-map/(map.yaml,template.html,render.py,README.md);make lintпроверяет ruff для сборщика и свежесть рендера.Решения по ходу.
dm.dq_summary_vстрелок нет:dq_checkсравнивает, а не переносит; карточка объясняет это и называет пять проверок. Уdic.productsвхода нет — словарь читает CSV.ёв якорях закодирована.Расхождения справочника с кодом (не правились):
storage.mdво вводке называет две физические модели DDS этапа 4 и не упоминает карту идентичностей; описание55-dm-tables.sqlтам же не упоминаетdm.dq_summary(карта таблиц ниже его содержит).Конвейер. Постановка — Fable, ревью постановки — Opus (18 находок, все внесены). Реализация — Codex (Sol), саморевью 7/7. Два слепых ревью Opus: уместность и вкус (11 находок), код (10); два круга починки, все закрыты; от оркестратора — проверка в headless Chromium (карта не помещалась в окно, совет читать Kafka-таблицу напрямую). Вычитка прозы — Sol: 36 находок, 34 внесены.
Дальше по карте: ТЗ ступеней 2–7 в
docs/labs/— следующий тикет открывается при старте работы.