netwatch/doc/DATABASE.md

Datenbankdokumentation

Dieses Dokument beschreibt das Datenbankschema des netzwerkbasierten Dokumentations- und Verkabelungstools.

Die Datenbank ist so entworfen, dass sie:

• reale Netzwerkinfrastrukturen exakt abbildet
• keine Annahmen über Topologien erzwingt
• auch exotische Technologien unterstützt
• langfristig erweiterbar bleibt

Die Datenbank ist für Single-User-Betrieb ausgelegt.

---

Überblick

Die Datenbank lässt sich grob in folgende Bereiche gliedern:

1. Standort- & Gebäude-Struktur
2. Racks & physische Infrastruktur
3. Gerätetypen & Geräte
4. Ports, Module & Verbindungstypen
5. Logische & physische Verbindungen

---

1. Standort- & Gebäude-Struktur

locations

Repräsentiert einen übergeordneten Standort (z. B. Firmencampus, Außenstelle).

Verwendung

• Oberste organisatorische Ebene
• Kann mehrere Gebäude enthalten

---

buildings

Ein Gebäude innerhalb eines Standorts.

Verwendung

• Gruppiert Stockwerke
• Ermöglicht mehrere Gebäude pro Standort

Beziehung

• Gehört zu genau einem Standort

---

floors

Ein Stockwerk innerhalb eines Gebäudes.

Verwendung

• Träger für Stockwerkspläne (SVG)
• Gruppiert Räume, Racks und Netzwerkdosen

Besonderheiten

• svg_path verweist auf den grafischen Stockwerksplan

---

rooms

Ein Raum innerhalb eines Stockwerks.

Verwendung

• Dient zur räumlichen Zuordnung von Netzwerkdosen
• Kann im SVG-Plan positioniert werden

Grafische Attribute

• x, y, width, height zur visuellen Darstellung im Stockwerks-SVG
• polygon_points (JSON) fuer optionale Freiform-Polygone auf Basis der Stockwerkskarte

---

2. Netzwerkdosen

network_outlets

Physische Netzwerkdose innerhalb eines Raums.

Verwendung

• Repräsentiert Wand- oder Bodendosen
• Kann mehrere Ports besitzen

Grafische Attribute

• x, y zur Platzierung im Stockwerksplan

---

network_outlet_ports

Einzelne Ports einer Netzwerkdose.

Verwendung

• Jeder Port ist ein vollwertiger Verbindungspunkt
• Kann direkt mit Geräten, Switches oder Modulen verbunden werden

---

Patchpanel-Objekte im Floorplan

Patchpanels haben eine Sonderstellung: Sie sind fest verkabelte Bündel von Ports und werden nicht wie normale devices im Rack verschoben, sondern als eigene Floorplan-Objekte fest auf einem Stockwerk positioniert.

Verwendung

• Repräsentieren physische Patchfelder auf dem Stockwerksplan.
• Werden im SVG mit festen x/y-Koordinaten verankert und symbolisieren deren reale Position.
• Ermöglichen die Dokumentation der dauerhaften Verbindungen zu anderen Patchpanels, Netzwerkdosen oder Geräteports ohne Rack-Neuanlage.

Grafische Attribute

• x, y, width, height für die Visualisierung im Floorplan.
• name/label und port_count für die eindeutige Kennzeichnung.
• Optional: connection_group oder cross_connect_id, um zusammengehörige Patchfelder zu bündeln.

Verbindungen

• Jeder Patchpanel-Port wird über connections mit passenden Gegenstellen verbunden (andere Patchpanels, Dosen, Geräteports, Module).
• Da sie Teil der Floorplan-Grafik sind, lassen sich die permanenten Kabelverbindungen direkt auf der Stockwerkskarte darstellen.

Tabellenstruktur floor_patchpanels

Die Bühne für Patchpanel-Objekte auf dem Stockwerkplan.

• floor_id referenziert das Stockwerk, in dem das Panel liegt.
• pos_x, pos_y, width, height definieren das feste Rechteck auf der SVG.
• port_count und comment beschreiben die Kapazität und zusätzliche Hinweise.

Tabellenstruktur floor_patchpanel_ports

• Jeder Eintrag ist ein physischer Port eines Patchpanels.
• Attributes: Panel-Referenz, name, port_type_id, optionale VLAN- bzw. Status-Attribute.
• Ports werden über connections sowohl mit anderen Patchpanels als auch mit Netzwerkbuchsen (network_outlet_ports) oder Gerätports verbunden; dadurch lassen sich Router-Kabel grafisch darstellen.

Status (18. Februar 2026)

• Floorplan- und CRUD-Module wurden für Patchpanels als Floor-Objekte inkl. Port-Pflege erweitert (floor_patchpanels, floor_patchpanel_ports).
• Verbindungen zwischen Patchpanel ↔ Patchpanel und Patchpanel ↔ Netzwerkbuchse sind in der connections-Logik abbildbar.
• UI/CSV/Export-Dokumentation weiter ausbauen, damit Planer Kabelverläufe direkt auswerten können.

---

3. Racks & physische Infrastruktur

racks

Ein Serverschrank oder Netzwerkschrank.

Verwendung

• Befindet sich auf einem Stockwerk
• Enthält Geräte

---

4. Gerätetypen & Geräte

device_types

Definiert eine Gerätevorlage.

Verwendung

• Bestimmt Aussehen, Portanzahl und Portpositionen
• Wird beim Anlegen eines Geräts instanziiert

Grafik

• Unterstützt SVG und Bitmap (PNG/JPG)
• Grundlage für alle grafischen Ansichten

Technische Attribute

• shape_definition: JSON-Objekt mit meta und shapes. meta enthält den Formfaktor ('10', '19', 'other'), die Rack-Höhe in HE (heightHe) sowie die Zeichenflächen-Abmessungen (canvasWidth, canvasHeight). Bei 1HE-Geräten mit 10" oder 19" Frontpanel wird der Zeichenbereich automatisch auf die dort üblichen Breiten/Höhen (420×80px bzw. 760×80px) skaliert und zusätzlich von einem weißen Rahmen mit schwarzer Linie umgeben, damit die Darstellung den realen Formfaktor besser widerspiegelt. Der shapes-Array enthält wie bisher die einzelnen Formen (rect, circle, text), die im Editor platziert wurden.

---

device_type_ports

Portdefinitionen eines Gerätetyps.

Verwendung

• Definiert, wo sich Ports im Bild befinden
• Wird beim Erzeugen eines Geräts kopiert

Grafische Attribute

• x, y: relative Position im Gerätebild

Metadata

• JSON-Feld für erweiterte Eigenschaften

---

devices

Konkretes Gerät in der Infrastruktur.

Verwendung

• Instanz eines Gerätetyps
• Kann in einem Rack platziert werden
• Beim Anlegen eines Geräts werden Ports aus device_type_ports übernommen

Rack-Attribute

• rack_position_he
• rack_height_he

Technische Attribute

• web_config_url: Optionale Adresse zur Weboberfläche / Webconfig des Geräts.

---

device_ports

Ports eines konkreten Geräts.

Verwendung

• Entstehen aus device_type_ports
• Tragen den aktuellen Betriebszustand

Technische Attribute

• Status (aktiv / deaktiviert)
• VLAN-Konfiguration
• Modus (Access, Trunk, Custom)

---

5. Port- & Verbindungstypen

port_types

Definiert die physische oder logische Art eines Ports.

Beispiele

• RJ45
• SFP
• LC
• BNC
• Proprietär

Zweck

• Einheitliche Typisierung von Ports
• Grundlage für Modul-Kompatibilität

---

connection_types

Definiert die Art einer Verbindung.

Verwendung

• Bestimmt technische Eigenschaften
• Steuert grafische Darstellung

Grafische Attribute

• Linienfarbe
• Linienart (durchgezogen, gestrichelt, gepunktet)

---

6. Module (z. B. SFP)

modules

Ein Modul, das in einen Port eingesetzt werden kann.

Verwendung

• SFP, SFP+, QSFP, Medienkonverter, Spezialkarten
• Kann selbst Ports besitzen

---

module_ports

Ports eines Moduls.

Verwendung

• Verbindungspunkt nach außen
• Typischerweise Glasfaser- oder Spezialports

---

device_port_modules

Verknüpfung zwischen Geräteport und eingesetztem Modul.

Verwendung

• Erlaubt modulare Portstrukturen
• Unterstützt komplexe Hardware-Topologien

---

7. VLANs

vlans

Definiert VLANs unabhängig von Ports.

Verwendung

• Wiederverwendbare VLAN-Definitionen
• Referenz in Port- und Verbindungs-Konfigurationen

---

8. Verbindungen

connections

Zentrale Tabelle für alle Verbindungen.

Verwendung

• Verbindet beliebige Ports miteinander
• Unterstützt:
  • Geräteports
  • Modulports
  • Dosenports

Designentscheidung

• Ports werden polymorph referenziert (port_type, port_id)
• Ermöglicht maximale Flexibilität ohne Schemaänderungen

Zusatzinformationen

• VLAN-Konfiguration
• Betriebsmodus
• Freitext-Kommentare

---

Designphilosophie

• Grafik ist Teil des Modells
• Ports sind universelle Verbindungspunkte
• Keine Einschränkung auf Ethernet
• Keine Annahmen über Netzwerk-Topologie
• Erweiterbarkeit vor Perfektion

---

Hinweis zur Erweiterung

Das Schema ist vorbereitet für:

• Mehrbenutzerbetrieb
• Historisierung
• API-Nutzung
• Exporte
• Design-Themes

Diese Funktionen sind bewusst nicht Bestandteil der ersten Version.