# Anforderungsdokument v0.1
## Automatisiertes Finance Management & Decision-Support-System

**Version:** 0.1  
**Status:** Draft / Requirements Baseline  
**Sprache:** Deutsch mit English Technical Terms  
**Scope:** Technische Systemarchitektur, Datenmodell, fachliche Anforderungen und MVP-Roadmap  
**Nicht-Ziel:** Keine Investmentstrategie, keine Anlageberatung, kein automatisiertes Trading

---

## 1. Zweck und Leitprinzipien

Das System soll private oder professionelle Finanzdaten automatisiert konsolidieren, strukturieren, analysieren und für menschliche Entscheidungen aufbereiten. Es unterstützt Portfolio-Controlling, Cashflow-Planung, Risikoüberwachung, Steuer-/Income-Übersicht, Watchlist-Monitoring, Reporting und Entscheidungsdokumentation.

### 1.1 Kernprinzipien

- **Human Decision Authority:** Jede Investment-, Rebalancing-, Verkaufs-, Kauf- oder Steuerentscheidung bleibt beim Menschen.
- **No Automated Trading:** Das System darf keine Orders platzieren, keine Broker-Transaktionen auslösen und keine automatisierten Trade-Ausführungen durchführen.
- **Rule-based First:** Berechnungen, Klassifikationen, Alerts und Scoring müssen primär regelbasiert, nachvollziehbar und auditierbar sein.
- **Minimal LLM Usage:** LLMs dürfen nur unterstützend für nicht-deterministische Aufgaben eingesetzt werden, z. B. Textzusammenfassung, Belegklassifikationsvorschläge oder Report-Formulierungen. Kritische Berechnungen und Entscheidungen dürfen nicht LLM-basiert sein.
- **Explainability:** Jede Kennzahl, jeder Alert und jeder Score muss eine nachvollziehbare Quelle, Regel und Berechnungslogik haben.
- **Data Quality over Automation:** Fehlende, doppelte oder inkonsistente Daten müssen sichtbar gemacht werden, statt stillschweigend korrigiert zu werden.

---

## 2. Systemgrenzen

### 2.1 In Scope

- Import und Normalisierung von Konto-, Broker-, Depot-, Transaktions-, Preis-, FX-, Dividenden-, Steuer-, Watchlist- und Makrodaten.
- Portfolio Accounting inklusive Cash, Securities, Fees, Taxes, Dividends, Interest, Splits und Corporate Actions.
- Total Return, Income, Risk, Liquidity und Exposure Analytics.
- Watchlist Pipeline mit regelbasiertem Monitoring und Signal-Priorisierung.
- Dashboard UX für Vermögen, Risiken, Cashflows, Alerts und Reports.
- Entscheidungsunterstützung durch Szenarien, Stress Tests, Bias Detection und Audit Trail.
- Exportierbare Reports für persönliche Review, Steuerunterlagen und Dokumentation.

### 2.2 Out of Scope

- Automatisierte Orderausführung.
- Portfolio-Optimierung mit automatischer Umsetzung.
- Black-box Investmentempfehlungen.
- Steuerberatung oder rechtlich verbindliche Steuerberechnung.
- Garantie für Marktdatenvollständigkeit oder Performance.

---

## 3. Zielnutzer und Rollen

### 3.1 Rollen

- **Owner / Investor:** Prüft Vermögen, Risiken, Cashflows, Reports und entscheidet manuell.
- **Analyst / Controller:** Pflegt Regeln, prüft Datenqualität, erstellt Reports und Szenarien.
- **Admin:** Konfiguriert Integrationen, Berechtigungen, Datenquellen und Systemparameter.
- **Read-only Reviewer:** Sieht Reports, Audit Trail und Dashboards ohne Änderungsrechte.

### 3.2 Rollenrechte

- Owner: Vollzugriff auf Dashboards, Regeln, Reports und manuelle Korrekturen.
- Analyst: Zugriff auf Datenpflege, Analysen, Reports, Watchlists; keine Sicherheits- oder Integrationsadministration.
- Admin: Systemkonfiguration und User Management; nicht automatisch fachlich entscheidungsberechtigt.
- Reviewer: Nur Lesen, Export und Kommentierung.

---

## 4. Zielarchitektur

### 4.1 Architekturüberblick

Das System soll modular aufgebaut sein und eine klare Trennung zwischen Data Ingestion, Accounting Engine, Analytics Layer, Rule Engine, Reporting Layer und Dashboard Frontend besitzen.

**Zielbild:**

1. **Data Sources**
   - Banken, Broker, CSV/Excel, APIs, PDF/Statements, Market Data Provider, FX Provider, Macro Data Provider.

2. **Ingestion Layer**
   - Connectoren, File Uploads, Parser, API Jobs.
   - Validierung von Format, Pflichtfeldern, Währung, Datum und Duplikaten.

3. **Normalization & Staging**
   - Mapping auf internes Canonical Data Model.
   - Quarantäne für unsichere Daten.
   - Source Lineage und Import Audit.

4. **Accounting Engine**
   - Positionsführung, Cash Ledger, Transaction Ledger, Cost Basis, Realized/Unrealized P&L, Fees, Taxes, Corporate Actions.

5. **Reference Data & Market Data Store**
   - Instrumente, ISIN/Ticker, Preise, FX Rates, Benchmarks, Sektoren, Länder, Asset Classes.

6. **Analytics & Rule Engine**
   - Total Return, Risk, Exposure, Stress Tests, Liquidity Ladder, Alerts, Watchlist Scoring, Bias Detection.

7. **Reporting & Export Layer**
   - Periodische Reports, Steuer-/Income-Exports, PDF/CSV/Excel, Audit Snapshots.

8. **Dashboard UX**
   - Portfolio Overview, Transactions, Watchlists, Alerts, Risk, Income, Tax, Macro Overlay, Reports.

9. **Governance & Security Layer**
   - RBAC, Audit Log, Data Quality Monitoring, Configuration Versioning, Backups.

### 4.2 Architekturprinzipien

- **Event-sourced Ledger where useful:** Transaktionen werden unverändert als Events gespeichert; abgeleitete Positionen sind reproduzierbar.
- **Immutable Raw Data:** Rohimporte dürfen nicht überschrieben werden.
- **Canonical Model:** Alle Quellen werden auf ein einheitliches internes Modell gemappt.
- **Separation of Concerns:** Accounting, Analytics, Rules, UI und Integrationen bleiben entkoppelt.
- **Idempotent Imports:** Wiederholte Imports derselben Datei/API-Daten dürfen keine Duplikate erzeugen.
- **Configurable Rules:** Schwellenwerte, Kategorien, Alert Rules und Watchlist-Kriterien sind konfigurierbar.
- **Explainable Outputs:** Jede abgeleitete Kennzahl referenziert Inputdaten, Regelversion und Berechnungszeitpunkt.

---

## 5. Funktionale Anforderungen

## 5.1 Datenimport und Normalisierung

### FR-001: Multi-Source Import
Das System muss Daten aus mehreren Quellen importieren können:

- Bankkonten.
- Broker/Depotkonten.
- CSV/Excel-Dateien.
- PDF-Statements, sofern technisch möglich.
- Marktdaten-APIs.
- FX-Rates.
- Makrodaten.
- Manuelle Eingaben.

### FR-002: Canonical Transaction Mapping
Alle importierten Bewegungen müssen auf ein internes Transaktionsschema gemappt werden:

- Datum / Buchungsdatum / Valutadatum.
- Konto oder Depot.
- Instrument oder Cash Asset.
- Transaktionstyp.
- Menge.
- Preis.
- Brutto-/Nettowert.
- Gebühren.
- Steuern.
- Währung.
- FX Rate.
- Quelle und Import-ID.

### FR-003: Import Audit Trail
Jeder Import muss dokumentieren:

- Quelle.
- Zeitpunkt.
- Importmethode.
- Anzahl gelesener Zeilen.
- Anzahl akzeptierter Zeilen.
- Anzahl abgelehnter oder quarantined Zeilen.
- Mapping-Version.
- Prüfsumme oder eindeutige Source-ID.

### FR-004: Data Quarantine
Fehlerhafte oder unsichere Datensätze müssen in eine Quarantine Queue verschoben werden, z. B. bei:

- fehlendem Datum.
- unbekannter Währung.
- unklarer Instrument-ID.
- doppelverdächtiger Transaktion.
- nicht plausibler Menge oder Preis.
- fehlender FX Rate.

---

## 5.2 Transaction Accounting

### FR-010: Transaction Ledger
Das System muss ein vollständiges, unveränderbares Transaction Ledger führen.

Pflichttypen:

- Buy.
- Sell.
- Dividend.
- Interest.
- Deposit.
- Withdrawal.
- Fee.
- Tax.
- Tax Refund.
- FX Conversion.
- Split.
- Merger.
- Spin-off.
- Transfer In.
- Transfer Out.
- Cash Adjustment.
- Manual Correction.

### FR-011: Cash Ledger
Das System muss Cash je Konto und Währung führen:

- Anfangsbestand.
- Einzahlungen.
- Auszahlungen.
- Käufe/Verkäufe.
- Dividenden/Zinsen.
- Gebühren/Steuern.
- FX Conversions.
- Endbestand.

### FR-012: Position Accounting
Das System muss Positionen je Instrument, Konto und Tax Lot berechnen:

- Menge.
- Average Cost oder FIFO/LIFO je Konfiguration.
- Cost Basis.
- Marktwert.
- Unrealized P&L.
- Realized P&L.
- Gebührenanteile.
- Steueranteile.

### FR-013: Corporate Actions
Das System muss Corporate Actions abbilden:

- Splits und Reverse Splits.
- Dividenden in Cash oder Stock.
- Mergers.
- Spin-offs.
- Symbol-/ISIN-Wechsel.
- Delistings.

### FR-014: Reconciliation
Das System muss Bestände gegen Broker-/Bank-Snapshots abgleichen:

- Cash Reconciliation.
- Position Reconciliation.
- Market Value Reconciliation.
- Difference Report.
- manuelle Resolution mit Audit Trail.

---

## 5.3 Watchlist Pipeline

### FR-020: Watchlist Entities
Das System muss Watchlists für Assets, Instrumente, Themen oder Makroindikatoren unterstützen.

Eine Watchlist Item muss enthalten:

- Name.
- Identifier, z. B. ISIN, ticker, symbol, macro series ID.
- Asset Class.
- Region.
- Sector / Theme.
- Status, z. B. active, paused, archived.
- Beobachtungsgrund.
- Regeln und Schwellenwerte.
- Notizen und Decision Log.

### FR-021: Rule-based Watchlist Scoring
Watchlist Scores müssen regelbasiert sein und z. B. folgende Komponenten unterstützen:

- Valuation Trigger.
- Momentum Trigger.
- Volatility Trigger.
- Drawdown Trigger.
- Earnings / Dividend Trigger.
- Macro Sensitivity Trigger.
- Liquidity Trigger.
- News/Sentiment Summary nur als optionales, nicht entscheidendes Signal.

### FR-022: Watchlist Pipeline Steps
Die Pipeline muss folgende Schritte unterstützen:

1. Data Refresh.
2. Data Quality Check.
3. Rule Evaluation.
4. Score Calculation.
5. Alert Prioritization.
6. Human Review Queue.
7. Decision Logging.
8. Rule Feedback / Rule Adjustment.

### FR-023: No Auto-Execution
Ein Watchlist Signal darf ausschließlich eine Review-Aufgabe oder einen Alert erzeugen, niemals eine Order.

---

## 5.4 Dashboard UX

### FR-030: Dashboard Overview
Das Hauptdashboard muss eine Executive Summary zeigen:

- Net Worth.
- Portfolio Market Value.
- Cash Balance.
- Daily / Monthly / YTD P&L.
- Total Return.
- Income YTD.
- Realized Gains/Losses.
- Asset Allocation.
- Top Risks.
- High Priority Alerts.
- Data Quality Status.

### FR-031: Portfolio View
Die Portfolio View muss unterstützen:

- Gruppierung nach Konto, Asset Class, Region, Sector, Currency, Strategy Tag.
- Drill-down von Portfolio zu Position zu Tax Lot zu Transaktion.
- Performance Attribution.
- Exposure Analyse.
- Vergleich gegen Benchmark.

### FR-032: Transaction View
Die Transaction View muss bieten:

- Filter nach Datum, Konto, Instrument, Typ, Währung, Quelle, Status.
- Split View: Raw Import vs. Normalized Transaction.
- Manual Correction Workflow.
- Duplicate Detection Hinweise.
- Export.

### FR-033: Alert Center
Das Alert Center muss Alerts nach Priorität, Kategorie und Status anzeigen:

- Critical.
- High.
- Medium.
- Low.
- Info.

Status:

- New.
- Acknowledged.
- In Review.
- Deferred.
- Resolved.
- False Positive.

### FR-034: Decision Journal
Das System muss ein Decision Journal bereitstellen:

- Anlass / Trigger.
- relevante Kennzahlen.
- betrachtete Alternativen.
- menschliche Entscheidung.
- Begründung.
- Zeitstempel.
- beteiligte Nutzer.
- Folgeaufgaben.

---

## 5.5 Reports

### FR-040: Standard Reports
Das System muss folgende Reports unterstützen:

- Monthly Portfolio Report.
- Quarterly Review Report.
- Annual Performance Report.
- Income Report.
- Tax Preparation Report.
- Risk Report.
- Liquidity Report.
- Data Quality Report.
- Watchlist Review Report.
- Decision Audit Report.

### FR-041: Report Inhalte
Reports müssen enthalten können:

- Zeitraum.
- Start-/Endvermögen.
- Cashflows.
- Time-weighted Return.
- Money-weighted Return, optional.
- Income.
- Fees.
- Taxes.
- Realized/Unrealized P&L.
- Allocation.
- Top Contributors/Detractors.
- Risk Kennzahlen.
- Alerts und Entscheidungen.
- Data Quality Hinweise.

### FR-042: Exportformate
Das System muss mindestens folgende Exportformate unterstützen:

- PDF.
- CSV.
- Excel.
- JSON für maschinenlesbare Exporte.

---

## 5.6 Tax und Income

### FR-050: Income Tracking
Das System muss Income separat tracken:

- Dividenden.
- Zinsen.
- Ausschüttungen.
- Quellensteuer.
- Steuererstattungen.
- Fees bezogen auf Income.
- Währung und FX Rate zum Zahlungszeitpunkt.

### FR-051: Tax Buckets
Das System muss steuerrelevante Buckets führen:

- Realized short-term gains/losses, sofern relevant.
- Realized long-term gains/losses, sofern relevant.
- Dividend income.
- Interest income.
- Withholding tax.
- Transaction taxes.
- Deductible fees, sofern relevant.
- Carry-forward losses, manuell/konfigurierbar.

### FR-052: Tax Disclaimer
Alle Steuerreports müssen einen Hinweis enthalten, dass die Ausgabe keine Steuerberatung ersetzt und durch Nutzer oder Steuerberater geprüft werden muss.

### FR-053: Jurisdiction Configuration
Steuerlogik muss nach Jurisdiction konfigurierbar sein, z. B. Deutschland, USA, Schweiz, Österreich. MVP darf mit generischem Tax Categorization Model starten.

---

## 5.7 Total Return und Performance

### FR-060: Performance Metrics
Das System muss berechnen:

- Absolute Return.
- Total Return inklusive Dividenden und Zinsen.
- Time-weighted Return.
- Money-weighted Return / IRR, optional nach MVP.
- Realized P&L.
- Unrealized P&L.
- Fees Impact.
- Tax Impact.
- FX Impact.

### FR-061: Benchmarking
Das System muss Portfolio- und Segmentperformance gegen Benchmarks darstellen können:

- ein Benchmark pro Portfolio.
- optionale Benchmarks pro Asset Class.
- Abweichung absolut und relativ.
- Tracking Difference.

### FR-062: Performance Attribution
Das System sollte Performance nach folgenden Dimensionen zerlegen:

- Asset Class.
- Region.
- Sector.
- Currency.
- Instrument.
- Income vs. Price Return.
- FX Contribution.

---

## 5.8 Risk Management

### FR-070: Risk Metrics
Das System muss Risiko-Kennzahlen berechnen oder darstellen:

- Volatility.
- Maximum Drawdown.
- Value at Risk, optional und mit Methodikhinweis.
- Concentration Risk.
- Currency Exposure.
- Sector Exposure.
- Region Exposure.
- Counterparty/Broker Exposure.
- Liquidity Risk.
- Correlation Matrix.

### FR-071: Risk Limits
Das System muss regelbasierte Risk Limits unterstützen:

- maximale Positionsgröße.
- maximale Asset-Class-Quote.
- maximale Währungsquote.
- maximale Broker-Exposure.
- maximale Drawdown-Schwelle.
- minimale Cash Reserve.
- maximale illiquide Quote.

### FR-072: Risk Breach Workflow
Bei Limit-Verletzung muss ein Alert erzeugt werden mit:

- verletzter Regel.
- Ist-Wert.
- Grenzwert.
- betroffene Assets.
- Schweregrad.
- vorgeschlagene Review-Aktion, keine automatische Handlung.

---

## 5.9 Macro Overlay

### FR-080: Macro Data Integration
Das System soll Makrodaten integrieren können:

- Zinskurven.
- Inflation.
- Arbeitsmarktdaten.
- GDP / PMI.
- Credit Spreads.
- Volatility Indices.
- FX Rates.
- Commodity Prices.

### FR-081: Macro Regime Tags
Das System soll regelbasierte Macro Regime Tags erzeugen:

- rising rates.
- falling rates.
- high inflation.
- disinflation.
- risk-on.
- risk-off.
- recession watch.
- liquidity tightening.

### FR-082: Macro-to-Portfolio Mapping
Das System soll Portfolio-Exposures gegen Makrofaktoren mappen:

- Duration Sensitivity.
- Equity Beta.
- Credit Sensitivity.
- Inflation Sensitivity.
- FX Sensitivity.
- Commodity Sensitivity.

### FR-083: Macro Overlay Disclaimer
Macro Overlay darf keine Investmentanweisung erzeugen, sondern nur Kontext und Risikoindikatoren anzeigen.

---

## 5.10 Stress Tests und Szenarien

### FR-090: Scenario Library
Das System muss eine Szenario-Bibliothek unterstützen:

- Equity Crash.
- Rate Shock.
- Inflation Shock.
- FX Shock.
- Credit Spread Widening.
- Commodity Shock.
- Liquidity Freeze.
- Custom Scenario.

### FR-091: Portfolio Stress Test
Für jedes Szenario muss das System berechnen:

- geschätzter Portfolio Impact.
- Impact je Asset Class.
- Impact je Position.
- Cash Impact.
- Risk Limit Breaches.
- betroffene Watchlist Items.

### FR-092: Assumption Transparency
Jeder Stress Test muss Annahmen anzeigen:

- verwendete Shocks.
- Mapping-Regeln.
- Sensitivitäten.
- Datenstand.
- Limitations.

---

## 5.11 Liquidity Ladder

### FR-100: Liquidity Classification
Das System muss Assets nach Liquiditätsklassen einordnen:

- sofort verfügbar, z. B. Cash.
- T+1/T+2 liquide Wertpapiere.
- kurzfristig liquidierbar.
- eingeschränkt liquide.
- illiquide.
- unbekannt.

### FR-101: Liquidity Ladder View
Das System muss eine Liquidity Ladder anzeigen:

- verfügbare Liquidität heute.
- verfügbare Liquidität innerhalb 2 Tage.
- innerhalb 1 Woche.
- innerhalb 1 Monat.
- innerhalb 3 Monate.
- länger als 3 Monate.

### FR-102: Cash Need Matching
Das System soll geplante Cash Needs gegen verfügbare Liquidität mappen:

- regelmäßige Ausgaben.
- Steuerzahlungen.
- geplante Investitionen.
- Notfallreserve.
- Ausschüttungsbedarf.

---

## 5.12 Bias Detection

### FR-110: Behavioral Bias Indicators
Das System soll regelbasierte Bias-Indikatoren erkennen:

- Home Bias.
- Concentration Bias.
- Recency Bias.
- Overtrading.
- Loss Aversion / Disposition Effect.
- Anchoring an Kaufkursen.
- Confirmation Bias über Watchlist/Decision Notes.
- Performance Chasing.

### FR-111: Bias Evidence
Jeder Bias Hinweis muss Evidenz anzeigen:

- betroffene Datenpunkte.
- Regeldefinition.
- Zeitraum.
- Vergleichswert.
- mögliche Reflexionsfrage.

### FR-112: No Psychometric Claims
Bias Detection darf keine psychologische Diagnose darstellen, sondern nur Datenmuster für Selbstreflexion anzeigen.

---

## 5.13 Alert Priorities

### FR-120: Alert Kategorien
Alerts müssen kategorisiert werden:

- Data Quality.
- Accounting/Reconciliation.
- Risk Limit.
- Liquidity.
- Tax/Income.
- Watchlist.
- Macro.
- Bias.
- Report Due.
- Security/System.

### FR-121: Prioritätslogik
Priorität muss regelbasiert abgeleitet werden aus:

- Impact.
- Urgency.
- Confidence.
- Data Quality.
- User-defined criticality.
- Wiederholungshäufigkeit.

### FR-122: Alert Escalation
Alerts müssen eskalieren können:

- Critical: sofortige Review erforderlich.
- High: Review innerhalb kurzer Frist.
- Medium: Review im nächsten Routinezyklus.
- Low: Information / Watch.
- Info: rein dokumentarisch.

### FR-123: Alert Fatigue Prevention
Das System muss Mechanismen zur Alert Fatigue Prevention unterstützen:

- Deduplizierung.
- Snooze.
- Aggregation ähnlicher Alerts.
- Prioritätsdämpfung bei bekannten False Positives.
- periodische Alert Quality Review.

---

## 5.14 Data Quality

### FR-130: Data Quality Dimensions
Das System muss Data Quality anhand folgender Dimensionen bewerten:

- Completeness.
- Validity.
- Consistency.
- Timeliness.
- Uniqueness.
- Accuracy.
- Lineage Coverage.

### FR-131: Data Quality Score
Das System muss einen Data Quality Score pro Datenbereich anzeigen:

- Transactions.
- Prices.
- FX Rates.
- Instruments.
- Corporate Actions.
- Tax Data.
- Watchlist Data.
- Macro Data.

### FR-132: Blocking Rules
Bestimmte Analysen müssen blockiert oder markiert werden, wenn Datenqualität unzureichend ist, z. B.:

- Performance Report ohne vollständige Preise.
- Tax Report ohne vollständige Steuerbuchungen.
- FX Exposure ohne aktuelle FX Rates.
- Reconciliation ohne Broker Snapshot.

---

## 6. Datenmodell v0.1

### 6.1 Core Entities

#### User
- user_id.
- name.
- email.
- role.
- status.
- preferences.

#### Account
- account_id.
- institution_id.
- account_type.
- base_currency.
- owner.
- status.

#### Institution
- institution_id.
- name.
- type, z. B. bank, broker, custodian.
- country.

#### Instrument
- instrument_id.
- name.
- identifiers, z. B. ISIN, WKN, ticker, CUSIP.
- asset_class.
- currency.
- exchange.
- country.
- sector.
- issuer.
- status.

#### Transaction
- transaction_id.
- source_id.
- account_id.
- instrument_id, optional bei Cash.
- transaction_type.
- trade_date.
- settlement_date.
- quantity.
- price.
- gross_amount.
- net_amount.
- fees.
- taxes.
- currency.
- fx_rate.
- metadata.
- import_batch_id.
- status.

#### Position
- position_id.
- account_id.
- instrument_id.
- quantity.
- cost_basis.
- market_value.
- unrealized_pnl.
- currency.
- valuation_date.

#### TaxLot
- lot_id.
- position_id.
- acquisition_date.
- quantity_open.
- acquisition_price.
- fees_allocated.
- cost_basis.
- realized_status.

#### Price
- price_id.
- instrument_id.
- price_date.
- close_price.
- currency.
- source.
- quality_flag.

#### FXRate
- fx_rate_id.
- base_currency.
- quote_currency.
- rate_date.
- rate.
- source.

#### CorporateAction
- action_id.
- instrument_id.
- action_type.
- effective_date.
- terms.
- source.
- status.

#### WatchlistItem
- watchlist_item_id.
- instrument_id oder macro_series_id.
- list_name.
- reason.
- status.
- rules.
- tags.
- owner.

#### Alert
- alert_id.
- category.
- priority.
- status.
- entity_ref.
- rule_id.
- message.
- evidence.
- created_at.
- resolved_at.

#### DecisionLog
- decision_id.
- trigger_ref.
- user_id.
- decision_type.
- rationale.
- considered_options.
- timestamp.
- attachments.

#### Report
- report_id.
- report_type.
- period_start.
- period_end.
- generated_at.
- data_quality_status.
- file_refs.

#### Rule
- rule_id.
- rule_type.
- name.
- definition.
- threshold.
- priority_mapping.
- version.
- active_status.

#### DataQualityIssue
- issue_id.
- entity_type.
- entity_id.
- dimension.
- severity.
- description.
- status.
- detected_at.

### 6.2 Relationships

- Ein User kann mehrere Accounts besitzen oder verwalten.
- Ein Account gehört zu einer Institution.
- Eine Transaction referenziert Account und optional Instrument.
- Transactions erzeugen Positions- und Cash-Ledger-Effekte.
- Eine Position besteht aus einem oder mehreren TaxLots.
- Prices und FXRates bewerten Positions und Returns.
- CorporateActions transformieren Instruments, Positions und TaxLots.
- WatchlistItems referenzieren Instruments oder Macro Series.
- Rules erzeugen Alerts.
- Alerts können DecisionLogs auslösen.
- Reports referenzieren aggregierte Daten, Perioden und Data Quality Status.

---

## 7. Nicht-funktionale Anforderungen

### NFR-001: Security

- Verschlüsselung ruhender Daten, soweit sensibel.
- TLS für Datenübertragung.
- Role-based Access Control.
- Secret Management für API Keys.
- Audit Log für kritische Aktionen.

### NFR-002: Privacy

- Datenminimierung.
- klare Trennung von Rohdaten, normalisierten Daten und Reports.
- Export und Löschkonzept.
- keine Weitergabe an LLMs ohne explizite Freigabe und Redaction.

### NFR-003: Auditability

- Jeder Wert im Dashboard muss auf Rohdaten oder definierte Regeln zurückführbar sein.
- Jede manuelle Korrektur muss versioniert und begründet werden.
- Reports müssen Datenstand, Regelversion und Generierungszeitpunkt enthalten.

### NFR-004: Reliability

- Idempotente Importjobs.
- Wiederanlauf nach Fehlern.
- Backups.
- Monitoring der Datenpipelines.
- definierte Recovery Procedures.

### NFR-005: Performance

- Dashboard Overview für normale Portfoliogrößen innerhalb weniger Sekunden.
- Batch-Import großer CSV-Dateien ohne UI-Blockade.
- Analytics Jobs asynchron, wenn Laufzeit hoch ist.

### NFR-006: Maintainability

- Modularer Aufbau.
- klare Schnittstellen.
- dokumentierte Regeln.
- Versionierung von Mapping und Rule Configs.

### NFR-007: Explainability

- Rule Evidence muss pro Alert sichtbar sein.
- Berechnungsformeln müssen dokumentiert sein.
- LLM-generierte Texte müssen als solche markiert werden.

### NFR-008: Compliance-by-Design

- Keine automatisierte Anlageberatung.
- Keine automatische Orderausführung.
- Steuerberichte mit Disclaimer.
- Trennung von Analyse und Entscheidung.

---

## 8. LLM Policy

### 8.1 Erlaubte LLM Use Cases

- Zusammenfassung langer News- oder Reporttexte.
- Vorschläge zur Kategorisierung von Transaktionsbeschreibungen, mit menschlicher Bestätigung.
- Formulierung von Report Narratives aus deterministisch berechneten Kennzahlen.
- Extraktion unstrukturierter PDF-Informationen als Vorschlag mit Confidence Score.

### 8.2 Nicht erlaubte LLM Use Cases

- Berechnung von Returns, Taxes, Risk Metrics oder Accounting-Werten.
- finale Klassifikation ohne Regel oder Human Review.
- Kauf-/Verkaufsempfehlungen.
- Orderauslösung.
- Änderung von Regeln ohne menschliche Freigabe.

### 8.3 LLM Governance

- Prompt und Response Logging, sofern datenschutzkonform.
- Redaction sensibler Daten.
- Human-in-the-loop Review.
- Kennzeichnung LLM-generierter Inhalte.
- Fallback ohne LLM muss möglich sein.

---

## 9. Dashboard UX Struktur

### 9.1 Navigation

- Overview.
- Portfolio.
- Transactions.
- Cash & Liquidity.
- Income & Tax.
- Risk.
- Watchlist.
- Macro.
- Stress Tests.
- Alerts.
- Reports.
- Data Quality.
- Decision Journal.
- Settings.

### 9.2 UX Prinzipien

- Jede Kennzahl mit Drill-down.
- Ampelstatus nur mit erklärender Detailansicht.
- Keine versteckten Auto-Entscheidungen.
- Alerts priorisiert statt chronologisch überladen.
- Data Quality sichtbar auf jeder Analyse.
- Unterschied zwischen Ist-Daten, Simulation und Annahme klar markieren.

### 9.3 Critical Screens MVP

1. Portfolio Overview.
2. Transaction Ledger.
3. Data Quality Queue.
4. Alert Center.
5. Income & Tax Summary.
6. Risk Exposure View.
7. Watchlist Review.
8. Monthly Report Export.

---

## 10. Accounting- und Berechnungsregeln

### 10.1 Grundsatz

Alle Accounting-Berechnungen müssen deterministisch, reproduzierbar und testbar sein.

### 10.2 Cost Basis

- MVP: Average Cost oder FIFO konfigurierbar.
- Erweiterung: Jurisdiction-specific tax lot rules.
- Gebühren müssen optional in Cost Basis einbezogen werden können.

### 10.3 FX Behandlung

- Jede Transaktion in Fremdwährung benötigt FX Rate zum relevanten Datum.
- Reporting Currency muss konfigurierbar sein.
- FX Impact soll separat ausgewiesen werden.

### 10.4 Fees und Taxes

- Fees getrennt von Taxes speichern.
- Fees nach Transaktion, Position, Zeitraum und Instrument aggregieren.
- Taxes nach Art und Jurisdiction klassifizieren.

### 10.5 Cashflows

- External Cashflows von internal Cashflows trennen.
- Deposits/Withdrawals dürfen Performance nicht verzerren.
- Dividenden/Zinsen zählen als Income und Total Return Komponente.

---

## 11. Risk, Stress und Liquidity Methodik

### 11.1 Risk Methodik

- Historical Volatility auf Basis historischer Preise.
- Drawdown auf Portfolio- und Instrumentebene.
- Exposure Limits über aktuelle Marktwerte.
- Correlation auf Basis verfügbarer Return-Zeitreihen.
- VaR nur optional und mit Methodikhinweis.

### 11.2 Stress Methodik

- Szenarien müssen simple, nachvollziehbare Shocks verwenden.
- Mapping von Shocks auf Asset Classes muss konfigurierbar sein.
- Ergebnisse sind Schätzungen, keine Prognosen.

### 11.3 Liquidity Methodik

- Cash ist sofort verfügbar.
- Listed Securities nach Settlement Cycle und Handelsliquidität klassifizieren.
- Illiquide Assets benötigen manuelle Klassifikation.
- Liquidity Ladder muss Unsicherheiten markieren.

---

## 12. Data Quality Konzept

### 12.1 Quality Gates

- Import Gate: Format, Pflichtfelder, Typvalidierung.
- Mapping Gate: Instrument, Währung, Konto, Transaktionstyp.
- Accounting Gate: Ledger Balance, Cash Consistency, Position Consistency.
- Analytics Gate: Preise, FX Rates, Benchmarks, Macro Data Freshness.
- Report Gate: Vollständigkeit für Zeitraum und Berichtstyp.

### 12.2 Issue Workflow

1. Issue Detection.
2. Severity Assignment.
3. Quarantine oder Warning.
4. Human Resolution.
5. Re-run affected calculations.
6. Audit Log.

### 12.3 Data Quality Severity

- Critical: Report oder Accounting unbrauchbar.
- High: wichtige Kennzahl potenziell falsch.
- Medium: eingeschränkte Aussagekraft.
- Low: kosmetisch oder wenig Auswirkung.
- Info: Hinweis ohne unmittelbare Auswirkung.

---

## 13. Alert Priority Matrix

### 13.1 Priority Inputs

- Financial Impact.
- Time Sensitivity.
- Confidence.
- Data Quality Confidence.
- User Criticality.
- Regulatory/Tax Relevance.

### 13.2 Beispiele

- Critical: Cash Ledger stimmt nicht mit Broker Snapshot überein und Report wird heute erzeugt.
- Critical: Steuerreport basiert auf unvollständigen Transaktionen.
- High: Risk Limit für Einzelposition überschritten.
- High: Watchlist Item erreicht mehrere harte Trigger.
- Medium: Macro Regime wechselt auf risk-off.
- Medium: Home Bias Schwelle überschritten.
- Low: einzelne Preisquelle verspätet, alternative Quelle verfügbar.
- Info: Monthly Report ist bereit.

---

## 14. MVP Roadmap

## Phase 0: Discovery und Baseline

Ziele:

- Datenquellen inventarisieren.
- Ziel-Reporting Currency festlegen.
- Transaktionstypen finalisieren.
- MVP-Broker/Bank-Formate priorisieren.
- Steuer-Jurisdiction für MVP bestimmen.

Deliverables:

- Source Inventory.
- Canonical Data Model v0.1.
- Rule Catalogue v0.1.
- Dashboard Wireframe v0.1.

## Phase 1: Core Ledger MVP

Ziele:

- CSV/Excel Import.
- Transaction Ledger.
- Cash Ledger.
- Position Accounting.
- Basic Instrument Master Data.
- Manual Correction Workflow.
- Import Audit Trail.

Akzeptanzkriterien:

- Wiederholter Import erzeugt keine Duplikate.
- Cash und Positionen lassen sich aus Transaktionen reproduzieren.
- Unklare Daten landen in Quarantine.

## Phase 2: Portfolio Dashboard und Reporting

Ziele:

- Portfolio Overview.
- Transaction View.
- Market Value und P&L.
- Monthly Report.
- Data Quality Dashboard.
- Basic PDF/CSV Export.

Akzeptanzkriterien:

- Dashboard zeigt Datenstand und Quality Status.
- Monthly Report enthält Start-/Endwerte, Cashflows, P&L, Income und Fees.

## Phase 3: Income, Tax und Total Return

Ziele:

- Dividend/Interest Tracking.
- Tax Buckets.
- Total Return inkl. Income.
- Realized/Unrealized P&L.
- FX Impact.

Akzeptanzkriterien:

- Income Report ist nach Zeitraum, Instrument, Konto und Währung filterbar.
- Tax Export enthält Disclaimer und prüfbare Quelltransaktionen.

## Phase 4: Watchlist und Alerts

Ziele:

- Watchlist Management.
- Rule-based Watchlist Scoring.
- Alert Center.
- Decision Journal.
- Alert Priority Matrix.

Akzeptanzkriterien:

- Watchlist Trigger erzeugen Review Alerts, keine Orders.
- Jede Entscheidung wird mit Kontext dokumentiert.

## Phase 5: Risk, Stress und Liquidity

Ziele:

- Exposure Limits.
- Volatility/Drawdown.
- Concentration Risk.
- Liquidity Ladder.
- Scenario Stress Tests.

Akzeptanzkriterien:

- Risk Breaches erzeugen nachvollziehbare Alerts.
- Stress Tests zeigen Annahmen und Limitations.

## Phase 6: Macro Overlay und Bias Detection

Ziele:

- Macro Data Integration.
- Macro Regime Tags.
- Portfolio Macro Mapping.
- Behavioral Bias Indicators.

Akzeptanzkriterien:

- Macro Overlay ist klar als Kontext markiert.
- Bias Detection zeigt Evidenz und Reflexionsfragen, keine Diagnose.

---

## 15. Abnahmekriterien v0.1

Das System erfüllt v0.1, wenn:

- Datenimport, Ledger und Positionen reproduzierbar funktionieren.
- Dashboard die Kernwerte mit Data Quality Status anzeigt.
- Reports exportierbar und auditierbar sind.
- Alerts regelbasiert und priorisiert erzeugt werden.
- Watchlist Signale ausschließlich Review-Aufgaben erzeugen.
- Steuer-/Income-Daten transparent und mit Disclaimer dargestellt werden.
- Risk, Liquidity und Stress Ergebnisse ihre Annahmen offenlegen.
- LLM-Nutzung optional, markiert und nicht entscheidungsführend ist.
- keine Funktion automatisierte Trades auslösen kann.

---

## 16. Offene Fragen für v0.2

- Welche konkreten Broker- und Bankformate haben Priorität?
- Welche Steuer-Jurisdiction ist für den ersten produktiven Einsatz maßgeblich?
- Welche Market Data Provider sollen genutzt werden?
- Welche Reporting Currency ist Default?
- Welche Benchmarks sollen initial unterstützt werden?
- Welche Asset Classes sind im MVP zwingend?
- Welche Genauigkeit wird für historische FX Rates benötigt?
- Welche Rollen und Berechtigungen werden organisatorisch benötigt?
- Welche Retention Policy gilt für Rohdaten und Reports?
- Welche Integrationen sind langfristig geplant, z. B. Steuerberater, Notion, Obsidian, Google Sheets?

---

## 17. Risiken und Annahmen

### 17.1 Annahmen

- Nutzer akzeptieren manuelle Review bei unsicheren Daten.
- Initiale Datenquellen können per CSV/Excel bereitgestellt werden.
- Marktdatenqualität ist für MVP ausreichend, wenn Datenlücken sichtbar sind.
- Steuerlogik startet generisch und wird später jurisdiction-specific erweitert.

### 17.2 Projektrisiken

- Brokerdaten sind uneinheitlich und schwer zu normalisieren.
- Corporate Actions können Accounting-Komplexität stark erhöhen.
- Steuerregeln sind länderspezifisch und fehleranfällig.
- Zu viele Alerts können Nutzer überfordern.
- LLM-Nutzung kann Datenschutz- und Erklärbarkeitsrisiken erzeugen.

### 17.3 Gegenmaßnahmen

- Quarantine und Review Queue statt stiller Autokorrektur.
- MVP mit begrenzten Datenquellen starten.
- Regelversionierung und Audit Trail.
- Alert Priority Matrix und Deduplizierung.
- LLM optional, redacted und nicht entscheidungsführend.

---

## 18. Glossar

- **Accounting Engine:** deterministische Komponente zur Ableitung von Cash, Positions, P&L und Cost Basis aus Transactions.
- **Canonical Data Model:** einheitliches internes Datenmodell über alle Quellen hinweg.
- **Data Quarantine:** Bereich für Datensätze, die nicht automatisch verarbeitet werden dürfen.
- **Decision Journal:** dokumentierte menschliche Entscheidung mit Kontext und Begründung.
- **Human Decision Authority:** finale Entscheidungsgewalt bleibt beim Menschen.
- **Liquidity Ladder:** Darstellung, wann welche Mittel voraussichtlich verfügbar sind.
- **Macro Overlay:** Kontextschicht mit makroökonomischen Indikatoren und Regime Tags.
- **Rule Engine:** deterministische Auswertung von Regeln und Schwellenwerten.
- **Tax Lot:** steuerlich relevante Teilposition mit eigener Anschaffungshistorie.
- **Total Return:** Gesamtrendite inklusive Kursänderung, Dividenden, Zinsen und relevanter Effekte.
- **Watchlist Pipeline:** Prozess zur Überwachung interessanter Assets oder Makroindikatoren anhand definierter Regeln.

---

## 19. Zusammenfassung

Dieses Anforderungsdokument v0.1 definiert ein rule-based Finance Management und Decision-Support-System mit klarer menschlicher Entscheidungsautorität. Der Fokus liegt auf Datenqualität, auditierbarem Transaction Accounting, transparenten Reports, risikobewusstem Dashboarding, Watchlist Monitoring und nachvollziehbaren Alerts. Automatisiertes Trading und black-box Entscheidungen sind explizit ausgeschlossen.