docs(map): добавлены карта и руководство по структуре DWH
Объяснены зерно таблиц, связи и путь бронирования до витрины. Добавлена автономная карта с двумя видами связей и адресами объектов. Состояние заглушек сверено с DDL и ТЗ; SQL и DAG не изменялись. Проверки: сборка и ссылки, make lint, pytest (4 passed, 14 skipped), Chromium file:// offline: выбор, связи, сброс, история и узкий экран. Refs #2
This commit is contained in:
1 parent
77d72b08c6
commit
b9bcfe7230
9 files changed
+10806
-373
No files matched your search
@@ -0,0 +1,60 @@
|
||||
# Исходники карты DWH
|
||||
|
||||
Готовый файл - [../architecture-map.html](../architecture-map.html).
|
||||
Откройте его локально в браузере. Сервер и интернет не требуются;
|
||||
SQL и Markdown открываются из соседних каталогов репозитория.
|
||||
Учебный маршрут находится в [руководстве о структуре](../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 вручную.
|
||||
|
||||
Внешние `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 и пункт задания из карточки.
|
||||
6. Проверьте выбор клавишами Enter/пробел и вид на узком экране.
|
||||
На узком экране карта прокручивается, карточка находится под ней.
|
||||
Reference in new issue
Block a user