349 lines
14 KiB
Markdown
349 lines
14 KiB
Markdown
<!-- status: canonical -->
|
|
<!-- lastReviewed: 2026-04-26 -->
|
|
<!-- verifiedAgainst: gateway+frontend-nyla (codebase audit 2026-04-26) -->
|
|
|
|
# Datenbank-Architektur
|
|
|
|
## Ueberblick
|
|
|
|
PowerOn verwendet **PostgreSQL** mit einer klaren Trennung: jedes Modul (App, Chat, Billing, Knowledge, Features) hat eine eigene physische Datenbank (`poweron_*`). Datenbank-Zugriffe laufen ueber **Interfaces** (`interfaceDb*.py`), die auf dem zentralen **DatabaseConnector** (`connectorDbPostgre.py`) aufbauen. Datenbanken und Tabellen werden **automatisch** beim ersten Zugriff erzeugt -- kein manuelles Schema-Management noetig.
|
|
|
|
---
|
|
|
|
## Architektur-Stack
|
|
|
|
```
|
|
Route / Service
|
|
|
|
|
v
|
|
Interface (interfaceDb*.py)
|
|
|-- XxxObjects Klasse
|
|
|-- getInterface() Factory (cached)
|
|
|-- setUserContext() -> RBAC-Anbindung
|
|
|
|
|
v
|
|
DatabaseConnector (connectorDbPostgre.py)
|
|
|-- Auto-Create Database
|
|
|-- Auto-Create/Extend Tables (aus Pydantic-Modellen)
|
|
|-- CRUD-Operationen (getRecordset, recordCreate, recordUpdate, recordDelete)
|
|
|
|
|
v
|
|
PostgreSQL (+ pgvector Extension)
|
|
```
|
|
|
|
---
|
|
|
|
## Datenbanken
|
|
|
|
### Inventar
|
|
|
|
| Datenbank | Modul / Zweck | Interface |
|
|
|-----------|---------------|-----------|
|
|
| `poweron_app` | Kernapplikation: UAM, Mandanten, Rollen, RBAC-Regeln, Navigation, Config | `interfaceDbApp.py` |
|
|
| `poweron_chat` | Chat-Verlaeufe, Messages, Attachments | `interfaceDbChat.py` |
|
|
| `poweron_management` | System-Management, Logs | `interfaceDbManagement.py` |
|
|
| `poweron_knowledge` | RAG Knowledge-Store (mit pgvector) | `interfaceDbKnowledge.py` |
|
|
| `poweron_billing` | Billing Accounts, Transactions, Usage | `interfaceDbBilling.py` |
|
|
| `poweron_billing` | Subscriptions (gleiche DB wie Billing) | `interfaceDbSubscription.py` |
|
|
| `poweron_workspace` | AI Workspace Feature-Daten | Feature-Interface |
|
|
| `poweron_automation` | Automation v1 Workflows, Runs | Feature-Interface |
|
|
| `poweron_automation2` | Automation v2 (Graph-Editor) Workflows, Runs | Feature-Interface |
|
|
| `poweron_chatbot` | Chatbot Feature-Daten | Feature-Interface |
|
|
| `poweron_trustee` | Trustee Feature-Daten | Feature-Interface |
|
|
| `poweron_commcoach` | CommCoach Feature-Daten | Feature-Interface |
|
|
| `poweron_neutralization` | Neutralisierungs-Daten | Feature-Interface |
|
|
| `poweron_realestate` | RealEstate Feature-Daten | Feature-Interface |
|
|
| `poweron_teamsbot` | Teams-Bot Feature-Daten | Feature-Interface |
|
|
| `poweron_test` | Test-Datenbank | Nur in Tests |
|
|
|
|
### Namenskonvention
|
|
|
|
Feature-Datenbanken folgen dem Pattern `poweron_{featureCode.lower()}`. Der Datenbankname wird hart-codiert in der `_initializeDatabase()` Methode des jeweiligen Interfaces.
|
|
|
|
### Konfiguration
|
|
|
|
Verbindungsparameter kommen aus `APP_CONFIG` (config.ini / Environment):
|
|
|
|
| Key | Beschreibung |
|
|
|-----|-------------|
|
|
| `DB_HOST` | PostgreSQL Host |
|
|
| `DB_PORT` | PostgreSQL Port |
|
|
| `DB_USER` | Datenbank-Benutzer |
|
|
| `DB_PASSWORD_SECRET` | Passwort (ggf. verschluesselt) |
|
|
| `DB_DATABASE` | Default-DB-Name (Standard: `poweron_app`) |
|
|
|
|
---
|
|
|
|
## Interface-Pattern
|
|
|
|
Jedes Interface folgt einem einheitlichen Aufbau:
|
|
|
|
### XxxObjects Klasse
|
|
|
|
```python
|
|
class AppObjects:
|
|
db: DatabaseConnector # Connector zur eigenen DB
|
|
rbac: RbacClass # RBAC-Integration
|
|
currentUser: dict # Aktueller Benutzer
|
|
mandateId: str # Aktueller Mandant
|
|
featureInstanceId: str # (nur bei Feature-Interfaces)
|
|
```
|
|
|
|
### _initializeDatabase()
|
|
|
|
Setzt den Datenbanknamen und erstellt den Connector:
|
|
|
|
```python
|
|
def _initializeDatabase(self):
|
|
dbDatabase = "poweron_app" # hart-codiert pro Interface
|
|
self.db = DatabaseConnector(
|
|
host=APP_CONFIG.get("DB_HOST"),
|
|
database=dbDatabase,
|
|
user=APP_CONFIG.get("DB_USER"),
|
|
password=APP_CONFIG.get("DB_PASSWORD_SECRET"),
|
|
port=APP_CONFIG.get("DB_PORT")
|
|
)
|
|
```
|
|
|
|
### setUserContext()
|
|
|
|
Bindet Benutzer und RBAC an die Instanz:
|
|
|
|
```python
|
|
def setUserContext(self, currentUser, mandateId):
|
|
self.currentUser = currentUser
|
|
self.userId = currentUser["id"]
|
|
self.mandateId = mandateId
|
|
self.rbac = RbacClass(self.db, dbApp=dbApp)
|
|
self.db.updateContext(self.userId)
|
|
```
|
|
|
|
**RBAC-Besonderheit:** `poweron_app` ist Sonderfall (`dbApp=self.db`), weil RBAC-Regeln selbst in `poweron_app` liegen. Alle anderen Interfaces nutzen `getRootDbAppConnector()` um Rules aus der App-DB zu lesen:
|
|
|
|
```python
|
|
dbApp = getRootDbAppConnector()
|
|
self.rbac = RbacClass(self.db, dbApp=dbApp)
|
|
```
|
|
|
|
### getInterface() Factory
|
|
|
|
Cached pro Kontext:
|
|
|
|
| Interface | Cache-Key | Ergebnis |
|
|
|-----------|-----------|----------|
|
|
| App | `{mandateId}_{userId}` | `AppObjects` |
|
|
| Chat | `{mandateId}_{featureInstanceId}_{userId}` | `ChatObjects` |
|
|
| Billing | `{userId}_{mandateId}` | `BillingObjects` |
|
|
| Knowledge | `"default"` (Singleton) | `KnowledgeObjects` |
|
|
|
|
---
|
|
|
|
## DatabaseConnector
|
|
|
|
### Auto-Initialisierung
|
|
|
|
Beim Erstellen eines `DatabaseConnector` (`initDbSystem()`):
|
|
|
|
```
|
|
1. _create_database_if_not_exists()
|
|
-> Verbindet sich zu DB "postgres"
|
|
-> Prueft pg_database auf Existenz
|
|
-> CREATE DATABASE "{name}" falls fehlend
|
|
|
|
2. _create_tables()
|
|
-> Erstellt nur die _system Registry-Tabelle
|
|
-> Applikations-Tabellen werden lazy durch Interfaces erzeugt
|
|
|
|
3. _connect()
|
|
-> psycopg2-Verbindung zur Ziel-DB
|
|
|
|
4. _initializeSystemTable()
|
|
-> _ensureTableExists(SystemTable)
|
|
```
|
|
|
|
### Lazy Table Creation
|
|
|
|
Tabellen werden **bei erstem Zugriff** automatisch aus Pydantic-Modellen erzeugt (`_ensureTableExists(model_class)`):
|
|
|
|
- **Tabellenname** = Python-Klassenname des Pydantic-Modells (z.B. `Role`, `AccessRule`, `UserMandate`)
|
|
- **Spalten** werden aus Modellfeldern abgeleitet
|
|
- **JSONB** fuer komplexe Typen (dict, list, Pydantic-Submodelle)
|
|
- **vector** fuer pgvector-Felder (Knowledge-Store)
|
|
- **Additive Migration**: Wenn die Tabelle existiert, werden fehlende Spalten automatisch hinzugefuegt. Bestehende Spalten werden **nicht** geaendert oder entfernt.
|
|
|
|
### Connector-Caching
|
|
|
|
```python
|
|
_get_cached_connector(host, database, port)
|
|
```
|
|
|
|
Wiederverwendet einen `DatabaseConnector` pro Datenbank-Identitaet (`host:database:port`). Genutzt von App, Management, Knowledge. Chat und Billing instanziieren direkt (kein Cache).
|
|
|
|
### userId Context
|
|
|
|
`userId` wird ueber eine `contextvar` am Connector gesetzt (`updateContext(userId)`). Damit werden System-Felder (`_createdBy`, `_updatedBy`) automatisch befuellt.
|
|
|
|
---
|
|
|
|
## RBAC-Integration in DB-Abfragen
|
|
|
|
Die RBAC-Schicht greift direkt in Datenbank-Abfragen ein:
|
|
|
|
### Kern-Funktionen in interfaceRbac.py
|
|
|
|
| Funktion | Zweck |
|
|
|----------|-------|
|
|
| `getRecordsetWithRBAC()` | Listet Datensaetze mit RBAC-Filter in SQL WHERE |
|
|
| `buildRbacWhereClause()` | Uebersetzt Access Levels in SQL-Bedingungen |
|
|
| `buildDataObjectKey()` | Baut Keys wie `data.uam.UserInDB` fuer Rule-Lookup |
|
|
| `TABLE_NAMESPACE` | Mapping von Modellnamen zu logischen Namespaces |
|
|
|
|
### Namespace-Mapping
|
|
|
|
`TABLE_NAMESPACE` ordnet Pydantic-Modellnamen logischen Bereichen zu:
|
|
|
|
| Namespace | Modelle (Beispiele) |
|
|
|-----------|-------------------|
|
|
| `uam` | UserInDB, UserMandate, Role, AccessRule |
|
|
| `chat` | ChatHistory, ChatMessage |
|
|
| `files` | FileRecord, FileFolder |
|
|
| `feature.trustee` | TrusteePosition, TrusteeDocument |
|
|
| `feature.workspace` | Workspace-spezifische Modelle |
|
|
|
|
### SQL-Filter nach Access Level
|
|
|
|
| Level | SQL WHERE |
|
|
|-------|-----------|
|
|
| `a` (ALL) | Kein Filter |
|
|
| `m` (MANDATE) | `mandateId = :mandateId` |
|
|
| `o` (OWN) | `_createdBy = :userId` |
|
|
| `n` (NONE) | `1=0` (kein Ergebnis) |
|
|
|
|
---
|
|
|
|
## System-Felder
|
|
|
|
Jedes `PowerOnModel` erbt automatisch System-Felder:
|
|
|
|
| Feld | Beschreibung | Schutz |
|
|
|------|-------------|--------|
|
|
| `id` | UUID, auto-generiert | Immutable |
|
|
| `_createdBy` | userId des Erstellers | Immutable |
|
|
| `_createdAt` | Zeitstempel Erstellung | Immutable |
|
|
| `_updatedBy` | userId der letzten Aenderung | Auto-gesetzt |
|
|
| `_updatedAt` | Zeitstempel letzte Aenderung | Auto-gesetzt |
|
|
|
|
Felder mit fuehrendem `_` sind fuer Anwendungs-CUD geschuetzt -- der Connector erzwingt das unabhaengig von Access Rules.
|
|
|
|
---
|
|
|
|
## Feature-DB-Registrierung
|
|
|
|
Jedes Interface registriert seine Datenbank ueber `registerDatabase()` aus `dbRegistry.py`:
|
|
|
|
1. Jedes `interfaceDb*.py` / `interfaceFeature*.py` definiert eine Modul-Konstante (z.B. `appDatabase = "poweron_app"`)
|
|
2. Auf Modul-Ebene wird `registerDatabase(appDatabase)` aufgerufen — damit ist die DB im zentralen Registry
|
|
3. Der `DatabaseConnector` erzeugt die DB automatisch beim ersten Zugriff
|
|
4. Neue DBs werden automatisch erkannt, entfernte DBs verschwinden
|
|
|
|
---
|
|
|
|
## Database Health und Orphan-Scanner
|
|
|
|
### Ueberblick
|
|
|
|
SysAdmin-Seite unter **Admin > System > Datenbank-Gesundheit** mit zwei Funktionen:
|
|
|
|
1. **Tabellenstatistiken** — Row Count, Size, Index Size, Last Vacuum/Analyze fuer alle Tabellen
|
|
2. **Orphan Cleanup** — Generische Erkennung verwaister Datensaetze mit Clean-Buttons
|
|
|
|
### Dynamische DB-Registry (`modules/shared/dbRegistry.py`)
|
|
|
|
- `registerDatabase(dbName, configPrefix)` — oeffentliche API, aufgerufen in jedem Interface
|
|
- `_getRegisteredDatabases()` — alle registrierten DBs
|
|
- `_getConnectorForDb(dbName)` — Factory fuer read-only Connector
|
|
|
|
### Model-Registry (`modules/datamodels/datamodelBase.py`)
|
|
|
|
- `_MODEL_REGISTRY: Dict[str, Type[PowerOnModel]]` — automatisch via `__init_subclass__`
|
|
- Jede `PowerOnModel`-Subklasse registriert sich beim Import (Tabellenname = Klassenname)
|
|
|
|
### FK-Discovery (`modules/shared/fkRegistry.py`)
|
|
|
|
- Scannt alle PowerOnModel-Subklassen nach `fk_target` in `json_schema_extra`
|
|
- Baut automatisch `{tableName → dbName}` Mapping aus den Annotationen
|
|
- Fallback: Catalog-Query (`information_schema.tables`) fuer unmapped Tables
|
|
- Cached nach erstem Scan
|
|
- `FkRelationship` Dataclass: `sourceDb, sourceTable, sourceColumn, targetDb, targetTable, targetColumn`
|
|
|
|
### FK-Annotationen (`fk_target`)
|
|
|
|
Jedes `*Id`-Feld das eine echte FK-Beziehung darstellt, hat `fk_target` in `json_schema_extra` mit drei Pflichtschluesseln (`db`, `table`, `labelField`):
|
|
|
|
```python
|
|
mandateId: str = Field(
|
|
...,
|
|
json_schema_extra={
|
|
...,
|
|
"fk_target": {"db": "poweron_app", "table": "Mandate", "labelField": "label"},
|
|
},
|
|
)
|
|
```
|
|
|
|
- Standard `targetColumn` ist `"id"`, Sonderfall `Feature.code` nutzt `"column": "code"`
|
|
- `labelField` gibt das Feld fuer das menschenlesbare Label an; `None` = kein Label (Junction-IDs)
|
|
- `fk_target` ist die einzige FK-Annotation — sowohl fuer Orphan-Detection als auch Label-Resolution und UI-Attribute
|
|
- Felder ohne DB-FK (Stripe-IDs, Graph-Node-IDs, polymorphe referenceId) haben kein `fk_target`
|
|
- Startup-Validierung (`validateFkTargets`) prueft Vollstaendigkeit; fehlende Keys brechen den Start ab
|
|
- **Soft FK** (`"softFk": True`): Optionaler Marker fuer "weiche" Referenzen, die Sentinel-/Lineage-Werte halten, fuer die absichtlich keine DB-Zeile existiert (z. B. `AutoWorkflow.templateSourceId = "trustee-receipt-import"` aus `featureModule.getTemplateWorkflows()`). Label-Resolution funktioniert weiterhin; der Orphan-Scanner ueberspringt soft FKs vollstaendig (kein Display, kein Cleanup), damit korrekte Datensaetze nicht geloescht werden.
|
|
|
|
### Orphan-Scanner (`modules/system/databaseHealth.py`)
|
|
|
|
- `_getTableStats(dbFilter)` — `pg_stat_user_tables` + `pg_total_relation_size`
|
|
- `_scanOrphans(dbFilter)` — Same-DB: `NOT EXISTS`, Cross-DB: Parent-IDs laden + `NOT IN`
|
|
- `_cleanOrphans(db, table, column)` — loescht Orphans, gibt Count zurueck
|
|
- `_cleanAllOrphans(force, excludeUserFks)` — alle Orphans bereinigen; `excludeUserFks=True` ueberspringt UserInDB.id-Referenzen
|
|
- `_isUserIdFk(targetTable, targetColumn)` — Helper: matcht `UserInDB.id` (case-insensitive). Eine Stelle, die scan-route + clean-all + frontend gemeinsam nutzen
|
|
- 5-Minuten-Cache fuer Orphan-Ergebnisse
|
|
- **Pre-Filter:** Source-/Target-Tabelle muss existieren, Source-/Target-Spalte muss als physische Spalte vorhanden sein, FK darf nicht `softFk: True` sein. Erst dann wird ein Orphan-Eintrag erzeugt — sonst werden produktive Datensaetze geloescht (z. B. Trustee-Workflows mit Sentinel-`templateSourceId`).
|
|
- **User-FK-Filter:** Orphans, die auf `UserInDB.id` zeigen (Audit-/Billing-/Membership-Reste geloeschter User), gehoeren in den separaten User-Purge-Workflow. Frontend-Checkbox `Ohne FK-Referenzen zu UserInDB.id` (default ON) blendet sie aus dem Scan-Resultat aus, und `clean-all` ueberspringt sie identisch — die UI zeigt also nie Orphans an, die der naechste Klick nicht auch loeschen wuerde.
|
|
|
|
### API (`modules/routes/routeAdminDatabaseHealth.py`)
|
|
|
|
| Methode | Pfad | Beschreibung |
|
|
|---------|------|-------------|
|
|
| GET | `/api/admin/database-health/stats` | Tabellenstatistiken (optional `?db=...`) |
|
|
| GET | `/api/admin/database-health/orphans` | Orphan-Scan (optional `?db=...`, `?excludeUserFks=true`) |
|
|
| POST | `/api/admin/database-health/orphans/clean` | Einzeln-Cleanup `{"db","table","column"}` |
|
|
| POST | `/api/admin/database-health/orphans/clean-all` | Batch-Cleanup `{"force","excludeUserFks"}` |
|
|
|
|
Alle Endpunkte: SysAdmin-only via `requireSysAdminRole`.
|
|
|
|
### Frontend (`AdminDatabaseHealthPage.tsx`)
|
|
|
|
- Tab "Statistiken": Sortierbare Tabelle mit DB-Filter und Summary-Leiste
|
|
- Tab "Orphan Cleanup": Tabelle mit Clean-Button pro Zeile + "Alle bereinigen", Checkboxen `Nur Probleme` und `Ohne FK-Referenzen zu UserInDB.id` (letzteres default ON)
|
|
|
|
---
|
|
|
|
## Schluessel-Dateien
|
|
|
|
| Thema | Pfad |
|
|
|-------|------|
|
|
| PostgreSQL Connector | `gateway/modules/connectors/connectorDbPostgre.py` |
|
|
| DB-Registry | `gateway/modules/shared/dbRegistry.py` |
|
|
| FK-Registry | `gateway/modules/shared/fkRegistry.py` |
|
|
| Database Health | `gateway/modules/system/databaseHealth.py` |
|
|
| Health API Route | `gateway/modules/routes/routeAdminDatabaseHealth.py` |
|
|
| App-DB Interface | `gateway/modules/interfaces/interfaceDbApp.py` |
|
|
| Chat-DB Interface | `gateway/modules/interfaces/interfaceDbChat.py` |
|
|
| Management-DB Interface | `gateway/modules/interfaces/interfaceDbManagement.py` |
|
|
| Knowledge-DB Interface | `gateway/modules/interfaces/interfaceDbKnowledge.py` |
|
|
| Billing-DB Interface | `gateway/modules/interfaces/interfaceDbBilling.py` |
|
|
| Subscription Interface | `gateway/modules/interfaces/interfaceDbSubscription.py` |
|
|
| RBAC in DB-Schicht | `gateway/modules/interfaces/interfaceRbac.py` |
|
|
| Feature-Interface (Template) | `gateway/modules/interfaces/interfaceFeatures.py` |
|
|
| Bootstrap / DB-Seed | `gateway/modules/interfaces/interfaceBootstrap.py` |
|
|
| DB-Migration Script | `gateway/scripts/script_db_export_migration.py` |
|
|
| Datenmodelle (Pydantic) | `gateway/modules/datamodels/` |
|
|
| Frontend Health Page | `frontend_nyla/src/pages/admin/AdminDatabaseHealthPage.tsx` |
|