# JARVIS Finance System – Spezifikation v0.2

**Version:** 0.2  
**Datum:** 2026-05-14  
**Status:** Fachlich-technische Spezifikation / kein Code  
**Topic:** Finance System – Architektur & Scripts  
**Basiswährung:** CHF  
**Leitlinie:** Finanzbuchhaltung, Risikoanalyse und Decision Support – kein Trading-System.

---

## 1. Verbindliche Systementscheidungen v0.2

### 1.1 Basiswährung

Die eindeutige Reporting- und Systembasiswährung ist **CHF**.

Alle Werte werden doppelt geführt:

- Originalwährung der Transaktion, Position oder Ausschüttung.
- CHF-Gegenwert mit historischem oder aktuellem FX-Kurs.

Das System muss Performance sauber zerlegen in:

- Wertpapier-/Asset-Performance in Originalwährung.
- FX-Effekt gegenüber CHF.
- Total Return in CHF.
- Realisierter Gewinn/Verlust.
- Unrealisierter Gewinn/Verlust.
- Dividenden-/Ausschüttungs-/Income-Beitrag.
- Gebühren- und Steuer-Effekt.

### 1.2 Plattform-/Konto-Trennung

Das Dashboard muss Gesamtansicht und getrennte Plattformansichten unterstützen:

- **Raiffeisenbank:** Cashpositionen und allgemeine Anlageübersicht.
- **PostFinance:** Einzeltitel, ETFs und Crypto-Übersicht.
- **True Wealth:** diverse ETF-Positionen.
- **Crypto-Coins:** separat ausgewiesene Coin-Positionen.

Crypto-Werte aus vorhandenen Auszügen dürfen nicht als aktuelle Bewertung verwendet werden, wenn sie historisch/veraltet sind. Für Crypto gilt: **Menge übernehmen, Marktwert später über CoinGecko neu berechnen.**

### 1.3 Importstrategie

Für den Start gibt es drei Wege:

1. Manuelle Eingabe direkt im Dashboard.
2. CSV-Import nach eigenem Standardformat.
3. Später Import aus Broker-/Bank-Exporten.

Direkte Broker-/Bank-Anbindungen werden für MVP 1 nicht eingeplant. Das System arbeitet transaktionsbasiert; aktuelle Bestände dürfen nur als Initial Snapshot verwendet werden, wenn keine vollständige Transaktionshistorie verfügbar ist.

### 1.4 Storage

MVP Storage: **SQLite**.

Design-Anforderung: Migration auf **PostgreSQL** muss später möglich sein.

Keine Daten-Sackgasse:

- CSV Export.
- JSON Export.
- Parquet Export.
- SQLite Dump.
- später PostgreSQL Dump.

### 1.5 Git- und Geheimhaltungsregel

Code, Skripte, Schemata, Tests und technische Dokumentation dürfen in ein privates Git-Repository.

**Nie in Git:**

- reale Finanzdaten.
- Broker-/Bank-Exports.
- Portfolio-Auszüge.
- SQLite/Postgres-Dumps mit Echtdaten.
- PDF/DOCX/XLSX Auszüge.
- API Keys, OAuth Tokens, Credentials.
- Reports mit realen Zahlen.
- Screenshots mit Finanzdaten.

Das Repository muss `.gitignore`, Secret Scan und klare Trennung zwischen `src/`, `docs/`, `config.example/` und lokalen `data/`-Ordnern enthalten. Finanzdaten bleiben lokal bzw. in einem privaten, kontrollierten Speicher – nicht im Code-Repo. Eine banale Regel, aber genau an solchen banalen Regeln scheitern erstaunlich teure Organisationen.

---

## 2. Realitätscheck vorhandene Portfolio-Dokumente

Auf Google Drive liegt der Ordner:

`Finanzen / 01 Aktueller Stand Portfolios`

Darin befinden sich aktuelle Portfolio-Auszüge für PostFinance, True Wealth, eine Gesamtübersicht und eine Crypto-Coin-Übersicht. Die Dateien wurden für v0.2 **nur strukturell** geprüft, nicht für Umsetzung oder Wertübernahme.

### 2.1 Beobachtete Dateiarten

- XLSX mit Gesamtübersicht aller Anlagen.
- XLSX mit Crypto-Coin-Zusammenstellung.
- DOCX mit True-Wealth-Portfolio-Auszug.
- DOCX mit PostFinance-Portfolio-Auszug.

### 2.2 Tatsächlich erkennbare Feldarten

Je nach Datei sind folgende Feldarten vorhanden oder ableitbar:

- Plattform/Konto oder Quelle.
- Cashpositionen/Kontostände.
- Stichtag/Erstellungsdatum.
- Titelname/Produktbezeichnung.
- Ticker oder Symbol teilweise vorhanden.
- Menge/Anzahl.
- Währung.
- Kurs oder Bewertungskurs.
- Marktwert in Originalwährung teilweise.
- Marktwert in CHF teilweise.
- Einstandskurs/Einstandswert teilweise.
- Gewinn/Verlust in CHF teilweise.
- Positionsanteil/Portfolioanteil teilweise.
- Crypto-Coin-Menge.
- historischer Gesamtwert bei Crypto teilweise, aber nicht als aktuelle Bewertung zu verwenden.

### 2.3 Typisch fehlende Felder

Für saubere transaktionsbasierte Buchhaltung fehlen in solchen Snapshot-Auszügen voraussichtlich:

- vollständige Kauf-/Verkaufsdaten je Transaktion.
- historischer FX-Kurs je Transaktion.
- Gebühren je Kauf/Verkauf.
- Steuerabzüge je Transaktion.
- Ex-Dividenden-Datum.
- Zahlungsdatum von Dividenden/Ausschüttungen.
- Brutto-/Netto-Dividende.
- Schweizer Verrechnungssteuer.
- ausländische Quellensteuer.
- Tax Lots.
- Investment Case.
- Zielgewichtung.
- Kategorie Core/Opportunity.
- Exit-Regeln.
- Quellen-/Datenprovider-Metadaten.
- Decision Journal Einträge.

### 2.4 Mapping-Logik Snapshot → internes Modell

Wenn keine vollständige Transaktionshistorie vorhanden ist, werden Auszüge als **Initial Snapshot** importiert.

Mapping:

- Plattform/Konto → `accounts`.
- Cashbestand → `cash_snapshots` plus optional `initial_cash_balance`.
- Position → `position_snapshots`.
- Titel/Symbol/ISIN → `instruments`.
- Menge → `initial_position.quantity`.
- Einstandswert, falls vorhanden → `initial_cost_basis` mit Quality Flag.
- Marktwert am Stichtag → `snapshot_market_value`, nicht als Transaktion.
- Crypto-Menge → `initial_position.quantity`.
- Crypto-Marktwert aus Auszug → `legacy_snapshot_value`, nicht aktuelle Bewertung.

Ab Startdatum des Systems gilt: neue Käufe, Verkäufe, Dividenden, Cashflows, FX-Effekte und Gebühren werden transaktionsbasiert erfasst.

---

## 3. Empfohlene Dashboard-Technologie

### 3.1 Vergleich

#### Streamlit

Stärken:

- sehr schnelle MVP-Entwicklung.
- Python-nativ, ideal für Pandas, SQLite, Plotly, Reports.
- einfache Forms für manuelle Eingabe.
- schnelle Tabellen, Filter, Charts.
- gute lokale/private Nutzung.
- einfache Integration von Report-Buttons.
- wenig Frontend-Komplexität.

Schwächen:

- komplexe Multi-Page-Apps und feine UX-Kontrolle sind begrenzt.
- Mobile ist brauchbar, aber nicht perfekt.
- sehr interaktive Sidebar-/Workflow-UX kann irgendwann an Grenzen kommen.

#### Dash / Plotly

Stärken:

- starke Charts und interaktive Analytics.
- gute Tabellen und Callbacks.
- besser für analytische Dashboards als Streamlit, wenn die App wächst.

Schwächen:

- mehr Boilerplate.
- Forms und Workflows weniger angenehm für schnellen MVP.
- Entwicklungsaufwand höher.

#### NiceGUI

Stärken:

- moderne UI-Komponenten.
- gute Forms und Workflows.
- Python-basiert.
- bessere App-ähnliche UX möglich als Streamlit.

Schwächen:

- kleineres Ökosystem.
- weniger etabliert für Data-Dashboards.
- Reporting/Analytics müssen stärker selbst zusammengesetzt werden.

#### FastAPI + React

Stärken:

- beste langfristige Architektur.
- API/UI sauber getrennt.
- mobile/PWA-fähig.
- professionelle Workflows und Komponenten möglich.

Schwächen:

- für MVP deutlich zu schwer.
- mehr Code, mehr Tests, mehr Deployment-Komplexität.
- Gefahr, eine Enterprise-Web-App zu bauen, bevor die Buchhaltung stimmt. Klassischer Architekten-Selbstunfall.

### 3.2 Empfehlung v0.2

**MVP-Empfehlung: Streamlit + SQLite + SQLAlchemy + Pandas + Plotly + WeasyPrint/Playwright für Reports.**

Begründung:

- MVP 1 braucht korrekte Buchhaltung und schnelle Iteration, nicht perfekte Frontend-Architektur.
- Manuelle Eingabe, Tabellen, Filter, Charts und Report-Buttons sind schnell realisierbar.
- Python bleibt durchgängig: Import, Accounting, FX, Reports, Analytics.
- Dashboard liest primär aus lokaler SQLite-Datenbank.
- Später kann die Business-Logik in ein Backend ausgelagert werden.

Zielarchitektur später:

- Core Engine bleibt Python Package.
- API Layer: FastAPI.
- Frontend: React/PWA oder NiceGUI/Dash je nach Bedarf.
- Storage: PostgreSQL.

---

## 4. Storage- und Tabellenmodell auf Feldebene

### 4.1 `platforms`

- `platform_id`
- `name`: Raiffeisen, PostFinance, True Wealth, Crypto-Coins
- `platform_type`: bank, broker, robo_advisor, crypto_wallet, crypto_exchange, manual
- `country`
- `default_currency`
- `is_active`
- `notes`

### 4.2 `accounts`

- `account_id`
- `platform_id`
- `account_name`
- `account_type`: cash, brokerage, crypto, reserve, tax, other
- `base_currency`
- `performance_included`: boolean
- `is_health_reserve`: boolean
- `target_cash_min_chf`
- `target_cash_max_chf`
- `created_at`
- `notes`

### 4.3 `instruments`

- `instrument_id`
- `asset_class`: equity, etf, crypto, cash, bond, commodity, other
- `name`
- `ticker`
- `isin`
- `wkn`
- `coingecko_id`
- `exchange`
- `currency`
- `country`
- `sector`
- `industry`
- `issuer`
- `benchmark_symbol`
- `data_provider_primary`
- `data_provider_fallback`
- `is_active`

### 4.4 `transactions`

- `transaction_id`
- `transaction_type`
- `account_id`
- `instrument_id`
- `trade_date`
- `settlement_date`
- `quantity`
- `price_original`
- `gross_amount_original`
- `fee_original`
- `tax_original`
- `net_amount_original`
- `currency_original`
- `fx_rate_to_chf`
- `fx_source`
- `fx_timestamp`
- `gross_amount_chf`
- `fee_chf`
- `tax_chf`
- `net_amount_chf`
- `source_type`: manual, csv, broker_export, snapshot, api
- `source_file_id`
- `source_row_hash`
- `quality_status`
- `notes`
- `decision_id`
- `created_at`
- `updated_at`

Unterstützte Typen:

- buy
- partial_sell
- full_sell
- dividend
- etf_distribution
- fee
- tax
- cash_deposit
- cash_withdrawal
- fx_conversion
- crypto_buy
- crypto_sell
- crypto_transfer
- staking_reward_later
- initial_position_snapshot
- initial_cash_snapshot
- manual_correction

### 4.5 `cash_ledger`

- `cash_ledger_id`
- `account_id`
- `transaction_id`
- `date`
- `currency`
- `amount_original`
- `fx_rate_to_chf`
- `amount_chf`
- `balance_after_original`
- `balance_after_chf`
- `description`

### 4.6 `positions_current`

Abgeleitete Tabelle/View:

- `position_id`
- `account_id`
- `platform_id`
- `instrument_id`
- `quantity`
- `average_cost_original`
- `cost_basis_original`
- `cost_basis_chf`
- `market_price_original`
- `market_value_original`
- `market_fx_rate_to_chf`
- `market_value_chf`
- `unrealized_price_pnl_original`
- `unrealized_price_pnl_chf`
- `unrealized_fx_pnl_chf`
- `realized_pnl_chf`
- `income_chf`
- `fees_chf`
- `taxes_chf`
- `total_return_chf`
- `portfolio_weight_pct`
- `target_weight_pct`
- `category`: Core, Opportunity, Watch, Reserve
- `valuation_timestamp`
- `data_quality_status`

### 4.7 `dividends_distributions`

- `income_id`
- `transaction_id`
- `account_id`
- `instrument_id`
- `income_type`: dividend, etf_distribution, interest, staking_reward
- `ex_date`
- `payment_date`
- `record_date`
- `quantity_eligible`
- `gross_amount_original`
- `swiss_withholding_tax_35_original`
- `foreign_withholding_tax_original`
- `other_tax_original`
- `net_amount_original`
- `currency_original`
- `fx_rate_to_chf`
- `fx_source`
- `gross_amount_chf`
- `swiss_withholding_tax_35_chf`
- `foreign_withholding_tax_chf`
- `net_amount_chf`
- `source`
- `quality_status`
- `notes`

### 4.8 `market_prices`

- `price_id`
- `instrument_id`
- `price_date`
- `price_timestamp`
- `open`
- `high`
- `low`
- `close`
- `adjusted_close`
- `currency`
- `provider`
- `provider_symbol`
- `is_intraday`
- `quality_status`
- `created_at`

### 4.9 `fx_rates`

- `fx_rate_id`
- `base_currency`
- `quote_currency`: CHF
- `rate_date`
- `rate_timestamp`
- `rate`
- `provider`
- `rate_type`: transaction, eod, latest, manual_override
- `quality_status`
- `created_at`

### 4.10 `watchlist_items`

- `watchlist_item_id`
- `instrument_id`
- `status`
- `reason`
- `target_entry_price`
- `target_entry_currency`
- `desired_position_size_chf`
- `desired_weight_pct`
- `trigger_rules`
- `risk_notes`
- `investment_case`
- `bear_case`
- `sources`
- `next_review_date`
- `created_at`

### 4.11 `alerts`

- `alert_id`
- `priority`: info, wichtig, kritisch
- `category`
- `entity_type`
- `entity_id`
- `rule_id`
- `message`
- `evidence_json`
- `status`: new, acknowledged, snoozed, resolved, false_positive
- `created_at`
- `resolved_at`

### 4.12 `decision_journal`

- `decision_id`
- `decision_date`
- `decision_type`
- `entity_type`
- `entity_id`
- `system_recommendation`
- `human_decision`
- `rationale`
- `investment_case`
- `risks`
- `exit_rule`
- `alternatives_considered`
- `sources`
- `review_date`
- `outcome_status`
- `outcome_return_chf`
- `created_at`

---

## 5. CSV-Importformat v0.2

### 5.1 Standard CSV: `transactions_standard.csv`

Pflichtspalten:

```text
transaction_id_external,transaction_type,platform,account,trade_date,settlement_date,asset_class,name,ticker,isin,coingecko_id,quantity,price_original,gross_amount_original,fee_original,tax_original,net_amount_original,currency_original,fx_rate_to_chf,fx_source,notes
```

Optionale Spalten:

```text
category,target_weight_pct,investment_case,exit_rule,decision_ref,source_file,source_row,quality_hint
```

Regeln:

- `currency_original` ist Pflicht.
- `fx_rate_to_chf` darf leer sein, wenn das System den historischen FX-Kurs holen soll.
- Bei manuellem FX Override muss `fx_source = manual_override` gesetzt werden.
- `coingecko_id` wird für Crypto bevorzugt.
- Für Aktien/ETFs ist ISIN bevorzugt, Ticker als Fallback.
- Import muss idempotent sein: gleiche externe ID oder gleicher Row Hash darf nicht doppelt gebucht werden.

### 5.2 Standard CSV: `positions_initial_snapshot.csv`

Für bestehende Bestände ohne vollständige Historie.

Pflichtspalten:

```text
snapshot_date,platform,account,asset_class,name,ticker,isin,coingecko_id,quantity,currency_original,market_price_original,market_value_original,market_value_chf,cost_basis_original,cost_basis_chf,data_quality_note
```

Regeln:

- Wird als `initial_position_snapshot` importiert.
- Erzeugt keine fiktiven historischen Käufe, ausser Sir entscheidet später bewusst eine approximierte Historie aufzubauen.
- Bei Crypto wird `market_value_original`/`market_value_chf` aus Snapshot als `legacy_snapshot_value` markiert und nicht als aktuelle Bewertung genutzt.

### 5.3 Standard CSV: `income_standard.csv`

Pflichtspalten:

```text
income_type,platform,account,payment_date,ex_date,name,ticker,isin,quantity_eligible,gross_amount_original,swiss_withholding_tax_35_original,foreign_withholding_tax_original,other_tax_original,net_amount_original,currency_original,fx_rate_to_chf,fx_source,source,notes
```

---

## 6. FX- und CHF-Ledger-Logik

### 6.1 Grundsatz

Jede Transaktion in Fremdwährung speichert:

- Originalwährung.
- Originalbetrag.
- historischen FX-Kurs zum Transaktionszeitpunkt.
- CHF-Gegenwert zum Transaktionszeitpunkt.
- FX-Quelle.
- FX-Zeitstempel.

### 6.2 Bewertung aktueller Positionen

Für aktuelle Bewertung:

1. aktueller Marktpreis in Originalwährung.
2. aktuelle FX Rate zu CHF.
3. Marktwert Originalwährung = Menge × Marktpreis.
4. Marktwert CHF = Marktwert Originalwährung × aktuelle FX Rate.

### 6.3 Trennung Preis-PnL und FX-PnL

Für Positionen in Fremdwährung:

- **Preis-PnL Original:** `(aktueller Preis - Einstandspreis) × Menge`.
- **Preis-PnL CHF:** Preis-PnL Original × historischer/gewichteter Einstands-FX oder methodisch definierter FX-Ansatz.
- **FX-PnL CHF:** Differenz zwischen aktuellem CHF-Wert und CHF-Wert bei Einstands-FX, bereinigt um Preisbewegung.

MVP-Methode:

- gewichteter durchschnittlicher FX-Kurs pro Position für Cost Basis.
- explizite Trennung in `unrealized_price_pnl_chf` und `unrealized_fx_pnl_chf`.
- Methodik im Report anzeigen.

### 6.4 FX-Wechsel

FX-Wechsel wird als eigene Transaktion gespeichert:

- Ausgangswährung und Betrag.
- Zielwährung und Betrag.
- impliziter FX-Kurs.
- Gebühren.
- Konto/Plattform.

---

## 7. Dividenden-, Ausschüttungs- und Steuerdatenmodell

### 7.1 Pflichtunterscheidung

Bei Dividenden und ETF-Ausschüttungen muss unterschieden werden:

- Bruttodividende.
- Schweizer Verrechnungssteuer 35%.
- ausländische Quellensteuer.
- andere Steuer/Abzug.
- Nettodividende.
- Währung.
- historischer FX-Kurs am Ausschüttungstag.
- CHF-Gegenwert brutto/netto.
- Depot/Konto.
- ISIN/Ticker.
- Zahlungsdatum.
- Ex-Dividenden-Datum, falls verfügbar.

### 7.2 Tax View

Die Tax View zeigt:

- Jahresendwerte per 31.12.
- Dividenden/Ausschüttungen pro Jahr.
- Brutto/Netto in Originalwährung und CHF.
- Schweizer Verrechnungssteuer.
- ausländische Quellensteuer.
- realisierte Verkäufe.
- Gebühren/Steuern.
- Export für Steuerunterlagen.
- Datenqualität und offene Lücken.

### 7.3 ESTV/ICTax

Für spätere Versionen:

- ESTV/ICTax-Kurslisten für Jahresendwerte und Steuerkurse berücksichtigen.
- Instrument-Mapping zu ISIN/Valor/ICTax-ID vorbereiten.
- Tax View muss anzeigen, ob Steuerwerte aus ICTax, Market Data Provider oder manuell stammen.

---

## 8. Market-Data-Provider-Strategie

### 8.1 Aktien/ETFs

Provider modular, austauschbar:

- Finnhub als möglicher Primäranbieter.
- Financial Modeling Prep als Kandidat für Fundamentals/Profiles.
- Twelve Data für internationale Märkte und FX.
- Stooq für kostenlose historische End-of-Day-Daten.
- Alpha Vantage nur selektiv wegen engem Free Tier.
- Yahoo Finance nur Fallback, nicht Primärquelle.

### 8.2 Crypto

- CoinGecko als Primärquelle.
- DefiLlama später optional für DeFi/TVL.

### 8.3 Steuerkurse

- ESTV/ICTax für Jahresabschluss und Steuerwerte, soweit verfügbar.

### 8.4 Rate-Limit-Management

Pflichtkomponenten:

- lokaler Cache.
- historische Kurse lokal speichern.
- Batch-Abfragen, wo möglich.
- Rate-Limit-Queue pro Provider.
- Exponential Backoff bei 429.
- Provider-spezifische Tages-/Minutenlimits.
- `last_successful_update` je Instrument.
- `data_staleness_status` je Preis/FX/Instrument.
- Fallback-Provider nur kontrolliert und markiert.

Dashboard darf nicht bei jedem Seitenaufruf APIs abfragen. Dashboard liest aus lokaler DB; APIs laufen über geplante Update-Jobs.

---

## 9. Dashboard-Seiten v0.2

### 9.1 Command Center

Beantwortet sofort:

- Was ist heute wichtig?
- Gibt es kritische Alerts?
- Welche Positionen haben grosse Bewegungen?
- Welche Daten sind veraltet oder widersprüchlich?
- Gibt es Rebalancing-Bedarf?
- Welche Watchlist-Titel sind kaufnah?
- Kann ein Report erzeugt werden?

### 9.2 Gesamtportfolio

- Gesamtwert CHF.
- Performance CHF.
- Total Return CHF.
- Cashquote.
- Plattform-Allokation.
- Assetklassen-Allokation.
- Währungs-Exposure.
- Top Gewinner/Verlierer.

### 9.3 Plattformansichten

Tabs/Filter:

- Gesamt.
- Raiffeisen.
- PostFinance.
- True Wealth.
- Crypto-Coins.

Je Ansicht:

- Cash.
- Positionen.
- P&L.
- Income.
- FX-Effekt.
- Datenqualität.

### 9.4 Transactions

- Ledger-Tabelle.
- Filter nach Plattform, Konto, Typ, Datum, Instrument.
- manuelle Eingabe.
- CSV Import.
- Korrekturworkflow.

### 9.5 Dividenden & Tax

- Brutto/Netto.
- Schweizer Verrechnungssteuer.
- ausländische Quellensteuer.
- Jahresfilter.
- Steuerexport.

### 9.6 Watchlist

- Pipeline-Status.
- Ziel-Einstiegspreis.
- Trigger.
- gewünschte Positionsgrösse.
- Übernahme ins Portfolio.

### 9.7 Reports

- Sofortreport per Button.
- Tages-/Wochen-/Monatsreport.
- Positionsreport.
- Watchlist-Report.
- PDF/HTML/Markdown.

### 9.8 Alerts

- Info/Wichtig/Kritisch.
- Status: neu, geprüft, snoozed, erledigt.
- Evidence anzeigen.

### 9.9 Decision Journal

- Entscheidung dokumentieren.
- Systemempfehlung speichern.
- Override markieren.
- Review-Datum setzen.

---

## 10. Kern-Workflows

### 10.1 Neue Position erfassen

1. Plattform/Konto auswählen.
2. Titel über Suche auswählen oder neu anlegen.
3. Assetklasse setzen.
4. Kaufdaten erfassen.
5. FX-Kurs automatisch holen oder manuell überschreiben.
6. Gebühren/Steuern erfassen.
7. Kategorie Core/Opportunity setzen.
8. Zielgewichtung und Investment Case optional erfassen.
9. Speichern erzeugt Buy-Transaction und Position wird neu berechnet.

### 10.2 Kauftransaktion erfassen

- Menge, Preis, Währung, Gebühren, Datum.
- FX Rate in CHF.
- Cash-Abzug im passenden Konto.
- Positionserhöhung.
- Audit Trail.

### 10.3 Teilverkauf erfassen

- Position wählen.
- Menge, Preis, Gebühren, Steuern, Datum.
- Cost-Basis-Methode anwenden.
- Realized P&L und FX-Effekt berechnen.
- Cash-Zugang buchen.
- Decision Journal optional/empfohlen.

### 10.4 Dividende/Ausschüttung erfassen

- Instrument auswählen.
- Zahlungsdatum und Ex-Date.
- Brutto, Schweizer Verrechnungssteuer, ausländische Quellensteuer, Netto.
- Währung und FX.
- Cash-Zugang netto.
- Income- und Tax-Tabellen aktualisieren.

### 10.5 FX-Kurs automatisch holen oder überschreiben

- System schlägt historischen FX-Kurs vor.
- Nutzer kann manuell überschreiben.
- Override erfordert Begründung/Quelle.
- Alle Overrides werden markiert.

### 10.6 Watchlist-Titel hinzufügen

- Titel suchen.
- Beobachtungsgrund.
- Zielpreis.
- gewünschte Positionsgrösse.
- Trigger.
- Risiko/Bear Case.
- Quellen.

### 10.7 Watchlist → Portfolio

- Watchlist Item auswählen.
- `In Portfolio übernehmen`.
- Kaufmaske wird vorbefüllt.
- Nutzer ergänzt tatsächliche Kaufdaten.
- Decision Journal wird erzeugt.

### 10.8 Umschichtung dokumentieren

- Ausgangsposition und Zielposition wählen.
- System zeigt geplante Beträge, Auswirkungen, Gebühren-/Steuerhinweise.
- Nutzer entscheidet.
- Transaktionen werden manuell erfasst.
- Journal dokumentiert Begründung.

### 10.9 PDF-Report erzeugen

- Reporttyp wählen.
- Zeitraum wählen.
- Datenqualität prüfen.
- Report generieren.
- PDF/HTML/Markdown speichern.

### 10.10 Alert prüfen

- Alert öffnen.
- Evidence prüfen.
- Status setzen: acknowledged/snoozed/resolved/false positive.
- optional Decision Journal Eintrag.

### 10.11 Rebalancing-Vorschlag anschauen

- Ist-/Zielgewicht prüfen.
- Differenzbetrag sehen.
- Auswirkungen auf Cash/Risk/FX prüfen.
- `Order vorbereiten` erzeugt manuelle Eingabehilfe, keine Ausführung.

### 10.12 Plattformansicht wechseln

- Umschalter: Gesamt / Raiffeisen / PostFinance / True Wealth / Crypto.
- Alle Widgets filtern auf Plattform/Konto.

---

## 11. MVP 1 Priorisierung

### 11.1 Muss-Funktionen

- Transaktionen erfassen.
- Plattform/Konto erfassen.
- aktive Positionen berechnen.
- Cash berechnen.
- Gewinn/Verlust pro Position.
- Gesamtgewinn/-verlust.
- Total Return in CHF.
- Gebühren berücksichtigen.
- Dividenden/Ausschüttungen erfassen.
- Schweizer Verrechnungssteuer und ausländische Quellensteuer getrennt erfassen.
- FX-Effekte getrennt berechnen.
- Watchlist.
- manuelle Eingabe.
- CSV Import/Export.
- PDF/HTML/Markdown Sofortreport.
- getrennte Ansichten für Raiffeisen, PostFinance, True Wealth, Crypto-Coins.
- Gesamtportfolio-Ansicht.

### 11.2 Nicht zwingend in MVP 1

- komplexe Newsanalyse.
- Analystenratings.
- Opportunity Scanner.
- ML/LLM-Auswertungen.
- automatische Broker-Anbindung.
- automatische Orderausführung.
- komplexer Fundamental Score.

---

## 12. Initiale Score-Regeln MVP 1

### 12.1 Trend Score

Ziel: einfache technische Orientierung.

Inputs:

- Kurs vs. 50DMA.
- Kurs vs. 200DMA.
- 1M Performance.
- 3M Performance.
- Abstand zum 52W Hoch/Tief, falls verfügbar.

MVP Ampel:

- Grün: Kurs > 50DMA und > 200DMA, 3M positiv.
- Gelb: gemischte Signale.
- Rot: Kurs < 200DMA oder starker negativer Trend.

### 12.2 Portfolio Fit Score

Inputs:

- Istgewicht vs Zielgewicht.
- Core/Opportunity Kategorie.
- Plattform-/Kontozuordnung.
- Cashquote.
- Assetklassenquote.

MVP Ampel:

- Grün: innerhalb Zielband.
- Gelb: 10–20% relativ über/unter Zielgewicht.
- Rot: >20% relativ über/unter Zielgewicht oder Zielband verletzt.

### 12.3 Risk Score

Inputs:

- Positionsgrösse.
- Tagesverlust.
- unrealisiertes Minus.
- Volatilität, wenn Daten vorhanden.
- Crypto-/Opportunity-Klassifikation.
- Datenqualität.

MVP Ampel:

- Grün: Risiko innerhalb Limits.
- Gelb: erhöhte Volatilität oder Gewichtung.
- Rot: Verlust-/Drawdown-/Konzentrationslimit verletzt.

### 12.4 Vorbereitet, aber nicht MVP-Kern

- Fundamental Score.
- Sentiment Score.
- Analyst Score.
- News Score.
- Opportunity Scanner.

---

## 13. Alert-Regeln v0.2

### 13.1 Info

- Watchlist-Zielzone erreicht.
- Dividende/Ausschüttung erfasst.
- Report generiert.
- Kursdaten älter als 24h.
- neuer Initial Snapshot importiert.
- manuelles FX Override gespeichert.

### 13.2 Wichtig

- Position >20% über Zielgewicht.
- Tagesverlust einer Position >5%.
- Kurs unter 200DMA.
- Cashquote ausserhalb Zielband.
- Dividenden-/Steuerdaten unvollständig.
- Crypto-Preisupdate fehlgeschlagen, alter Preis noch verwendbar.
- Rebalancing-Bedarf über definierter Schwelle.

### 13.3 Kritisch

- Portfolio Drawdown >10%.
- Einzelposition Verlust >20%.
- harte Exit-Regel ausgelöst.
- widersprüchliche Datenquelle bei kritischem Wert.
- FX-Daten fehlen für Transaktion.
- Cash Ledger stimmt nicht mit Snapshot überein.
- Position kann wegen Datenfehler nicht bewertet werden.
- Report würde auf unvollständigen Kernbuchungen basieren.

---

## 14. Sicherheits- und Geheimhaltungsanforderungen

### 14.1 Datenklassifikation

- **Public:** generische Code-Dokumentation, Beispiel-CSV ohne Echtdaten.
- **Internal:** technische Architektur, Schema, Testdaten synthetisch.
- **Confidential:** Portfolio-Struktur, Auszüge, echte Transaktionen, Reports.
- **Secret:** API Keys, OAuth Tokens, Passwörter.

### 14.2 Git-Regeln

`.gitignore` muss mindestens ausschliessen:

```text
data/
reports/
exports/
backups/
*.db
*.sqlite
*.sqlite3
*.parquet
*.xlsx
*.xls
*.docx
*.pdf
*.csv
*.json
.env
*token*
*credential*
*client_secret*
```

Ausnahme: synthetische Beispiel-Dateien explizit unter `examples/` mit Dummy-Werten.

### 14.3 Secret Scan

Vor jedem Commit:

- Scan auf API Keys.
- Scan auf bekannte Credential-Dateinamen.
- Scan auf reale Finanzdaten-Dateitypen.
- Commit blockieren bei Treffer.

---

## 15. Roadmap ab v0.2

### Phase 0 – v0.3 Detailentscheidungen

- finale Dashboard-Technologie bestätigen.
- konkrete SQLite-Schema-Spezifikation.
- Standard-CSV finalisieren.
- Provider-Auswahl für MVP.
- erste synthetische Testdaten definieren.

### Phase 1 – MVP 1 Ledger & Dashboard

- SQLite Schema.
- Streamlit App.
- Manuelle Eingabe.
- CSV Import.
- Ledger-Berechnung.
- Plattformansichten.
- Report Export.

### Phase 2 – FX, Income, Tax

- historische FX-Kurse.
- Dividenden-/Ausschüttungsmodell.
- Tax View.
- Schweizer Verrechnungssteuer.
- ausländische Quellensteuer.

### Phase 3 – Market Data & Crypto

- Finnhub/FMP/Twelve/Stooq modular.
- CoinGecko für Crypto.
- Rate-Limit-Queue.
- lokale Kurshistorie.

### Phase 4 – Scores, Alerts, Watchlist

- Trend/Fit/Risk Scores.
- Alert Center.
- Watchlist Pipeline.
- Decision Journal.

### Phase 5 – Rebalancing & Risk

- Zielgewichtungen.
- Rebalancing-Vorschläge.
- Risk Heatmap.
- ETF-Look-through Basis.

---

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

1. Sollen Raiffeisen-Cashkonten in Performance einbezogen werden oder nur im Net Worth erscheinen?
2. Soll die Health Reserve auf einem bestimmten Raiffeisenkonto liegen und aus Investment-Performance ausgeschlossen werden?
3. Welche Ziel-Cashquote gilt für das Anlageportfolio?
4. Welche Zielgewichte gelten für Core, Opportunity, Crypto und Cash?
5. Welche Broker-/Bank-Auszüge sollen als erste Testfälle für Initial Snapshot verwendet werden?
6. Welche CSV-Spaltennamen sollen exakt finalisiert werden?
7. Welche Market-Data-Provider-API wird zuerst eingerichtet?
8. Welche FX-Quelle soll primär genutzt werden?
9. Soll True Wealth im MVP als einzelne ETF-Positionen oder zusätzlich als Plattformstrategie aggregiert dargestellt werden?
10. Wie sollen historische PostFinance-Crypto-Werte gekennzeichnet werden?
11. Soll das Dashboard nur lokal laufen oder im privaten Heimnetz erreichbar sein?
12. Welche Telegram-Alerts sollen sofort gesendet werden, welche nur im Dashboard erscheinen?
13. Welche Report-Vorlage soll zuerst gebaut werden: Tagesreport oder Monatsreport?
14. Welche synthetischen Testdaten dürfen ins Git-Repo?

---

## 17. Abschluss v0.2

Diese Spezifikation setzt die Kernarchitektur auf ein solides Fundament: CHF als Basiswährung, transaktionsbasierte Buchhaltung, klare Plattformtrennung, lokale Datenhoheit, strukturierte FX-Logik, Dividenden-/Tax-Modell, modulare Market-Data-Provider, MVP-fähiges Streamlit-Dashboard und strikte Geheimhaltung.

Der wichtigste Satz bleibt: **Erst muss die Buchhaltung stimmen. Danach darf das System Meinungen haben.**