# KONZEPT: File-Transfer Service & Handler-Architektur

Stand: 2026-01-24
Status: ENTWURF - Zur Pruefung

---

## Grundidee

BACH verwendet ein Zwei-Ebenen-System:

1. **Handler** = Features/Use-Cases (WAS will ich tun?)
2. **Services** = Wiederverwendbare Komponenten (WIE wird es technisch umgesetzt?)

---

## Architektur-Uebersicht

```
┌─────────────────────────────────────────────────────────────────┐
│  HANDLER-EBENE (Features/Use-Cases)                             │
│                                                                 │
│  ┌──────────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │ Dokumenten-      │  │ Steuer-Agent │  │ Backup-System    │  │
│  │ Scanner          │  │ (beleg scan) │  │ (file export)    │  │
│  │ bach inbox ...   │  │ bach steuer  │  │ bach backup      │  │
│  └────────┬─────────┘  └──────┬───────┘  └────────┬─────────┘  │
│           │                   │                   │             │
│           └───────────────────┼───────────────────┘             │
│                               ▼                                 │
│                     [ NUTZEN SERVICES ]                         │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│  SERVICE-EBENE (Wiederverwendbare Komponenten)                  │
│                                                                 │
│  skills/_services/file_transfer/                                │
│  ├── folder_watch.py      # Ordner ueberwachen (watchdog)       │
│  ├── folder_scan.py       # Einmaliger Ordner-Scan              │
│  ├── folder_import.py     # Ordner-Inhalte importieren          │
│  ├── folder_export.py     # Ordner-Inhalte exportieren          │
│  ├── file_import.py       # Einzelne Datei importieren          │
│  ├── file_export.py       # Einzelne Datei exportieren          │
│  ├── file_search.py       # Dateien suchen                      │
│  └── file_routing.py      # Routing-Engine (Verteilung)         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## Beispiel: Dokumenten-Scanner

Der Dokumenten-Scanner ist ein **Handler**, der mehrere **Services** kombiniert:

```
Dokumenten-Scanner (Handler)
│
├── Nutzt: folder_watch.py     # Ueberwacht Downloads/Scanner-Ordner
├── Nutzt: file_import.py      # Importiert neue Dateien
├── Nutzt: file_routing.py     # Verteilt nach Regeln
│
├── Eigene Config:
│   ├── inbox_folders.txt      # Manuell gepflegte Ordnerliste
│   └── routing_rules.json     # Sortier-Regeln
│
└── CLI: bach inbox scan/watch/status/add-folder/rules
```

**Ablauf:**
```
[Downloads]  [Scanner-Ordner]  [Andere ueberwachte Ordner]
      │              │                    │
      └──────────────┼────────────────────┘
                     ▼
         ┌─────────────────────┐
         │ folder_watch.py     │  (Service)
         │ - Erkennt neue      │
         │   Dateien           │
         └──────────┬──────────┘
                    ▼
         ┌─────────────────────┐
         │ file_routing.py     │  (Service)
         │ - Pattern-Matching  │
         │ - Anbieter-Erkennung│
         │ - Duplikat-Check    │
         └──────────┬──────────┘
                    ▼
    ┌───────┬───────┼───────┬───────┐
    ▼       ▼       ▼       ▼       ▼
 Steuer  Gesund-  Versich. Unsort. Review
 BELEGE/ heit/    erungen/ inbox/  Queue
```

---

## Trennung der Verantwortlichkeiten

| Komponente | Verantwortung |
|------------|---------------|
| **Dokumenten-Scanner** | Routing & Verteilung (WO kommt es hin?) |
| **Steuer-Agent** | Fachliche Verarbeitung (WAS mache ich damit?) |
| **file_transfer Service** | Technische Datei-Operationen (WIE bewege ich Dateien?) |

Der Steuer-Agent muss sich nicht um Datei-Erkennung kuemmern - er bekommt
bereits vorsortierte Belege in seinen BELEGE/ Ordner und verarbeitet diese
dann fachlich (B-Nummer, Posten, Export).

---

## Geplante Service-Komponenten

### file_transfer Service

```
skills/_services/file_transfer/
├── README.md
├── config.json
├── file_transfer.py           # Hauptmodul (Fassade)
│
├── components/
│   ├── file_import.py         # Dateien importieren (einzeln)
│   ├── file_export.py         # Dateien exportieren
│   ├── file_search.py         # Dateien suchen
│   ├── file_routing.py        # Routing-Logik (Verteilung)
│   │
│   ├── folder_scan.py         # Ordner einmalig scannen
│   ├── folder_watch.py        # Ordner ueberwachen (watchdog)
│   ├── folder_import.py       # Ordner-Inhalte importieren
│   └── folder_export.py       # Ordner-Inhalte exportieren
│
└── rules/
    └── routing_rules.json     # Verteilungs-Regeln (zentral)
```

---

## Routing-Regeln Schema

```json
{
  "version": "1.0",
  "rules": [
    {
      "name": "steuer-belege",
      "pattern": "rechnung|invoice|quittung|beleg",
      "target_agent": "steuer",
      "target_path": "user/steuer/{year}/BELEGE/",
      "priority": 1
    },
    {
      "name": "gesundheit",
      "pattern": "arzt|krankenhaus|rezept|befund",
      "target_agent": "gesundheit",
      "target_path": "user/gesundheit/",
      "priority": 2
    },
    {
      "name": "versicherungen",
      "pattern": "versicherung|police|schaden",
      "target_agent": "versicherungen",
      "target_path": "user/versicherungen/",
      "priority": 3
    }
  ],
  "fallback": {
    "target_path": "user/inbox/unsortiert/",
    "create_task": true,
    "task_title": "Unbekanntes Dokument klassifizieren: {filename}"
  }
}
```

---

## Offene Fragen

1. Soll `routing_rules.json` zentral im Service liegen oder pro Handler?
2. Namensgebung der CLI-Befehle: `bach inbox` oder `bach scanner`?
3. Wie interagiert das mit dem bestehenden Steuer-Agent `bach steuer scan`?

---

## Naechste Schritte

Wenn dieses Konzept passt:
1. Service-Grundstruktur unter `skills/_services/file_transfer/` anlegen
2. ROADMAP Phase 10 entsprechend erweitern (INBOX + FT Tasks)
3. Handler `hub/inbox.py` erstellen

---

*Erstellt durch Claude Session 2026-01-24*
*Migriert aus user/KONZEPT_file_transfer_service.md*
