# Smart Watch Recorder — Projektplan

## Überblick

Medizinisches Diktiersystem für Ärzte. Aufnahmen werden per Pixel Watch (primäres Erfassungsgerät) oder weiteren Clients (Android-Handy, künftig optional Linux-/Windows-Desktop, iOS) erstellt, automatisch transkribiert, durch ein LLM aufbereitet und über ein schlichtes Webinterface abgerufen. Alle Clients — einschließlich Browser, Watch und jedes native App — sprechen dieselbe Server-HTTP-Schnittstelle; ihre Rolle ergibt sich allein daraus, *welchen Teil* der API sie nutzen. Das System unterstützt mehrere Ärzte mit vollständig getrennten Daten.

**Datenphilosophie:** Das System ist kein Langzeitspeicher. Daten sollen so schnell wie möglich durch die Pipeline fließen und nach Übernahme ins Praxissystem vom Arzt zum Entfernen markiert werden. Je weniger Daten in der Pipeline verbleiben, desto besser. Die Watch löscht Aufnahmen erst nach Server-Bestätigung — so gehen keine Daten verloren, solange die Watch funktioniert. Serverseitig besteht bewusst kein Backup-Konzept — bei Datenverlust auf dem Server vor Übernahme ins Praxissystem gehen Daten verloren. Dieses Risiko wird den Nutzern kommuniziert.

**Timestamps:** Alle Zeitstempel im gesamten System (Dateinamen, API-Kommunikation, Logs) sind **UTC**. Die Anzeige in der lokalen Zeitzone erfolgt ausschließlich in der UI-Schicht (Watch-App, Webinterface). "Heute" wird systemweit als aktueller UTC-Tag definiert.

---

## Architektur

```
Clients (alle sprechen dieselbe HTTPS-API)
  ┌────────────────────────────────────────────────────────────┐
  │ Pixel Watch (Wear OS) — primär: Aufnahme + Oneliner-Polling│
  │ Android-Handy (geplant) — Aufnahme + optional Review       │
  │ Browser — Review, Admin, Audio-Streaming                   │
  │ Linux / Windows / iOS (optional, später) — dieselbe Rolle  │
  └────────────────────────────────────────────────────────────┘
                │
                │  HTTPS (einheitliche Server-API, keine
                │  geräte-spezifischen Endpoints)
                │  Watch ohne eigene Connectivity:
                │  transparent via Wear OS Proxy über Phone
                ↓
Unraid Server
    └── nginx (reverse proxy, TLS)
            ↓ lokales Netz
Ubuntu Server (RTX 3060, 12 GB VRAM)
    ├── Docker: Axum (Webserver, API, Worker)
    │     Empfang → Transkriptions-Queue (mpsc, sequentiell)
    │                             + separater Analyse-Worker
    │           ↓ HTTP (localhost)
    ├── Docker: faster-whisper (STT, CTranslate2, large-v3)
    ├── Ollama (Gemma 3 4B, Oneliner)
    │         ↓ HTTPS
    └── externer LLM-Provider (Ionos als Default, OpenAI-API-kompatibel, austauschbar)
```

---

## Design-Prinzipien

### Filesystem ist Source of Truth (SoT)

Der Zustand eines Falls wird **ausschließlich aus dem Dateisystem** abgeleitet, nicht aus einer parallelen Sidecar- oder Metadaten-Datei. Das Vorhandensein bestimmter Dateimarker (`.m4a`, `.m4a.failed`, `.transcript.txt`, `oneliner.txt`, `analysis_input.json`, `document.md`, `.deleted`) plus die `WorkerBusy`-Flags bestimmen jederzeit eindeutig, was als Nächstes zu tun ist.

**Konsequenzen**:
- Keine State-Duplizierung (kein `state.json`, keine DB). Der zu synchronisierende Zweitstand fehlt ersatzlos — also kann er auch nicht drift.
- Recovery-Scan nach Restart ist trivial: finde `.m4a` ohne `.transcript.txt` → transkribieren. Natürliche Idempotenz, kein Crash-Recovery-Protokoll.
- Crash mitten in Whisper = `.transcript.txt` fehlt = nächster Lauf macht's nochmal. Keine Intermediate-States, die rückwärts abgewickelt werden müssten.
- Manuelle Reparatur möglich: Datei löschen, neu triggern. Kein „state irgendwie auf Received setzen".

**Bewusst verzichtet** auf: retry-Budget, Failed-Kategorie mit Error-Details. Wenn ein Audio dauerhaft an Whisper scheitert, loggt der Server im Crash-Loop — das fällt sofort auf und wird manuell entfernt. Diese Kategorie wird erst eingeführt, wenn ein realer Bedarf entsteht (z.B. hochvolumiger Betrieb).

### Client-Prinzip

Clients sind flüchtige Zugriffs- und Erfassungsstellen. Der Server ist die einzige autoritative Datenquelle; jeder Client nutzt dieselbe HTTP-API, aber nur so viel davon, wie für seine Form und sein Use-Case sinnvoll ist.

- **Pixel Watch (primär):** minimaler API-Ausschnitt — Upload + Oneliner-Polling. Kein Playback, kein Review, kein lokaler Archivspeicher.
- **Android-Handy (geplant):** identische Erfassung wie die Watch; darf zusätzlich Review-Endpoints (`/web/...`) nutzen, weil Display und Eingabe das sinnvoll machen.
- **Browser:** klassisches Review-Frontend via `/web/...` + Audio-Streaming.
- **Linux / Windows / iOS (optional, später):** gleiche Invariante, beliebiger Funktionsumfang — Tech-Stack pro Plattform offen (z.B. Compose Multiplatform, Tauri, nativ).

#### Invariante (fixiert)

> **Alle Clients sprechen ausschließlich die einheitliche Server-HTTP-Schnittstelle.** Es gibt keine gerätespezifische API und keinen geräteeigenen Backchannel. Die Rolle eines Clients ergibt sich allein daraus, *welchen Teil* der API er nutzt.
>
> **Lokale Datenhaltung ist strikt flüchtig:** Kein Client hält mehr Daten lokal, als für den aktuellen Upload- oder Render-Vorgang nötig. Alle dauerhaften Daten leben auf dem Server.

**Lackmustest für neue Features:** *„Zwingt das Feature einen Client, Daten länger lokal zu halten als für den aktuellen Upload- oder Render-Vorgang nötig?"* Wenn ja, gehört das Feature ins Web-UI / auf den Server, nicht in den Client.

**Konsequenzen:**
- Server-Code bleibt client-agnostisch: ein neuer Client-Typ erfordert keinen neuen Endpoint.
- Clients sind austauschbar und können unterschiedlich mächtig sein (Watch = 2 Endpoints, Browser ≈ 15, Handy dazwischen).
- Review-Funktionen sind automatisch überall konsistent — ein nativer Client kann die Web-UI als WebView einbetten und ist damit sofort synchron mit dem Browser.

---

## Komponenten

### 1. Clients (Erfassung + Review)

Alle Clients folgen dem [Client-Prinzip](#client-prinzip): einheitliche Server-API, flüchtige lokale Datenhaltung, Rolle ergibt sich aus genutztem API-Teil.

**Entwicklungs-Reihenfolge:**
1. **Pixel Watch (primäres Entwicklungsziel, MVP-relevant)** — siehe unten.
2. **Android-Handy** — geplant direkt nach der Watch, teilt Core-Module.
3. **Linux / Windows / iOS** — optional, frühestens nach Handy-Abschluss; Tech-Stack pro Plattform zu entscheiden.

**Gemeinsame Code-Basis (Android-Clients):**

Die Watch-App und die spätere Handy-App werden als **Multi-Modul-Gradle-Projekt** aufgesetzt, sodass UI-unabhängige Business-Logik von Anfang an in geteilten Modulen liegt. Diese Struktur ist **nicht optional** — sie wird bereits beim Bau der Watch-App eingehalten, damit die Handy-App später ohne Refactoring andocken kann.

```
doctate-android/
├── :core-domain    ← case_id, Modelle, State-Machine (reines Kotlin/JVM)
├── :core-audio     ← MediaRecorder-Wrapper, Bluetooth-Headset-Routing
├── :core-sync      ← Queue, WorkManager-Jobs, Retry-Logik
├── :core-http      ← API-Client, API-Key-Auth, Endpoints
├── :core-storage   ← Marker-Dateien, Room/DataStore, Lazy Cleanup
│
├── :app-wear       ← Watch-UI (Compose for Wear OS)
└── :app-mobile     ← Handy-UI (Compose Material 3) — später
```

UI-unabhängige Tests laufen auf der JVM (keine Emulator-Runtime). Importe von `android.*`/`androidx.compose.*` sind in `:core-*` strukturell verboten — Verstöße schlagen beim Kompilieren fehl.

#### 1a. Pixel Watch App (Wear OS / Kotlin) — primäres Entwicklungsziel

**Funktion:**
- Audioaufnahme direkt auf der Watch (MediaRecorder, AAC/m4a)
- Optionale Aufnahme über gekoppeltes Bluetooth-Headset (automatisch bevorzugt)
- case_id (UUIDv4) Generierung lokal auf der Watch: "Neu" erzeugt eine neue case_id + Marker-Datei (`/recordings/cases/{case_id}.json`), "Fortsetzen" verwendet die bestehende case_id des gewählten Falls
- Ein Fall = 1–n Aufnahmen, identifiziert durch case_id + Aufnahme-Zeitstempel
- Aufnahmen persistent ins lokale Dateisystem (überlebt Neustarts, Akku leer)
- Nach Aufnahme: Stop → direkt in Sync-Queue, Korrekturen per Folge-Diktat
- Vollautomatischer Sync im Hintergrund (Foreground Service)
- Kein Review, kein Playback, kein Archiv — konsequent nach Client-Prinzip
- Kein eigener Code auf dem Phone nötig (Wear OS Network Proxy tunnelt transparent, wenn Watch keine eigene Connectivity hat)

**Sync-Service (Foreground Service):**
- Läuft permanent im Hintergrund, überlebt Doze-Modus
- Bei Netzwerk-Verfügbarkeit: alle ungesyncten Aufnahmen hochladen
- Upload → Server-Bestätigung abwarten → bei "received" oder "gone": lokal löschen
- Bei Fehler / kein ACK: exponentieller Backoff, automatischer Retry
- Bei Watch-Neustart: Service startet automatisch, prüft Dateisystem auf ungesyncte Aufnahmen
- Kein manuelles Eingreifen des Arztes nötig — es muss einfach funktionieren

**Netzwerk-Verhalten:**
```
Watch mit LTE/WiFi  → direkt an Server
Watch ohne LTE/WiFi → Wear OS Proxy → Phone → Server (transparent)
Kein Netzwerk       → Aufnahmen bleiben lokal, Sync bei Wiederherstellung
```

---

**UI — Ein Screen pro Eintrag, zwei Zustände:**

Jeder Listeneintrag füllt das gesamte Watch-Display. Navigation via Swipe hoch/runter. "Neu" immer ganz oben, darunter heutige Fälle chronologisch absteigend (neuester zuerst). Nur ein Button pro Eintrag.

```
"Neu" (ganz oben):              Recording (gleicher Screen):
┌─────────────────┐            ┌─────────────────┐
│  ⏱ 10:35        │            │  ⏱ 10:35        │
│                  │            │  ● REC  00:42    │
│  [● Neu]         │            │  [■ Stop]        │
│                  │            │                  │
│  ☁↑ 2            │            │  ☁↑ 2            │
└─────────────────┘            └─────────────────┘

    ↓ Swipe runter                 nach Stop:

┌─────────────────┐            ┌─────────────────┐
│  10:32           │            │  10:32           │
│  Kniegelenk...   │            │  ⏳               │ ← Oneliner noch nicht da
│  [▶ Fortsetzen]  │            │  [▶ Fortsetzen]  │
└─────────────────┘            └─────────────────┘

    ↓ Swipe runter

┌─────────────────┐
│  09:15           │
│  Hypertonie...   │
│  [▶ Fortsetzen]  │
└─────────────────┘
```

**Screen-Verhalten nach Stop:**
Nach dem Stoppen einer Aufnahme bleibt der aktuelle Fall auf dem Display — der Screen wechselt vom Recording-Zustand direkt zu "Fortsetzen". Der Arzt kann sofort weiter diktieren, ohne zu scrollen. Für einen neuen Fall swiped er bewusst nach oben zu "Neu".

**Oneliner-Polling:**
Solange der aktuell angezeigte Fall noch keinen Oneliner hat (⏳), fragt die Watch alle paar Sekunden den Server ab (`GET /api/oneliner/{case_id}`). Sobald ein Oneliner empfangen wird, wird er in die Marker-Datei geschrieben und im Display angezeigt — das Polling für diesen Fall stoppt. Beim Weiterswischen zu einem anderen Fall ohne Oneliner beginnt das Polling für den neuen sichtbaren Fall.

- 🎧 Headset-Indikator wenn Bluetooth-Headset aktiv
- ☁↑ zeigt Anzahl ungesyncter Aufnahmen (dezent, verschwindet bei 0)
- Default beim Öffnen: immer ganz oben ("Neu")
- Stop → Aufnahme geht direkt in Sync-Queue, kurzes ✓-Feedback, Screen bleibt auf aktuellem Fall
- Kein Verwerfen-Button — Korrekturen per Diktat ("Korrektur: ...")

Oneliner-Zustände bei Fällen:
- Verfügbar → Uhrzeit + Oneliner (stabil, Polling beendet)
- Lädt → Uhrzeit + ⏳ (Polling aktiv)
- Kein Server → nur Uhrzeit (Polling mit Backoff)
- Keine Fälle heute → nur "Neu" sichtbar

---

**Lokale Datenhaltung (persistent im Dateisystem):**

Das Dateisystem ist die einzige Quelle der Wahrheit. Die Fallliste ergibt sich aus zwei Ordnern: `cases/` (welche Fälle existieren + Oneliner) und `unsynced/` (welche Aufnahmen noch auf Upload warten).

```
/recordings/
├── cases/
│   ├── {case_id}.json    ← Marker-Datei (JSON, bei Erstellung minimal, wächst bei Bedarf)
│   └── ...
└── unsynced/
    ├── {case_id}_{UTC-timestamp}.m4a    ← wartet auf Upload
    └── ...
```

- **Marker-Datei** (`cases/{case_id}.json`): wird bei "Neu" mit minimalem JSON angelegt. Oneliner wird ergänzt, sobald er vom Server empfangen wird. Format ist erweiterbar für zukünftige Felder.

```json
// Bei Erstellung ("Neu"):
{
  "created_at": "2026-04-06T09:32:00Z"
}

// Nach Oneliner-Empfang:
{
  "created_at": "2026-04-06T09:32:00Z",
  "oneliner": "Kniegelenk re., V.a. Meniskus"
}
```

- **Fallliste** = alle `.json`-Dateien in `cases/` deren `created_at` von heute (UTC) ist. Sortierung absteigend. `oneliner` fehlt oder null → nur Uhrzeit anzeigen. Vorhanden → Uhrzeit + Oneliner.
- **Sync-Indikator** (☁↑) = Anzahl Dateien in `unsynced/`
- Dateinamen-Format Aufnahmen: `{case_id}_{yyyy-MM-ddTHH:mm:ssZ}.m4a` (UTC)
- UI zeigt Uhrzeiten in lokaler Zeitzone an

**Lazy Cleanup (Watch):**
Beim App-Start / Scan: Marker-Dateien in `cases/` deren `created_at` nicht von heute (UTC) ist, werden gelöscht — sie sind rein informativ für die UI und enthalten keine Audiodaten.

Audiodateien in `unsynced/` werden **nie** durch die Lazy Cleanup gelöscht. Der Sync-Service ist der einzige Verantwortliche für das Löschen von Audiodateien — ausschließlich nach Server-Bestätigung (ACK mit `received` oder `gone`). So gehen keine Aufnahmen verloren, auch wenn die Watch tagelang offline war (z.B. Wochenende im Spind). Beim nächsten Netzwerkzugang synct der Foreground Service alle ausstehenden Aufnahmen nach.

**Speicherplatz-Warnung (optional):** Pixel Watch 2/3 hat 32 GB, eine Minute AAC/m4a ≈ 1 MB. Selbst 100 ungesyncte Aufnahmen sind unkritisch. Dennoch: bei >500 MB ungesyncten Daten dezenten Warnhinweis in der UI anzeigen (nicht löschen, nur informieren).

---

**Upload-Paket (vom Sync-Service gesendet):**

```json
{
  "case_id": "uuid",
  "recorded_at": "2026-04-06T09:32:00Z",
  "audio": "..."
}
```

**Server-Antwort (ACK — drei Zustände):**

```json
{
  "case_id": "uuid",
  "recorded_at": "2026-04-06T09:32:00Z",
  "status": "received | gone"
}
```

| Status | Bedeutung | Watch-Verhalten |
|---|---|---|
| `received` | Upload angenommen | Lokale Datei löschen |
| `gone` | Fall existiert nicht mehr (vom Arzt entfernt) | Lokale Datei löschen |
| (kein ACK / Fehler) | Server nicht erreichbar oder interner Fehler | Retry mit exponentiellem Backoff |

→ Sowohl `received` als auch `gone` führen zum Löschen der lokalen Datei. Die Watch muss nicht verstehen, *warum* der Fall weg ist — nur dass sie die Datei gefahrlos löschen kann. Das hält den Watch-Code einfach.

---

**Oneliner-Abfrage (Polling, informativ):**

```
GET /api/oneliner/{case_id}
→ 200: { "oneliner": "Hypertonie Grad 2..." }
→ 404: noch nicht verarbeitet (erstes Transkript noch ausstehend)
→ 503: Ollama nicht verfügbar
```

- Oneliner wird beim ersten Transkript einmalig generiert und danach nur noch gelesen
- Der Arzt kann den Oneliner beeinflussen, indem er im Diktat eine Bezeichnung nennt (z.B. „Bezeichnung: Kniegelenk")
- Timeout: ~2 Sekunden
- **Polling:** Solange der aktuell angezeigte Fall keinen Oneliner in seiner Marker-Datei hat, fragt die Watch alle paar Sekunden ab. Polling läuft nur für den sichtbaren Fall.
- Bei 200: Oneliner in Marker-Datei `/recordings/cases/{case_id}.json` schreiben → Polling für diesen Fall beenden
- Bei 404/503/Timeout → weiter pollen (Watch funktioniert normal, Marker-Datei bleibt ohne Oneliner, UI zeigt ⏳)
- Keine Blockierung des Aufnahme-Workflows — Polling läuft unabhängig vom Recording

---

**Sicherheit Clients (API-Key-Auth für `/api/...`):**
- API-Key pro Arzt im HTTPS-Header
- Server mappt API-Key → Arzt-Identität (bestimmt Speicherpfad `/data/{arzt}/`)
- Einmalig pro Client-Gerät konfiguriert (Watch und Handy verwenden denselben Key pro Arzt; verschiedene Geräte desselben Arztes teilen sich den Key)

---

#### 1b. Android-Handy-App — sekundäres Erfassungsgerät (geplant)

Wird nach Abschluss der Watch-App gebaut, andockt an dieselben `:core-*`-Module. Funktional-Set in zwei Blöcken:

**Erfassungs-Features (identisch zur Watch):**
- Audioaufnahme, case_id-Verwaltung, Marker-Dateien, Sync-Queue, ACK-Protokoll, Oneliner-Polling, exponentieller Backoff, Lazy Cleanup — nichts davon wird neu geschrieben, alles kommt aus `:core-*`.
- UI ist eigenständig (Compose Material 3, Bottom-Nav, größeres Display), folgt aber demselben „flüchtiges Erfassungsgerät"-Ansatz.

**Review-Features (nur Handy, nutzen bestehende Web-Endpoints):**
- Zugriff auf `/web/cases`, `/web/cases/{case_id}`, `/web/cases/{case_id}/document`, `/web/audio/{user}/{case_id}/{filename}` etc.
- **Keine neuen Server-APIs nötig** — das Handy ist aus Server-Sicht ein weiterer Web-Client.
- Erste Ausbaustufe kann als **WebView auf `/web/...`** umgesetzt werden (kein doppelter UI-Code, automatisch synchron zum Browser-UI); spätere Ausbaustufen dürfen selektiv Teile nativ ersetzen.

**Invariante bleibt gewahrt:** Das Handy zeigt mehr als die Watch, hält aber keinen lokalen Archiv-Cache — Review-Daten werden on-demand vom Server gerendert.

**Data Layer Sync (optional, später):**
Wenn Watch und Handy gekoppelt sind (klassisches Wear-OS-Pairing), *könnten* beide Geräte die heutige Fallliste via `DataClient` (Wear OS Data Layer API) replizieren — nur Marker-Dateien, keine Audios. Das ist eine reine UX-Verbesserung (beide Geräte sehen denselben Fall), nicht MVP-relevant und wird erst nach Handy-App-Grundfunktion evaluiert.

#### 1c. Desktop-Clients (Linux / Windows) — erster nativer Client

**Ist-Stand:** Der Linux-Desktop-Client ist gebaut und funktioniert (`client-desktop/`). Er ist der **erste echte native Client überhaupt** — wurde vor der Watch-App gebaut, weil der Nutzer noch keine Pixel-Watch-Hardware hat und ein realer Client für API-Ergonomie-Tests (Retry, Content-Types, Auth-Fehlerpfade) nötig war.

**Features (MVP):**
- Config-Panel beim Erststart (Server-URL + API-Key, TOML unter `~/.config/doctate/client.toml`)
- Ein-Klick-Aufnahme („● Neu") + Stop-Button mit Live-Timer
- Persistente Pending-Queue (`~/.local/share/doctate/pending/`, m4a + `{stem}.meta.json`-Sidecar)
- Uploader mit exponentieller Retry (2/4/8/16/32 s, Cap 60 s, unbegrenzt für transiente Fehler, sofortiger Abbruch bei 400/401/403/413)
- Startup-Recovery: Pending-Dir-Scan beim Launch → Crash-Residuen automatisch retried
- State-Machine: `NotConfigured` → `Idle` → `Recording` → `FinalizingRecording` → `Uploading` → `Idle` | `Error`

**Tech-Stack (Linux):** `eframe`/`egui` (Immediate-Mode-UI, natives Fenster, keine WebView) + `tokio` (Background-Runtime für Recorder + Uploader) + `reqwest` (Multipart-Upload, rustls) + `ffmpeg`-Subprozess (m4a/AAC direkt; Graceful-Stop via `SIGINT` über `libc::kill`).

**Windows-Desktop:** geplant „bald" — derselbe `client-desktop`-Crate mit `#[cfg(target_os = "windows")]`-Gates, vor allem für `audio_input_args` (dshow statt PulseAudio) und Graceful-Stop (`q`-Stdin als Best-Effort, weil `tokio::process::Child` keine einfache SIGINT-Entsprechung auf Windows bietet).

**iOS:** SwiftUI, Ausblick — nicht in Arbeit.

**Zurückgestellt (nicht MVP):** System-Tray-Icon (Design war fertig, dann `tray-icon`-Crate verworfen wegen System-Dep-Schwergewicht mit `libxdo`/`gtk3`/`libappindicator`; `ksni` als pure-Rust-dbus-Alternative für später dokumentiert), Autostart, Keyboard-Shortcuts, Fall-Liste, Oneliner-Polling.

---

### 2. Server (Axum / Rust — Docker Container auf Ubuntu Server)

Axum ist der zentrale Koordinator. Er empfängt Uploads, startet die sequentiellen Worker (Transcribe + Analyze) und bedient das Webinterface. STT und Preprocessing laufen als externe Services (faster-whisper, Ollama) — Axum selbst braucht keinen GPU-Zugriff.

**Endpunkte (Ist-Stand):**

```
# Erfassungs-API (API-Key-Auth; Watch, Handy, künftige Erfassungs-Clients)
POST /api/upload                              → Aufnahme empfangen, ACK zurück
GET  /api/health                              → Liveness-Probe für Deployments
GET  /api/debug/whoami                        → API-Key → slug (Entwicklungshilfe)

# Web: Login / Session
GET  /web/login                               → Login-Seite
POST /web/login                               → Login-Formular absenden
POST /web/logout                              → Session zerstören

# Web: Arzt-UI (Session-gebunden, kein {slug} in URL, IDOR-geschützt)
GET  /web/cases                               → eigene Fallübersicht
GET  /web/cases/{case_id}                    → Fall-Detail (Transkripte + Status)
GET  /web/cases/{case_id}/document            → Gerendertes Dokument (Markdown → HTML)
POST /web/cases/{case_id}/analyze             → Analyse starten / neu anstoßen
POST /web/cases/{case_id}/reset               → Analyse/Transkripte verwerfen, alles neu transkribieren
POST /web/cases/{case_id}/delete              → Soft-Delete (Batch-Marker)
POST /web/cases/undo-delete                   → letzte Lösch-Batch wiederherstellen
POST /web/cases/bulk                          → Bulk-Aktionen (analyze / delete auf mehrere Fälle)
GET  /web/audio/{user}/{case_id}/{filename}   → Audio-Streaming (Cookie-Auth; Arzt oder Admin)

# Web: Admin-Log (flache Liste aller User/Fälle für Entwicklung)
GET  /web/                                    → Admin-Übersicht (später auf role="admin" eingrenzen)
```

**Geplant, noch nicht implementiert:** `GET /api/oneliner/{case_id}` (Client-Polling, genutzt von Watch und Handy), `GET /web/events` (SSE), Preset- und Undo-Endpoints für Dokument-Versionen. Siehe Phase 4 und Client-Pläne weiter unten.

**Kein `{arzt}` in URLs (IDOR-Prävention):**
Die Arzt-Identität wird ausschließlich aus dem Session-Cookie abgeleitet, nie aus der URL. Ein Axum-Extractor (`AuthenticatedArzt`) liest das Session-Token, schlägt den zugehörigen Arzt nach und gibt ihn als typisierte Struct zurück. Alle `/web/`-Handler erhalten den Arzt nur über diesen Extractor — der Dateisystempfad `/data/{arzt}/` wird serverseitig aus der Session konstruiert. Dadurch kann ein eingeloggter Arzt prinzipbedingt nicht auf Daten eines anderen Arztes zugreifen, selbst wenn er URLs manuell ändert. `case_id` wird zusätzlich als UUIDv4 validiert (`uuid::Uuid::parse_str`), um Path-Traversal über manipulierte IDs auszuschließen.

**Fall-States:**

```
┌────────────┐     sofort      ┌───────────────┐    Arzt klickt    ┌─────────────┐
│  Empfangen │ ──────────────→ │ Transkribiert │ ──────────────→  │ Ausgewertet │
│  (queued)  │  Transkription  │  (einsehbar)  │  "Analysieren"   │ (Dokument)  │
└────────────┘                 └───────────────┘                  └─────────────┘
```

- **Empfangen:** Mindestens eine Aufnahme ist noch in der Transkriptions-Queue oder wird gerade verarbeitet
- **Transkribiert:** Alle Aufnahmen dieses Falls sind transkribiert. Arzt kann jedes Transkript einzeln einsehen
- **Ausgewertet:** LLM hat aus allen Transkripten ein Dokument generiert

Ein Fall wechselt erst zu "Transkribiert", wenn *alle* zugehörigen Aufnahmen transkribiert sind. Solange eine Aufnahme noch in der Queue ist, bleibt der Fall im State "Empfangen".

"Analysieren" ist nur im State "Transkribiert" möglich. Der Button ist ausgegraut / nicht sichtbar, solange Aufnahmen noch ausstehen **oder** der LLM-Provider nicht konfiguriert ist.

---

**Pipeline nach Aufnahme-Eingang (Ist-Stand):**

```
1. API-Key → User-Slug auflösen (HashMap aus users.toml, kein {slug} in URL)
2. case_id validieren (UUIDv4)
3. Case-Verzeichnis bestimmen: /data/{slug}/{case_id}/
     ├─ Verzeichnis fehlt → anlegen (erster Upload einer neuen case_id)
     ├─ .deleted-Marker vorhanden → Marker entfernen (verspäteter Upload für gelöschten Fall)
     └─ sonst → Nachtrag zu bestehendem Fall
4. Audio speichern: {case_dir}/{UTC-ISO-Zeitstempel}.m4a
5. Transcribe-Job in mpsc-Queue einreihen
6. ACK mit status "received" an Watch senden
```

Das ursprünglich geplante `open/`/`done/`-Split wurde verworfen — siehe Abweichungen-Sektion. Es gibt nur noch eine flache Struktur pro User.

**Nachträgliche Aufnahmen nach Fallabschluss:**
Wenn eine Aufnahme für einen Fall mit bereits vorhandenem `document.md` eintrifft, wird sie angenommen, gespeichert und transkribiert. Das Dokument bleibt unverändert bestehen. Der Nachtrag-Hinweis im UI („⚠ 1 neue Aufnahme seit Abschluss — neu analysieren?") ist in Phase 4 geplant, aber noch nicht implementiert. Der Arzt kann manuell „Neu analysieren" anstoßen, dann wird `document.md` aus allen Transkripten neu erzeugt.

**Verspätete Uploads für gelöschte Fälle (Ist-Stand):**
Trifft ein Upload für einen Fall mit `.deleted`-Marker ein, wird der Marker entfernt und die Aufnahme normal als Nachtrag behandelt. Der ursprünglich geplante `"gone"`-ACK-Status ist nicht implementiert — der Upload-Handler antwortet immer mit `"received"`. Grund: Sonst würde der allererste Upload einer neuen case_id unnötig abgelehnt. Details in der Abweichungen-Sektion.

**Gazetteer (Post-AI-Terminologie-Normalisierung):**

```
Whisper-Output  ──┐
Oneliner (Ollama) ├──→ gazetteer::replace() ──→ Persistenz (.transcript.txt, oneliner.txt, document.md)
Analyse-LLM ──────┘
```

Der Gazetteer ist ein deterministischer Filter, der jede KI-Ausgabe passiert, bevor sie aufs Dateisystem geschrieben wird. Er korrigiert zwei typische Fehlerklassen:

1. **Whisper-Typos** an Fachtermini (z.B. `Zerebrum` → `Cerebrum`, `Pantoprasol` → `Pantoprazol`).
2. **LLM-Drift** zurück zu englischem/anglisiertem Wortlaut (`Amiodarone` → `Amiodaron`), den ein Pre-LLM-Hint-Kanal nicht einfangen könnte, weil das Drift im Output entsteht.

**Matching-Logik:**
- Kuratiertes Vokabular in `server/vocab/*.txt`, eine Phrase pro Zeile, Leerzeilen und `#`-Kommentare erlaubt, non-recursive, case-insensitive.
- Min. Tokenlänge 5 Zeichen (`MIN_TOKEN_LEN`) — schützt gegen falsche Kollisionen bei kurzen Alltagswörtern (`Bein` ↔ `Behn`).
- Damerau-Levenshtein-Distanz ≤ 2 (`MAX_EDIT_DISTANCE`) gegen das Vocab. Exakte Treffer werden per `HashSet`-Shortcut gehandhabt.
- `==text==`-Markierungen aus dem LLM-Prompt werden **nicht angetastet**.

**Dict-Veto gegen False Positives:**
`Kaktus` (DL=2 zu `Lantus`) darf nicht zu einem Medikamentennamen umgeschrieben werden. Deswegen prüft der Gazetteer vor jedem Commit, ob das Input-Token selbst ein gültiges deutsches Wort ist — über einen pluggable `DictChecker`-Trait. Produktiv liefert `SpellbookDict` (pure-Rust Hunspell-Parser) diese Prüfung, inklusive Flexions-Expansion: `Kakteen` wird aus `Kaktus` via `.aff`-Affix-Regeln anerkannt, ohne dass wir Flexionen explizit im Dict haben müssten. Der Dict-Check läuft lazy — nur wenn es überhaupt einen DL-Kandidaten gibt (99% der Tokens fallen nicht in dieses Fenster).

**Konfiguration:** `VOCAB_DIR` (Vokabular-Verzeichnis) und `HUNSPELL_DICT` (Stamm-Pfad zu `.aff`/`.dic`). Beide sind optional — ohne Vokabular läuft die Pipeline ungefiltert, ohne Dict-Veto erhöht sich die False-Positive-Rate (aktuelle Fälle zeigen das deutlich).

**Wichtige Eigenschaft:** Das Vokabular ist manuell kuratiert (ca. 200 Einträge, Medikamente + Substanzen + Anatomie). Keine Web-Crawls. Das hält die Qualität hoch, das Repository klein und das Urheberrecht sauber.

---

**Worker-Zyklus (sequentielle Tokio-Worker):**

**Ist-Stand:** Zwei unabhängige `tokio::spawn`-Worker, je mit eigener `mpsc`-Queue:

| Worker | Eingang | Externer Call | Ausgang |
|---|---|---|---|
| `transcribe::worker` | `TranscribeSender` (unbounded) | ffmpeg remux → `WHISPER_URL/asr` | `{ts}.transcript.txt`, anschließend Oneliner via Ollama |
| `analyze::worker` | `AnalyzeSender` (unbounded) | `LLM_URL/v1/chat/completions` | `document.md` |

Jeder Worker arbeitet sequentiell (ein Job nach dem anderen). Parallelität innerhalb eines Workers ist bewusst ausgeschlossen — die GPU auf der Whisper-Seite kann nur eine Aufgabe gleichzeitig sinnvoll bedienen, und der Analyse-LLM profitiert nicht von Burst-Lasten. Beide Worker laufen aber **zueinander parallel**: während Whisper noch transkribiert, kann der Analyse-Worker bereits einen anderen Fall abschließen.

**Kein striktes GPU-Phasen-Modell mehr.** Ein früher Entwurf wechselte explizit zwischen Whisper- und Ollama-Phase (mit `keep_alive=0`), um VRAM zu sparen. Der aktuelle Whisper-Wrapper (`large-v3-turbo`, ~1.6 GB) und Ollama (`gemma4:latest`, ~9 GB) passen gleichzeitig in die 12 GB der RTX 3060, das Phasen-Modell ist daher nicht mehr nötig. Ollama nutzt `OLLAMA_KEEP_ALIVE=300` statt 0 — spart das Modell-Reload pro Oneliner. Siehe Abweichungs-Sektion.

**Live-Flag pro Worker:** `WorkerBusy = Arc<AtomicBool>` + `BusyGuard` (RAII). Der Worker setzt `true` bei Job-Start, `false` bei Job-Ende (Drop-safe). Das UI nutzt das Flag, um zwischen echter In-flight-Aufgabe und orphaned On-disk-Markern (Crash-Residuen) zu unterscheiden. Es ersetzt den ursprünglich geplanten `RwLock<HashMap<CaseId, CaseState>>` — aufgrund der sequentiellen Worker-Semantik genügt ein einfaches Flag.

**Concurrency-Schutz aktuell:**
- Upload-Handler und Worker teilen sich keinen In-Memory-State; Synchronisation läuft ausschließlich über das Dateisystem (z.B. `has_pending_recordings(case_dir)` scannt nach `.m4a` ohne passendes `.transcript.txt`).
- Race zwischen Upload-Write und Worker-Scan: in der Praxis unkritisch, weil nachfolgende Uploads erneut in die Queue wandern und ein weiterer Recovery-Scan offene Stellen findet. Im Plan als Phase-3-TODO markiert, bei Bedarf auf explizites Locking nachrüstbar.

**Latenz-Profil (3 Ärzte, ~10 Min. pro Patient, Turbo-Modell):**
Eine Aufnahme trifft alle ~3 Min. ein. faster-whisper-turbo verarbeitet 60 s Audio in ~2–4 s. Typischer Ablauf bei einem Burst:

```
00:00  5 Aufnahmen in Queue
00:00  Transcribe-Worker: sequentielle Abarbeitung
00:00   ├─ ffmpeg faststart remux (~0.5 s/Datei)
00:00   ├─ Whisper call (~3 s/Datei)
00:00   └─ Gazetteer replace (<1 ms)
00:18  Alle 5 Transkripte geschrieben. Weil keine .m4a mehr pending:
00:18  Oneliner wird aus allen 5 Transkripten EINMAL regeneriert (~1 s)
00:19  Worker idle, wartet auf nächsten Job
```

Mehrere Ärzte teilen sich die Queue fair (FIFO).

**Oneliner-Generierung (aktuelle Semantik):**
Der Oneliner wird am Ende jedes Batches aus **allen** nicht-leeren Transkripten des Falls neu generiert (`update_oneliner`). „Batch-Ende" = `has_pending_recordings(case_dir) == false`. Das hat zwei Gründe:

1. **Spätere Aufnahmen dürfen korrigieren.** Sagt der Arzt „Korrektur: das Mittel heißt Vomex", soll der Oneliner diese Korrektur reflektieren. Wäre der Oneliner nach dem ersten Transkript eingefroren, bliebe der ursprüngliche Begriff (z.B. `Womax`) sichtbar.
2. **Keine überflüssigen LLM-Calls.** Während ein Batch noch läuft (mehrere Uploads hintereinander), wird der Oneliner nicht nach jedem einzelnen Transkript, sondern genau einmal am Ende regeneriert.

Silent-Case-Handling: LLM-Fehler oder leerer Oneliner-Text lassen einen evtl. bereits existierenden Oneliner unangetastet. Der nächste Transkript-Write versucht es erneut. Startup-Recovery (`recovery::regenerate_missing_oneliners`) fängt Fälle ein, bei denen ein früherer Lauf zwischen Transkript- und Oneliner-Write abgestürzt ist.

Der Arzt kann den Oneliner weiterhin durch eine explizite Bezeichnung im Diktat beeinflussen („Bezeichnung: Kniegelenk"). Die Erkennung läuft vollständig über den Ollama-Prompt, keine deterministische Keyword-Suche.

**Queue-Recovery bei Serverstart:**
- `transcribe::recovery::scan_and_enqueue`: findet alle `.m4a` ohne passendes `.transcript.txt` (und ohne `.m4a.failed`) und schiebt sie in die Transcribe-Queue.
- `transcribe::recovery::regenerate_missing_oneliners`: für Fälle mit Transkripten aber ohne `oneliner.txt` (oder mit leerem) wird der Oneliner einmalig erzeugt.
- `analyze::recovery::scan_and_enqueue`: findet `analysis_input.json` ohne `document.md` und reiht sie in die Analyze-Queue ein.
- Kein Datenverlust bei Server-Neustart; alle drei Scans laufen bei Boot parallel.

---

**Pipeline bei „Fall abschließen" (Ist-Stand):**

```
1. Handler serialisiert alle Transkripte chronologisch als AnalysisInput-JSON
   → schreibt `analysis_input.json` (persistent, überlebt Crash)
2. Job in AnalyzeSender-Queue einreihen (mpsc::unbounded)
3. Analyze-Worker liest `analysis_input.json`, rendert Prompt, ruft LLM
   (Temperatur 0, System-Prompt aus Config):
     - "bereinigen und strukturieren, nichts hinzufügen"
     - "spätere Aufnahmen haben Vorrang"
     - ASR-Fehler aktiv korrigieren, unsichere Stellen mit ==text== markieren
4. Gazetteer::replace() auf der LLM-Antwort (post-AI-Normalisierung)
5. Atomic write (`.tmp` → rename) → `document.md`
6. `analysis_input.json` löschen (Queue-Marker weg, recovery kein Duplikat)
```

Crash zwischen LLM-Antwort und Dokument-Write: akzeptiert. Recovery-Scan enqueued den Job erneut, ein LLM-Call wird wiederholt — seltenes Ereignis, kleiner Preis.

Silent-Case (keine verwertbaren Transkripte): Worker schreibt eine Stub-Datei (`_Keine verwertbaren Aufnahmen (alle Aufnahmen still)._`) statt LLM-Call.

---

**Pipeline bei „Neu analysieren" (Ist-Stand):**

```
1. Handler löscht bestehendes `document.md`
2. Pipeline wie oben neu ausführen
```

Keine Versionierung. Eine neue Analyse überschreibt die alte in-place.

---

**Geplant für Phase 4 (noch nicht implementiert):**

- **Preset-basiertes „Neu generieren"**: Preset-Prompt + optionaler Freitext kombinieren, LLM erneut aufrufen, vorige Version erhalten.
- **Dokument-Versionierung** (`document_v{N}.md` oder Alternative) als Voraussetzung für Undo. Noch offen, ob via Filename-Suffix + Max-Scan oder Content-Hash.
- **Undo-Button**: Rückkehr zur vorherigen Version.

Diese drei Features hängen zusammen — erst mit Versionierung ist Undo sinnvoll.

---

**Background Tasks (tokio::spawn in main.rs):**

- **Transcribe-Worker**: sequentielle mpsc-Abarbeitung (ffmpeg remux → Whisper → Gazetteer → Transkript-Write → Oneliner am Batch-Ende).
- **Analyze-Worker**: sequentielle mpsc-Abarbeitung (LLM → Gazetteer → atomic rename auf `document.md`).
- **Recovery-Scans bei Boot** (siehe Worker-Zyklus): fehlende Transkripte, fehlende Oneliner, fehlende Dokumente.
- **Rolling-File-Logger** (`tracing_appender::rolling::daily`) für `recorder.{datum}.log`.

**Geplant, noch nicht implementiert:**
- Health-Checks / Backoff für faster-whisper und Ollama bei Ausfall.
- Retention-Prüfung: lazy bei Zugriff — Audio/Transkripte älter als `RETENTION_*_DAYS` löschen, wenn der Ordner ohnehin gelesen wird.
- Lazy Cleanup für soft-deleted Fälle (`.deleted`-Marker älter als ein Tag → physisch entfernen). Aktuell bleibt der Ordner bestehen.

---

**Service-Ausfall (Ist-Stand):**

| Situation | Verhalten |
|---|---|
| faster-whisper nicht erreichbar | Transcribe-Worker loggt Fehler, markiert Aufnahme als `.m4a.failed`. Recovery-Scan ignoriert sie. |
| Ollama nicht erreichbar | Oneliner-Generierung loggt Fehler, bestehender Oneliner bleibt erhalten. Nächster Transkript-Write versucht es erneut. |
| LLM-Provider nicht erreichbar | Analyze-Worker loggt Fehler, `analysis_input.json` bleibt → Recovery-Scan enqueued beim nächsten Start. |
| Server-Neustart | Queue-Recovery aus Dateisystem (alle drei Recovery-Scans). |

**Geplant:** Automatische Re-Try-Policy statt `.m4a.failed`-Rename nach einmaligem Whisper-Fehler; Admin-Warnung im UI bei > 30 Min. Ausfall.

---

**Webinterface (askama Templates, Vanilla-Forms):**

Aktuell reines HTML + Formular-Submits, ohne Live-Updates. SSE ist als Phase-4-Feature geplant, aber noch nicht implementiert.

**Ist-Stand UI (vereinfacht):**

```
Meine Fälle — dr_mueller
────────────────────────────────────────────
Offen
  08:14  │  ⏳ Empfangen (transkribiere ...)
  09:32  │  ✓ Transkribiert                       [Ansehen] [Analysieren] [Reset]
  11:05  │  ✓ Transkribiert                       [Ansehen] [Analysieren] [Reset]
  [Bulk: alle markierten analysieren]   [Bulk: alle markierten löschen]

Abgeschlossen
  2026-04-06  08:14  „Kniegelenk, re."            [Öffnen] [Reset] [Löschen]
  2026-04-05  14:20  „Hypertonie Grad 2"          [Öffnen] [Reset] [Löschen]

Zuletzt gelöscht   [Undo letzten Batch]
```

Fall-Detail (transkribiert, Ist-Stand):
```
Fall 09:32 — 3 Aufnahmen
────────────────────────────────────────────
09:32  „Patient klagt über Schmerzen ..."    ← Transkript 1 (Audio-Link)
09:45  „Röntgenbild zeigt ..."               ← Transkript 2
10:02  „Diagnose: ..."                       ← Transkript 3

[Analysieren]   [Reset]   [Löschen]
```

Dokumentansicht (ausgewertet, Ist-Stand):
```
Dokument (Markdown → HTML, single version)
────────────────────────────────────────────
... Inhalt ...

[Neu analysieren]   [Reset]   [Löschen]
```

„Löschen" legt einen `.deleted`-Batch-Marker an. Der Fall verschwindet aus den Listen, kann aber über „Zuletzt gelöscht → Undo" en bloc wiederhergestellt werden. Physisches Entfernen (Cleanup) ist geplant, aber noch nicht implementiert — der Ordner bleibt bis auf Weiteres bestehen.

**Phase-4-Entwurf (noch nicht gebaut):**
- SSE-Live-Updates (`GET /web/events`) für Status-Wechsel und Oneliner-Fertig ohne Reload.
- Nachtrag-Hinweis: „⚠ 1 neue Aufnahme seit Abschluss — neu analysieren?"
- Preset-System + Undo für Dokument-Versionen (Arztbrief / Kürzer / Formeller / Diagnosen / Medikamente).
- CSRF-Tokens in allen POST-Formularen.
- Service-Ausfall-Warnung im UI (> 30 Min. Ausfall).

---

### 3. Filesystem-Struktur

```
/data/
└── {slug}/                                      ← User-Slug aus users.toml (kein open/done-Split)
    └── {case_id}/
        ├── {UTC-timestamp}.m4a                 ← Aufnahme (unveränderlich)
        ├── {UTC-timestamp}.m4a.failed          ← optional: dauerhaft gescheiterte Aufnahme
        ├── {UTC-timestamp}.transcript.txt      ← nach erfolgreicher Transkription (Gazetteer-normalisiert)
        ├── oneliner.txt                        ← aus allen Transkripten regeneriert
        ├── analysis_input.json                 ← nur während Analyse-Lauf (wird nach Erfolg gelöscht)
        ├── document.md                         ← nach LLM-Analyse (Gazetteer-normalisiert)
        └── .deleted                            ← Soft-Delete-Marker (JSON mit Batch-UUID + deleted_at)

/var/log/recorder/
└── recorder.{datum}.log
```

**Keine Versionierung im Code (Ist-Stand).** `document.md` und `analysis_input.json` existieren genau einmal pro Fall. Re-Analyze überschreibt `document.md` in-place (Handler löscht vorher). Dokument-Versionierung (`document_v{N}.md`) und „Undo" sind als Phase-4-Feature geplant — siehe Abweichungen-Sektion.

**Soft-Delete (`.deleted`-Marker):**

```json
{ "batch": "7f3a...uuid", "deleted_at": "2026-04-17T10:20:00Z" }
```

- Marker wird beim Klick auf „Entfernen" geschrieben. Alle in einem UI-Klick gelöschten Fälle teilen sich die `batch`-UUID, damit `POST /web/cases/undo-delete` gezielt den letzten Batch wiederherstellen kann.
- Ordner bleibt physisch bestehen, ist nur in den Listen ausgeblendet. Lazy-Cleanup älter als ein Tag ist geplant, aber aktuell **nicht implementiert**.

**Marker-Semantik im Überblick:**

| Datei | Bedeutung |
|---|---|
| `{ts}.m4a` ohne `{ts}.transcript.txt` | Transkriptions-Auftrag offen |
| `{ts}.m4a.failed` | Dauerhaft gescheitert, Recovery-Scan ignoriert, UI zeigt „failed" |
| `analysis_input.json` vorhanden | Analyse-Job in Queue / in-flight |
| `document.md` vorhanden | Fall gilt als „ausgewertet" |
| `.deleted` vorhanden | Fall ist soft-deleted (per Undo-Batch wiederherstellbar) |

---

### 4. Konfiguration

**System-Konfiguration (.env):**

```
# Server (required)
SERVER_PORT=3000
DATA_PATH=/data
USERS_FILE=users.toml

# Logging
LOG_LEVEL=info
LOG_PATH=/var/log/recorder
LOG_MAX_DAYS=90

# Retention (noch nicht durchgesetzt, siehe Phase 2-Checkliste)
RETENTION_AUDIO_DAYS=30
RETENTION_TRANSCRIPT_DAYS=30
RETENTION_DOCUMENT_DAYS=0        # 0 = permanent

# faster-whisper (eigener FastAPI-Wrapper, siehe Phase 2b.5)
WHISPER_URL=http://localhost:9001
WHISPER_TIMEOUT_SECONDS=120

# Ollama (Oneliner)
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=gemma3:4b
OLLAMA_KEEP_ALIVE=0

# LLM Provider (OpenAI-kompatibel, z.B. Ionos) — optional:
# Fehlt einer dieser Werte, versteckt das UI den "Analysieren"-Button.
LLM_URL=https://openai.inference.de-txl.ionos.com
LLM_API_KEY=...
LLM_MODEL=...
LLM_TEMPERATURE=0
LLM_TIMEOUT_SECONDS=180

# Consolidation system prompt — optional override. Leer → Default aus
# analyze/prompt.rs. Runtime-konfigurierbar, damit Admins iterieren und
# per "Neu analysieren" bestehende Fälle re-runnen können.
LLM_SYSTEM_PROMPT="..."

# Gazetteer (Post-AI-Normalisierung)
VOCAB_DIR=./vocab                          # Verzeichnis mit *.txt (eine Phrase pro Zeile)
HUNSPELL_DICT=/usr/share/hunspell/de_DE    # Stamm-Pfad (ohne .aff/.dic), Dict-Veto

# Session
SESSION_TIMEOUT_HOURS=8
COOKIE_SECURE=true                         # false nur für Plain-HTTP-Dev
```

**Verhalten bei fehlenden optionalen Blöcken:**

| Fehlt | Konsequenz |
|---|---|
| `LLM_URL` / `LLM_API_KEY` / `LLM_MODEL` | UI versteckt „Abschließen", Handler antwortet 503. Pipeline startet ohne Fehler (`config.llm_configured()` entscheidet). |
| `VOCAB_DIR` oder kein passendes `*.txt` darin | `warn!` beim Start, Pipeline läuft **ohne** Gazetteer-Normalisierung. |
| `HUNSPELL_DICT` bzw. `.aff`/`.dic` nicht lesbar | `warn!` beim Start, Gazetteer läuft **ohne** Dict-Veto (potentiell mehr False-Positive-Rewrites). |
| `LLM_SYSTEM_PROMPT` leer | Fallback auf hardcoded Default aus `analyze/prompt.rs` (inkl. `==text==`-Markierungen). |

**User-Verwaltung (users.toml):**

User-Daten (API-Keys, Passwörter, Rollen, Per-User-Whisper-Settings) werden separat in `users.toml` verwaltet statt in .env. So können neue User hinzugefügt werden, ohne die System-Konfiguration anzufassen. Das `role`-Feld ermöglicht neben `doctor` auch andere Rollen (z.B. `mta`, `admin`).

```toml
[[user]]
slug = "dr_mueller"
api_key = "..."
web_password = "$2b$12$..."
role = "doctor"

  [user.whisper]                    # optional; missing block = Service-Defaults
  language = "de"
  hotwords = "HOCM Valsalva"        # technisch durchverdrahtet, wird nicht beworben
  initial_prompt = "Kardiologie"

[[user]]
slug = "dr_schmidt"
api_key = "..."
web_password = "$2b$12$..."
role = "doctor"
```

Der Transkriptions-Worker reicht `[user.whisper]` pro Upload an den Whisper-Service durch. Siehe Abweichungen-Eintrag „Hotwords".

---

### 5. Prompts (Ist-Stand: hardcoded)

**Aktuell keine `prompts.toml`.** Die zwei aktiven Prompts leben direkt im Rust-Code:

| Prompt | Ort | Override |
|---|---|---|
| Consolidation-Prompt (Fallabschluss-LLM) | `server/src/analyze/prompt.rs::SYSTEM_PROMPT` | env `LLM_SYSTEM_PROMPT` |
| Oneliner-Prompt (Ollama) | `server/src/transcribe/ollama.rs` | bisher kein Override |

**Semantik des Consolidation-Prompts:**
- „Bereinigen und strukturieren, nichts hinzufügen, keine Diagnose, keine Arztbrief-Struktur."
- „Spätere Aufnahmen haben Vorrang — Korrekturen, Nachträge und Widersprüche zugunsten der chronologisch letzten Aussage auflösen."
- ASR-typische Fehler (phonetische Verwechslungen, zerschnittene Komposita) aktiv korrigieren. Bei Unsicherheit Original behalten.
- Unsichere Stellen / korrigierte Tokens / unklare Zahlen mit `==text==` umschließen. Diese Markierungen werden später vom Gazetteer nicht mehr angefasst. Keine anderen Annotation-Formen erlaubt.

**Geplant für Phase 4 (noch nicht implementiert):** Preset-System für „Neu generieren" (Arztbrief / Kürzer / Formeller / Diagnosen / Medikamente). Konfigurierbar vermutlich via `prompts.toml` — Format ist noch nicht festgelegt. Bis dahin gibt es nur den einen Default-Prompt.

**Entwurf (für spätere Umsetzung):**

```toml
[[preset]]
label = "Arztbrief"
prompt = "Formatiere das Dokument als formellen Arztbrief mit Anrede und Grußformel."

[[preset]]
label = "Kürzer fassen"
prompt = "Fasse das Dokument kürzer zusammen ohne inhaltliche Verluste."

# ... weitere Presets
```

Ziel: neue Presets ohne Code-Änderung hinzufügbar.

---

### 6. Sicherheit

| Verbindung | Methode |
|---|---|
| Watch → nginx | HTTPS TLS 1.3 + API-Key im Header |
| Browser → nginx | HTTPS TLS 1.3 + Session-Cookie (`Secure`, `HttpOnly`, `SameSite=Strict`) |
| nginx → Axum | HTTP lokal (Unraid → Ubuntu, internes Netz) |
| Axum → faster-whisper | HTTP localhost (gleicher Server) |
| Axum → Ollama | HTTP localhost (gleicher Server) |
| Axum → Ionos | HTTPS + API-Key |
| TLS-Zertifikat | Let's Encrypt (certbot, auto-renewal) |
| Fail2Ban | Zu viele Fehlversuche → IP geblockt |
| Rate Limiting | Max 10 Requests/Minute pro IP |
| Ports | Nur 443 offen (Unraid), SSH nur lokal |
| Datenhaltung | /data/ nur root lesbar |
| IDOR-Prävention | Arzt-Identität kommt ausschließlich aus der Session, nie aus der URL. `AuthenticatedArzt`-Extractor leitet den Dateisystempfad serverseitig ab. |
| Input-Validierung | `case_id` wird als UUIDv4 validiert (`uuid::Uuid::parse_str`, aktuell inline in Handlern; `ValidCaseId`-Extractor als Phase-4-TODO). Ungültige Werte → 400. Verhindert Path-Traversal. |
| CSRF | Token pro Session, Hidden Field in allen POST-Formularen, serverseitige Validierung. `SameSite=Strict` als zusätzliche Ebene. |
| Security Headers (nginx) | `Content-Security-Policy: default-src 'self'`, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer` |

---

### 7. Logging

**Setup:** `tracing` + `tracing-subscriber` mit zwei Sinks — stdout (Container-Logs) und `tracing_appender::rolling::daily` für `{LOG_PATH}/recorder.{datum}.log`. Log-Level via `LOG_LEVEL` env (Default `info`). Keine ANSI-Farben im File-Sink.

Typische Log-Linien im Regelbetrieb (strukturiert, key=value):

```
INFO  Transcription worker started
INFO  Analyze worker started                 vocab_entries=187
INFO  Transcribing                           audio=/data/dr_mueller/<uuid>/2026-04-17T10-15-00Z.m4a user=dr_mueller
INFO  Transcript written                    audio=... bytes=1423
INFO  gazetteer replaced                     token="Pantoprasol" canonical="Pantoprazol" distance=1
INFO  gazetteer blocked by dict veto         token="Kaktus" candidate="Lantus" distance=2
INFO  Oneliner updated                      path=/data/.../oneliner.txt chars=23
INFO  sending to llm                         case=/data/.../<uuid> recording_count=3 total_chars=1840
INFO  analysis done                         case=... bytes=2105
WARN  Gazetteer not available; running without proper-name correction   dir=... error=...
WARN  Hunspell dict unavailable; gazetteer running without dict veto    stem=... error=...
ERROR whisper call failed                   audio=... error=...
ERROR llm call failed                       case=... error=...
```

Wichtig: LLM-Antworten werden **nicht** geloggt (potenziell patientenbezogene Daten). Der `LlmError::Display` ist bereits redigiert.

---

## Tech Stack

| Schicht | Technologie |
|---|---|
| Android-Clients (Watch primär, Handy geplant) | Kotlin, Multi-Modul-Gradle. UI: Compose for Wear OS (`:app-wear`) bzw. Jetpack Compose Material 3 (`:app-mobile`). Geteilte Core-Module (`:core-*`) sind UI-unabhängig und JVM-testbar. |
| Desktop-Client (Linux gebaut, Windows geplant) | Rust, Cargo-Workspace-Member `client-desktop`. `eframe`/`egui` (Immediate-Mode-UI), `tokio` (async I/O), `reqwest` (Multipart-Upload), `ffmpeg`-Subprozess (m4a-Recording, SIGINT-Stop). Teilt `doctate-common`-Lib mit dem Server. |
| iOS-Gerät (optional, später) | SwiftUI oder Compose Multiplatform. Entscheidung nach Watch/Handy-Erfahrung. |
| Server | Rust (edition 2024), Axum 0.8, askama, reqwest, tracing, `strsim` + `spellbook` (Gazetteer); SSE für Live-Updates ist Phase-4-TODO |
| STT | faster-whisper (CTranslate2, large-v3, eigener Docker Container mit HTTP-API) |
| Preprocessing | Ollama, Gemma 3 4B (keep_alive: 0 für VRAM-Freigabe nach Request) |
| Dokument-LLM | Ionos (OpenAI-API-kompatibel, Temperatur 0) |
| Deployment | Docker auf Ubuntu Server (NVIDIA Container Toolkit für faster-whisper + Ollama), nginx reverse proxy auf Unraid |
| TLS | Let's Encrypt / certbot |

### Rust Crates (Server)

Axum selbst benötigt keinen GPU-Zugriff — STT und Preprocessing laufen als externe Services (faster-whisper, Ollama). Der Axum-Container ist daher ein schlankes Image ohne NVIDIA-Abhängigkeiten. Edition ist `2024`, was axum `0.8`, tower-http `0.6` und axum-extra `0.12` voraussetzt (native async fn in Traits).

```toml
[package]
edition = "2024"

[dependencies]
# Web
axum = { version = "0.8", features = ["multipart"] }
axum-extra = { version = "0.12", features = ["cookie", "form"] }
tower-http = { version = "0.6", features = ["limit", "trace"] }

# Async runtime + HTTP client
tokio = { version = "1", features = ["full"] }
reqwest = { version = "0.12", default-features = false, features = ["json", "multipart", "rustls-tls"] }

# Templates + Rendering
askama = "0.12"
pulldown-cmark = { version = "0.13", default-features = false, features = ["html"] }  # document.md → HTML

# Auth / Session
bcrypt = "0.15"
rand = "0.8"                                              # Session-Token (OsRng)
rpassword = "7.4"                                         # hash-password CLI (keine Passwort-Echos)

# Config / Daten
serde = { version = "1", features = ["derive"] }
serde_json = "1"
toml = "0.8"
toml_edit = "0.25"                                        # User-CRUD ohne Kommentarverlust
dotenvy = "0.15"
uuid = { version = "1", features = ["v4", "serde"] }
time = { version = "0.3", features = ["local-offset", "parsing", "formatting", "macros"] }

# Observability
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
tracing-appender = "0.2"

# Pipeline-Utilities
tempfile = "3"                                            # ffmpeg remux temp files

# Gazetteer (Post-AI-Normalisierung)
strsim = "0.11"                                           # Damerau-Levenshtein
spellbook = "0.4"                                         # pure-Rust Hunspell-compat, Dict-Veto

[dev-dependencies]
tower = { version = "0.5", features = ["util"] }
wiremock = "0.6"
```

**Gazetteer-Stack separat begründet:** `strsim` liefert die Kernmetrik (Damerau-Levenshtein ≤ 2 über N-Gramme gegen kuratiertes Vocab). `spellbook` ist ein pure-Rust Hunspell-kompatibler Parser, der `.aff`-Affix-Regeln live anwendet — Tokens, die als gültige deutsche Alltagswörter erkannt werden (inkl. Flexionen wie *Kakteen* aus *Kaktus*), werden vom Rewrite ausgenommen (Dict-Veto). Siehe Abschnitt „Gazetteer" weiter oben.

### Cargo-Workspace-Layout

Das Repository ist ein **Cargo-Workspace** mit drei Rust-Crates:

```
doctate/
├── Cargo.toml              (Workspace-Root, edition 2024, resolver 3)
├── server/                 (doctate-server bin; Axum)
├── doctate-common/         (doctate-common lib; API-Typen + Konstanten)
├── client-desktop/         (doctate-desktop bin; eframe + ffmpeg)
└── watch/wearos/           (Kotlin, kein Rust-Member)
```

**`doctate-common`** ist die einzige Quelle der API-Wahrheit zwischen Server und Clients:
- `ack::AckResponse`, `ack::AckStatus` — ACK-Typen für `POST /api/upload`
- `timestamp::now_rfc3339()`, `filename_stem_to_recorded_at()`, `recorded_at_to_filename_stem()` — bijektive Umwandlung UTC-RFC3339 ↔ Filesystem-safe-Name (Colon ↔ Hyphen im Zeit-Teil)
- `constants::API_KEY_HEADER` (= `"X-API-Key"`), `UPLOAD_PATH`, `FIELD_CASE_ID`, `FIELD_RECORDED_AT`, `FIELD_AUDIO`, `CONTENT_TYPE_AUDIO_MP4`

Deps der Shared-Lib sind minimal: nur `serde`, `uuid`, `time` — **kein** `tokio`, `reqwest`, `axum`. Dadurch bleibt sie runtime-agnostisch und kompiliert auch in WASM-Kontexten, falls je ein Browser-Client dazukommt.

### Rust Crates (Client-Desktop)

```toml
[dependencies]
doctate-common = { path = "../doctate-common" }
eframe = "0.28"                                    # egui + winit
reqwest = { workspace = true }
tokio = { workspace = true }
serde, serde_json, toml, uuid, tracing, tracing-subscriber  # workspace-geerbt
directories = "5"                                   # OS-konforme Config-/Data-Pfade
thiserror = "1"
which = "6"                                         # ffmpeg-PATH-Check

[target.'cfg(unix)'.dependencies]
libc = "0.2"                                        # SIGINT via libc::kill

[dev-dependencies]
tempfile = "3"
tokio = { workspace = true, features = ["test-util"] }   # für start_paused in Retry-Tests
wiremock = "0.6"
```

**Bewusst NICHT verwendet:**
- `ffmpeg-next`/`libav-sys`: Build-Komplexität (system-ffmpeg-Headers) + GPL/LGPL-Lizenzfragen. Subprozess-Aufruf hat keine Linkage-Probleme.
- `cpal` + `fdk-aac-sys` + `mp4`: wäre ~500 LOC Reimplementierung von ffmpeg für marginalen Benefit.
- `tray-icon`: zieht `libxdo`/`gtk3`/`libappindicator` als System-Deps. Für MVP zu viel Friktion; `ksni` als Pure-Rust-dbus-Alternative dokumentiert für später.

---

## Hardware

| Gerät | Rolle |
|---|---|
| Pixel Watch 2 oder 3 (LTE empfohlen) | Primäres Erfassungsgerät (Aufnahme + Upload + Oneliner-Polling) |
| Bluetooth-Headset (optional) | Bessere Aufnahmequalität |
| Android Phone | Sekundäres Erfassungsgerät (eigene App, geplant — Erfassung + Review) **und** Wear OS Companion. Für LTE-lose Watches bleibt der Wear-OS-Network-Proxy als Framework-Mechanismus erhalten — kein eigener Code auf der Companion-Ebene nötig. |
| Linux-Desktop (Arzt-PC, CachyOS/Arch) | Erster nativer Client — Aufnahme + Upload. Tray-los, Fenster bleibt sichtbar. |
| Windows-Desktop | Geplant „bald"; gleicher Crate via `#[cfg(target_os = "windows")]`-Gates |
| iOS-Gerät (optional, später) | Weitere Client-Plattform — spricht dieselbe Server-API wie alle anderen |
| Unraid Server | nginx reverse proxy, TLS-Terminierung |
| Ubuntu Server (RTX 3060, 12 GB VRAM) | Docker: Axum (kein GPU), faster-whisper (GPU), Ollama (GPU) |

---

## Entwicklungsreihenfolge

### Phase 1 — Server-Grundgerüst
- [x] Axum Setup, Routing, Authentifizierung (API-Key → User-Mapping via `users.toml`)
- [x] Filesystem-Struktur anlegen
- [x] .env Konfiguration (dotenvy)
- [x] Logging (tracing + tracing-appender)
- [x] Upload-Endpunkt mit ACK-Response
- [x] Docker Container für Axum auf Ubuntu Server (kein GPU nötig)
- [x] faster-whisper Container mit HTTP-API (NVIDIA Container Toolkit) — jetzt eigener `whisper/`-Service, siehe Phase 2b.5
- [x] Ollama einrichten, Modell gepullt (`gemma4:latest` statt `gemma3:4b`, siehe Abweichungen)
- [ ] nginx auf Unraid + Let's Encrypt + Security Headers (CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy)

### Phase 2 — Transkriptions-Pipeline
- [x] Transkriptions-Queue (tokio mpsc channel)
- [~] GPU-Phasen-Worker (Greedy-Zyklus Whisper↔Ollama) — **nicht nötig** im aktuellen Setup (Turbo + Ollama passen gleichzeitig in VRAM, OLLAMA_KEEP_ALIVE=300). Wird erst wieder relevant, wenn größere Modelle zurückkehren — siehe Abweichungen
- [x] faster-whisper HTTP-Client (reqwest, POST `/asr`, multipart Audio)
- [x] Ollama HTTP-Client (reqwest, POST /api/chat) — `keep_alive=300` statt `0`, siehe Abweichungen
- [x] Oneliner-Generierung (einmalig, erst geschrieben wenn ein sinnvoller Oneliner vorliegt; sonst Retry beim nächsten Transkript)
- [x] Queue-Recovery bei Serverstart (Filesystem-Scan)
- [ ] faster-whisper Health-Check + Retry
- [ ] Ollama Health-Check + Retry
- [ ] Lazy Cleanup bei Falllisten-Zugriff (zum Entfernen markierte Fälle vom Vortag löschen)
- [ ] Retention-Prüfung bei Zugriff (Audio/Transkripte nach RETENTION_*_DAYS)
- [x] Per-User Whisper-Settings in `users.toml` (`[user.whisper]` mit `language`, `hotwords`, `initial_prompt`) — Worker reicht sie pro Upload an den `whisper/`-Service durch. **Hotwords sind technisch verfügbar, werden aber nicht als Feature angeboten** (siehe Abweichungen).

### Phase 2b.5 — Eigener faster-whisper-Service (`whisper/`)
- [x] FastAPI-Wrapper um `faster-whisper` mit fest verdrahteten Anti-Halluzinations-Params (`condition_on_previous_text=False`, `temperature=0.0`, `vad_filter=True`)
- [x] Endpoints: `POST /asr` (txt/json), `GET /health`, `GET /info`
- [x] Modell `large-v3-turbo` via `WHISPER_MODEL` umschaltbar, Modelle persistent in Docker-Volume
- [x] Hotwords-Support (faster-whisper 1.2.1) als Form-Feld durchgereicht
- [x] Dockerfile (CUDA 12.1 + cuDNN), `docker-compose.yml`, `deploy.sh` (rsync + `/health`-Polling)
- [x] README mit Begründung (Halluzinations-Befund), Build- und Deploy-Anleitung
- [x] Deployed auf minerva:9001, `WHISPER_URL` in `server/.env` umgestellt

### Phase 3 — Fallverwaltung
- [x] Drei States: Empfangen → Transkribiert → Ausgewertet — rein aus FS abgeleitet (`compute_flags` in `user_web.rs`, kein State-Sidecar)
- [x] State-Übergang: erst "Transkribiert" wenn alle `.m4a` ein passendes `.transcript.txt` haben
- [x] "Analysieren" nur möglich, wenn LLM konfiguriert und Fall transkribiert — `handle_analyze_case` in `routes/case_actions.rs`
- [x] Aufnahmen nach case_id zusammenführen — `analysis_input.json` (single, nicht versioniert) enthält alle Transkripte
- [x] Chronologische Sortierung nach UTC-Zeitstempel — lexikographische Filename-Sortierung
- [x] Externes LLM → Dokument generieren — `analyze/`-Modul, OpenAI-kompatibel (`llm.rs`)
- [x] Fall soft-löschen — `.deleted`-Marker (JSON mit Batch-UUID), Undo letzter Batch via `POST /web/cases/undo-delete`
- [x] Bulk-Aktionen (analyze/delete auf mehrere Fälle gleichzeitig) — `POST /web/cases/bulk`
- [x] Reset-Endpoint — löscht Transkripte/Analyse/Document, re-enqueued alle `.m4a` (inkl. `.m4a.failed` → zurück auf `.m4a`)
- [x] Upload verspätet für gelöschten Fall → `.deleted`-Marker entfernen, Nachtrag normal behandeln
- [ ] Concurrency-Schutz: optional Pending-Zähler / Lock — aktuell genügt sequenzieller Worker + WorkerBusy-Flag
- [ ] Upload-Deduplizierung (gleiche case_id + Timestamp → ignorieren)
- [ ] Nachtrag-Erkennung im UI (Transkript neuer als `document.md` → Hinweis im Fall-Detail)
- [ ] Dokument-Versionierung (`document_v{N}.md` o.ä.) — Voraussetzung für Undo
- [ ] Undo-Logik für Dokument-Versionen
- [ ] Lazy Cleanup: `.deleted`-Marker älter als N Tage → Ordner physisch entfernen
- [ ] Retention-Prüfung: `RETENTION_*_DAYS` durchsetzen (derzeit nur in Config)
- [ ] Upload für gelöschte Fälle: explizit ACK `"gone"` statt Marker-entfernen (Rollback vs. Auferstehung — Policy-Entscheidung offen)

### Phase 4 — Webinterface
- [x] Session-Management: kryptographisches Token (256-Bit über 43 Alphanumeric-Zeichen, `OsRng`), Cookie (`HttpOnly`, `SameSite=Strict`, `Secure` via `COOKIE_SECURE`-ENV schaltbar für Dev), serverseitiger `RwLock<HashMap<Token, Session>>`, Ablauf nach 8 h
- [x] `AuthenticatedWebUser`-Extractor: Session-Token → User auflösen, bei ungültiger/abgelaufener Session → Redirect `/web/login`
- [x] Login-Seite (`GET /web/login`, `POST /web/login`), Logout (`POST /web/logout`)
- [x] askama Templates: `login.html`, `my_cases.html`, `case_detail.html`, `cases.html` (Admin), `document.html`
- [x] Übersicht für Arzt: zwei Sektionen (Offen / Abgeschlossen), plus "Zuletzt gelöscht" mit Undo-Batch
- [x] Fall-Detail: Transkripte pro Aufnahme einsehen (`GET /web/cases/{case_id}`, read-only, IDOR-geschützt via Session-Slug)
- [x] Audio-Streaming: `GET /web/audio/{user}/{case_id}/{filename}` (Cookie-Auth, Arzt eigene Dateien oder Admin)
- [x] Fall analysieren — Button im Detail-View
- [x] Bulk-Aktionen (alle markierten analysieren / löschen) über `POST /web/cases/bulk`
- [x] Dokumentansicht — `GET /web/cases/{id}/document`, rendert `document.md` via `pulldown-cmark` nach HTML
- [x] Soft-Delete mit Undo letzter Batch (ohne Bestätigungsdialog)
- [ ] `ValidCaseId`-Extractor: UUID-Validierung als Axum-Extractor (aktuell inline in Handlern)
- [ ] SSE-Endpunkt (`GET /web/events`), Session-Check bei Aufbau + periodisch bei Heartbeat
- [ ] Vanilla-JS EventSource-Client
- [ ] Nachtrag-Hinweis bei Aufnahmen nach Abschluss (⚠ "N neue Aufnahmen seit Abschluss")
- [ ] Preset-basiertes „Neu generieren" (Preset + Freitext, Freitext max. 500 Zeichen) — hängt an Dokument-Versionierung
- [ ] Undo-Button für Dokument-Versionen — hängt an Versionierung
- [ ] Service-Ausfall-Warnung (faster-whisper/Ollama/LLM > 30 Min.)
- [ ] CSRF-Token pro Session (Hidden Field in allen POST-Formularen, serverseitige Validierung)

**Admin-Log (separat vom Arzt-UI)**
- [x] `GET /web/` — flache Liste aller Fälle quer über User, inkl. Transkripten und Oneliner. Dient als "interaktives Log" für Entwicklung und Admin-Zwecke.
- [x] `hash-password` CLI (`cargo run --bin hash-password`) — erzeugt bcrypt-Hashes für `users.toml`, mit `toml_edit`-Schreibzugriff ohne Kommentarverlust.
- [ ] Zugriffsschutz: `GET /web/` und Admin-Audio auf `role = "admin"` einschränken (aktuell noch offen für alle).

### Phase 5 — Clients (Erfassung + Review)

**Reihenfolge:** 5a (gemeinsame Code-Basis) → 5b (Watch, primäres Entwicklungsziel) → 5c (Handy) → 5d (optional: Data Layer Sync) → 5e (Ausblick: weitere Plattformen).

**Hinweis:** Ein früher Proof-of-Concept (minimale Aufnahme + Upload auf echter Pixel Watch) sollte parallel zu Phase 2–3 stattfinden, um Wear-OS-spezifische Einschränkungen (Doze-Mode, Foreground-Service-Limits, Battery-Optimization) frühzeitig aufzudecken.

**Stand-in, solange keine Hardware:** `scripts/dictate.sh` simuliert den Client-Flow via ffmpeg-PulseAudio-Aufnahme + Upload gegen den laufenden Server (Modi: neuer Fall / aktuellen Fall fortsetzen / refresh). State in `/tmp/doctate-current-case`. So lassen sich Transkription und Oneliner ohne native Clients testen.

#### 5a — Gemeinsame Code-Basis (vor jeder UI-Arbeit)
- [ ] Gradle-Multi-Modul-Projekt aufsetzen (`:core-domain`, `:core-audio`, `:core-sync`, `:core-http`, `:core-storage`, `:app-wear`, `:app-mobile` als Platzhalter)
- [ ] `:core-*`-Module strikt UI-frei halten (kein Import von `android.*`/`androidx.compose.*` erlaubt — Build schlägt sonst fehl)
- [ ] JVM-Unit-Tests für `:core-domain` und `:core-sync` (case_id-Generierung, ACK-Zustandsautomat, Backoff-Kurve)
- [ ] API-Client (`:core-http`): Endpoints typisiert, API-Key im Header, Reqwest-Äquivalent (Ktor oder OkHttp)

#### 5b — Pixel Watch App (primäres Entwicklungsziel)
- [ ] Wear OS Projekt in Android Studio (`:app-wear`)
- [ ] Jetpack Compose UI (ein Screen pro Eintrag, fullscreen, Swipe-Navigation)
- [ ] Vertikale Fallliste (Neu ganz oben, heutige Fälle darunter)
- [ ] Nach Stop: Screen bleibt auf aktuellem Fall (→ "Fortsetzen" direkt sichtbar)
- [ ] MediaRecorder-Integration via `:core-audio`
- [ ] Bluetooth-Headset Erkennung + Indikator
- [ ] case_id (UUIDv4) Generierung: Neu → neue case_id, Fortsetzen → bestehende
- [ ] Persistente Speicherung im lokalen Dateisystem (UTC-Timestamps in Dateinamen)
- [ ] Marker-Datei pro Fall (`/recordings/cases/{case_id}.json`): minimales JSON bei Erstellung, Oneliner ergänzen nach Empfang
- [ ] Fallliste aus Marker-Dateien ableiten (`created_at` von heute + optionaler Oneliner)
- [ ] Lazy Cleanup: nur Marker-Dateien (`cases/`) von gestrigen/älteren UTC-Tagen beim Scan löschen — Audiodateien in `unsynced/` werden nie durch Cleanup gelöscht
- [ ] Foreground Sync Service (automatischer Upload) — einziger Verantwortlicher für Audio-Löschung (nur nach ACK)
- [ ] ACK-Protokoll: "received" → lokal löschen, "gone" → lokal löschen, kein ACK → Retry
- [ ] Exponentieller Backoff bei Fehlern
- [ ] Doze-Modus-Kompatibilität (Netzwerk-Wiederherstellung)
- [ ] Sync-Indikator (☁↑ Anzahl ungesyncter Aufnahmen)
- [ ] (optional) Speicherplatz-Warnung bei >500 MB ungesyncten Daten
- [ ] Stop → direkt in Sync-Queue, ✓-Feedback, Screen bleibt auf aktuellem Fall
- [ ] Oneliner-Polling (alle paar Sekunden für den sichtbaren Fall, bis Oneliner empfangen)
- [ ] Emulator-Tests + Pixel Watch Hardware-Test

#### 5c — Android-Handy-App (nach Watch-Abschluss)
- [ ] `:app-mobile`-Modul auf bestehende `:core-*`-Basis aufsetzen
- [ ] Erfassungs-UI (Compose Material 3): Fallliste, Neu/Fortsetzen, Recording-Screen — funktional-identisch zur Watch, aber an Handy-Ergonomie angepasst
- [ ] Alle Erfassungs-Features via `:core-*` (keine Duplizierung von Sync/Queue/ACK/Marker-Logik)
- [ ] Review-UI: Erste Ausbaustufe als WebView auf `/web/...`-Endpoints (schneller, kein doppelter Code, automatisch synchron zum Browser-UI)
- [ ] Auth-Integration für `/web/...` (siehe „Offene Entscheidungen": Handy-App-Auth)
- [ ] **Invariante prüfen:** kein lokaler Archiv-Cache für Transkripte/Audios außerhalb des aktiven Upload-Vorgangs
- [ ] End-to-End-Test: Erfassung Handy → Server → Review in Handy-App

#### 5d — Data Layer Sync zwischen Watch und Handy (optional, später)
- [ ] `DataClient` (Wear OS Data Layer API) in `:core-storage` einbetten
- [ ] Nur Marker-Dateien syncen (keine Audios — Audio-Upload bleibt beim Aufnahmegerät)
- [ ] Tombstone-Strategie für „gestern gelöscht" (TTL ~25 h, um Auferstehung zu vermeiden)
- [ ] Test: Watch + Handy offline → beide nehmen auf → bei erneuter Bluetooth-Verbindung gleicht sich die Liste ab

#### 5e — Desktop-Clients (in Arbeit, nativer Rust-Stack)
- [x] Tech-Stack entschieden: `eframe`/`egui` + `tokio` + `reqwest` + `ffmpeg`-Subprozess (nicht Tauri/Compose)
- [x] Cargo-Workspace + `doctate-common`-Shared-Lib
- [x] Linux-Desktop: Config, Recorder (SIGINT-Stop), Uploader mit Retry + persistenter Queue, State-Machine, UI mit Fehlerpfad
- [x] Integration-Test für Recorder (`lavfi`-Silence, `#[ignore]`, verifiziert SIGINT-Graceful-Stop + `ftyp`-Magic)
- [ ] Windows-Desktop: `dshow`-Device-Enumeration; ffmpeg-Installationspfad (winget vs. Bundle)
- [ ] Tray-Icon (zurückgestellt; später via `ksni`, weil `tray-icon` zu viele System-Deps mitzieht)
- [ ] Oneliner-Polling + Fall-Liste im Client (post-MVP)
- [ ] iOS-App (SwiftUI, Ausblick)
- [x] Invariante gewahrt: jeder Client = weiterer HTTP-Client, kein Server-Code-Ausbau nötig

### Phase 6 — Integration & Testing
- [ ] End-to-End Test (Watch → Server → Webinterface)
- [ ] SSE Live-Updates testen
- [ ] Pixel Watch Hardware-Test
- [ ] LTE-Modus testen
- [ ] Bluetooth-Headset testen
- [ ] Sync-Service testen (Netzwerkausfall, Neustart, Doze)
- [ ] Stop-und-Sync-Flow testen
- [ ] Korrektur-Diktate testen (LLM löst Widersprüche korrekt auf)
- [ ] faster-whisper-Ausfall simulieren + Warnung prüfen
- [ ] Ollama-Ausfall simulieren + Warnung prüfen
- [~] GPU-Phasen-Wechsel testen (Whisper → Ollama → Whisper, VRAM-Freigabe) — obsolet, Phasen-Modell existiert nicht mehr; nur relevant beim Zurückkehren zu großen Modellen
- [ ] Queue-Recovery nach Server-Neustart testen
- [ ] Upload-Deduplizierung testen
- [ ] Concurrent Uploads: mehrere Aufnahmen gleichzeitig für denselben Fall → State-Übergang erst nach letzter Transkription
- [ ] Mehrere Ärzte testen
- [ ] IDOR-Test: eingeloggter Arzt A versucht `case_id` von Arzt B aufzurufen → 404, kein Datenleck
- [ ] Session-Ablauf testen: nach 8 h → Redirect zu Login, SSE-Stream geschlossen
- [ ] CSRF-Test: POST ohne gültiges CSRF-Token → 403
- [ ] Path-Traversal-Test: `case_id` mit `../` → 400
- [ ] Ungültige `case_id` (kein UUID) → 400
- [ ] Lazy Cleanup testen (Watch: nur Marker-Dateien von gestern gelöscht, Audiodateien in unsynced/ bleiben)
- [ ] Lazy Cleanup testen (Server: markierte Fälle am Folgetag entfernt?)
- [ ] Retention-Prüfung testen (Audio/Transkripte nach RETENTION_*_DAYS)
- [ ] Undo/Regenerate testen
- [ ] Fall zum Entfernen markieren → am Folgetag gelöscht
- [ ] Nachträglicher Upload nach Fallabschluss → Nachtrag-Hinweis im Webinterface
- [ ] Upload für gelöschten Fall → ACK "gone", Watch löscht lokal
- [ ] Verspäteter Upload für soft-deleted Fall → `.deleted`-Marker entfernt, Nachtrag verarbeitet (Logik implementiert, End-to-End-Test offen)
- [ ] Edge-Case: Watch über Nacht/Wochenende offline → Aufnahmen bleiben in unsynced/, Sync bei Wiederherstellung

---

## Offene Entscheidungen

| Thema | Status |
|---|---|
| Whisper Modell | **Entschieden:** `large-v3-turbo` via eigener `whisper/`-Service, float16, optional Hotwords per Request. Qualitativer Vergleich gegen `large-v3` zeigte: gleichwertig bei Fachvokabular, nur Hotwords bringen echte Fehlerreduktion. Deutsches Fine-Tuning (primeline) getestet, lieferte schlechtere Ergebnisse. Umschaltbar via `WHISPER_MODEL`. |
| Ollama Modell | **Entschieden (vorläufig):** `gemma4:latest` (läuft). Llama 3.1 8B als Option, wenn Oneliner-Qualität nicht reicht. |
| Ionos Modell | Noch zu evaluieren |
| Watch Hardware | Pixel Watch 2 oder 3 (LTE empfohlen) |
| Authentifizierung Browser | Entschieden: Serverseitiges Session-Token (256-Bit, Cookie mit `Secure`/`HttpOnly`/`SameSite=Strict`), Ablauf 8 h. User-Identität ausschließlich aus Session, nie aus URL (IDOR-Prävention). Login gegen User-Passwort in `users.toml`. |
| Prompt-Qualität | Erfordert Testing mit echten Diktaten |
| Transkript editierbar? | Read-only oder editierbar vor Abschluss — offen |
| Sicheres Löschen | Reicht rm oder Overwrite nötig? — offen |
| faster-whisper HTTP-API | **Entschieden:** eigener FastAPI-Wrapper (`whisper/`). Grund siehe Phase 2b.5 / Abweichungen. |
| Recovery-UI (Webinterface) | Dedizierte Ansicht für verspätet eingetroffene Aufnahmen (Anhören / Ins Dokument / Verwerfen) — optional, Bedarf im Echtbetrieb evaluieren |
| Handy-App-Authentifizierung | Aktuell zwei Mechanismen: API-Key für `/api/...` (Erfassung), Cookie-Session für `/web/...` (Review). Varianten für die Handy-App: (a) beide parallel, (b) API-Key für alles vereinheitlichen (Cookie-Pfad erweitern oder Token-basiert), (c) WebView mit Cookie-Login für Review + API-Key für Upload. Entscheidung zu Beginn von Phase 5c. |
| Weitere Client-Plattformen (Linux/Windows/iOS) | Tech-Stack-Kandidaten: Compose Multiplatform (Code-Sharing über Android hinaus), Tauri + Rust (Desktop, kleine Binaries), nativ (SwiftUI). Entscheidung nach Handy-App-Erfahrung; Server-seitig keine Änderungen nötig (Client-Invariante). |

---

## Nicht im Scope (vorerst)

- Apple Watch (iOS-App für iPhone/iPad ist in Phase 5e als optionaler Ausblick enthalten)
- Praxissoftware-Integration (Medical Office / GDT)
- Multi-Tenant / Cloud-Hosting
- Echtzeit-Transkription
- Automatische Patientenzuordnung

**Hinweis zu Client-Plattformen:** Android-Handy, Linux-/Windows-Desktop und iOS sind nach dem [Client-Prinzip](#client-prinzip) explizit *erlaubt* — ihre Umsetzung ist in Phase 5c bzw. 5e geplant, aber zeitlich nach der Watch-App priorisiert.

---

## Abweichungen von der Originalplanung

Alle Einträge beziehen sich auf den Ist-Stand im Repository. Die ursprüngliche Idee bleibt erhalten, damit spätere Entscheidungen nachvollziehbar bleiben.

### Infrastruktur / Toolchain

| Änderung | Original | Aktuell | Grund |
|---|---|---|---|
| Rust-Edition + Crate-Versionen | edition 2021, axum 0.7, tower-http 0.5, axum-extra 0.9 | edition 2024, axum 0.8, tower-http 0.6, axum-extra 0.12 | Edition 2024 erlaubt native `async fn` in Traits; axum 0.7 nutzt `#[async_trait]`, inkompatibel |
| STT-Service | `lscr.io/linuxserver/faster-whisper` (Wyoming-Protokoll) → `onerahmet/openai-whisper-asr-webservice` → **eigener `whisper/`-FastAPI-Wrapper** | Wyoming ist binäres TCP, ungeeignet. Kein verfügbarer HTTP-Wrapper reicht `condition_on_previous_text=False` + feste `temperature=0.0` durch; Tests zeigten 2/13 Runs mit katastrophalen Halluzinationen (russisch/chinesisch). Eigener Service hardcodet die Anti-Halluzinations-Params. | Hardware-Tests auf echter Pipeline |
| Whisper-Port | 8100 (Plan) → 10300 (ahmetoner-Container) → **9001** (eigener Service) | freier Port auf minerva; alter Container optional parallel belassen |
| Whisper-Modell | `large-v3` int8 | `large-v3-turbo` float16 | Gleiche Qualität auf europäischen Sprachen, ~1.6 GB statt ~3 GB VRAM — ermöglicht Koexistenz mit Ollama im 12-GB-VRAM |
| Ollama-Modell | `gemma3:4b` | `gemma4:latest` | Neuere Version beim Aufsetzen verfügbar; Llama 3.1 8B als Fallback, falls Oneliner-Qualität nicht reicht |
| m4a-Preprocessing | nicht erwähnt | Server remuxt m4a mit `-movflags faststart` vor Whisper-Aufruf | Bekannter Bug ([Issue #97](https://github.com/ahmetoner/whisper-asr-webservice/issues/97)): m4a > 20 s liefern leere Transkripte, weil Android `MediaRecorder` das `moov atom` ans Dateiende schreibt. `faststart`-Remuxing (verlustfrei, < 1 s) behebt es. ffmpeg wird im Axum-Container mitgeliefert. |
| GPU-Phasen-Worker | Strikter Whisper↔Ollama-Wechsel, Ollama `keep_alive=0` | Zwei unabhängige sequentielle Worker (transcribe + analyze), beide Modelle parallel im VRAM, `OLLAMA_KEEP_ALIVE=300` | Dank Turbo-VRAM-Footprint passen beide gleichzeitig in die GPU. Spart Modell-Reload (~2 s pro Oneliner). Phasen-Wechsel bleibt als Fallback für größere Modelle (`large-v3`, Llama 3.1 8B) dokumentiert. |
| Analyse-Queue | `mpsc::channel(depth=32)` (bounded) | `mpsc::unbounded_channel` | `AnalyzeJob` ist ~110 Bytes; selbst 100 000 Jobs ≈ 11 MB. Persistenz lebt in `analysis_input.json` auf Platte, nicht in der Queue. Unbounded spart den 503-Pfad. |
| LLM-Provider-Naming | `ionos.rs`, `IonosError`, `IonosSettings` | `llm.rs`, `LlmError`, `LlmSettings` | OpenAI-API-kompatibel — Ionos ist durch Azure/OpenAI/Together.ai ersetzbar. Provider lebt nur in `.env`. |

### Daten-Modell und State

| Änderung | Original | Aktuell | Grund |
|---|---|---|---|
| Filesystem-Layout | `/data/{arzt}/open/{case_id}/` bzw. `done/{case_id}/` | Flach: `/data/{slug}/{case_id}/` | State aus Dateimarkern ableiten statt aus Ordnerlage. Migration zwischen `open`/`done` war ein zusätzlicher atomarer Schritt mit eigenem Crash-Pfad. |
| Terminologie | "Arzt/Ärzte" | "User/slug" | Rollen-System: auch MTAs und Admins (`role`-Feld in `users.toml`) |
| Case-State-Machine | Nicht vorgesehen | **Verworfen** (nach Live-Test): explizite State-Machine + `state.json`-Sidecar war kurzzeitig gebaut, erzeugte aber sofort Datendrift bei Schema-/Code-Änderungen. FS bleibt einzige Wahrheitsquelle. | Recovery hätte Self-Healing-Checks gegen die FS-Invariante gebraucht — `state.json` wäre dann eine überflüssige Cache-Kopie. Siehe „Design-Prinzipien: Filesystem ist SoT". |
| Soft-Delete | `.remove`-Marker (leere Datei) + Lazy Cleanup am Folgetag | `.deleted`-JSON-Marker `{batch, deleted_at}` + explizites „Undo letzter Batch" via `POST /web/cases/undo-delete` | Mehrere in einem UI-Klick gelöschte Fälle bilden eine Batch, dezidiertes Undo ist besser testbar als Zeit-Fenster. Physisches Cleanup älter als N Tage bleibt als TODO. |
| Erster Upload neue case_id | ACK „gone" | Neuer Fall anlegen, ACK „received" | Sonst würde der allererste Upload einer neuen case_id immer abgelehnt. „gone" aktuell gar nicht implementiert — auch Uploads für soft-deleted Fälle reaktivieren den Fall (Marker entfernen + Nachtrag). |
| Dokument-Versionierung | `document_v{N}.md` + `current`-Symlink | **Single-Version** `document.md`; Re-Analyze überschreibt in-place | Versionierung + Undo sind aktuell nicht benötigt — Re-Analyze ist selten, der Arzt hat den Markdown-Export in der Hand. Als Phase-4-TODO behalten (Voraussetzung für Preset-System). |
| Analyse-Input-Format | Zusammengeführter Markdown-Text als Prompt | Single `analysis_input.json` mit `{last_recording_mtime, recordings[{recorded_at, text}]}` | Persistenz und LLM-Prompt entkoppelt. Prompt wird zur Call-Zeit aus dem JSON gerendert. Schema-Evolution bleibt billig, ohne Prompt-Format zu brechen. Keine Versionierung der Input-Datei — sie ist ephemeral und wird nach erfolgreichem Dokument-Write entfernt. |

### Pipeline und LLM-Nutzung

| Änderung | Original | Aktuell | Grund |
|---|---|---|---|
| Gazetteer (Post-AI) | Nicht vorgesehen | Deterministische Terminologie-Normalisierung auf **jeder** KI-Ausgabe (Whisper, Oneliner, Analyse). Damerau-Levenshtein ≤ 2 über kuratiertes Vokabular | LLMs haben starke Training-Priors, die Kontext-Hints überstimmen (z.B. `Amiodarone` statt `Amiodaron`). Ein Pre-LLM-Hint-Kanal kann das nicht fangen, weil der Drift im Output passiert. Post-AI fängt Whisper-Typos und LLM-Drift in einem Mechanismus. |
| Gazetteer-Dict-Veto | Nicht vorgesehen | Hunspell-kompatibler `spellbook`-Crate veto'ed Rewrite, wenn Token ein gültiges deutsches Wort ist | `Kaktus` (DL=2 zu `Lantus`) darf nicht zu Medikamentennamen umgeschrieben werden. Flexions-Expansion via `.aff` fängt `Kakteen` ohne expliziten Eintrag. Lazy Lookup (nur bei DL-Kandidaten) → vernachlässigbarer Overhead. |
| LLM-Annotation `==text==` | Nicht vorgesehen | Analyse-Prompt fordert, unsichere/korrigierte Stellen mit `==text==` zu umschließen | Dem Arzt expliziten „bitte prüfen"-Hinweis geben. Der Gazetteer respektiert diese Markierungen und normalisiert Inhalt darin nicht. |
| Oneliner-Semantik | „Einmalig beim ersten Transkript, danach unveränderlich" | Regeneriert am **Batch-Ende** aus **allen** Transkripten (`has_pending_recordings == false`). Spätere Aufnahmen dürfen korrigieren (symmetrisch zur Analyse-LLM-Regel). | Der Arzt hält den Oneliner für mutierbar: „Korrektur: das Mittel heißt Vomex" soll auch im Oneliner landen. Batch-Ende verhindert, dass wir mitten in einem Upload-Burst LLM-Calls verbrennen, die der nächste Job wieder überschreibt. |
| Recovery-Scans | Nur „fehlende Transkripte bei Start" | Drei parallele Scans bei Boot: Transkripte, **Oneliner**, Dokumente | Ein früherer Lauf kann zwischen Transkript-Write und Oneliner-Write crashen → Startup-Scan holt das auf, bevor der Arzt die Watch öffnet. |

### UI / Entwickler-Tools

| Änderung | Original | Aktuell | Grund |
|---|---|---|---|
| User-Verwaltung | `API_KEY_*` / `WEB_PASSWORD_*` in `.env` | Separate `users.toml` + `hash-password`-CLI mit `toml_edit` | Neue User ohne `.env`-Änderung; CLI aktualisiert `users.toml` kommentar-erhaltend; Rollen-System (doctor, mta, admin) |
| LLM-Gate im UI | Nicht vorgesehen | „Analysieren"-Button nur sichtbar, wenn `LLM_URL`/`LLM_API_KEY`/`LLM_MODEL` alle gesetzt; Handler hat denselben Guard (503 Defense-in-Depth) | Ohne Provider würde der Close zur Laufzeit an einem `reqwest`-Fehler scheitern. `Config::llm_configured()` macht das Gate explizit. |
| Bulk-Aktionen | Nur „Alle abschließen" im UI angedacht | `POST /web/cases/bulk` mit mehreren markierten Fällen, Aktion `analyze` oder `delete` | Realer Workflow: Arzt räumt am Tagesende mehrere Fälle gleichzeitig ab. |
| Reset-Endpoint | Nicht vorgesehen | `POST /web/cases/{id}/reset` löscht Transkripte/Oneliner/Analyse/Document und re-enqueued alle `.m4a` (inkl. `.m4a.failed` → zurück auf `.m4a`) | Debug-Tool während der Entwicklung; hilft bei Prompt-Iteration und Gazetteer-Tuning, ohne den Case neu aufzunehmen. |
| Audio-Streaming-Route | Nicht vorgesehen | `GET /web/audio/{user}/{case_id}/{filename}` mit Cookie-Auth (Arzt eigene Audios, Admin alle) | Ermöglicht das direkte Anhören im Browser — unverzichtbar für Plausibilitätsprüfung bei Gazetteer/LLM-Fehlern. |
| Admin-Log vs. Arzt-UI | Nur Arzt-UI geplant | Zusätzlich frühes Admin-Log unter `GET /web/` (flache Liste aller Fälle) | Gebaut, bevor Session/States/Fall-Detail existierten, um die Pipeline während Entwicklung inspizieren zu können. Soll später hinter `role = "admin"` geschützt werden. |
| Test-Client für Watch-Flow | Erst ab Phase 5 mit Hardware | `scripts/dictate.sh` ab Phase 2/3 als Stand-in (ffmpeg + curl + c/n/r/q-Loop) | End-to-End-Tests ohne Pixel-Watch-Hardware. |
| Hotwords (Whisper) | Nicht vorgesehen | Per-User-Feld `[user.whisper].hotwords` **im Code**, aber nicht als Feature angeboten | Regress-Lauf über 10 Fixtures zeigt **keinen** Vorteil (ohne 12/257 Wortfehler, mit 14/257). Hotwords schluckten Funktionswörter. Leitung bleibt durchverdrahtet, bewerben wir aber nicht — re-evaluieren bei konkretem Bedarf. |

### Client-Architektur

| Änderung | Original | Aktuell | Grund |
|---|---|---|---|
| Repository-Layout | `server/` standalone + `watch/wearos/` separat | **Cargo-Workspace** mit `server/`, `doctate-common/` (shared lib), `client-desktop/` (erster nativer Client) | Mit zweitem Rust-Consumer rechtfertigt sich eine geteilte Lib. API-Typen + Konstanten + Timestamp-Helper zentral → keine Wire-Format-Drift zwischen Server und Clients. |
| Reihenfolge der Clients | Pixel Watch zuerst, dann Handy, Desktop später (Phase 5e „Ausblick") | **Linux-Desktop zuerst** (vor Watch), Windows nächster, Watch sobald Hardware verfügbar | Nutzer hat noch keine Pixel-Watch-Hardware. Desktop-Client dient zusätzlich als API-Ergonomie-Test-Fahrzeug (Retry, Content-Types, Auth-Fehlerpfade, die Wiremock-Tests nicht zeigen) und als Arzt-Workflow-Tool am PC (nebenher diktieren beim Arztbrief-Tippen). |
| Desktop-Tech-Stack | Offen — Kandidaten Tauri / Compose Multiplatform / nativ | `eframe`/`egui` (Immediate-Mode-UI) + `tokio` + `reqwest` + `ffmpeg`-Subprozess | Kleinere Binaries als Tauri (keine WebView, kein WebKitGTK auf Linux), keine Android-Verpflichtung wie Compose, pure Rust-Toolchain. ffmpeg-Subprozess statt `libav`-FFI: Lizenz (GPL vs. LGPL), Build-Komplexität, plattformübergreifende Konsistenz. |
| Desktop-Audio-Stop | nicht spezifiziert | **Unix:** `SIGINT` via `libc::kill`. **Windows:** `q`-Stdin-Write als Best-Effort. | ffmpeg's `term_init()` prüft `isatty(stdin)`; bei Pipe-stdin wird Keyboard-Polling deaktiviert, `q` landet in der Pipe, wird aber nie gelesen. SIGINT triggert ffmpeg's Signal-Handler unabhängig vom TTY-Status. Exit-Code 255 bei SIGINT-Exit ist normal — wir prüfen Datei-Existenz + Nicht-Leer statt Exit-Code. |
| Desktop-Tray-Icon | Geplant als Schritt 4f des Client-Aufbaus | Zurückgestellt, kein Tray im MVP. Close-Button beendet App. | `tray-icon`-Crate zieht drei System-Libs (`libxdo`, `gtk3`, `libappindicator`) für triviale Funktion. `ksni` (pure-Rust via dbus/zbus) als saubere Linux-Alternative für später dokumentiert. Client läuft ohne Tray sinnvoll. |
