# Portabilität: UNIVERSAL
# Version: 1.1.0
# Zuletzt validiert: 2026-02-08 (Help-Forensik - Daemon-Integration)
# Nächste Prüfung: 2026-08-07

BACH INBOX-SYSTEM
=================

Automatisierte Dokumenten-Sortierung mit Watchdog-Überwachung.

KONZEPT
-------

Das Inbox-System überwacht Eingangsordner (Downloads, Scans) und
sortiert Dateien automatisch nach Regeln in Zielordner.

KONFIGURATION
-------------

Zwei Dateien steuern das System:

  data/inbox_folders.txt     Watch-Ordner (Quellen)
  data/inbox_config.json     Sortier-Regeln

INBOX_FOLDERS.TXT FORMAT
------------------------

  # Format: PFAD | MODUS | FILTER | ZIEL
  C:\Users\User\Downloads | auto | pdf | inbox
  C:\Users\User\Scans | manual | pdf,jpg | inbox

  MODUS: auto (automatisch sortieren) oder manual (nur sammeln)
  FILTER: Dateiendungen (kommasepariert) oder * für alle
  ZIEL: inbox (Transfer-Zone) oder relativer BACH-Pfad

INBOX_CONFIG.JSON
-----------------

  settings:
    enabled: true/false
    interval_seconds: 60
    transfer_zone: user/inbox/unsortiert
    ocr_enabled: false
    auto_task_on_unknown: true

  rules:
    - id: steuer_rechnung
      pattern: rechnung|invoice|beleg
      pattern_type: filename|content|ocr
      target: user/steuer/{year}/belege/Weitere
      priority: 1

ORDNER
------

  user/inbox/           Transfer-Zone (Eingang)
  user/inbox/unsortiert Nicht zuordenbare Dateien

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

  bach inbox status      Status anzeigen
  bach inbox start       Inbox-Watcher starten (Hintergrund)
  bach inbox stop        Inbox-Watcher stoppen
  bach inbox scan        Einmaliger Dry-Run Scan
  bach inbox config      Konfiguration anzeigen

DAEMON-INTEGRATION
------------------

Das Inbox-System ist als Daemon-Job integriert:

  Job-ID: 3 (inbox-scan)
  Typ:    interval
  Zyklus: 30 Minuten (standardmäßig OFF)
  Modus:  --process (einmaliger Scan pro Durchlauf)

Befehle:
  bach daemon jobs               Alle Jobs auflisten
  bach daemon run 3              Inbox-Scan manuell starten
  bach daemon toggle 3           Job aktivieren/deaktivieren
  bach daemon reschedule 3 15m   Intervall ändern (z.B. 15 Minuten)

WICHTIG: Der Daemon-Job ruft `inbox_watcher.py --process` auf, NICHT
         den dauerhaften Watchdog-Modus. Für Echtzeit-Überwachung:
         `bach inbox start` (startet watchdog direkt)

GUI
---

  /inbox                 Inbox-Dashboard
  /inbox/rules           Regeln verwalten (Task #443)

  API-Endpunkte:
    POST /api/inbox/scan     Scan manuell triggern (GUI + index.html)

WORKFLOW
--------

ZWEI MODI:

A. WATCHDOG-MODUS (bach inbox start):
   - Echtzeit-Überwachung mit watchdog-Library
   - Reagiert sofort auf neue Dateien
   - Läuft dauerhaft im Hintergrund

B. DAEMON-MODUS (bach daemon run 3):
   - Periodischer Scan alle 30 Minuten (konfigurierbar)
   - Ruft `inbox_watcher.py --process` auf
   - Integriert in Daemon-System

Verarbeitungsablauf (beide Modi):
1. Datei erscheint in Watch-Ordner (z.B. Downloads)
2. Scanner wartet bis Datei stabil (keine Schreibzugriffe)
3. Datei wird nach Transfer-Zone verschoben
4. Regel-Engine prüft Muster (Dateiname, Inhalt, OCR)
5. Treffer: Datei wird in Zielordner verschoben
6. Kein Treffer: Bleibt in unsortiert, Task wird erstellt

CONNECTOR-INTEGRATION
---------------------

Ab v1.1.0 werden Connector-Nachrichten (E-Mails, Slack, etc.) automatisch
in die messages-Inbox geroutet. Siehe:

  system/hub/_services/connector/queue_processor.py
  bach --help messages
  bach --help connector

KONZEPT-DOKUMENTE
-----------------

  docs/CONCEPT_INBOX_SCANNER.md         Architektur (aktiv)
  docs/_archive/CONCEPT_inbox_*.md      Format-Specs (archiviert)

IMPLEMENTATION
--------------

  system/tools/inbox_watcher.py         Hauptscript (watchdog + --process)
  system/hub/inbox.py                   CLI-Handler
  system/gui/server.py                  GUI-API (POST /api/inbox/scan)
  system/hub/_services/document/scanner_service.py  Dokumenten-Scanner

SIEHE AUCH
----------

  bach --help dirscan       Dokumenten-Scanner
  bach --help daemon        Hintergrund-Dienste
  bach --help steuer        Steuer-Integration
  bach --help messages      Nachrichten-System
  bach --help connector     Connector-System

VERSION: 1.1.0 (2026-02-08)
