Карта хранилища: поле «Как соединяет» у стрелок #224

New Issue

2026-09-03T11:09:43+03:00

ddmitry commented

2026-09-03 11:09:43 +03:00

Part of #206

Цель

На интерактивной карте хранилища (docs/handbook/architecture-map.html,
тикет #222) карточка стрелки говорит, кто и каким SQL переносит данные, но не
говорит, по какому ключу они соединяются. Ключи есть только в карточках узлов.
Читатель, который щелкает по стрелке, должен получить ответ там же: у каждой
из семнадцати стрелок появляется поле «Как соединяет».

Урок: перенос между слоями — это либо разбор строки целиком, либо соединение
по названным колонкам; какие именно колонки склеивают слои, видно с одного
щелчка.

Кому поручать

Вкусовые решения приняты в #222: форма карточки, словарь, стиль прозы.
Здесь — фактура из SQL и одно новое поле, поэтому исполнитель — модель
попроще (Sonnet или Codex на medium), ревью — одна линия, свежая сессия.
Проза поля — короткая, по образцу соседних полей карточки; на финале —
вычитка по правилам «Языка» AGENTS.md.

Что сделать

В docs/handbook/architecture-map/map.yaml у каждой стрелки (edges)
добавить поле join — одна-две фразы на русском. Порядок ключей в
стрелке: после actor, до links.
В docs/handbook/architecture-map/template.html, функция
renderEdgeCard: показывать поле разделом «Как соединяет» после раздела
«Кто именно» и до ссылок, тем же addSection, что и остальные разделы.
Больше в шаблоне ничего не менять.
Пересобрать карту: uv run docs/handbook/architecture-map/render.py.

Содержание поля — гипотеза, сверить с SQL

Каждую строку проверить по названному файлу; расхождение — исправить и
назвать в отчете. Имена колонок — точно как в DDL sql/ddl/.

Стрелка	Как соединяет	Где проверить
`hits` → `stg.hits_raw_dist`	Соединения нет: сообщение кладется строкой целиком	`sql/ddl/40-stg-views.sql`
`stg.hits_raw_dist` → `ods.event_v`	Соединения нет: матвью разбирает строку в колонки	`sql/ddl/30-ods-views.sql`
`stg.hits_raw_dist` → `ods.event_errors_dist`	Соединения нет: негодная строка уходит целиком вместе с классом ошибки	`sql/ddl/30-ods-views.sql`
`orders` → `stg.orders_raw_dist`	Соединения нет: сообщение слепка кладется целиком, пачка помечена `_load_id`	`sql/stg/orders_raw_load.sql`
`stg.orders_raw_dist` → `ods.order_v`	Соединения нет: разбор строки; версия заказа — `order_id` и `snapshot_date`	`sql/ods/order_parse.sql`
`stg.orders_raw_dist` → `ods.order_errors_dist`	Соединения нет: негодная строка пачки целиком	`sql/ods/order_parse.sql`
`ods.event_v` → `dds.event_v`	Соединения нет: представление переименовывает колонки той же строки	`sql/ddl/50-dds-views.sql`
`dds.event_v` → `dds.session_v`	События одного `client_id` за день, разрезанные по паузам; ключ сессии — по фактическому SQL	`sql/dds/session_rebuild.sql`
`ods.order_v` → `dds.order_v`	По `order_id`; берется текущая версия по `snapshot_date`	`sql/dds/order_rebuild.sql`
`dds.event_v` → `dds.identity_map_v`	Покупка события `purchase_id[1]` = `order_id` заказа	`sql/dds/identity_map_rebuild.sql`
`dds.order_v` → `dds.identity_map_v`	Из заказа берется `user_id` к `client_id` события покупки	`sql/dds/identity_map_rebuild.sql`
`dds.session_v` → `dm.daily_traffic_v`	Группировка сессий по `session_date` → `report_date`; посетители — `uniq(client_id)`	`sql/dm/daily_traffic_rebuild.sql`
`dds.identity_map_v` → `dm.daily_traffic_v`	По `client_id`: известные пользователи	`sql/dm/daily_traffic_rebuild.sql`
`dds.order_v` → `dm.revenue_daily_v`	Позиции заказа раскрываются по `item_sku`; день — `order_date` → `report_date`	`sql/dm/revenue_daily_rebuild.sql`
`dic.products` → `dm.revenue_daily_v`	`dictGet` по `item_sku`, ключ словаря `sku` → `product_category`	`sql/dm/revenue_daily_rebuild.sql`
`dds.event_v` → `dm.purchase_vs_orders_v`	`purchase_id[1]` события = `order_id`; день — `order_day`	`sql/dm/purchase_vs_orders_rebuild.sql`
`dds.order_v` → `dm.purchase_vs_orders_v`	По `order_id`; `FULL JOIN` с покупками, отсутствующая сторона — `NULL`	`sql/dm/purchase_vs_orders_rebuild.sql`

Форма фразы — как у соседних полей карточки: короткая, без «ё», без
олицетворений (не «стрелка соединяет», а «строки соединяются по …» или
«ключ — …»), имена колонок в обратных кавычках.

Критерии приемки

У всех семнадцати стрелок в map.yaml есть поле join, каждое
сверено с названным SQL; расхождения с таблицей названы в отчете.
Карточка стрелки показывает раздел «Как соединяет» между «Кто именно»
и ссылками; в шаблоне изменена только renderEdgeCard.
uv run docs/handbook/architecture-map/render.py --check и
make lint зеленые; grep -n 'ё' docs/handbook/architecture-map/map.yaml
молчит.
Никакие другие файлы не изменены.

Границы

Узлы, слои, механизмы, раскладка, стили, README и главы путеводителя не
трогаются. Справочники, DDL, SQL и даги не правятся.
Никаких коммитов: правки остаются в рабочем дереве.

Сначала прочитать

docs/handbook/architecture-map/README.md и map.yaml — форма стрелки
и стиль полей.
docs/handbook/architecture-map/template.html, функции addSection,
renderNodeCard, renderEdgeCard.
SQL из таблицы выше.
AGENTS.md, раздел «Язык».

Команды проверки

uv run docs/handbook/architecture-map/render.py
uv run docs/handbook/architecture-map/render.py --check
make lint
grep -n 'ё' docs/handbook/architecture-map/map.yaml

Part of #206 ## Цель На интерактивной карте хранилища (`docs/handbook/architecture-map.html`, тикет #222) карточка стрелки говорит, кто и каким SQL переносит данные, но не говорит, по какому ключу они соединяются. Ключи есть только в карточках узлов. Читатель, который щелкает по стрелке, должен получить ответ там же: у каждой из семнадцати стрелок появляется поле «Как соединяет». Урок: перенос между слоями — это либо разбор строки целиком, либо соединение по названным колонкам; какие именно колонки склеивают слои, видно с одного щелчка. ## Кому поручать Вкусовые решения приняты в #222: форма карточки, словарь, стиль прозы. Здесь — фактура из SQL и одно новое поле, поэтому исполнитель — модель попроще (Sonnet или Codex на `medium`), ревью — одна линия, свежая сессия. Проза поля — короткая, по образцу соседних полей карточки; на финале — вычитка по правилам «Языка» AGENTS.md. ## Что сделать 1. В `docs/handbook/architecture-map/map.yaml` у каждой стрелки (`edges`) добавить поле `join` — одна-две фразы на русском. Порядок ключей в стрелке: после `actor`, до `links`. 2. В `docs/handbook/architecture-map/template.html`, функция `renderEdgeCard`: показывать поле разделом «Как соединяет» после раздела «Кто именно» и до ссылок, тем же `addSection`, что и остальные разделы. Больше в шаблоне ничего не менять. 3. Пересобрать карту: `uv run docs/handbook/architecture-map/render.py`. ## Содержание поля — гипотеза, сверить с SQL Каждую строку проверить по названному файлу; расхождение — исправить и назвать в отчете. Имена колонок — точно как в DDL `sql/ddl/`. | Стрелка | Как соединяет | Где проверить | |---|---|---| | `hits` → `stg.hits_raw_dist` | Соединения нет: сообщение кладется строкой целиком | `sql/ddl/40-stg-views.sql` | | `stg.hits_raw_dist` → `ods.event_v` | Соединения нет: матвью разбирает строку в колонки | `sql/ddl/30-ods-views.sql` | | `stg.hits_raw_dist` → `ods.event_errors_dist` | Соединения нет: негодная строка уходит целиком вместе с классом ошибки | `sql/ddl/30-ods-views.sql` | | `orders` → `stg.orders_raw_dist` | Соединения нет: сообщение слепка кладется целиком, пачка помечена `_load_id` | `sql/stg/orders_raw_load.sql` | | `stg.orders_raw_dist` → `ods.order_v` | Соединения нет: разбор строки; версия заказа — `order_id` и `snapshot_date` | `sql/ods/order_parse.sql` | | `stg.orders_raw_dist` → `ods.order_errors_dist` | Соединения нет: негодная строка пачки целиком | `sql/ods/order_parse.sql` | | `ods.event_v` → `dds.event_v` | Соединения нет: представление переименовывает колонки той же строки | `sql/ddl/50-dds-views.sql` | | `dds.event_v` → `dds.session_v` | События одного `client_id` за день, разрезанные по паузам; ключ сессии — по фактическому SQL | `sql/dds/session_rebuild.sql` | | `ods.order_v` → `dds.order_v` | По `order_id`; берется текущая версия по `snapshot_date` | `sql/dds/order_rebuild.sql` | | `dds.event_v` → `dds.identity_map_v` | Покупка события `purchase_id[1]` = `order_id` заказа | `sql/dds/identity_map_rebuild.sql` | | `dds.order_v` → `dds.identity_map_v` | Из заказа берется `user_id` к `client_id` события покупки | `sql/dds/identity_map_rebuild.sql` | | `dds.session_v` → `dm.daily_traffic_v` | Группировка сессий по `session_date` → `report_date`; посетители — `uniq(client_id)` | `sql/dm/daily_traffic_rebuild.sql` | | `dds.identity_map_v` → `dm.daily_traffic_v` | По `client_id`: известные пользователи | `sql/dm/daily_traffic_rebuild.sql` | | `dds.order_v` → `dm.revenue_daily_v` | Позиции заказа раскрываются по `item_sku`; день — `order_date` → `report_date` | `sql/dm/revenue_daily_rebuild.sql` | | `dic.products` → `dm.revenue_daily_v` | `dictGet` по `item_sku`, ключ словаря `sku` → `product_category` | `sql/dm/revenue_daily_rebuild.sql` | | `dds.event_v` → `dm.purchase_vs_orders_v` | `purchase_id[1]` события = `order_id`; день — `order_day` | `sql/dm/purchase_vs_orders_rebuild.sql` | | `dds.order_v` → `dm.purchase_vs_orders_v` | По `order_id`; `FULL JOIN` с покупками, отсутствующая сторона — `NULL` | `sql/dm/purchase_vs_orders_rebuild.sql` | Форма фразы — как у соседних полей карточки: короткая, без «ё», без олицетворений (не «стрелка соединяет», а «строки соединяются по …» или «ключ — …»), имена колонок в обратных кавычках. ## Критерии приемки - [x] У всех семнадцати стрелок в `map.yaml` есть поле `join`, каждое сверено с названным SQL; расхождения с таблицей названы в отчете. - [x] Карточка стрелки показывает раздел «Как соединяет» между «Кто именно» и ссылками; в шаблоне изменена только `renderEdgeCard`. - [x] `uv run docs/handbook/architecture-map/render.py --check` и `make lint` зеленые; `grep -n 'ё' docs/handbook/architecture-map/map.yaml` молчит. - [x] Никакие другие файлы не изменены. ## Границы - Узлы, слои, механизмы, раскладка, стили, README и главы путеводителя не трогаются. Справочники, DDL, SQL и даги не правятся. - Никаких коммитов: правки остаются в рабочем дереве. ## Сначала прочитать 1. `docs/handbook/architecture-map/README.md` и `map.yaml` — форма стрелки и стиль полей. 2. `docs/handbook/architecture-map/template.html`, функции `addSection`, `renderNodeCard`, `renderEdgeCard`. 3. SQL из таблицы выше. 4. `AGENTS.md`, раздел «Язык». ## Команды проверки ```bash uv run docs/handbook/architecture-map/render.py uv run docs/handbook/architecture-map/render.py --check make lint grep -n 'ё' docs/handbook/architecture-map/map.yaml ```

ddmitry added the wayfinder:task label 2026-09-03 11:09:43 +03:00

ddmitry referenced this issue

2026-09-03 11:09:47 +03:00

Реализация учебной программы: документация стенда и ТЗ лаб #206

ddmitry referenced a pull request that will close this issue

2026-09-03 11:35:03 +03:00

docs(handbook): добавить поле «Как соединяет» на карте #225

ddmitry closed this issue

2026-09-03 12:32:43 +03:00

Sign in to join this conversation.