# CLAUDE.md – Aussendienst Voice-Agent (PoC)

## Was wir bauen
Eine iOS-App fuer Aussendienstmitarbeiter, die pro Kundenbesuch zwei Dinge per Sprache ermoeglicht:
1. **Vorbereitung** – der Agent liest den CRM-Stand vor und beantwortet Rueckfragen (gegroundet ausschliesslich in `preparation.json`).
2. **Dokumentation** – nach dem Termin fuehrt der Agent ein Gespraech, erkennt Themen, stellt gezielt Fragen zu Nicht-Besprochenem und erzeugt einen freigabepflichtigen Besuchsbericht.

Zielsystem des CRM ist **CAS genesisWorld** (GGUID als Datensatz-Schluessel, Hex mit `0x`).

## PoC-Ziel (Scope-Grenze!)
Beweisen, dass Spracheingabe im Auto effektiver ist UND dass die Extraktion **CAS-konformes JSON** mit korrekten IDs, Statuswerten und Bearbeitern erzeugt.
- **KEIN CRM-Rueckschreiben.** Der PoC endet beim **freigegebenen `report.json`**.
- Datenquelle sind lokale JSON-Fixtures (kein Docker/Supabase noetig).

## Architektur-Entscheidungen (fix)
- **Voice-Ansatz: Hybrid.** Live-Gespraech als Speech-to-Speech (natuerlich, freihaendig). Die strukturierte Extraktion ist ein **separater, deterministischer Text-Schritt NACH dem Gespraech** – nie im Realtime-Loop.
- **Voice-Provider: xAI Grok Voice** (Deutsch, EU-Residenz), angebunden ueber das **LiveKit-Plugin**. Provider ist austauschbar (OpenAI-Realtime-kompatibel).
- **Framework: LiveKit Agents (Node/TypeScript)**, lebt als Package im bestehenden pnpm-Turborepo.
- **Frontend: iOS (LiveKit Swift SDK)** – wird in einem SEPARATEN Prompt/Chat gebaut. Dieses Repo stellt die Kontrakte + Token-/Freigabe-Endpunkte bereit.
- **Validierung: Zod** – alle vier JSON-Artefakte haben ein Zod-Schema in `packages/schemas`.

## Die vier Daten-Artefakte
Liegen unter `DATA_DIR` (Default `./data`):
- `benutzer.json` – Tenant-weites Benutzerverzeichnis (Bearbeiter-Aufloesung).
- `visits/<visitId>/preparation.json` – CRM-Stand (Input), inkl. `delta` pro Objekt (Aenderung seit letztem Besuch) und `referenz` auf den Vorbesuch.
- `visits/<visitId>/transkript.json` – rohes Gespraech (Turns). Zur Laufzeit erzeugt; die mitgelieferte Datei dient als **Test-Fixture**.
- `visits/<visitId>/report.json` – Besuchsbericht (Output). Die mitgelieferte Datei ist die **Golden-Referenz** fuer die Extraktion.

## Harte Regeln fuer die Extraktion
- **IDs nie erfinden.** Bestehende Objekte behalten ihre GGUID aus `preparation.json`. Neue Objekte bekommen eine `temp_id` (echte GGUID vergibt spaeter das CRM).
- **Bearbeiter-Aufloesung** ueber `benutzer.json`: gesprochenen Namen/Alias -> genau eine `gguid`. **`aktiv: false` wird bei der Aufloesung ausgeschlossen** (Datensatz bleibt aber im Verzeichnis).
  - Ergebnis pro Aufgabe im Feld `bearbeiter_aufloesung`: `eindeutig | mehrdeutig | nicht_gefunden | rolle`.
  - Nur Rolle genannt ("der Innendienst") -> `abteilungs_defaults` greifen, sonst rollen-basiert ohne Person.
- **`naechste_schritte`** sind Pflichtbestandteil jeder Doku (Kundenentwicklung). Typ `aufgabe` (mit Verantwortlichem/Verknuepfung) oder `strategisch`.
- **`offen_geblieben`** = Coverage-Check: erwartete Agenda (offene Items aus `preparation.json`), die NICHT besprochen wurde -> wird zum naechsten Besuch mitgefuehrt.
- **`abgeleitet_aus_gespraech: true`** markiert alles, was der Agent interpretiert hat (statt woertlich diktiert) – das sind die Punkte, die der AD bei der Freigabe prueft.
- Der Bericht ist `status: entwurf`, bis der AD **freigibt** (`status: freigegeben`, `freigabe`-Feld gesetzt). `version` erlaubt spaetere Verfeinerung.

## CAS-Mapping (bestaetigt)
- Kundenanfrage -> **Vorgang**
- Besuch -> **Termin** (Kontaktbericht optional, `bericht_gguid` darf null sein)
- Verkaufschance: `phase`, `abschlusswahrscheinlichkeit` (%), `erwartetes_volumen`, `waehrung`
- Alle `status`/`phase`-Werte sind Platzhalter -> spaeter auf Tenant-Eingabehilfen mappen.

## Schnittstelle Frontend <-> Agent (fuer den separaten iOS-Prompt)
- Token-Endpunkt fuer die LiveKit-Verbindung der App.
- Nach Doku: `report.json` wird der App **textlich** zur Pruefung bereitgestellt.
- **Freigabe-Aktion** der App setzt `status: freigegeben` + `freigabe`. Erst dann gilt der Bericht als final (Write-back ist ausserhalb PoC).

## Arbeitsweise (verbindlich)
- **Plan-first.** Erst Plan + Versionen vorlegen, dann bauen.
- **Explizite Hold-Points** nach jeder Phase – auf Freigabe warten.
- **Ein Commit pro logischem Schritt.**
- **CLAUDE.md pro Package.**
- TypeScript, strikte Zod-Validierung. JSON-Keys sind Deutsch (CAS-nah), Code-Identifier duerfen Englisch sein.
- Domain-/LLM-Prompts auf **Deutsch**.