airflow-greenplum/docs/design/architecture-map/README.md

Исходники карты DWH

Готовый файл - ../architecture-map.html. Откройте его локально в браузере. Для самой карты сервер и интернет не требуются. Ссылки на SQL, DAG и Markdown открывают Gitea, поэтому для переходов нужен интернет. Учебный маршрут находится в руководстве о структуре.

Редактирование и сборка

• map.json - единственный каталог объектов, полей, связей и текстов карточек.
• template.html - интерфейс. SVG, карточки, постоянная раскладка и выделение адаптированы из clickstream-data-platform/docs/handbook/architecture-map/template.html.
• render.py - сборка автономного HTML и статические проверки. Нужны uv и Python 3.11 или новее; пакеты Python и JavaScript не требуются. JSON заменяет YAML образца, чтобы сборка обходилась стандартной библиотекой.

Из корня репозитория:

uv run docs/design/architecture-map/render.py
uv run docs/design/architecture-map/render.py --check

Правьте исходники, затем пересобирайте HTML. --check сверяет: имена объектов с DDL/PXF, важные поля и поля связей, статусы загрузок и DQ, входы готовых SQL со стрелками потока, файлы и разделы по ссылкам, уникальность идентификаторов и позиций, свежесть HTML. Проверка входов учитывает именованные таблицы в FROM/JOIN; смысл соединений нужно сверять при изменении SQL вручную.

repository_url в map.json задает адрес Gitea с окончанием /src/. В нем нет имени ветки или коммита: Gitea открывает файл из текущей ветки по умолчанию. Пути в links остаются относительными к готовому HTML, чтобы сборка проверяла файлы и разделы в локальном репозитории; интерфейс преобразует их в адреса Gitea. Ссылки вида #node=… остаются в локальной карте. Ссылка на руководство в шапке собирается из того же адреса.

Внешние stg.*_ext представлены в карточках STG, поскольку это входы чтения, а не еще одна копия данных. Поля источника сверяются с контрактом PXF. Для заглушек используются DDL и docs/assignment/analyst_spec.md. Новые предположения о поведении загрузок в карточки не добавляйте.

Адреса объектов

../architecture-map.html#node=ods.airplanes выбирает таблицу. Дополнение &view=keys включает связи по ключам; без него показан поток данных. Идентификатор равен полному имени таблицы и не зависит от позиции в карте. Неизвестный адрес возвращает обзор с сообщением. Назад/вперед в браузере восстанавливают предыдущий выбор и вид связей.

Проверка в браузере

Статические проверки не заменяют этот проход:

1. Откройте готовый HTML с диска. Убедитесь, что видны пять слоев, имена таблиц и пометки заданий; ошибок JavaScript нет.
2. Выберите bookings.tickets, затем ods.segments и dds.fact_flight_sales. Проверьте источники, потребителей и карточки связей. Снимите выделение повторным выбором, кнопкой "Общий вид" и клавишей Esc.
3. Для выбранных билета, факта и dds.dim_airplanes переключите оба вида: выбор, позиции и прокрутка карты должны сохраниться.
4. У факта откройте обе роли dim_airports, путь через ods.routes и выбор версии dim_routes. Проверьте отдельные карточки связей.
5. Откройте адрес объекта, обновите страницу, проверьте назад/вперед. Откройте DDL, загрузку, DQ, DAG и пункт задания из карточки в Gitea. Проверьте форматирование Markdown, подсветку кода и переход к разделу задания. Ссылка на таблицу должна открывать локальную карту с тем же выбором.
6. Проверьте выбор клавишами Enter/пробел и вид на узком экране. На узком экране карта прокручивается, карточка находится под ней.