AFC-Demo/misc/database-tables-detailed-description.md

Detaillierte Beschreibung der Datenbank-Tabellen

Backend Schema

1. backend.transactions

Zweck: Rohdaten-Tabelle für eingehende Transaktionen aus verschiedenen Quellen (vermutlich CSV/Excel-Uploads oder API-Imports)

Struktur: 14 Spalten

Identifikation

• id (integer, NOT NULL, AUTO_INCREMENT)
  • Primärschlüssel
  • Sequenz: backend.transactions_id_seq

Transaktions-Stammdaten

• corporate_entity (text, NOT NULL)

  • Name der durchführenden Firma/Entität
  • Kein Foreign Key - als Textfeld gespeichert

• corporate_counterparty (text, NOT NULL)

  • Name der Gegenpartei/Empfänger
  • Freitext, keine Normalisierung

• tx_date (text, NOT NULL)

  • Transaktionsdatum
  • ⚠️ Als Text gespeichert (nicht als DATE/TIMESTAMP)
  • Wahrscheinlich verschiedene Formate möglich

• tx_amount (double precision, NOT NULL)

  • Transaktionsbetrag
  • Fließkommazahl für Währungsbeträge

• tx_currency (text, nullable)

  • Währungscode (z.B. EUR, USD)
  • Optional

• tx_purpose (text, nullable)

  • Verwendungszweck/Beschreibung der Transaktion
  • Freitextfeld

Geografische Informationen

• tx_country_outgoing (text, nullable)

  • Herkunftsland der Zahlung

• tx_country_incoming (text, nullable)

  • Zielland der Zahlung

Metadaten & Verarbeitung

• source_file (text, nullable)

  • Name/Pfad der Quelldatei
  • Für Nachverfolgbarkeit der Datenherkunft

• raw_payload (text, nullable)

  • Rohdaten im Originalformat
  • Ermöglicht Reprocessing bei Bedarf

• status (text, NOT NULL)

  • Verarbeitungsstatus (z.B. "pending", "processed", "error")

• created_at (text, NOT NULL)

  • Erstellungszeitpunkt
  • ⚠️ Als Text gespeichert (nicht als TIMESTAMP)

• last_modified_at (text, NOT NULL)

  • Letzte Änderung
  • ⚠️ Als Text gespeichert (nicht als TIMESTAMP)

Charakteristik: ETL-/Staging-Tabelle mit lockerer Typisierung für maximale Flexibilität beim Import

---

2. backend.transaction_outputs

Zweck: Speichert generierte Outputs/Ergebnisse aus Prompt-Verarbeitung für Transaktionen (vermutlich KI/LLM-generierte Analysen)

Struktur: 5 Spalten

Primärschlüssel (zusammengesetzt)

• transaction_id (integer, NOT NULL)

  • Foreign Key zu backend.transactions.id
  • Referenziert die analysierte Transaktion

• prompt_id (integer, NOT NULL)

  • Foreign Key zu backend.prompt_templates (vermutlich)
  • Identifiziert welcher Prompt verwendet wurde

• output_key (text, NOT NULL)

  • Schlüssel für den Output-Typ
  • Beispiele: "risk_assessment", "compliance_check", "summary", "recommendations"

Output-Daten

• content (text, NOT NULL)
  • Der generierte Inhalt/Ergebnis
  • Kann strukturierter Text, JSON oder Markdown sein

Verknüpfung

• run_id (integer, nullable)
  • Foreign Key zu backend.prompt_runs (vermutlich)
  • Gruppiert Outputs aus demselben Batch/Durchlauf
  • Optional für ad-hoc Generierungen

Charakteristik: N:M-Mapping zwischen Transaktionen und Prompts mit flexiblen Output-Keys

---

Public Schema

3. public.companies

Zweck: Normalisierte Firmenstammdaten für KYC (Know Your Customer) und Compliance

Struktur: 11 Spalten

Identifikation

• id (bigint, NOT NULL, AUTO_INCREMENT)
  • Primärschlüssel
  • Sequenz: companies_id_seq

Firmenidentifikation

• name (varchar, NOT NULL)

  • Primärer Firmenname (Kurzform/Handelsname)

• legal_name (varchar, nullable)

  • Offizieller rechtlicher Name
  • Kann vom Handelsnamen abweichen

• ticker (varchar, nullable)

  • Börsenticker-Symbol (z.B. "AAPL", "MSFT")
  • Nur für börsennotierte Unternehmen

Klassifikation & Lokalisierung

• sector (varchar, nullable)

  • Wirtschaftssektor/Branche
  • Z.B. "Technology", "Finance", "Manufacturing"

• country (varchar, NOT NULL, default: 'DE')

  • Ländercode (ISO 2-Letter)
  • Standard: Deutschland

• headquarters (varchar, nullable)

  • Hauptsitz/Firmenzentrale
  • Stadt oder Stadt + Land

Risk & Compliance

• kyc_risk_level (varchar, NOT NULL, default: 'medium')
  • KYC-Risikoeinstufung
  • Mögliche Werte: "low", "medium", "high"
  • Default: mittleres Risiko

Zusatzinformationen

• summary (text, nullable)
  • Firmenbeschreibung/Zusammenfassung
  • Freitextfeld für Kontext

Zeitstempel

• created_at (timestamp, nullable)

  • Erstellungszeitpunkt

• updated_at (timestamp, nullable)

  • Letzte Aktualisierung
  • Laravel-Standard für Timestamps

Charakteristik: Saubere, normalisierte Stammdatentabelle mit KYC-Fokus

---

4. public.transactions

Zweck: Produktive Transaktionsdaten mit umfassender Anreicherung aus externen Datenquellen und Risikoanalyse

Struktur: 54 Spalten (!)

Identifikation

• id (bigint, NOT NULL, AUTO_INCREMENT) - 9x aufgelistet (⚠️ Schema-Anomalie!)
  • Primärschlüssel
  • Sequenz: transactions_id_seq

Transaktions-Basis

• company_id (bigint, NOT NULL, default: 1)

  • Foreign Key zu public.companies.id
  • Zuordnung zur durchführenden Firma

• reference (varchar, NOT NULL)

  • Transaktionsreferenz/Buchungsnummer
  • Eindeutiger Identifier

• amount (numeric, NOT NULL)

  • Transaktionsbetrag
  • Numeric für präzise Währungsbeträge

• currency (varchar, NOT NULL, default: 'EUR')

  • Währungscode
  • Standard: Euro

• counterparty (varchar, NOT NULL)

  • Name der Gegenpartei

• counterparty_country (varchar, nullable)

  • Land der Gegenpartei

• channel (varchar, nullable)

  • Transaktionskanal (z.B. "wire", "sepa", "swift")

• executed_at (timestamp, NOT NULL)

  • Ausführungszeitpunkt der Transaktion

Risk Management

• risk_score (smallint, NOT NULL, default: 0)

  • Risikobewertung (0-100 oder ähnlich)

• status (varchar, NOT NULL)

  • Transaktionsstatus (z.B. "pending", "approved", "flagged")

• requires_review (boolean, NOT NULL, default: true)

  • Manuelles Review erforderlich?

• flagged_by (varchar, nullable)

  • System/User der die Transaktion markiert hat

• flagged_reason (text, nullable)

  • Grund für Markierung

• signals (json, nullable)

  • Risikosignale/Trigger als JSON
  • Strukturierte Risikoindikatoren

Externe Datenquellen (11 Integrationen)

1. Registry (Handelsregister Basic)

• registry_company_number (text)
• registry_source (text) - Quelle (z.B. "Handelsregister")
• registry_match_score (double precision) - Matching-Genauigkeit
• registry_data (jsonb) - Registrierungsdaten
• registry_last_refreshed_at (timestamp)

2. Genesis (Statistisches Bundesamt)

• genesis_context (jsonb)
• genesis_last_refreshed_at (timestamp)

3. GovData (Offene Verwaltungsdaten)

• govdata_data (jsonb)
• govdata_last_refreshed_at (timestamp)

4. Bundesanzeiger

• bundesanzeiger_data (jsonb)
• bundesanzeiger_last_refreshed_at (timestamp)

5. Insolvency (Insolvenzregister)

• insolvency_data (jsonb)
• insolvency_last_refreshed_at (timestamp)

6. RSS Alerts (News/Medien)

• rss_alerts (jsonb)
• rss_last_refreshed_at (timestamp)

7. Sanctions (Sanktionslisten)

• sanctions_data (jsonb)
• sanctions_last_refreshed_at (timestamp)

8. PEP (Politically Exposed Persons)

• pep_data (jsonb)
• pep_last_refreshed_at (timestamp)

9. GLEIF (Legal Entity Identifier)

• gleif_lei (text) - LEI-Nummer
• gleif_data (json)
• gleif_last_refreshed_at (timestamp)

10. EU Sanctions

• eu_sanctions_data (jsonb)
• eu_sanctions_last_refreshed_at (timestamp)

11. Handelsregister (Extended)

• handelsregister_data (jsonb)
• handelsregister_last_refreshed_at (timestamp)
• handelsregister_status (text)
• handelsregister_entity_id (bigint)

Zeitstempel

• created_at (timestamp, nullable)
• updated_at (timestamp, nullable)

Charakteristik: Hochgradig angereichertes Data Warehouse für Compliance und Risk Management mit Multi-Source-Integration

---

Zusammenfassung der Architektur

┌─────────────────────────────────────┐
│     Backend Schema (Staging)        │
├─────────────────────────────────────┤
│ • Rohdaten-Import                   │
│ • Lockere Typisierung (text)        │
│ • Source-Tracking                   │
│ • Prompt/AI-Integration             │
└────────────┬────────────────────────┘
             │
             │ ETL/Processing
             ↓
┌─────────────────────────────────────┐
│     Public Schema (Production)      │
├─────────────────────────────────────┤
│ • Normalisierte Daten               │
│ • Strikte Typisierung               │
│ • Multi-Source-Enrichment           │
│ • Risk & Compliance Features        │
└─────────────────────────────────────┘

Datenfluss-Hypothese

1. Import: Rohdaten landen in backend.transactions
2. AI-Verarbeitung: Prompts generieren Outputs in backend.transaction_outputs
3. Enrichment: Externe Datenquellen werden abgefragt
4. Normalisierung: Daten werden nach public.companies und public.transactions übertragen
5. Risk Assessment: Risikoscores und Flags werden berechnet
6. Review: Transaktionen mit requires_review=true landen in der Queue

Technische Hinweise

Probleme

• ⚠️ public.transactions hat 9x duplizierte id Spalte im Schema
• ⚠️ backend.transactions speichert Timestamps als TEXT statt TIMESTAMP
• ⚠️ Keine expliziten Foreign Key Constraints sichtbar zwischen den Schemas

Empfehlungen

1. Schema-Anomalie in public.transactions untersuchen
2. Datum-Felder in backend.transactions zu echten TIMESTAMP-Typen migrieren
3. Indizes auf häufig genutzte JOIN/WHERE Spalten prüfen
4. Foreign Key Constraints zwischen den Schemas dokumentieren