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

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

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

- `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
  образца, чтобы сборка обходилась стандартной библиотекой.

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

```bash
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/пробел и вид на узком экране.
   На узком экране карта прокручивается, карточка находится под ней.