# JARVIS Finance System – MVP Zwischenbericht & Abnahmeplan Stand: 2026-05-16 Status: MVP-Freeze nach Provider Integration Sprint v2 Scope: Dokumentation und Abnahmeplan; keine neuen Provider, keine neuen grossen Features. ## Leitplanken - Dieses Dokument enthält keine echten Finanzwerte, Mengen, Depotwerte, Wallet-Bestände oder API-Keys. - Runtime-Daten, produktive Reports, produktive CSV/XLSX/DOCX/PDF-Dateien und SQLite-Datenbanken bleiben ausserhalb des Git-Repositories. - Dokumentation im Repository darf nur Architektur, Bedienung, Checklisten und synthetische Beispiele enthalten. - Provider-Abfragen erfolgen nur durch explizite CLI-Befehle oder explizite Dashboard-Aktionen, nicht beim normalen Dashboard-Rendern. - MVP 1 ist ein lokal-first, auditierbares Finance-System; keine Trading-Automation. --- ## 1. Aktueller Projektstand - Aktueller Git-Commit: `4835f11` (`feat: add provider integration sprint v2`) - Aktueller Branch: `main` - Runtime-Basis: `~/jarvis_runtime/finance-system/` - Runtime-DB-Pfad: `~/jarvis_runtime/finance-system/data/finance.sqlite3` - Reports-Pfad: `~/jarvis_runtime/finance-system/reports/` - Secrets-Pfad: `~/jarvis_runtime/finance-system/secrets/` - Provider-Secrets-Datei: `~/jarvis_runtime/finance-system/secrets/.env` - Streamlit-Startbefehl: ```bash cd /home/agent/.hermes/repos/FinanceManager PYTHONPATH=src streamlit run src/jarvis_finance/app.py ``` Alternative, falls Paket im Environment installiert ist: ```bash streamlit run src/jarvis_finance/app.py ``` - CLI-Basisbefehl aus dem Repo: ```bash cd /home/agent/.hermes/repos/FinanceManager PYTHONPATH=src python -m jarvis_finance.cli.main ``` - Teststatus zuletzt vor MVP-Zwischenbericht: `294 passed` - Git-Safety-Status zuletzt vor MVP-Zwischenbericht: `GIT_SAFETY_OK` - Erwarteter Verification-Lauf für diese Dokumentation: Compile, pytest, Git-Safety, `git diff --check`, Git-Status. ### Aktuell unterstützte Hauptmodule - Core Ledger / Transaktionen / Cash / WAC / Positionen - Runtime-Konfiguration und Migrationsschema - Audit-Log - Data Quality / Alerts - Runtime Backup / Restore / Verify - Crypto Assets, Wallets, Holdings, Transactions, Transfers und manuelle Korrekturen - Crypto Pricing via CoinGecko mit lokalem Cache - Crypto Reports, lokal im Runtime-Reports-Verzeichnis - Equity/ETF Instrument Catalog, manuelle Positionserfassung und Provider-Suche - Equity/ETF Market-Price Update Workflow - FX Rates / FX Update / FX-Recheck - Broker/Import Dry-run, Review Queue und Mapping-Vorbereitung - Streamlit Dashboard: User Mode und Admin/Review/Debug Mode - Git-Safety Scanner --- ## 2. Umgesetzte Funktionen ### A. Core / Ledger - Transaktionsmodell: - Einheitliches Ledger-Modell für produktive und synthetische Transaktionen. - Unterstützt Originalwährung, CHF-Bezug, Instrument, Account/Platform, Source-Typen und Statusflags. - Initial Snapshots: - `initial_position_snapshot` als expliziter Startbestand, nicht als künstlicher historischer Kauf. - `initial_cash_snapshot` als Start-Cash-Basis. - Cash-Logik: - Cash wird nach Systemstart aus Ledger-Transaktionen abgeleitet. - Cash-Snapshots sind Start-/Kontrollpunkte, nicht alleinige Wahrheit. - FX-Logik: - CHF als Basiswährung. - Originalwährung bleibt erhalten. - Fehlende FX-Daten erzeugen Quality-Hinweise statt erfundener Werte. - FX-Update über CLI vorbereitet und testbar. - Weighted Average Cost: - MVP-WAC implementiert für Buy/Sell/Positionen. - Gebühren können die Kostenbasis beeinflussen, soweit im Ledger vorhanden. - WAC ist bewusst kein vollständiges Tax-Lot-System. - Positionenberechnung: - Positionen werden aus Transaktionen berechnet. - Nullbestände können historisch erhalten bleiben, wenn Verkaufshistorie existiert. - Audit-Log: - Schreibende Workflows erzeugen Audit-Einträge. - Korrekturen und manuelle Eingriffe sind nachvollziehbar statt stille Mutationen. - Data Quality: - Fehlende FX-Daten, fehlende Preise, fehlende Provider-Mappings und Review-Bedarf werden als Quality-/Alert-Themen sichtbar. - Alert-Deduplizierung und Lifecycle-Status sind vorbereitet. ### B. Crypto - Wallets: - Wallet-Modell mit Typen und eindeutigen Wallet-Namen. - Wallet-Dashboard vorhanden. - Holdings: - Holdings nach Asset und Wallet. - Aggregation über mehrere Wallets möglich. - Negative Bestände werden im MVP defensiv behandelt. - Transfers: - Transfer-Workflow mit Quelle/Ziel, gleicher Asset-Identität und Audit. - Manuelle Korrekturen: - Audited Add/Correct/Remove-Workflows vorhanden. - Korrekturen benötigen bewusst Review/Bestätigung und Notizen, wo sinnvoll. - CoinGecko-IDs: - CoinGecko-ID als bevorzugte Provider-Identität. - Fehlende IDs erzeugen Quality-Hinweise und blockieren verlässliche Bewertung. - Preisupdate: - CoinGecko Preisupdate über CLI, mit Cache, Retry/Backoff und aggregierter Ausgabe. - Keine Live-API-Abfrage beim Dashboard-Rendern. - Crypto-Report: - Runtime-only Report-Export vorbereitet. - Report erzeugt keine Git-Artefakte. - Crypto Dashboard: - User-Mode Crypto-Seite vorhanden. - Lokale Preise/Bestände werden aus Runtime-DB gelesen. - Wallet Dashboard: - Wallet-Aufteilung und Drilldown vorhanden. ### C. Aktien/ETFs - Manuelle Positionserfassung: - User-Mode-Seite `Position hinzufügen` vorhanden. - Manual workflow ist der bevorzugte MVP-Pfad, weil DOCX/Broker-Imports strukturell unsicher sind. - Instrumentensuche: - Lokaler Instrumentenkatalog zuerst. - Provider-Suche nur explizit auf Nutzeraktion. - ISIN-/Name-/Ticker-Suche: - ISIN als stärkste Identität. - Name-Suche unterstützt Kandidaten. - Ticker-Suche zeigt Kandidaten und wird nicht automatisch eindeutig behandelt. - Providerintegration: - OpenFIGI, FMP, Finnhub, Twelve Data und Massive für Public Instrument Lookup / Kandidaten vorbereitet. - Provider-Ergebnisse werden normalisiert und lokal gecacht. - Initial Snapshot: - Initial Position Snapshot kann aus manuellem Wizard/Workflow geschrieben werden. - Fehlende Cost Basis bleibt als Quality-Thema sichtbar. - Buy/Sell/Dividend: - Buy, Partial Sell und Dividend sind im manuellen Positionserfassungs-/Ledger-Kontext vorbereitet bzw. testabgedeckt. - Vollständige steuerliche Behandlung bleibt ausserhalb MVP 1. - Preisvorschau: - Preisvorschau liest lokale `market_prices` und zeigt fehlende Preise als „Preis noch nicht verfügbar“ statt `0`. - Equity-Preisupdate: - CLI-Workflow `update-equity-prices` vorhanden. - Auto-Provider-Fallback: FMP, Twelve Data, Finnhub, Massive. - EODHD nur explizit mit Low-Volume-Opt-in. ### D. Provider/APIs - OpenFIGI: - Aktiv für Mapping/Search. - Auth per Header, keine Keys in Logs/Status. - Korrigierter Key wurde im Sprint v2 erfolgreich gegen Mapping/Search getestet. - FMP: - Primary für Suche und Preisvorschau/Preisupdate. - Auth-/Rate-/Restricted-Endpunkte werden kategorisiert. - Finnhub: - Integriert für Symbol Lookup, Quote und Fallback-Preisupdate. - Profile kann je nach Instrument leer sein; Workflow crasht nicht. - Twelve Data: - Integriert für Symbol/Quote und FX. - `TWELVEDATA_API_KEY` wird unterstützt. - Massive: - Integriert für US-fokussierte Ticker Details und Preis-/Previous-Day-Daten. - Frankfurter FX: - Primary/no-key FX Provider für CHF-Rates. - EODHD low-volume: - Eingebunden, aber nicht Default. - Nur explizit mit `--provider eodhd --allow-low-volume`. - Nicht für routinemässige Tests vorgesehen. - Alpha Vantage optional: - Key-Erkennung/Status vorbereitet; kein MVP-Primary. - Stooq optional: - Optionaler Providerstatus; kein MVP-Primary. ### E. Dashboard/UI - Command Center: - Ruhiger User-Mode-Einstieg. - Navigation zu MVP-relevanten Seiten. - Crypto: - Crypto User-Mode-Seite vorhanden. - Wallets: - Wallet User-Mode-Seite vorhanden. - Aktien & ETFs: - Aktien/ETF-Übersicht vorhanden. - Valuation bleibt abhängig von lokalen Marktpreisen/FX. - Position hinzufügen: - MVP-Wizard für manuelle Equity/ETF-Erfassung. - Provider-Suche nur explizit. - Technische IDs sind im User Mode verborgen. - Reports: - Report-Seite vorhanden; generierte Reports bleiben Runtime-only. - Admin/Debug: - Ledger, Audit, Alerts, Data Quality, Import Wizard, Settings, Crypto Manage, Equity/ETF Manage, Manual Review Queue und Watchlist sind im Admin/Review/Debug Mode verfügbar. ### F. Sicherheit - Runtime außerhalb Repo: - Default: `~/jarvis_runtime/finance-system/`. - Runtime-inside-repo wird durch Settings validiert/blockiert. - Git-Safety: - Eigener Git-Safety Scanner vorhanden. - Blockiert typische Runtime-/Data-/Report-/Secret-Artefakte. - Secrets: - Secrets liegen in `~/jarvis_runtime/finance-system/secrets/`. - API-Key-Werte werden nicht im Dashboardstatus, Testoutput oder Git dokumentiert. - Backups: - Runtime Backup, Verify und Restore CLI vorbereitet. - Backups gehören in Runtime, nicht ins Repo. - Keine echten Daten in Git: - Repo enthält Code, Dokumentation, synthetische Fixtures und Beispielkonfiguration. - Produktive DBs, Exporte, Reports und Rohdaten bleiben ausgeschlossen. --- ## 3. Was noch nicht fertig ist ### Noch nicht MVP-kritisch - Scoring / quantitative Scores - Analysten-/News-Integration - Opportunity Scanner - Rebalancing Engine - Telegram-Erfassungsworkflow - Broker-Automation oder direkte Broker-API-Anbindung - Vollständige Steuerlogik / Tax-Lot-System / FIFO/LIFO - Vollständige ESTV-/ICTax-Abdeckung - FastAPI/React-Frontend - Automatisierte Watchlist-Entscheidungen - Vollständige Performanceanalyse über alle Assetklassen ### MVP-relevant, aber noch zu prüfen - Manuelle Aktien-/ETF-Erfassung im echten Betrieb. - Preisupdate für echte Equity/ETF-Instrumente mit bestätigten Provider-Mappings. - FX-Update für `USD/CHF` und `EUR/CHF`. - Gesamtportfolio-Bewertung mit bewertbaren und nicht bewertbaren Assets. - Report-Erstellung mit echten Runtime-Daten, ohne Git-Artefakte. - Backup/Restore-Test gegen separate Test-Restore-DB. - UI-Bedienbarkeit aus Nutzersicht: User Mode, Edit Mode, Fehlermeldungen, Review-Hinweise. - Data-Quality-Hinweise nach echten manuellen Einträgen. --- ## 4. Offene Risiken - Streamlit UX-Limitierungen: - Streamlit ist schnell und pragmatisch, aber kein poliertes React-Frontend. - Session State, Forms und Navigation bleiben begrenzt; UX muss bewusst einfach bleiben. - Provider-Limits: - Free-/Fallback-Provider haben Rate Limits, Paywalls, leere Profile oder unvollständige historische Daten. - Providerfehler dürfen Bewertung nicht verfälschen. - EODHD Low-Volume: - Nur ca. 20 Calls/Tag; darf nicht in automatische oder routinemässige Pfade gelangen. - Fehlende Cost Basis bei Initial Snapshots: - Initial Snapshots ohne Cost Basis sind für Bestand nutzbar, aber Performance/Steuerwerte bleiben unvollständig. - Marktpreis-/FX-Datenqualität: - Fehlende/stale Preise und FX-Rates müssen markiert werden. - Keine falschen `0`-Werte erzeugen. - DOCX-Import ungeeignet für automatischen Aktien-/ETF-Import: - DOCX kann niedrige ISIN-Abdeckung, fehlende Cost Basis und keine Transaktionshistorie enthalten. - Daher MVP-Pfad: manuelle Erfassung / Review statt produktive Massenübernahme. - Kein steuerlich vollständiges Tax-Lot-System: - WAC ist MVP-intern; Tax-Lots/FIFO/LIFO bleiben später. - Echte Daten nur Runtime: - Vorteil: sicherer. - Risiko: Backup/Restore muss diszipliniert getestet werden. - Watchlist noch nicht MVP-fertig: - Watchlist existiert als Admin-/optional Bereich, ist aber nicht Abnahmekern. --- ## 5. MVP-Abnahmekriterien ### Crypto-Abnahme - [ ] Crypto-Preise aktualisieren funktioniert. - [ ] Crypto-Gesamtwert wird angezeigt, sofern lokale Preise vorhanden sind. - [ ] Wallet-Aufteilung stimmt. - [ ] Coin auf mehreren Wallets wird aggregiert. - [ ] Crypto-Report wird im Runtime-Reports-Verzeichnis erzeugt. - [ ] Bestand korrigieren erzeugt Audit. - [ ] Transfer erzeugt Audit. ### Aktien/ETF-Abnahme - [ ] ISIN-Suche funktioniert. - [ ] Name-Suche funktioniert. - [ ] Ticker-Suche zeigt Kandidaten und übernimmt nicht automatisch blind. - [ ] Manuelle Anlage funktioniert. - [ ] Initial Snapshot kann gespeichert werden. - [ ] Fehlende Cost Basis wird als unvollständig / Quality-Hinweis markiert. - [ ] Fehlender FX wird als Hinweis markiert. - [ ] Preisupdate funktioniert für ein bestätigtes Instrument. - [ ] Position erscheint auf der Aktien/ETF-Seite. ### Portfolio-Abnahme - [ ] Gesamtwert zeigt bewertbare Assets. - [ ] Nicht bewertete Assets werden markiert. - [ ] Keine falschen `0`-Werte bei fehlenden Preisen/FX. - [ ] Crypto, Aktien/ETF und Cash werden sauber getrennt. - [ ] Plattformen/Depots sind unterscheidbar. ### Safety-Abnahme - [ ] Git-Safety OK. - [ ] Runtime-DB liegt außerhalb Repo. - [ ] Backup vorhanden. - [ ] Keine echten Daten im Repo. - [ ] Reports werden nur unter Runtime erzeugt. - [ ] Secrets sind im Dashboard, in Git und in Reports nicht sichtbar. --- ## 6. Empfohlene nächste 10 Schritte 1. Dashboard neu starten. 2. Runtime prüfen: DB-Pfad, Secrets-Pfad, Read-only/Edit Mode. 3. Crypto-Preise aktualisieren. 4. Crypto-Report erzeugen und im Runtime-Reports-Verzeichnis prüfen. 5. Eine echte Test-Aktie oder einen echten ETF über ISIN im Wizard suchen. 6. Kandidat bewusst auswählen und Initial Snapshot erfassen. 7. FX aktualisieren, mindestens `USD/CHF` und `EUR/CHF`. 8. Equity-/ETF-Preisupdate für das bestätigte Instrument ausführen. 9. Aktien/ETF-Seite und Gesamtportfolio prüfen: bewertet, unbewertet, Quality-Hinweise. 10. Backup/Restore-Test gegen separate Test-Restore-DB durchführen; danach weitere offene Positionen manuell eintragen. --- ## 7. Bedienungsanleitung kurz Alle Befehle aus dem Repository: ```bash cd /home/agent/.hermes/repos/FinanceManager ``` ### Dashboard starten ```bash PYTHONPATH=src streamlit run src/jarvis_finance/app.py ``` ### Runtime prüfen ```bash PYTHONPATH=src python -m jarvis_finance.cli.main migrate ``` Erwartung: Schema-Version wird ausgegeben; Runtime liegt unter `~/jarvis_runtime/finance-system/`. ### Crypto-Preise aktualisieren ```bash PYTHONPATH=src python -m jarvis_finance.cli.main update-crypto-prices --currency CHF --only-stale ``` Schonender Testlauf: ```bash PYTHONPATH=src python -m jarvis_finance.cli.main update-crypto-prices --currency CHF --dry-run ``` ### Crypto-Report erzeugen Im Dashboard: 1. `Reports` öffnen. 2. Crypto-Report explizit erzeugen. 3. Ausgabe nur unter `~/jarvis_runtime/finance-system/reports/` prüfen. ### Aktie/ETF hinzufügen Im Dashboard: 1. `Position hinzufügen` öffnen. 2. Edit Mode bewusst aktivieren. 3. ISIN, Name oder Ticker eingeben. 4. Lokale Kandidaten prüfen. 5. Falls nötig: explizit `Online suchen` verwenden. 6. Kandidat auswählen oder manuelle Anlage mit Warnhinweis erstellen. ### Position speichern 1. Account/Depot auswählen. 2. Initial Snapshot oder passende Transaktionsart wählen. 3. Menge, Datum, Währung und Notiz erfassen. 4. Cost Basis eintragen, falls bekannt; sonst Quality-Hinweis akzeptieren. 5. Speichern bestätigen. 6. Audit/Data Quality prüfen. ### FX aktualisieren Latest Rates für USD/EUR gegen CHF: ```bash PYTHONPATH=src python -m jarvis_finance.cli.main update-fx-rates --latest --provider frankfurter --currency USD --currency EUR ``` Optional mit Twelve Data: ```bash PYTHONPATH=src python -m jarvis_finance.cli.main update-fx-rates --latest --provider twelvedata --currency USD --currency EUR ``` Fehlende FX-Flags neu prüfen: ```bash PYTHONPATH=src python -m jarvis_finance.cli.main update-fx-rates --recheck-transactions ``` ### Aktien-/ETF-Preise aktualisieren Schonender Dry-run: ```bash PYTHONPATH=src python -m jarvis_finance.cli.main update-equity-prices --asset-class all --provider auto --dry-run ``` Produktiver Update-Lauf nur nach Plausibilitätsprüfung: ```bash PYTHONPATH=src python -m jarvis_finance.cli.main update-equity-prices --asset-class all --provider auto --only-missing ``` EODHD nur explizit und sparsam: ```bash PYTHONPATH=src python -m jarvis_finance.cli.main update-equity-prices --provider eodhd --allow-low-volume --limit 1 --dry-run ``` ### Git-Safety prüfen ```bash rm -rf .pytest_cache find . -type d -name __pycache__ -prune -exec rm -rf {} + PYTHONPATH=src python -m jarvis_finance.cli.main git-safety-scan . ``` Erwartung: ```text GIT_SAFETY_OK ``` ### Backup erstellen ```bash PYTHONPATH=src python -m jarvis_finance.cli.main backup-runtime-db ``` Backup prüfen: ```bash PYTHONPATH=src python -m jarvis_finance.cli.main verify-backup --file ``` Restore nur gegen bewusst gewählten Ziel-/Testkontext und nie blind in die produktive Runtime. --- ## 8. MVP-Freeze-Regel ab jetzt Bis MVP 1 abgenommen ist: - Keine weiteren Provider integrieren. - Keine neuen grossen Features starten. - Fokus auf echte End-to-End-Abnahme, Fehlerkorrekturen, UX-Klarheit und Safety. - Jede produktive Aktion: vorher Backup, nachher Audit/Data Quality/Git-Safety prüfen. --- ## 9. Nächster End-to-End-Test Ziel des nächsten Tests: 1. Eine echte ETF-/Aktienposition über den Wizard erfassen. 2. Preisupdate ausführen. 3. FX für relevante Währungen prüfen. 4. Dashboard prüfen. 5. Report prüfen. Minimaler Testablauf: - [ ] Backup erstellen. - [ ] Dashboard starten. - [ ] `Position hinzufügen` öffnen. - [ ] Echte ISIN eingeben. - [ ] Kandidat prüfen und bewusst auswählen. - [ ] Initial Snapshot speichern. - [ ] Audit-Eintrag prüfen. - [ ] Data-Quality-Hinweise prüfen. - [ ] FX aktualisieren. - [ ] Equity-/ETF-Preisupdate als Dry-run ausführen. - [ ] Equity-/ETF-Preisupdate produktiv ausführen, falls Dry-run plausibel ist. - [ ] Aktien/ETF-Seite prüfen. - [ ] Portfolio-Seite prüfen. - [ ] Report erzeugen und Runtime-Pfad prüfen. - [ ] Git-Safety ausführen. Abnahmeziel: MVP 1 gilt als nutzbar, wenn Crypto, manuelle Aktien/ETF-Erfassung, FX, Preisupdate, Portfolio-Übersicht, Report und Safety-Checks in einem echten Runtime-Durchlauf ohne Git-Datenleck funktionieren.