Zum Hauptinhalt springen

Datenmodell

Diese Seite beschreibt die Entitäten, mit denen eine KNX-Clarity-Organisation arbeitet, und wie sie zueinander in Beziehung stehen. Ziel ist es, die Informations­architektur der Plattform verständlich zu machen, ohne Implementierungsdetails preiszugeben — die zugrunde liegende Speicher-Engine, das Tabellenlayout und die Indizes sind bewusst nicht Teil dieser Seite.

Entitäten im Überblick​

Organisation
├── Mitglieder (Nutzer mit Rollen)
├── Kunden
│   └── Eigentümer-Profil (wenn der Kunde auch Portal-Nutzer ist)
└── Projekte
    ├── Projekt-Mitglieder (dem Projekt zugeordnete Nutzer)
    ├── Projekt-Freigaben (an Kunden mit Lese-Zugriff)
    │   └── Schwärzungsregeln (für den Kunden ausgeblendete Räume)
    ├── ETS-Dateien (versionierte Uploads)
    ├── Grundrisse
    ├── Räume
    │   └── Geräte
    │       ├── Gruppenadressen (verknüpft über Gerätefunktionen)
    │       └── Gerätefunktionen
    ├── Servicefälle
    │   └── Kommentare + Anhänge
    ├── Änderungsanfragen
    ├── Aktivitäts-Feed
    ├── Audit-Log-Einträge
    ├── Meilensteine (Grundprogrammierung, Übergabe, Escrow, …)
    ├── Escrow-Eintrag
    └── Transfer-Anfrage (bei Eigentümerwechsel zwischen Organisationen)

Kern-Entitäten​

Organisation​

Der oberste Container. Abrechnung, Mitgliederverwaltung, das Audit-Log und jedes Projekt liegen unterhalb einer Organisation. Eine Nutzerin gehört zu null oder mehr Organisationen; organisationsübergreifender Zugriff ist nie implizit.

Mitglied​

Eine Nutzerin, die einer Organisation zugeordnet ist, mit einer memberRole, die bestimmt, was sie tun darf. Aktuelle Rollen sind admin, integrator und field_staff (siehe Team für die Rollen-Matrix).

Kunde​

Der Datensatz für den Gebäudeeigentümer/Endkunden, den ein Integrator in seiner CRM-artigen „Kunden“-Liste pflegt. Ein Kunde kann ein Anmeldekonto haben oder nicht; sobald er eine Einladung annimmt, wird der Kundeneintrag mit seinem Portalkonto verknüpft, damit er freigegebene Projekte einsehen kann.

Eigentümer-Profil​

Die portalseitige Identität eines Kunden, sobald er sich angemeldet hat. Ein Eigentümer-Profil kann mit Kundendatensätzen mehrerer Integratoren verknüpft sein — nützlich, wenn ein Gebäudeeigentümer mit mehr als einem Integrator arbeitet.

Projekt​

Ein Gebäudeautomatisierungsprojekt. Gehört zu genau einer Organisation und referenziert optional einen Kunden. Hält den Gebäudenamen, die Adresse, den Status (active, completed, archived, escrow) und die Meilensteine, die den Projekt-Lebenszyklus abbilden.

Projekt-Freigabe​

Gewährt einem bestimmten Kunden Lese-Zugriff auf ein bestimmtes Projekt. Die Freigabe trägt optionale Schwärzungsregeln — derzeit eine Liste von Raum-IDs, die der Integrator vor dem Kunden verbergen möchte; das Verbergen eines Raumes verbirgt transitiv seine Geräte, Gruppenadressen und Servicefälle.

ETS-Datei​

Ein versionierter Upload einer .knxproj-Exportdatei. Jeder Upload ist eine neue Version, nie ein Überschreiben. Beim Parsen werden die unten genannten Räume, Geräte, Gruppenadressen und Gerätefunktionen extrahiert.

Grundriss​

Ein PDF- oder Bild-Plan, der einem Projekt angehängt ist. Pläne können mit Markern je Raum annotiert werden; Marker sind für den Kunden sichtbar, wenn der Grundriss als kundensichtbar markiert ist.

Raum → Gerät → Gruppenadresse / Funktion​

Die geparste KNX-Struktur. Räume gehören zu einem Projekt; Geräte zu einem Raum; Gerätefunktionen und Gruppenadressen hängen an Geräten. Gruppenadressen tragen außerdem die kanonische KNX-Adress­notation (1/2/3) und den Datenpunkttyp.

Servicefall​

Ein Ticket im Kontext eines Projekts. Hat einen Status (open, in_progress, resolved, closed), eine Priorität, einen optionalen Anker an Raum/Gerät und einen Kommentar-Verlauf mit Anhängen.

Änderungsanfrage​

Eine vom Kunden initiierte Anfrage zur Änderung in seinem freigegebenen Projekt. Der Integrator genehmigt, lehnt ab oder fragt nach Details; der Kunde sieht einen Status-Verlauf.

Meilenstein​

Ein benannter Kontrollpunkt im Projekt-Lebenszyklus: Grundprogrammierung bestätigt, Abschlagsrechnung gestellt/gezahlt, ETS-Datei freigegeben, Übergabe bestätigt. Die Bestätigung eines Meilensteins ist rollenabhängig — manche nur durch den Integrator, manche durch den Kunden bestätigbar.

Escrow-Eintrag / Transfer-Anfrage​

Optional. Ein Escrow-Eintrag ist das vom Integrator zurückgehaltene Liefer-Paket, das dem Kunden erst nach Bestätigung eines Übergabe-Schritts ausgehändigt wird. Eine Transfer-Anfrage ist die organisations­übergreifende Übergabe, wenn der Besitz von einem Integrator zum anderen wechselt (z. B. bei einem Dienstleisterwechsel des Gebäudeeigentümers).

Aktivitäts-Feed & Audit-Log​

Jede bedeutsame Änderung schreibt einen oder beide Einträge:

  • Einen Aktivitäts-Eintrag — sichtbar im „Aktivität“-Tab des Projekts und im globalen Benachrichtigungsfeed, ausgelegt auf Awareness.
  • Einen Audit-Log-Eintrag — sichtbar unter Einstellungen → Audit-Log, ausgelegt auf Compliance-Prüfung. Nur für Admins.

Beziehungen in Klartext​

  • Eine Organisation hat viele Projekte; jedes Projekt gehört zu genau einer Organisation.
  • Ein Projekt kann höchstens einem Kunden zugeordnet sein; ein Kunde kann vielen Projekten zugeordnet sein.
  • Ein Projekt kann mit vielen Kunden-Nutzern geteilt werden; ein Kunden-Nutzer kann Freigaben für viele Projekte haben (typisch für Eigentümer-Profile, die mehrere Integratoren umfassen).
  • Eine ETS-Datei gehört zu einem Projekt; das Hochladen einer neuen Version ersetzt die alte nicht — sie wird darauf gestapelt.
  • Ein Servicefall gehört zu einem Projekt; Kommentare und Anhänge gehören zu einem Servicefall.

Fragen​

Nutzen Sie die Feedback-Schaltfläche in der App (rechts unten auf jeder Seite) oder schreiben Sie uns an info@knx-clarity.com.