ADR-009: Warum klickbare Links Drill-Down-Links nie überschreiben

Status Angenommen

Status	Angenommen
Datum	2026-07-10
Betrifft	`internal/sync/forward.go` — Priority-Regel zwischen Drill-Down-Links und user-definierten Element-Links

Datum

2026-07-10

Betrifft

internal/sync/forward.go — Priority-Regel zwischen Drill-Down-Links und user-definierten Element-Links

1. Kontext

Seit dem link-Feld auf Elementen (#483) kann ein Element auf zwei Arten einen klickbaren Link im draw.io-Export bekommen:

Drill-Down-Link — automatisch gesetzt, wenn das Element scope einer anderen View ist. Klick führt zum Detail-Diagramm (data:page/id,view-<viewID>).
User-definierter Link — explizit im Modell gesetzt ("link": "…"), z. B. auf eine ADR, ein Jira-Ticket oder eine Confluence-Seite.

Was passiert, wenn beide auf demselben Element vorkommen? Ohne klare Regel wäre das Verhalten zufällig davon abhängig, welcher Code-Pfad zuletzt geschrieben hat — nicht vorhersagbar für Nutzer.

2. Entscheidung

Drill-Down-Links haben immer Vorrang vor user-definierten Links.

Begründung:

Drill-Down ist strukturell Teil der Navigation zwischen Views desselben Modells — ein Klick, der innerhalb der Diagramm-Serie bleibt, wird als grundlegender erwartet als ein Sprung nach außen.
Ein Element, das gleichzeitig Scope einer Detail-View ist, hat bereits eine klare "was zeige ich als nächstes"-Antwort — ein zusätzlicher externer Link würde diese Antwort verdecken.
Die Alternative (User-Link gewinnt) würde Drill-Down-Navigation für jedes verlinkte Element stillschweigend brechen, sobald jemand eine ADR verlinkt — ein überraschender Seiteneffekt.

Bei einem Konflikt gibt bausteinsicht sync eine Warnung aus:

WARNING: element <id>: user-defined link overridden by drill-down link (ADR-009)

Der Sync bricht dabei nicht ab — die Warnung ist informativ, damit Modell-Autoren den Konflikt bewusst auflösen können (z. B. den Link auf ein anderes Element verschieben).

3. Konsequenzen

User-definierte Links funktionieren zuverlässig nur auf Elementen, die nicht Scope einer View sind.
Wer beides braucht (Drill-Down UND externen Link auf demselben fachlichen Konzept), modelliert zwei Elemente oder verlinkt die ADR stattdessen von der Detail-View eines Kind-Elements aus.
Die Regel ist einseitig und ohne Konfigurationsoption — Vorhersagbarkeit hat Vorrang vor Flexibilität.

4. Modellelement: Database (PostgreSQL)

onlineshop.db ist die persistente Datenhaltung des Online-Shop-Beispiels aus diesem Tutorial. Technologie: PostgreSQL.

Im Modell (teil_31.jsonc) gibt es genau eine Relationship, die auf diese Komponente zeigt:

onlineshop.payment -> onlineshop.db : "schreibt Transaktion"

Der Payment Service schreibt hierhin jede abgeschlossene Zahlungstransaktion. onlineshop.db selbst hat keine ausgehenden Relationships und ist in keiner View scope — kein Drill-Down-Konflikt, ein user-definierter link bleibt hier also garantiert erhalten (siehe Priority-Regel oben).

5. Live-Demonstration: Sprung zu genau diesem Abschnitt

Das Modell (teil_31.jsonc) verlinkt onlineshop.db nicht nur auf diese Seite, sondern direkt auf diesen Abschnitt hier — https://paul-fleischmann.com/projekte/bausteinsicht/tutorial/examples/teil_31_adr.html#_modellelement_database_postgresql. Klick auf Database im folgenden Diagramm springt deshalb genau hierher, unabhängig davon, ob du diese Seite direkt aufgerufen hast oder sie gerade im Tutorial-Post eingebettet siehst:

Das funktioniert nur, weil der Link im Modell eine vollständige, absolute URL ist — siehe die Einschränkungen dazu im Tutorial-Post. Ein relativer Link (wie ihn onlineshop.api trägt) würde beim SVG-Export gegen den internen Pfad der draw.io-CLI aufgelöst und liefe ins Leere, statt hierher zu springen.