wiki/z-archive/db-structure-model-comparison.md

Detaillierte Analyse: Datenbankstruktur vs. Pydantic-Modelle

Export-Datum: 2026-01-19T20:12:28.176720Z
Export-Quelle: Production Instance

Zusammenfassung

Von 19 Tabellen haben alle ein entsprechendes Pydantic-Modell, aber es wurden Unterschiede gefunden. Die meisten Unterschiede sind erwartbar (z.B. ID-Felder mit default_factory sind im Modell optional, aber in der DB NOT NULL), aber es gibt einige wichtige Inkonsistenzen, die behoben werden sollten.

---

Kritische Unterschiede (müssen behoben werden)

1. UserInDB (datamodelUam.py)

Felder nur in DB (fehlen im Modell):

• privilege (text, nullable)
  • Problem: Feld existiert in der Datenbank, aber nicht im Pydantic-Modell
  • Empfehlung: Entweder Feld zum Modell hinzufügen oder aus der DB entfernen

Typ-Mismatches:

1. roleLabels

   • DB: jsonb (dict) - nullable
   • Modell: List[str] - optional
   • Problem: Datenbank speichert JSONB (wird als dict interpretiert), Modell erwartet Liste von Strings
   • Empfehlung: Prüfen, wie die Daten tatsächlich gespeichert werden. Wenn es eine Liste ist, sollte der Typ in der DB korrekt sein. Wenn es ein dict ist, sollte das Modell angepasst werden.

2. resetTokenExpires

   • DB: text - nullable
   • Modell: float (UTC timestamp in seconds) - optional
   • Problem: Datenbank speichert als Text, Modell erwartet Float (Unix-Timestamp)
   • Empfehlung: DB-Typ sollte double precision (float8) sein, nicht text

---

2. ChatLog (datamodelChat.py)

Felder nur im Modell (fehlen in DB):

• actionNumber (Optional[int])
• roundNumber (Optional[int])
• taskNumber (Optional[int])
• Problem: Diese Felder sind im Modell definiert, aber nicht in der Datenbank vorhanden
• Empfehlung: Entweder Migration erstellen, um diese Spalten hinzuzufügen, oder aus dem Modell entfernen

Typ-Mismatches:

1. progress

   • DB: text - nullable
   • Modell: float (0.0 to 1.0) - optional
   • Problem: Datenbank speichert als Text, Modell erwartet Float
   • Empfehlung: DB-Typ sollte double precision (float8) sein

2. performance

   • DB: text - nullable
   • Modell: Dict[str, Any] - optional
   • Problem: Datenbank speichert als Text, Modell erwartet Dictionary (JSON)
   • Empfehlung: DB-Typ sollte jsonb sein

---

3. Token (datamodelSecurity.py)

Typ-Mismatches:

1. userId

   • DB: text - nullable
   • Modell: str - required (nicht optional)
   • Problem: Datenbank erlaubt NULL, Modell erwartet zwingend einen Wert
   • Empfehlung: DB sollte NOT NULL sein, da es ein required Feld ist

2. authority

   • DB: text - nullable
   • Modell: AuthAuthority (Enum) - required
   • Problem: Datenbank erlaubt NULL, Modell erwartet zwingend einen Wert
   • Empfehlung: DB sollte NOT NULL sein

3. tokenAccess

   • DB: text - nullable
   • Modell: str - required
   • Problem: Datenbank erlaubt NULL, Modell erwartet zwingend einen Wert
   • Empfehlung: DB sollte NOT NULL sein

4. createdAt

   • DB: text - nullable
   • Modell: float (UTC timestamp) - optional
   • Problem: Datenbank speichert als Text, Modell erwartet Float
   • Empfehlung: DB-Typ sollte double precision (float8) sein

5. revokedAt

   • DB: text - nullable
   • Modell: float (UTC timestamp) - optional
   • Problem: Datenbank speichert als Text, Modell erwartet Float
   • Empfehlung: DB-Typ sollte double precision (float8) sein

---

4. UserConnection (datamodelUam.py)

Typ-Mismatches:

1. expiresAt

   • DB: text - nullable
   • Modell: float (UTC timestamp) - optional
   • Problem: Datenbank speichert als Text, Modell erwartet Float
   • Empfehlung: DB-Typ sollte double precision (float8) sein

2. tokenExpiresAt

   • DB: text - nullable
   • Modell: float (UTC timestamp) - optional
   • Problem: Datenbank speichert als Text, Modell erwartet Float
   • Empfehlung: DB-Typ sollte double precision (float8) sein

---

5. ChatWorkflow (datamodelChat.py)

Typ-Mismatches (JSONB vs. List):

Mehrere Felder haben das Problem, dass die DB jsonb (als dict interpretiert) speichert, aber das Modell List[...] erwartet:

• logs: DB=jsonb (dict), Modell=List[ChatLog]
• messages: DB=jsonb (dict), Modell=List[ChatMessage]
• stats: DB=jsonb (dict), Modell=List[ChatStat]
• tasks: DB=jsonb (dict), Modell=List[...]
• expectedFormats: DB=text, Modell=List[...]

Problem: JSONB-Felder werden als Dictionary interpretiert, aber das Modell erwartet Listen. Dies deutet darauf hin, dass die Daten möglicherweise als Arrays im JSONB gespeichert werden sollten, oder dass die Serialisierung/Deserialisierung angepasst werden muss.

Empfehlung: Prüfen, wie diese Daten tatsächlich gespeichert und geladen werden. Möglicherweise benötigt die Anwendung eine Custom Serialisierung für JSONB-Arrays.

---

Erwartbare Unterschiede (keine Aktion erforderlich)

ID-Felder mit default_factory

Viele Tabellen haben ID-Felder, die im Modell als optional=True markiert sind (wegen default_factory=lambda: str(uuid.uuid4())), aber in der DB als NOT NULL definiert sind. Dies ist erwartbar und korrekt, da:

• Pydantic-Felder mit default_factory sind technisch optional (können beim Erstellen weggelassen werden)
• Die Datenbank erwartet jedoch immer einen Wert (NOT NULL)

Betroffene Tabellen: AccessRule, AuthEvent, DataNeutraliserConfig, DataNeutralizerAttributes, Mandate, Role, ChatDocument, FileData, FileItem, Prompt

---

Weitere Typ-Mismatches (möglicherweise erwartbar)

Role.description

• DB: jsonb (dict) - nullable
• Modell: str - optional
• Hinweis: Möglicherweise wird hier ein mehrsprachiges Dictionary gespeichert, während das Modell einen String erwartet. Prüfen, ob eine Custom Serialisierung verwendet wird.

ActionItem.expectedDocumentFormats

• DB: jsonb (dict) - nullable
• Modell: List[...] - optional
• Hinweis: Ähnlich wie bei ChatWorkflow - JSONB vs. List

AutomationDefinition.executionLogs

• DB: jsonb (dict) - nullable
• Modell: List[...] - optional
• Hinweis: Ähnlich wie bei ChatWorkflow - JSONB vs. List

ChatMessage.documents

• DB: jsonb (dict) - nullable
• Modell: List[...] - optional
• Hinweis: Ähnlich wie bei ChatWorkflow - JSONB vs. List

---

Empfohlene Maßnahmen

Priorität 1 (Kritisch - Datenintegrität):

1. UserInDB.privilege: Feld hinzufügen oder entfernen
2. ChatLog: actionNumber, roundNumber, taskNumber hinzufügen oder aus Modell entfernen
3. Token: Required-Felder (userId, authority, tokenAccess) sollten NOT NULL in DB sein
4. Timestamp-Felder: Alle Timestamp-Felder sollten double precision sein, nicht text

Priorität 2 (Wichtig - Typ-Konsistenz):

1. JSONB vs. List: Prüfen und korrigieren der Serialisierung für alle JSONB-Felder, die Listen enthalten sollen
2. UserInDB.roleLabels: Prüfen, ob es wirklich eine Liste oder ein Dictionary ist

Priorität 3 (Optional - Code-Qualität):

1. ID-Felder: Optional können die Modelle angepasst werden, um explizit NOT NULL zu reflektieren (aber nicht notwendig)

---

Technische Details

Typ-Mapping-Probleme

Das Vergleichstool mappt PostgreSQL-Typen wie folgt:

• character varying / varchar / text → str
• boolean / bool → bool
• integer / int / bigint → int
• double precision / float8 → float
• jsonb / json → dict

Problem: JSONB kann sowohl Dictionaries als auch Arrays enthalten. Das Tool interpretiert JSONB immer als dict, auch wenn es tatsächlich ein Array ist. Dies führt zu falschen Mismatch-Meldungen bei Listen-Feldern.

Lösung: Für eine genauere Analyse müsste das Tool die tatsächlichen JSONB-Werte prüfen oder die Datenbank-Schema-Definitionen genauer analysieren.