DSFinV-Standards – Visualisierung

Interaktive Datenstruktur-Diagramme für DSFinV-Standards (DSFinV-K, DSFinV-TW).
Gemeinsamer Renderer, ein Build pro Standard, statischer Output in dist/.

Schnellstart

npm install
npm run build             # erzeugt dist/
npm run dev               # Build + lokaler Server auf http://localhost:3000
npm run check             # nur Validierung der Datendateien (kein Build-Output)
bash scripts/release.sh   # dist/ bauen und als dsfinview-<tag>.zip packen

Bedienung des Viewers

Aktion	Ergebnis
Klick auf (i)	Detail-Panel öffnen · erneuter Klick schließt es
Klick auf (i) eines anderen Blocks	Detail-Panel wechselt direkt
Klick auf leere Fläche	Detail-Panel schließen
Hover über Tabellen-Kopf	Tooltip mit Beschreibung, Datei, Abschnitt und Modul
Hover über Feld-Zeile	Tooltip mit Feldbeschreibung und ggf. Hinweis
▾ alle N Felder	Nicht-Schlüsselfelder ein-/ausklappen
Drag auf Tabellen-Kopf	Node verschieben (Position wird gespeichert)
Scroll / Pinch	Zoom
Drag auf leere Fläche	Pan
Ansicht ▾	Dropdown: Layout wählen, alle Tabellen ein-/ausklappen
☀ / ☾	Dark/Light-Theme (folgt beim ersten Besuch der Systemeinstellung)
Suchfeld	Tabellen und Felder filtern, Treffer hervorheben
ℹ (unten links)	Legende ein-/ausblenden (Module, PK/FK, optional)
Exportieren ▾	Dropdown mit PNG- und PDF-Exportoptionen sowie Offline-Download
← Übersicht	Zurück zur Startseite

Layout-Optionen (Ansicht ▾)

Option	Beschreibung
Spalten-Layout	Standard-Layout: Tabellen in bis zu 3 Spalten, Reihenfolge aus Datendatei
Kräfte-Layout	Kräfte-Simulation (Abstoßung + Federkräfte); Kreisstart, überlappungsfrei
Hierarchie-Layout	Topologische Schichten (Kahn-Algorithmus): FK-Quellen oben, abhängige Tabellen unten
Alle ausklappen	Alle Nicht-Schlüsselfelder einblenden
Alle einklappen	Alle Nicht-Schlüsselfelder ausblenden

Export-Optionen

Option	Beschreibung
PNG – Ausschnitt	Aktuell sichtbarer Bereich als PNG (doppelte Auflösung)
PNG – Vollständig	Gesamtes Modell bei aktueller Zoomstufe als PNG
PDF drucken	Diagramm auf A4 Querformat eingepasst, dann Druckdialog
Offline-Datei herunterladen	Standalone-HTML (alles inline, kein Server nötig)

Neuen Standard hinzufügen (3 Schritte)

1. Datendatei anlegen: data/<id>.html mit dsf-meta-Kopf und Tabellen/Kanten (Vorlage: bestehende Datei).
2. dsf-meta ausfüllen: id, title, subtitle, version, storage-key (projektw. eindeutig), dsf-module-Einträge.
3. npm run build – fertig. Keine Änderung an src/ nötig.

Dateiformat data/*.html

<dsf-meta
  id="meinstandard"
  title="Mein Standard 1.0"
  subtitle="Digitale Schnittstelle der Finanzverwaltung für …"
  version="1.0"
  storage-key="meinstandard_pos_v1"
  href="https://example.com/spezifikation">
  <dsf-module key="stamm"   label="Stammdatenmodul"   class="s"/>
  <dsf-module key="einzeln" label="Einzelaufzeichnung" class="e"/>
</dsf-meta>

<dsf-table id="Stamm_Foo" file="foo.csv" module="stamm" col="0" section="3.2.1">
  <dsf-desc>Beschreibung der Tabelle.</dsf-desc>
  <dsf-field name="FOO_ID" type="Zeichen" len="50" pk="1" desc="Primärschlüssel."/>
  <dsf-field name="BAR_ID" type="Zeichen" len="50" fk="1" desc="FK → Stamm_Bar"/>
  <dsf-field name="WERT"   type="Num"     len="2"          desc="Ein Betrag."/>
</dsf-table>

<dsf-edge from="Stamm_Foo" to="Stamm_Bar" type="solid" card-from="1" card-to="N"/>

Attribut-Referenz

<dsf-meta>

Attribut	Pflicht	Beschreibung
id	✓	Eindeutiger Bezeichner (URL-sicher, z.B. dsfinvk)
title	✓	Anzeigename (z.B. DSFinV-K 2.4)
subtitle		Langform
version		Versionsnummer
storage-key	✓	localStorage-Schlüssel für Node-Positionen (projektw. eindeutig!)
href		URL zur offiziellen Spezifikation; wird als „Quelle ↗"-Link unten rechts im Viewer und auf der Übersichtsseite angezeigt

<dsf-module>

Attribut	Beschreibung
key	Interner Schlüssel (referenziert vom module-Attribut der Tabellen)
label	Anzeigename in der Legende
class	Farbklasse: s (Stamm/grün), e (Einzelaufzeichnung/blau), a (Abschluss/orange)

Aktuell stehen 3 Farbslots zur Verfügung. Für Standards mit mehr Modulen müssten weitere CSS-Variablen (--hdr-x, --ring-x, --txt-x) in graph.css ergänzt werden.

<dsf-table>

Attribut	Pflicht	Beschreibung
id	✓	Eindeutiger Tabellenname (gleichzeitig Anzeigename)
file		CSV-Dateiname
module		Schlüssel aus dsf-module
col		Layout-Spalte: 0, 1 oder 2 (Standard: 0)
optional		Tabelle ist optional
section		Abschnittsnummer in der Spezifikation (z.B. 3.2.1); erscheint im Hover-Tooltip und Detail-Panel

<dsf-field>

Attribut	Beschreibung
name	Feldname (Pflicht)
type	Datentyp (Zeichen, Num, …)
len	Länge oder 0 bei Num ohne Längenvorgabe
pk	Primärschlüssel
fk	Fremdschlüssel
optional	Feld ist optional
desc	Kurzbeschreibung (im Tooltip und Detail-Panel)
note	Ergänzender Hinweis (im Detail-Panel hervorgehoben)

<dsf-edge>

Attribut	Beschreibung
from	Quell-Tabellen-ID
to	Ziel-Tabellen-ID
type	solid (durchgezogen) oder ref (gestrichelt)
card-from	Kardinalität an der Quelle (z.B. 1)
card-to	Kardinalität am Ziel (z.B. N, 0..N)

Projektstruktur

/
├── data/
│   ├── dsfinvk.html          # Datendatei DSFinV-K 2.4
│   └── dsfinvtw.html         # Datendatei DSFinV-TW 1.1
├── src/
│   ├── renderer/
│   │   ├── graph.css         # Gemeinsames CSS (Dark/Light-Theme)
│   │   └── graph.js          # Gemeinsamer Renderer (Vanilla JS)
│   ├── templates/
│   │   ├── standard.html     # Seiten-Template pro Standard
│   │   ├── standalone.html   # Template für Offline-Einzeldatei
│   │   ├── index.html        # Template Übersichtsseite
│   │   └── site.css          # CSS nur für die Übersichtsseite
│   └── build/
│       ├── build.js          # Haupt-Build-Skript (npm run build)
│       ├── parse-data.js     # Parst data/*.html → Modell-Objekt
│       ├── validate.js       # Konsistenzprüfungen
│       ├── check.js          # npm run check (nur Validierung)
│       └── dev.js            # npm run dev (Watch + statischer Server)
├── scripts/
│   ├── release.sh            # dist/ bauen und als ZIP packen
│   └── migrate.js            # Einmalige Migration der Legacy-Dateien
├── legacy/                   # Original-Einzeldateien (Referenz)
└── dist/                     # Build-Output (gitignored)
    ├── index.html
    ├── assets/
    ├── dsfinvk/
    ├── dsfinvtw/
    └── downloads/

Build-Output (dist/)

dist/
├── index.html              # Übersicht aller Standards
├── assets/
│   ├── graph.css
│   ├── graph.js
│   ├── html2canvas.min.js  # PNG-Export-Bibliothek
│   └── site.css
├── dsfinvk/
│   └── index.html          # Standard-Seite DSFinV-K
├── dsfinvtw/
│   └── index.html          # Standard-Seite DSFinV-TW
└── downloads/
    ├── dsfinvk_graph.html  # Standalone-Datei (alles inline, offline-fähig)
    └── dsfinvtw_graph.html

dist/ kann mit jedem statischen Webserver ausgeliefert werden (keine absoluten Pfade, auch Unterverzeichnis-Deploy möglich).
Standalone-Dateien in downloads/ funktionieren per Doppelklick vom Dateisystem (file://, kein Server nötig).

Release erstellen

git tag -a v1.x -m "Version 1.x"
bash scripts/release.sh

Das Script baut dist/ und erzeugt dsfinview-<tag>.zip im Projektroot.
Die Zip-Datei kann als Asset in einem Gitea-Release hochgeladen werden.

Validierung (npm run check)

check.js prüft alle data/*.html ohne Build-Output:

• Jede dsf-edge referenziert existierende Tabellen-IDs
• Tabellen-IDs eindeutig pro Datei
• module-Attribut jeder Tabelle in dsf-meta definiert
• col ∈ {0, 1, 2}
• Pflichtattribute vorhanden (dsf-meta id/title/storage-key, dsf-field name)
• storage-key projektw. eindeutig (über alle Datendateien)

Fehler werden mit Dateiname und Element ausgegeben; Exit-Code 1 bricht auch npm run build ab.

Technische Hinweise

• Node ≥ 20, ESM ("type": "module"), Build-Abhängigkeiten: cheerio; Client-Abhängigkeit: html2canvas (wird als Asset kopiert und in Standalone-Dateien inline eingebettet).
• Renderer: Vanilla JS, keine Frameworks, keine Build-Tools clientseitig.
• Theme: Beim ersten Besuch wird prefers-color-scheme ausgewertet; manuelle Wahl wird in localStorage (dsf_theme) gespeichert und hat Vorrang.
• Node-Positionen: Pro Standard in localStorage unter dem jeweiligen storage-key gespeichert. Beim Upgrade von Legacy-Einzeldateien werden alte Keys einmalig migriert.
• Kanten: Kubische Bézier-Kurven; zwischen Spalten horizontal geroutet, innerhalb einer Spalte nach rechts ausweichend. Beim Auf-/Zuklappen von Nodes werden Kanten für die Dauer der CSS-Transition (220 ms) auf jedem Frame neu gezeichnet. Hover hebt Pfad und Kardinalitäts-Labels hervor (zwei SVG-Schichten, JS-gesteuert).
• Legende: Ausgelagert in ein ℹ-Overlay unten links; nicht Teil der Toolbar.
• Layouts: Spalten-Layout (Standard), Kräfte-Layout (force-directed, Kreisstart), Hierarchie-Layout (Kahn-Algorithmus, topologische Schichten).
• PNG-Export: html2canvas rendert #canvas mit Scale 2×. „Ausschnitt" erfasst das sichtbare Fenster; „Vollständig" berechnet die Bounding-Box aller Nodes, passt den Canvas temporär an und stellt danach den Ausgangszustand wieder her.
• PDF-Export: Diagramm wird vor window.print() per Transform auf A4 Querformat (1122 × 794 px) eingepasst und danach wiederhergestellt.