docs: plan odoo agent integration (D25)

pv-agent/planung.md

@@ -382,4 +382,95 @@ tests/            # pytest: Ingest-, Retrieval-, Grounding-Unit-Tests
   authentisierte `/v1/ratings`-API sowie die UI erfassen Daumen hoch/runter und
   optionales Feedback pro Request-ID. Im Metadatenmodus werden auch indirekte
   Freitexte aus Quellen, Konflikten und Suchplan entfernt.
+- **Antwortkommentare (2026-09-16, D23):** Unabhängig von `up|down` können
+  Nutzer über eine dauerhaft sichtbare Kommentarbox mehrere Kommentare pro
+  Antwort erfassen. `/v1/comments` bindet jeden Kommentar an die verifizierte
+  Request-ID; Audit-CLI und SQLite-Log führen die datierten Kommentare mit der
+  ursprünglichen Frage/Antwort zusammen. Im Metadatenmodus bleibt der
+  Kommentartext aus Persistenz und stdout entfernt.
+- **Kostenaufstellung für Gestaltungsfragen (2026-09-16, D24):** Der
+  Decision-Support-Trigger matched jetzt auf normalisierter Frage (NFKD-Folding
+  plus ue-Varianten) — Fragen wie "guenstigste loesung" ohne Umlaute liefen
+  vorher in den generischen LLM-Planer und verweigerten. Bei expliziter
+  Kostennnabsicht ("wieviel kostet mich das", "einmalig ... bar auszahlen")
+  ergänzt der deterministische Plan zwei gesetzlich gescopte Queries: Lohnsteuer
+  einmaliger Bezüge (lb-son-04) und Arbeitgeberbelastung (lb-sva-06, lb-lnk);
+  die Zukunftssicherungs-Query fällt dann zugunsten der Slots weg. Systemprompt
+  Regel 11 verlangt nun die Anwendung auf den konkreten Fall: Arbeitgeberkosten
+  Schritt für Schritt aus belegten Sätzen, Annahmen explizit, Rückfrage nur bei
+  wesentlichem Fehlen. think=true: Leerer Content (Antwort nur im thinking-Feld)
+  führt zu einem einmaligen Retry ohne Thinking statt HTTP 503. Goldset +2
+  (q-128/q-129, beide recall=1,00); Offline-Eval 56 Fragen: Hit-Rate 0,98 ·
+  Recall@8 **0,95** · MRR 0,67. Real-Läufe beider User-Fragen: verifiziert,
+  mit belegter Rechnung (AG-SV auf 500 €, Lohnsteuer, Prämienvergleich).
 - Betrieb: `agent/README.md`.
+
+## 14. Phase B / M4 — Odoo-Integration (D25-Planung, Stand 2026-09-16)
+
+**Vorentscheidung (mit User):** Odoo orchestriert und rechnet (System of
+Record); der Agent konsumiert nur das vorgegebene Ergebnis und prüft
+Plausibilität gegen die KB. Kein Rückpfad Odoo → Agent-Tools im Agenten;
+die Aufweichung der Privacy-Regel 8 passiert bewusst erst hier und wird
+im Agenten per Feature-Flag (`PV_REVIEW_MODE`, default aus) freigeschaltet.
+
+### 14.1 Modul-Review (verlinkt als `.oddo-module/` → ../odoo-at-payroll/addons)
+
+- Vier Module, Odoo **19.0** (`l10n_at_hr_payroll` 19.0.10.0.0 auf der
+  echten `hr_payroll`-Engine; `l10n_at_hr_payroll_private` 19.0.17.0.0;
+  `l10n_at_gemeinde_payroll` Bgld./GemBG; `l10n_at_payroll_dokumente`),
+  LGPL-3, ~22k Zeilen Python + ~7,5k XML, ~25 Testdateien.
+- **Kein Agenten-/HTTP-Code vorhanden** (keine Controller, requests,
+  ir.config_parameter) — M4 startet bei null, nichts ist zurückzubauen.
+- **Tenant-Isolation nativ:** `ir.rule`-Company-Regeln (GP9/AP9-Muster),
+  Felder am Vertrag mit `group_hr_payroll_user`-Gruppen.
+- **Rechenkern komplett:** `sozialversicherung.py` (SVDN/SVDG, §-49-
+  Ausschaltungen **mit Jahres-Kumulative** `_l10n_at_sv49_ytd`, WF-Satzvektor
+  Bundesland×Jahr, DAG), `lohnsteuer.py` (§ 66 kumulativ, § 67 Sechstel/
+  Fünftel, § 68-Freibeträge mit YTD-Verbrauch `_l10n_at_st_frei_ytd`),
+  `payslip_private.py` (KommSt § 9, DZ §§ 122/126 WKG, FLAF-DB § 41 FLAG,
+  SZ-Basis/Dienstzeitfaktor), `sachbezuege`/`reisekosten` (km-YTD-Split).
+  Genau die Jahres-Salden, die im KB-Chat nur Annahmen sind, sind hier real.
+- **Parametersystem:** `hr.rule.parameter`-Seeds 2026 (SV-Werte aus ÖGK-
+  TASY-Export, gegen offiziellen Report gespiegelt; LST 2026; 2027-Rahmen),
+  NSchAB/Wien als Company-Flags.
+- **KV-Katalog in Odoo:** `l10n.at.payroll.kv` (+ versionierte `kv.wert`,
+  Gruppen/Stufen, Import-Wizard per CSV-Paste mit Sprungwarnung >10 %).
+  `library_variant_id` verlinkt auf die KV-Library-Variante (z. B. SI-2203,
+  Seed SI-2203/SI-2748). **Offener Punkt:** unser KB-Katalog kennt nur
+  `kv-kvt-NNN` (WKO-Dokumente, keine SI-IDs) — die Brücke Odoo-KV ↔ KB-KV
+  braucht eine Mapping-Tabelle (via KV-Library-Katalog des Schwesterprojekts
+  bzw. Branchen-/Titelabgleich).
+- Vertragsfelder für Kontext-Whitelist vorhanden: `hr.version` (KV, Gruppe,
+  Erfahrungsstufe, Überzahlung, Vordienstzeiten), Company (Bundesland,
+  KommSt-Gemeinde, NSchAB).
+
+### 14.2 Architektur M4 (geplant)
+
+1. **Neues fünftes Modul** `l10n_at_payroll_agent` (statt Einbau in die vier
+   bestehenden): Service-Client, Kontext-Builder, Verdict-UI. Depends:
+   `l10n_at_hr_payroll_private` (+ `hr_payroll`).
+2. **Konfiguration:** Service-URL + API-Key über `ir.config_parameter`, nur
+   lesbar für eine eigene Gruppe `pv_agent_user`; Key nie in Views/Logs.
+3. **Serverseitiger Client** (`pv.agent.client`, Odoo-`requests`, Timeout,
+   neutrale Fehler): Aufruf `/v1/ask` mit `mode=review` und schematisiertem
+   Kontext — **Whitelist hart kodiert** (facts: key/value/note; keine Namen,
+   SVNR, Geburtsdaten; KV-Name/Code, Bundesland/Gemeinde, Beträge, Jahres-
+   salden, Berechnungsergebnis mit Basis). `X-Request-ID` aus Odoo.
+4. **Workflow „Plausibilitätsprüfung einer geplanten Auszahlung“** (Pilot):
+   Wizard/Dialog am Payslip/Kontext → Odoo rechnet mit den bestehenden
+   `_l10n_at_*`-Methoden auf einem Draft → `computation`-Objekt (Komponenten,
+   Bemessung, Ergebnis) → Agent prüft gegen KB → strukturiertes `plausibility`-
+   Verdict (verdict plausible/implausible/not-checkable + checks mit
+   erwartet/erhalten/⚠/source_id) → Anzeige im Dialog; keine automatische
+   Korrektur, Odoo bleibt autoritativ.
+5. **Agent-seitig (M4.2):** v1.x-Contract `mode=review` + `context`-Feld
+   (extra=forbid, Whitelist-Schema); Prompt-Regeln erweitert um drei
+   Beweisklassen (KB-Beleg vs. übermittelter Kontextwert vs. Odoo-Berechnung),
+   Injection-Abgrenzung (Kontext ist Daten, keine Anweisungen) und
+   Verdict-Format; Post-Validierung: KB-IDs weiter strikt, Kontextwerte ohne
+   KB-ID als „übermittelt“ referenzierbar; Eval um Review-Fälle ergänzen.
+6. **Audit:** Odoo protokolliert gesendete facts/Ergebnis + request_id;
+   agentseitig deckt sich `data/audit.db` über dieselbe Request-ID.
+7. **Nicht-Ziele Phase B:** keine Lohnart-Erstellung durch den Agenten, keine
+   automatischen Buchungen, kein direkter Mitarbeiterzugriff im Chat
+   (Mandanten-/Rollengrenze bleibt in Odoo).