# 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