From ec9dd4c1a8c7b89e63e5e1988ea0c905292210c8 Mon Sep 17 00:00:00 2001
From: Dmitry Dementev <me@dementev.space>
Date: Sun, 20 Sep 2026 13:20:39 -0400
Subject: [PATCH] =?UTF-8?q?docs(map):=20=D1=81=D1=81=D1=8B=D0=BB=D0=BA?=
 =?UTF-8?q?=D0=B8=20=D0=BD=D0=B0=20=D0=BC=D0=B0=D1=82=D0=B5=D1=80=D0=B8?=
 =?UTF-8?q?=D0=B0=D0=BB=D1=8B=20=D0=BF=D0=B5=D1=80=D0=B5=D0=BD=D0=B5=D1=81?=
 =?UTF-8?q?=D0=B5=D0=BD=D1=8B=20=D0=B2=20Gitea?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/design/architecture-map.html          |  8 +++++---
 docs/design/architecture-map/README.md     | 15 ++++++++++++---
 docs/design/architecture-map/map.json      |  1 +
 docs/design/architecture-map/render.py     | 17 +++++++++++++++--
 docs/design/architecture-map/template.html |  7 ++++---
 docs/design/db_schema.md                   | 10 +++++-----
 6 files changed, 42 insertions(+), 16 deletions(-)

diff --git a/docs/design/architecture-map.html b/docs/design/architecture-map.html
index ec3e9e4..7072ae1 100644
--- a/docs/design/architecture-map.html
+++ b/docs/design/architecture-map.html
@@ -148,7 +148,7 @@
   <header>
     <h1 id="page-title"></h1>
     <p class="lead" id="lead"></p>
-    <p class="navigation"><a href="db_schema.md">Руководство: от бронирования до витрины</a> · Учебная ветка main</p>
+    <p class="navigation"><a href="https://git.dementev.space/ddmitry/airflow-greenplum/src/docs/design/db_schema.md" target="_blank" rel="noopener noreferrer">Руководство: от бронирования до витрины (Gitea)</a> · Учебная ветка main</p>
   </header>
   <div class="controls">
     <div class="switcher" id="switcher" aria-label="Вид связей"></div>
@@ -196,11 +196,12 @@
     </div>
     <aside id="details" aria-live="polite" aria-label="Карточка выбранного объекта"></aside>
   </main>
-  <noscript>Для интерактивной карты включите JavaScript. Объяснение модели доступно в <a href="db_schema.md">руководстве</a>.</noscript>
+  <noscript>Для интерактивной карты включите JavaScript. Объяснение модели доступно в <a href="https://git.dementev.space/ddmitry/airflow-greenplum/src/docs/design/db_schema.md">руководстве в Gitea</a>.</noscript>
   <script>
     const MAP = {
   "title": "Хранилище авиаперевозок",
   "lead": "От бронирования до витрины: выберите таблицу или связь.",
+  "repository_url": "https://git.dementev.space/ddmitry/airflow-greenplum/src/",
   "layers": [
     {
       "id": "source",
@@ -5001,7 +5002,8 @@
       links.forEach((item) => {
         const row = document.createElement("li");
         const link = document.createElement("a");
-        link.href = item.url;
+        // Выбор таблицы остается в локальной карте; файлы открываются в Gitea.
+        link.href = item.url.startsWith("#") ? item.url : new URL(item.url, new URL("docs/design/", MAP.repository_url)).href;
         link.target = "_blank";
         link.rel = "noopener noreferrer";
         link.textContent = item.label;
diff --git a/docs/design/architecture-map/README.md b/docs/design/architecture-map/README.md
index 0107994..aa38469 100644
--- a/docs/design/architecture-map/README.md
+++ b/docs/design/architecture-map/README.md
@@ -1,8 +1,8 @@
 # Исходники карты DWH
 
 Готовый файл - [../architecture-map.html](../architecture-map.html).
-Откройте его локально в браузере. Сервер и интернет не требуются;
-SQL и Markdown открываются из соседних каталогов репозитория.
+Откройте его локально в браузере. Для самой карты сервер и интернет не требуются.
+Ссылки на SQL, DAG и Markdown открывают Gitea, поэтому для переходов нужен интернет.
 Учебный маршрут находится в [руководстве о структуре](../db_schema.md).
 
 ## Редактирование и сборка
@@ -28,6 +28,13 @@ uv run docs/design/architecture-map/render.py --check
 Проверка входов учитывает именованные таблицы в FROM/JOIN;
 смысл соединений нужно сверять при изменении SQL вручную.
 
+`repository_url` в `map.json` задает адрес Gitea с окончанием `/src/`.
+В нем нет имени ветки или коммита: Gitea открывает файл из текущей ветки
+по умолчанию. Пути в `links` остаются относительными к готовому HTML,
+чтобы сборка проверяла файлы и разделы в локальном репозитории;
+интерфейс преобразует их в адреса Gitea. Ссылки вида `#node=…` остаются
+в локальной карте. Ссылка на руководство в шапке собирается из того же адреса.
+
 Внешние `stg.*_ext` представлены в карточках STG, поскольку это входы чтения,
 а не еще одна копия данных. Поля источника сверяются с контрактом PXF.
 Для заглушек используются DDL и `docs/assignment/analyst_spec.md`.
@@ -55,6 +62,8 @@ uv run docs/design/architecture-map/render.py --check
 4. У факта откройте обе роли `dim_airports`, путь через `ods.routes`
    и выбор версии `dim_routes`. Проверьте отдельные карточки связей.
 5. Откройте адрес объекта, обновите страницу, проверьте назад/вперед.
-   Откройте DDL, загрузку, DQ и пункт задания из карточки.
+   Откройте DDL, загрузку, DQ, DAG и пункт задания из карточки в Gitea.
+   Проверьте форматирование Markdown, подсветку кода и переход к разделу задания.
+   Ссылка на таблицу должна открывать локальную карту с тем же выбором.
 6. Проверьте выбор клавишами Enter/пробел и вид на узком экране.
    На узком экране карта прокручивается, карточка находится под ней.
diff --git a/docs/design/architecture-map/map.json b/docs/design/architecture-map/map.json
index ca16d32..0384c8e 100644
--- a/docs/design/architecture-map/map.json
+++ b/docs/design/architecture-map/map.json
@@ -1,6 +1,7 @@
 {
   "title": "Хранилище авиаперевозок",
   "lead": "От бронирования до витрины: выберите таблицу или связь.",
+  "repository_url": "https://git.dementev.space/ddmitry/airflow-greenplum/src/",
   "layers": [
     {
       "id": "source",
diff --git a/docs/design/architecture-map/render.py b/docs/design/architecture-map/render.py
index 32d92fd..f2468ba 100644
--- a/docs/design/architecture-map/render.py
+++ b/docs/design/architecture-map/render.py
@@ -10,8 +10,9 @@ from __future__ import annotations
 import argparse
 import json
 import re
+from html import escape
 from pathlib import Path
-from urllib.parse import unquote, urlsplit
+from urllib.parse import unquote, urljoin, urlsplit
 
 HERE = Path(__file__).resolve().parent
 ROOT = HERE.parents[2]
@@ -34,6 +35,15 @@ def headings(text: str) -> set[str]:
 
 def validate(data: dict) -> None:
     """Сверить объекты, поля, статусы, входы готовых SQL и локальные ссылки."""
+    repository = urlsplit(data["repository_url"])
+    if (
+        repository.scheme != "https"
+        or not repository.netloc
+        or not repository.path.endswith("/src/")
+        or repository.query
+        or repository.fragment
+    ):
+        raise ValueError("Укажите HTTPS-адрес репозитория Gitea с окончанием /src/")
     nodes = {node["id"]: node for node in data["nodes"]}
     if len(nodes) != len(data["nodes"]):
         raise ValueError("Повторяется идентификатор объекта")
@@ -140,7 +150,10 @@ def main() -> int:
         if template.count(MARKER) != 1:
             raise ValueError("В шаблоне должен быть ровно один маркер данных")
         payload = json.dumps(data, ensure_ascii=False, indent=2).replace("<", "\\u003c")
-        result = NOTICE + template.replace(MARKER, payload)
+        guide_url = urljoin(data["repository_url"], "docs/design/db_schema.md")
+        result = NOTICE + template.replace(MARKER, payload).replace(
+            "__GUIDE_URL__", escape(guide_url, quote=True)
+        )
         if args.check:
             if not OUTPUT.exists() or OUTPUT.read_text(encoding="utf-8") != result:
                 raise ValueError(
diff --git a/docs/design/architecture-map/template.html b/docs/design/architecture-map/template.html
index 6baf267..15fd3a1 100644
--- a/docs/design/architecture-map/template.html
+++ b/docs/design/architecture-map/template.html
@@ -147,7 +147,7 @@
   <header>
     <h1 id="page-title"></h1>
     <p class="lead" id="lead"></p>
-    <p class="navigation"><a href="db_schema.md">Руководство: от бронирования до витрины</a> · Учебная ветка main</p>
+    <p class="navigation"><a href="__GUIDE_URL__" target="_blank" rel="noopener noreferrer">Руководство: от бронирования до витрины (Gitea)</a> · Учебная ветка main</p>
   </header>
   <div class="controls">
     <div class="switcher" id="switcher" aria-label="Вид связей"></div>
@@ -195,7 +195,7 @@
     </div>
     <aside id="details" aria-live="polite" aria-label="Карточка выбранного объекта"></aside>
   </main>
-  <noscript>Для интерактивной карты включите JavaScript. Объяснение модели доступно в <a href="db_schema.md">руководстве</a>.</noscript>
+  <noscript>Для интерактивной карты включите JavaScript. Объяснение модели доступно в <a href="__GUIDE_URL__">руководстве в Gitea</a>.</noscript>
   <script>
     const MAP = /*__MAP_DATA__*/;
     const NS = "http://www.w3.org/2000/svg";
@@ -252,7 +252,8 @@
       links.forEach((item) => {
         const row = document.createElement("li");
         const link = document.createElement("a");
-        link.href = item.url;
+        // Выбор таблицы остается в локальной карте; файлы открываются в Gitea.
+        link.href = item.url.startsWith("#") ? item.url : new URL(item.url, new URL("docs/design/", MAP.repository_url)).href;
         link.target = "_blank";
         link.rel = "noopener noreferrer";
         link.textContent = item.label;
diff --git a/docs/design/db_schema.md b/docs/design/db_schema.md
index 241e755..d6ecbbf 100644
--- a/docs/design/db_schema.md
+++ b/docs/design/db_schema.md
@@ -15,11 +15,11 @@ xdg-open docs/design/architecture-map.html
 ```
 
 На Windows можно открыть этот же файл в Проводнике. Сервер, интернет и работающий
-Docker для карты не нужны. Храните HTML рядом с остальными файлами репозитория:
-ссылки из карточек ведут в локальные SQL и Markdown.
-Браузер может показать Markdown как текст, а SQL предложить скачать.
-Скачанный файл можно открыть в редакторе; для форматированного чтения
-руководства используйте Markdown preview.
+Docker для карты не нужны: все ее данные включены в HTML.
+Ссылки на SQL, DAG, задание и это руководство открывают файлы в Gitea:
+документы — с форматированием, код — с подсветкой синтаксиса.
+Для этих переходов нужен интернет. Файлы берутся из текущей ветки репозитория
+по умолчанию.
 
 **В Gitea ссылка на HTML обычно показывает исходный текст, а не карту.**
 Сначала откройте локальный HTML. Адресная ссылка вида