docs: карта и руководство по структуре DWH #5

2026-09-20T20:02:50+03:00

ddmitry commented

2026-09-20 20:02:50 +03:00

Читателю было трудно связать бронирование, билет, сегмент и рейс с таблицами хранилища. Теперь руководство ведет через учебную поездку к факту и витрине, а автономная карта раскрывает смысл строк, ключи, входы загрузки и дальнейшее использование.

Closes #2
Задача: #2
Серия: #1

Что изменено

Карта на основе интерфейса Clickstream: 39 объектов источника/STG/ODS/DDS/DM, 90 связей, постоянное расположение, подсветка источников и потребителей, карточки и адреса #node=.... Переключение потока данных и связей по ключам сохраняет выбранную таблицу. Внешние stg.*_ext представлены внутри карточек STG.
Карточки сверены с действующими SQL/DDL, для девяти учебных заглушек — с DDL и актуальным ТЗ. Отдельно показаны две роли аэропорта, lookup через ods.routes, версия SCD2 по дате рейса и сохранение NULL в ранее вставленных ключах факта. Логические ключи не названы физическими ограничениями; стрелки данных отделены от порядка задач Airflow.
Легенда показывает образцы сплошных, пунктирных и выделенных стрелок, рамок и цветов таблиц; подписи соответствуют выбранному виду связей.
db_schema.md переписан вокруг небольшого явно вымышленного примера. Каталог объектов хранится в map.json; руководство использует адресные ссылки и не дублирует полный каталог. Входы README обновлены, существующие используемые якоря сохранены.
HTML включает данные, стили и JavaScript, открывается с диска без сервера и сети. Исходники и команда сборки лежат рядом. SQL, DAG, задание и руководство открываются в Gitea с подсветкой кода и форматированием Markdown. Адреса /src/путь не содержат ветку или коммит: Gitea выбирает текущую ветку по умолчанию. Для переходов к файлам нужен интернет; адреса таблиц остаются локальными.

SQL, DDL, DAG, конфигурация, данные стенда и содержание заданий не изменены. В docs/assignment/README.md обновлено только название ссылки на переписанное руководство. В reading_the_pipeline.md исправлены название раздела и устаревшее объяснение пунктира. Задачи #3 и #4 остаются отдельными.

Статические проверки

uv run docs/design/architecture-map/render.py --check: 39 объектов, 90 связей, 208 ссылок; поля проверены по DDL/PXF, входы готовых SQL совпали со стрелками, статусы загрузок/DQ и готовый HTML актуальны.
Проверены 68 локальных ссылок измененных Markdown, адреса объектов и входящие якоря db_schema.md.
make lint, Black/isort нового сборщика и git diff --check прошли.
make test: 4 passed, 14 skipped. 13 DAG smoke-тестов пропущены предусловием доступности Airflow в тестовом окружении; интеграционный ODS-тест требует RUN_ODS_INTEGRATION=1.

Проверка интерфейса

Выполнена в Chromium Headless Shell 131 через Playwright: HTML открыт по file:// при отключенной сети, внешних запросов и ошибок JavaScript нет. Для проверки переходов в Gitea сеть включена отдельно. Снимки общего вида, карточки факта, связи SCD2, экрана 390px, Markdown задания и SQL в Gitea просмотрены визуально.

Проверены:

все 39 адресных карточек, выбор таблиц и SVG-связи мышью, карточки двух ролей аэропорта, ODS lookup, SCD2 и посадочного талона;
сквозной путь через билет, STG/ODS-сегменты, факт и витрину, а также самолеты/места: выбранный объект, координаты всех таблиц и прокрутка сохраняются при обоих переключениях вида;
снятие выделения повторным выбором, кнопкой и Esc; Enter/пробел; reload, назад/вперед, неизвестный идентификатор;
реальные переходы по адресам без ветки на DDL/load/DQ/DAG и Markdown в Gitea: код отображается с подсветкой, ТЗ и руководство — с форматированием; ссылка на задание прокручивает страницу к разделу 1.1; ссылка на таблицу открывает локальную карту с тем же выбором и без сети;
отсутствие обрезанных подписей узлов и горизонтального переполнения страницы на ширине 390px;
образцы легенды визуально проверены на ширине 1440 и 390px в обоих видах: стили стрелок совпадают со стилями карты, подписи переключаются, выбранная таблица и координаты сохраняются.

Встроенный collaborative preview не смог выполнить навигацию; UI-проверка проведена локальным Chromium. Живые загрузки Airflow/Greenplum не запускались, примеры строк в руководстве не взяты из работающего стенда. Переход к руководству через Gitea проверен на текущем main; новая редакция этого документа появится по тому же адресу после слияния PR.

Для просмотра: открыть docs/design/architecture-map.html из локальной копии репозитория. Сценарии повторной проверки перечислены в docs/design/architecture-map/README.md.

Читателю было трудно связать бронирование, билет, сегмент и рейс с таблицами хранилища. Теперь руководство ведет через учебную поездку к факту и витрине, а автономная карта раскрывает смысл строк, ключи, входы загрузки и дальнейшее использование. Closes #2 Задача: https://git.dementev.space/ddmitry/airflow-greenplum/issues/2 Серия: https://git.dementev.space/ddmitry/airflow-greenplum/issues/1 ## Что изменено - Карта на основе интерфейса Clickstream: 39 объектов источника/STG/ODS/DDS/DM, 90 связей, постоянное расположение, подсветка источников и потребителей, карточки и адреса `#node=...`. Переключение потока данных и связей по ключам сохраняет выбранную таблицу. Внешние `stg.*_ext` представлены внутри карточек STG. - Карточки сверены с действующими SQL/DDL, для девяти учебных заглушек — с DDL и актуальным ТЗ. Отдельно показаны две роли аэропорта, lookup через `ods.routes`, версия SCD2 по дате рейса и сохранение NULL в ранее вставленных ключах факта. Логические ключи не названы физическими ограничениями; стрелки данных отделены от порядка задач Airflow. - Легенда показывает образцы сплошных, пунктирных и выделенных стрелок, рамок и цветов таблиц; подписи соответствуют выбранному виду связей. - `db_schema.md` переписан вокруг небольшого явно вымышленного примера. Каталог объектов хранится в `map.json`; руководство использует адресные ссылки и не дублирует полный каталог. Входы README обновлены, существующие используемые якоря сохранены. - HTML включает данные, стили и JavaScript, открывается с диска без сервера и сети. Исходники и команда сборки лежат рядом. SQL, DAG, задание и руководство открываются в Gitea с подсветкой кода и форматированием Markdown. Адреса `/src/путь` не содержат ветку или коммит: Gitea выбирает текущую ветку по умолчанию. Для переходов к файлам нужен интернет; адреса таблиц остаются локальными. SQL, DDL, DAG, конфигурация, данные стенда и содержание заданий не изменены. В `docs/assignment/README.md` обновлено только название ссылки на переписанное руководство. В `reading_the_pipeline.md` исправлены название раздела и устаревшее объяснение пунктира. Задачи #3 и #4 остаются отдельными. ## Статические проверки - `uv run docs/design/architecture-map/render.py --check`: 39 объектов, 90 связей, 208 ссылок; поля проверены по DDL/PXF, входы готовых SQL совпали со стрелками, статусы загрузок/DQ и готовый HTML актуальны. - Проверены 68 локальных ссылок измененных Markdown, адреса объектов и входящие якоря `db_schema.md`. - `make lint`, Black/isort нового сборщика и `git diff --check` прошли. - `make test`: 4 passed, 14 skipped. 13 DAG smoke-тестов пропущены предусловием доступности Airflow в тестовом окружении; интеграционный ODS-тест требует `RUN_ODS_INTEGRATION=1`. ## Проверка интерфейса Выполнена в Chromium Headless Shell 131 через Playwright: HTML открыт по `file://` при отключенной сети, внешних запросов и ошибок JavaScript нет. Для проверки переходов в Gitea сеть включена отдельно. Снимки общего вида, карточки факта, связи SCD2, экрана 390px, Markdown задания и SQL в Gitea просмотрены визуально. Проверены: - все 39 адресных карточек, выбор таблиц и SVG-связи мышью, карточки двух ролей аэропорта, ODS lookup, SCD2 и посадочного талона; - сквозной путь через билет, STG/ODS-сегменты, факт и витрину, а также самолеты/места: выбранный объект, координаты всех таблиц и прокрутка сохраняются при обоих переключениях вида; - снятие выделения повторным выбором, кнопкой и Esc; Enter/пробел; reload, назад/вперед, неизвестный идентификатор; - реальные переходы по адресам без ветки на DDL/load/DQ/DAG и Markdown в Gitea: код отображается с подсветкой, ТЗ и руководство — с форматированием; ссылка на задание прокручивает страницу к разделу 1.1; ссылка на таблицу открывает локальную карту с тем же выбором и без сети; - отсутствие обрезанных подписей узлов и горизонтального переполнения страницы на ширине 390px; - образцы легенды визуально проверены на ширине 1440 и 390px в обоих видах: стили стрелок совпадают со стилями карты, подписи переключаются, выбранная таблица и координаты сохраняются. Встроенный collaborative preview не смог выполнить навигацию; UI-проверка проведена локальным Chromium. Живые загрузки Airflow/Greenplum не запускались, примеры строк в руководстве не взяты из работающего стенда. Переход к руководству через Gitea проверен на текущем `main`; новая редакция этого документа появится по тому же адресу после слияния PR. Для просмотра: открыть `docs/design/architecture-map.html` из локальной копии репозитория. Сценарии повторной проверки перечислены в `docs/design/architecture-map/README.md`.

ddmitry added 1 commit 2026-09-20 20:02:52 +03:00

docs(map): добавлены карта и руководство по структуре DWH b9bcfe7230

Объяснены зерно таблиц, связи и путь бронирования до витрины.
Добавлена автономная карта с двумя видами связей и адресами объектов.
Состояние заглушек сверено с DDL и ТЗ; SQL и DAG не изменялись.

Проверки: сборка и ссылки, make lint, pytest (4 passed, 14 skipped),
Chromium file:// offline: выбор, связи, сброс, история и узкий экран.

Refs #2

ddmitry added 1 commit 2026-09-20 20:12:14 +03:00

docs(map): уточнены заголовки и добавлены образцы легенды 6be0442838

ddmitry added 1 commit 2026-09-20 20:20:45 +03:00

docs(map): ссылки на материалы перенесены в Gitea ec9dd4c1a8

ddmitry merged commit b6e950f52c into main

2026-09-20 20:24:01 +03:00

ddmitry referenced this pull request

2026-09-20 20:26:17 +03:00

Добавить интерактивную карту и переписать руководство о структуре DWH #2

ddmitry referenced this pull request

2026-09-20 20:26:19 +03:00

Сделать структуру учебного DWH понятной через карту и связные руководства #1