# JARVIS Finance System – v0.4.1 Korrekturrunde **Version:** 0.4.1 **Datum:** 2026-05-14 **Status:** akzeptierte Korrektur zur v0.4 Implementation Blueprint **Scope:** Präzisierungen vor v0.5 Repo Blueprint / Implementation Plan **Basiswährung:** CHF --- ## 1. Zweck Diese v0.4.1 ersetzt die v0.4 nicht vollständig, sondern schärft verbindliche Regeln, bevor die Umsetzung geplant wird. Die v0.4 bleibt die technische MVP-1-Basis. Die hier definierten Korrekturen haben Vorrang, falls Formulierungen in v0.4 zu weich oder missverständlich sind. --- ## 2. Allgemeines Ledger und Crypto-Detailtabellen koppeln Die Trennung zwischen `transactions` und `crypto_transactions` bleibt bestehen. Sie darf aber nicht dazu führen, dass Cash, Gesamtvermögen, Gebühren, FX oder Performance auseinanderlaufen. ### 2.1 Verbindliche Regel Jede Crypto-Transaktion mit Fiat-/Cash-/CHF-Auswirkung muss im allgemeinen Ledger abbildbar sein. ### 2.2 Buchungsfälle - **Crypto-Kauf mit Fiat-Betrag:** - Eintrag in `transactions` für Cash-Abfluss, Fiat-Betrag, FX, Gebühren, CHF-Auswirkung. - Eintrag in `crypto_transactions` für Coin-Menge, Zielwallet, Coin-Preis, Fee in Coin oder Fiat. - Beide Einträge werden über `crypto_transactions.transaction_id` oder eine Buchungsgruppe gekoppelt. - **Crypto-Verkauf mit Fiat-Betrag:** - Eintrag in `transactions` für Cash-Zufluss, Fiat-Betrag, FX, Gebühren, CHF-Auswirkung. - Eintrag in `crypto_transactions` für Coin-Menge, Quellwallet, Verkaufspreis, Fee. - Realisierte Performance kann MVP-intern berechnet werden; vollständige steuerliche Tax-Lot-Logik bleibt ausserhalb MVP 1. - **Crypto-Transfer zwischen Wallets:** - `crypto_transactions` reicht, sofern keine Fiat-Bewegung entsteht. - Coin-Fee wird als Coin-Reduktion in `crypto_transactions` erfasst. - Kein allgemeiner Ledger-Eintrag nötig, wenn kein Cash/Fiat betroffen ist. - **Crypto-Fee:** - Fee in Coin: Reduktion der Coin-Menge / eigener Fee-Anteil in `crypto_transactions`. - Fee in Fiat: allgemeiner Ledger-Eintrag als Gebühr plus Bezug zur Crypto-Transaktion. - Fee in anderer Coin: eigene Coin-Reduktion mit Audit und Datenqualitätsprüfung. ### 2.3 Ziel Das System muss jederzeit konsistent bleiben: - Gesamtvermögen CHF - Cash-Bestände - FX-Auswirkungen - Gebühren - Performance - Audit Trail Crypto darf kein paralleles Schattenbuch werden. Schattenbücher sind für Geheimdienste, nicht für Buchhaltung. --- ## 3. Wahrheit: Transaktionen und bestätigte Initial-Snapshots ### 3.1 Verbindliche Regel Die Wahrheit sind: 1. bestätigte Transaktionen; 2. bestätigte Initial-Snapshots. Nicht die Wahrheit sind: - `positions_snapshot` - `cash_balances` - `crypto_holdings` Diese Tabellen sind berechnete Zustände, Caches, Kontrollansichten oder importierte Start-/Kontrollbilder. ### 3.2 Bestandsänderungen Bestände dürfen grundsätzlich nicht direkt durch Überschreiben von Holdings geändert werden. Erlaubte Wege: - Transaktion; - Initial Snapshot; - `manual_adjustment` mit Pflichtnotiz und Audit-Log. ### 3.3 Konsequenz für UI Eine Streamlit-Aktion wie „Holding ändern“ darf intern nicht einfach `crypto_holdings.quantity` überschreiben. Sie muss stattdessen eine geeignete Transaktion, einen Initial Snapshot oder eine manuelle Korrektur erzeugen. --- ## 4. Cash-Logik präzisiert ### 4.1 `cash_balances` `cash_balances` wird für zwei Zwecke genutzt: 1. Initialstände; 2. Kontroll-Snapshots. Nach Systemstart soll Cash primär aus Ledger-Transaktionen berechnet werden. ### 4.2 Initial Cash Snapshot `initial_cash_snapshot` ist die Startwahrheit für ein Konto/eine Währung zum definierten Startdatum. Danach gilt: - Cash-Einzahlung erhöht Cash; - Cash-Auszahlung reduziert Cash; - Kauf reduziert Cash; - Verkauf erhöht Cash; - Dividende/Ausschüttung erhöht Cash netto; - Gebühr/Steuer reduziert Cash; - FX-Wechsel reduziert Cash in einer Währung und erhöht Cash in einer anderen. ### 4.3 Manuelle Cash-Korrektur Manuelle Cash-Korrekturen sind erlaubt, aber nur mit: - `transaction_type='manual_correction'` oder spezifischem Cash-Korrekturtyp; - Pflichtnotiz; - Audit-Log; - Data-Quality-Hinweis, falls dadurch eine Abweichung zu berechneten Werten entsteht. --- ## 5. Kostenbasis-Methode ### 5.1 MVP-Entscheidung Für MVP 1 wird **Weighted Average Cost** als interne Performance-Methode verwendet. ### 5.2 Abgrenzung - Weighted Average Cost dient der MVP-Performance-Berechnung. - MVP 1 enthält keine vollständige steuerliche Tax-Lot-Logik. - FIFO, LIFO, spezifische Tax-Lots und steuerliche Optimierungen bleiben optionale spätere Erweiterungen. - Reports müssen klar kennzeichnen, dass MVP-Performance nicht automatisch eine Steuerabrechnung ist. --- ## 6. Runtime-Daten ausserhalb des Git-Repos ### 6.1 Verbindliche Sicherheitsregel Der produktive Runtime-Ordner liegt standardmässig ausserhalb des Git-Repositories. Git enthält nur: - Code; - Dokumentation; - synthetische Testdaten; - Beispielkonfigurationen. Nicht ins Repo: - echte SQLite-Datenbank; - echte CSVs; - echte Reports; - echte Exporte; - echte Portfolioauszüge; - API Keys; - Secrets; - OAuth-Dateien; - Screenshots oder Dokumente mit echten Finanzwerten. ### 6.2 Beispielstruktur ```text ~/repos/jarvis-finance-system/ # Git-Repo: Code, Docs, Tests, synthetische Beispiele ~/jarvis_runtime/finance-system/ # produktive Runtime-Daten ausserhalb Repo data/ imports/ exports/ reports/ backups/ secrets/ ``` ### 6.3 Git-Safety Vor jedem Commit muss ein Safety-Check verhindern, dass echte Daten oder Secrets ins Repo gelangen. --- ## 7. Streamlit-Entscheidung bestätigt Für MVP 1 ist die primäre Technologie: - Python; - SQLite; - Streamlit; - Pandas; - SQLAlchemy oder leichte Repository-Schicht; - Plotly; - pytest. ### 7.1 Spätere Zieloption FastAPI + React bleibt spätere Zielarchitektur, falls eines der folgenden Themen wichtiger wird: - bessere Mobile UX; - Multi-User-Betrieb; - Authentifizierung und Rollen; - professioneller Betrieb; - getrenntes Backend/API; - stärkeres Deployment- und Monitoring-Modell. MVP 1 wird dadurch nicht verkompliziert. Erst bauen wir ein korrektes Buch, dann ein hübsches Schaufenster. --- ## 8. Akzeptanz von v0.4.1 v0.4.1 ist akzeptiert, wenn folgende Regeln in v0.5 und der späteren Implementierung als verbindlich gelten: - Crypto mit Fiat-Auswirkung koppelt `transactions` und `crypto_transactions`. - Holdings/Snapshots sind nicht die operative Wahrheit. - Cash wird nach Systemstart aus Ledger-Transaktionen berechnet. - Weighted Average Cost ist MVP-Performance-Methode. - Keine vollständige Tax-Lot-Logik in MVP 1. - Runtime-Daten liegen standardmässig ausserhalb des Git-Repos. - Streamlit + SQLite + Python ist MVP-Stack. - FastAPI + React bleibt spätere Option.