# Portabilität: UNIVERSAL
# Version: 1.0.1
# Zuletzt validiert: 2026-02-08 (Help-Forensik: Export-Formate korrigiert)
# Nächste Prüfung: 2026-08-08

STEUER-HILFE
============

Steuer-Agent für Werbungskosten-Erfassung.

ÜBERSICHT
----------
Der Steuer-Agent hilft bei der systematischen Erfassung von
Werbungskosten für die Steuererklärung. Er unterstützt
mehrere Nutzerprofile und Steuerjahre.

ORDNERSTRUKTUR
--------------
user/steuer/
+-- profile/              Nutzerprofile
+-- watch/                Überwachte Ordner (Konfiguration)
+-- templates/            Vorlagen für neue Jahre
+-- [JAHR]/               Pro Steuerjahr
    +-- Werbungskosten/   Werbungskosten (Hauptkategorie)
    |   +-- belege/           Beleg-Ablage
    |   |   +-- _bundles/         Text-Bundles für Batch-Verarbeitung
    |   |   +-- _Fahrten&Homeoffice/ Fahrtenbuch, AZN, timeGoat
    |   |   +-- _Fehlbelege/      Zur User-Prüfung (Nicht-Belege)
    |   |   +-- _Papierkorb/      Bestaetigte Nicht-Belege
    |   |   +-- Weitere/          Eingangsordner für neue Belege
    |   |   +-- [Anbieter]/       Pro Anbieter (amazon.de, eBay, ...)
    |   +-- export/           Erzeugte Berichte und Exporte
    |   |   +-- csv/              CSV-Exporte
    |   |   +-- POSTEN_*.txt      Posten-Listen
    |   |   +-- WERBUNGSKOSTEN_alle.txt
    |   |   +-- BELEGE_alle.txt
    |   |   +-- FAHRTKOSTEN_HOMEOFFICE_YYYY.*
    |   |   +-- FINANZAMT_YYYY.zip
    |   +-- STEUER_README.txt
    |   +-- FINANZAMT.bat
    |   +-- SYNC.bat
    +-- Außergewöhnliche Belastungen/
    +-- Haushaltsnahe Dienstleistungen & Handwerker/
    +-- Sonderausgaben/
    +-- Versicherungen und Altersvorsorge/

CLI-BEFEHLE
-----------

STATUS & ÜBERSICHT:
  bach steuer status              Gesamtstatus anzeigen
  bach steuer status --jahr 2025  Status für ein Jahr

STEUERJAHR:
  bach steuer init 2026           Neues Steuerjahr anlegen
  bach steuer init 2026 --user X  Mit bestimmtem Profil

LISTEN:
  bach steuer list                Alle Listen zeigen
  bach steuer list --jahr 2025    Listen für Jahr
  bach steuer list --liste WERBUNGSKOSTEN
                                  Bestimmte Liste anzeigen

BELEG-VERWALTUNG (NEU)
----------------------
Belege sind die PDF-Dateien in belege/. Status: ERFASST, 
NICHT_ERFASST, DEPRECATED.

  bach steuer beleg list                    Alle Belege auflisten
  bach steuer beleg list --status ERFASST   Nach Status filtern
  bach steuer beleg list --status NICHT_ERFASST
  bach steuer beleg list --status DEPRECATED
  bach steuer beleg list --status ALL --limit 1000
                                            Alle mit hohem Limit

  bach steuer beleg scan                    Neue Belege finden
  bach steuer beleg scan --dry-run          Nur anzeigen

  bach steuer beleg deprecate 215 466 "Grund"
                                            Belege als ungueltig markieren
                                            (Nummern bleiben reserviert)

  bach steuer beleg sync                    TXT-Dateien aus DB regenerieren

POSTEN-VERWALTUNG (NEU)
-----------------------
Posten sind einzelne Positionen aus Belegen. Ein Beleg kann
mehrere Posten enthalten. PostenID = BelegNr-PostenNr (z.B. 151-1).

  bach steuer posten list                   Alle Posten anzeigen
  bach steuer posten list --liste W         Nach Liste filtern (W/G/V/Z)
  bach steuer posten list --belegnr 151     Nach Belegnummer filtern
  bach steuer posten list --steller NAME    Nach Rechnungssteller filtern
  bach steuer posten list --rechnungsnr NR  Nach Rechnungsnummer filtern
  bach steuer posten list --limit 100       Mit Limit

  bach steuer posten search BEGRIFF         Posten übergreifend suchen
                                            (sucht in Bezeichnung, Steller,
                                            Bemerkung, Rechnungsnr, PostenID)

  bach steuer posten show 151-1             Einzelnen Posten anzeigen

  bach steuer posten add --belegnr 151 --bezeichnung "Produkt" --brutto 34.95 --liste W
                                            Neuen Posten erstellen
    Parameter:
    --belegnr NR       Belegnummer (erforderlich)
    --bezeichnung TXT  Produktbezeichnung (erforderlich)
    --brutto WERT      Bruttobetrag (erforderlich)
    --liste W|G|V|Z    Zielliste (default: Z)
    --anteil 0.0-1.0   Anteil bei Gemischt (default: 0.5)
    --bemerkung TXT    Optionale Bemerkung
    --datum YYYY-MM-DD Datum
    --anbieter NAME    Anbieter
    --rechnungsnr NR   Rechnungsnummer (oder --rechnr)

  bach steuer posten edit 151-1 --bezeichnung "Neuer Name"
                                            Posten bearbeiten
  bach steuer posten edit 151-1 --brutto 29.95
  bach steuer posten edit 151-1 --anteil 0.7
  bach steuer posten edit 151-1 --rechnungsnr "RE-12345"

  bach steuer posten move 151-1 W           In Liste verschieben
  bach steuer posten move 151-1 G --anteil 0.5
                                            Mit Anteil für Gemischte
    Listen-Kuerzel:
    W = WERBUNGSKOSTEN (100% absetzbar)
    G = GEMISCHTE (anteilig absetzbar)
    V = VERWORFEN (nicht absetzbar)
    Z = ZURÜCKGESTELLT (noch zu klaeren)

  bach steuer posten delete 151-1           Löschen (mit Bestaetigung)
  bach steuer posten delete 151-1 --force   Ohne Bestaetigung

BATCH-IMPORT (NEU v1.1.4)
-------------------------
Für schnelle Erfassung mehrerer Posten oder Belege.

  bach steuer batch help                    Batch-Hilfe anzeigen

  bach steuer batch posten --belegnr 42 --json '[...]'
                                            Mehrere Posten für einen Beleg
    JSON-Format:
    [{"bez":"Artikel","brutto":19.99,"liste":"W"},
     {"bez":"Privat","brutto":5.00,"liste":"V","bem":"privat"}]

  bach steuer batch posten --belegnr 42 --file posten.json
                                            Posten aus JSON-Datei

  bach steuer batch belege --inline "42:Artikel:19.99:W;43:Ware:5.00:V"
                                            Schnell-Erfassung mehrerer Belege
                                            Format: BELEGNR:BEZ:BRUTTO:LISTE

  bach steuer batch belege --file import.json
                                            Mehrere Belege mit Posten
    JSON-Format:
    {"belege":[
      {"belegnr":42,"posten":[{"bez":"X","brutto":10,"liste":"W"}]},
      {"belegnr":43,"posten":[{"bez":"Y","brutto":5,"liste":"V"}]}
    ]}

  bach steuer batch delete --belegnr 42 --force
                                            Alle Posten eines Belegs löschen

  bach steuer batch delete --posten "42-1,42-2,43-1" --force
                                            Bestimmte Posten löschen

  bach steuer batch delete --liste V --limit 100 --force
                                            Alle VERWORFEN löschen (max 100)
                                            VORSICHT: Kann viele Posten löschen!

  bach steuer batch move --posten "42-1,42-2" --liste W
                                            Bestimmte Posten verschieben

  bach steuer batch move --belegnr 42 --liste W
                                            Alle Posten eines Belegs verschieben

  bach steuer batch move --von V --nach W --limit 50
                                            Zwischen Listen verschieben

STEUER-TOOLS (NEU v1.1.4)
-------------------------
Eigenständige Python-Scripts in tools/steuer/.

  bach steuer tools list                    Alle Tools auflisten
  bach steuer tools <name> [args]           Tool ausführen (Kurzform)
  bach steuer tools run <name> [args]       Tool ausführen (explizit)
  bach steuer tools register                Tools in bach.db registrieren

Wichtige Tools:
  beleg_vorfilter   Neue Belege vorsortieren (NEU)
  make_bundle       Text-Bundles aus Belegen erstellen
  beleg_parser      Text aus PDFs extrahieren (mit OCR)
  regenerate_txt    Listen-TXTs aus DB regenerieren
  scan_new_belege   Neue Belege finden und registrieren
  temu_ocr_batch    Batch-OCR für Bild-PDFs

Direktaufruf:
  bach steuer tools make_bundle amazon 11 67
  bach steuer tools regenerate_txt

PROFILE:
  bach steuer profile list        Profile auflisten
  bach steuer profile show <name>  Profil anzeigen
  bach steuer profile create max  Neues Profil erstellen

WATCH-ORDNER:
  bach steuer watch list          Watch-Ordner anzeigen
  bach steuer watch add PFAD      Ordner hinzufügen
  bach steuer watch remove PFAD   Ordner entfernen
  bach steuer scan                Watch-Ordner prüfen

EXPORT:
  bach steuer export              Export (Standard: txt)
  bach steuer export --jahr 2025 --format csv
  bach steuer export --format datev         DATEV Buchungsstapel CSV
                                            (für Steuerberater)
  bach steuer export --format csv           Einfaches CSV (Excel-kompatibel)
  bach steuer export --format vorsorge      Anlage Vorsorgeaufwand
                                            (Versicherungsbeitraege)

VOLLSTAENDIGKEITSPRÜFUNG:
  bach steuer check                         Prüfung durchführen
  bach steuer check --jahr 2025             Für bestimmtes Jahr
                                            Prüft: Belege ohne Posten,
                                            Posten ohne Beleg, Luecken in
                                            Belegnummern, fehlende Monate,
                                            Posten ohne MwSt-Betrag

EIGENBELEG-ERSTELLUNG:
  bach steuer eigenbeleg --bezeichnung "Parkgebuehr" --brutto 5.00
                                            Eigenbeleg erstellen
  bach steuer eigenbeleg --bezeichnung "..." --brutto 10.00 --mwst 7
                                            Mit abweichendem MwSt-Satz
  Optionen: --liste, --datum, --mwst, --grund

BANK-IMPORT:
  bach steuer import camt <pfad>            CAMT.053 XML importieren

FINANZAMT-EXPORT (geplant):
  bach steuer finanzamt           ZIP mit allen Werbungskosten erstellen
                                  Erzeugt FINANZAMT_[JAHR].zip mit:
                                  - WERBUNGSKOSTEN_alle.txt (Übersicht)
                                  - csv/ Ordner mit CSV-Dateien
                                  - Alle referenzierten Belege (PDFs)

  Direkt via Script:
    python tools/steuer/steuer_sync.py finanzamt

CSV-EXPORT (NEU v1.3.1):
  bach steuer export --format csv CSV-Dateien in csv/ Ordner exportieren
                                  Für Excel/Steuersoftware-Import

  Format: Semikolon-getrennt, UTF-8 mit BOM, deutsches Zahlenformat

  CSV-Dateien werden NICHT automatisch bei sync geschrieben,
  nur bei: finanzamt (automatisch) oder export --format csv (explizit)

  Direkt via Script:
    python tools/steuer/steuer_sync.py csv

PROFILE
-------
Profile speichern nutzerspezifische Einstellungen:
- Beruflicher Kontext (Branche, Tätigkeit)
- Anbieter-Regeln (TEMU, Amazon, ...)
- Automatische Zuordnungen (Keywords)
- Standard-Anteile für gemischte Nutzung

Profil anlegen:
1. bach steuer profile create MEINNAME
2. Datei bearbeiten in user/steuer/profile/

LISTEN-TYPEN (ab V1.3.0)
------------------------
Neue Dateinamen in WERBUNGSKOSTEN/ Ordner:

  Code  Datei                    Beschreibung
  ----  -----------------------  ---------------------------
  W     POSTEN_reine.txt         100% absetzbar
  G     POSTEN_gemischt.txt      Anteilig absetzbar (mit Anteil)
  V     POSTEN_verworfen.txt     Nicht absetzbar (privat)
  Z     POSTEN_unsortiert.txt    Später bearbeiten / unklar
  -     WERBUNGSKOSTEN_alle.txt  W + G kombiniert (für Finanzamt)

BELEG-STATUS
------------
ERFASST             Beleg wurde bearbeitet, Posten erstellt
NICHT_ERFASST       Beleg noch nicht bearbeitet
DEPRECATED          Beleg als ungueltig markiert (z.B. Duplikat)

BELEG-VORFILTER (NEU)
---------------------
Automatische Vorsortierung neuer Belege in Anbieter-Ordner.

  python tools/steuer/beleg_vorfilter.py [--dry-run] [--verbose]

Workflow:
1. Neue PDFs aus Email/Downloads in belege/Weitere/ legen
2. Vorfilter ausführen:
   python tools/steuer/beleg_vorfilter.py --dry-run   # Vorschau
   python tools/steuer/beleg_vorfilter.py             # Ausführen
3. Ergebnis:
   - Belege werden automatisch in Anbieter-Ordner sortiert
   - Nicht-Belege (Tracking, Versandstatus) -> _Fehlbelege/
4. User prüft _Fehlbelege/ -> echte Fehlbelege nach _Papierkorb/

Erkennungsmethoden:
- Dateiname-Muster: RG64116 -> LingoPlay, 32xxxxxx -> TimeTEX
- PDF-Inhalt: "Anthropic, PBC" -> Anthropic, "TimeTEX" -> TimeTEX
- Fehlbeleg-Marker: "Sendungsverfolgung", "Tracking" -> _Fehlbelege

Unterstützte Anbieter:
  Anthropic, TimeTEX, LingoPlay, Autismusverlag, PayPal,
  eBay, Temu, Amazon, Apple, Google

BIDI-SYNC (BIDIREKTIONALER TXT-SYNC)
-------------------------------------
Erweiterte Aktionen direkt in TXT-Dateien schreiben.
Der Sync parst diese und führt sie in der DB aus.

AKTIONS-TYPEN:
  MOVE (Verschieben):
    42-3 -> W              In Werbungskosten verschieben
    42-3 -> G 0.5          In Gemischte mit 50% Anteil
    42-3 -> V privat       In Verworfen mit Bemerkung
    B42 -> W               Alle Posten eines Belegs verschieben

  EDIT (Bearbeiten):
    42-3 :: brutto=19.99   Bruttobetrag ändern
    42-3 :: bezeichnung=Neuer Name
    42-3 :: anteil=0.7     Anteil ändern

  DELETE (Löschen):
    42-3 DELETE            Einzelnen Posten löschen
    42-3 DEL               Kurzform

  DEPRECATED (Beleg ausbuchen):
    B42 DEPRECATED         Beleg als ungueltig markieren
    B42 DEPRECATED Duplikat  Mit Begründung

EINGABE-BEREICH:
  Aktionen in TXT-Dateien im Bereich "EINGABEN" schreiben:

  === EINGABEN (werden bei Sync verarbeitet) ===
  42-3 -> W
  43-1 :: brutto=25.50
  B44 DEPRECATED Storniert
  === ENDE EINGABEN ===

SYNC AUSFÜHREN:
  python tools/steuer/steuer_sync.py sync
  oder: bach steuer beleg sync

HINWEISE:
  - Aktionen werden bei Sync verarbeitet und dann entfernt
  - Fehlerhafte Aktionen werden im Error-Log gemeldet
  - Immer erst --dry-run testen (falls verfügbar)

TYPISCHER WORKFLOW
------------------
0. Neue Belege vorsortieren (beleg_vorfilter.py)

1. Status prüfen:
   bach steuer beleg list --status NICHT_ERFASST

2. Offene Belege nach Anbieter sehen:
   bach steuer beleg list --status NICHT_ERFASST --limit 500

3. Im Chat-Agent Belege erfassen

4. Ergebnis prüfen:
   bach steuer posten list --liste W

BATCH-VERARBEITUNG MIT BUNDLES
------------------------------
Bei vielen Belegen ist Einzelprüfung ineffizient. Stattdessen:

1. Bundle erstellen:
   python agents/_experts/steuer/make_bundle.py <quelle> <start> <ende>

   Beispiele:
     python agents/_experts/steuer/make_bundle.py paypal 171 214
     python agents/_experts/steuer/make_bundle.py ebay 77 128
     python agents/_experts/steuer/make_bundle.py google_play 129 170
   
   Quellen: paypal, ebay, google_play, amazon, weitere, temu
   Ausgabe: user/steuer/2025/bundles/<quelle>_B<start>-B<ende>.txt

2. Bundle analysieren:
   Claude liest das Bundle und klassifiziert alle Belege in:
   - W = Werbungskosten (100% absetzbar)
   - G = Gemischt (anteilig, z.B. 50%)
   - V = Verworfen (privat, Duplikate, Status-Mails)
   - Z = Zurückgestellt (noch zu klaeren)

3. Posten batch-erfassen:
   bach steuer posten add --belegnr 195 --bezeichnung "..." --brutto 55.85 --liste W ...

4. TXT-Dateien aktualisieren:
   python agents/_experts/steuer/regenerate_txt.py

HINWEISE ZUR KLASSIFIZIERUNG
----------------------------
- PayPal: Temu-Zahlungen sind Duplikate (Originale im Temu-Ordner)
- eBay: Viele Mails pro Kauf (Bestellung, Versand, Zustellung, Rechnung)
        -> Nur die Rechnung/Bestellbestaetigung als Hauptbeleg erfassen
        -> Status-Mails als V mit 0 EUR erfassen (Vollständigkeit)
- Therapie-Material: LEGO, Lernspiele, Fachliteratur = W
- Software: Microsoft 365, Office = G mit 50%
- Streaming: Netflix, Disney+ = V (privat)

DATENBANK
---------
Alle Daten in: data/bach.db

Tabellen:
- steuer_dokumente     Alle Belege mit Status
- steuer_posten        Alle Posten mit Zuordnung

Profile werden als TXT-Dateien in user/steuer/profile/ gespeichert.

CHAT-AGENT
----------
Der Steuer-Agent ist als Chat-Agent unter
agents/steuer-agent.txt verfügbar.

Er kann:
- Belege aus PDFs erfassen
- Posten automatisch kategorisieren
- Duplikate erkennen
- Mit dem Nutzer validieren
- Finanzamt-ZIP mit allen Belegen erstellen

BEREICHS-READMES (Stichwort-Nachschlagewerke)
---------------------------------------------
Jeder Steuer-Bereich hat eine README.txt mit Stichworttabelle,
benötigten Belegen und aktuellen Pauschbetraegen (Stand 2025).

  Datei                                              Bereich / Paragraph
  ------------------------------------------------   --------------------------
  user/steuer/[JAHR]/STEUER_README.txt               Gesamtverfahren & Sync
  user/steuer/[JAHR]/Werbungskosten/README.txt       Anlage N (Paragraph 9)
  user/steuer/[JAHR]/Außergewöhnliche Belastungen/   Paragraph 33 EStG
    README.txt
  user/steuer/[JAHR]/Haushaltsnahe Dienstleistungen  Paragraph 35a EStG
    & Handwerker/README.txt
  user/steuer/[JAHR]/Sonderausgaben/README.txt       Paragraph 10 EStG
  user/steuer/[JAHR]/Versicherungen und              Anlage Vorsorgeaufwand
    Altersvorsorge/README.txt

Inhalt der READMEs:
  - Definition des Bereichs mit Rechtsgrundlage
  - Stichworttabelle: Was kann eingereicht werden + benötigte Belege
  - Wichtige Pauschbetraege und Höchstgrenzen
  - Praxis-Hinweise

SIEHE AUCH
----------
  bach --help tasks                    Allgemeine Aufgaben
  bach --help backup                   Backup-System
  wiki/steuer/_index.txt          Steuer-Wiki (Hintergrundwissen)
  wiki/steuer/est_bereiche.txt    EStG-Anlagen Übersicht
  wiki/steuer/versicherungen.txt  Absetzbare Versicherungen
  wiki/steuer/sonderausgaben.txt  Sonderausgaben absetzen
  wiki/steuer/fortbildung.txt     Fortbildung und Studium
  wiki/steuer/fahrtkosten_homeoffice.txt  Fahrtkosten & Homeoffice
  agents/steuer-agent.txt      Steuer-Agent (Chat-Agent)
