Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/VA-P28d.md
T

157 lines
8.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# VA-P28d · Admin Telefonie
| | |
|---|---|
| **Plane** | `HIVEGRID-192` · Parent `HIVEGRID-190` |
| **Typ** | Dev (Code) |
| **Owner** | Raffael |
| **Phase** | P28 — Admin Sales Workspace |
| **Cycle/Fenster** | Backlog · nach CRM Core und Admin-Connection-Vertrag |
| **Status** | Ready for Review |
🎨 **design-nachzug: offen**
> **Owner-Änderung 2026-07-24:** Raffael übernimmt die Delivery. Working-ID, Scope, Status,
> Termine, DoD und Abhängigkeiten bleiben unverändert.
>
> **Dependency-Nachzug 2026-07-24:** Auch `VA-P28b` liegt jetzt bei Raffael; CRM- und
> Connection-Verträge sowie `blocked-by`/`blocks` bleiben unverändert.
>
> **Feste Recording-/Dialer-Entscheidung 2026-07-24:** Call-Recording ist standardmäßig
> deaktiviert. Ein aktivierter Recording-Import setzt dokumentierten Consent voraus und
> unterliegt 90 Tagen Retention. Der Power-Dialer bleibt gesperrt, bis DNC-/Consent-Regeln,
> Arbeitszeiten und Limits administriert wurden. Lokale Fixtures starten niemals echte Calls.
## Abhängigkeiten & Parallelität
- **Blocked by:** `VA-P28b` und das `AdminDataConnection`-Fundament aus `VA-P28c`.
- **Blocks:** `VA-P28e` für produktive Call-Tasks/Power-Dialer, `VA-P28h` für
Call-Reporting und `VR-P28a-RBAC` für Own-/Team-Kommunikationssicht und auditierte
Fremdzugriffe.
- **Extern:** `EXT-08` blockiert bei Aircall nur den echten Technology-Partner-OAuth-/Call-/Webhook-Proof;
Fixture-first-Implementierung bleibt möglich. Admin-Redirects/Webhooks müssen gegenüber den dortigen
Tenant-URLs getrennt registriert werden.
- **Design:** `VD-P28`, nach AD-28 kein Dev-Blocker.
- **Hardgrenze:** Calls gehören zu AdminContact/AdminLead/AdminDeal, niemals zum Tenant-CRM.
> **Implementierungsstart 2026-07-24:** `blocked-by` und `blocks` wurden in Plane sowie
> in den Ticket-Docs beider Richtungen geprüft. `VA-P28b` steht mit 10/10 DoD und
> `VA-P28c` mit 9/10 DoD auf Ready for Review; der providerneutrale
> `AdminDataConnection`-Vertrag ist für die Aircall-Implementierung freigegeben.
> `VA-P28e` und `VA-P28h` konsumieren den typisierten Call-/Activity-Vertrag.
> `EXT-08` bleibt ausschließlich Gate für den kontrollierten Aircall-Live-Proof.
## Was wir bauen
Click-to-Call, eingehendes Caller-Matching, automatische Protokollierung, Notizen, Rückruf-Aufgaben,
Ergebnis-Codes, Recordings und einen kontrollierten Power-Dialer für HiveGrids eigenen Vertrieb.
## Story-Ownership — 9/117
- `TEL-01` Kontakt per Klick anrufen.
- `TEL-02` Eingehenden Anruf automatisch dem Kontakt zuordnen.
- `TEL-03` Ausgehende Anrufe automatisch protokollieren.
- `TEL-04` Bei unbekannter Nummer direkt einen Lead anlegen.
- `TEL-05` Während oder nach dem Anruf eine Notiz erfassen.
- `TEL-06` Aus einem Anruf eine Rückruf-Aufgabe erzeugen.
- `TEL-07` Anrufergebnis aus der vorgegebenen Ergebnisliste erfassen.
- `TEL-08` Anrufaufzeichnung im Kontakt-Thread ablegen.
- `TEL-09` Eine Anrufliste automatisch nacheinander abtelefonieren.
## Benötigte Screens
| Screen [Admin-Host-Route] | Kern-Inhalt |
|---|---|
| Call-Panel im Kontakt/Lead/Deal | Click-to-Call, Live-Status, Notiz, Ergebnis, Rückruf |
| Caller-Popup | Kontaktmatch oder „Lead anlegen“ bei unbekannter Nummer |
| Call-Liste [`/sales/calls`] | Verlauf, Filter, Ergebnis und Recordingstatus |
| Power-Dialer [`/sales/calls/dialer`] | Liste, aktueller Kontakt, Skip/Ergebnis/Nächster |
| Telefonie-Settings [`/sales/settings/telephony`] | Connect, Nummern, Webhookstatus, Recording-Policy |
## Definition of Done
- [x] Provider-Connect und Click-to-Call verwenden `AdminDataConnection`; Webhooks sind token-/signaturgeprüft
nach realem Providervertrag, idempotent, rate-limited und auf eine Admin-Verbindung gebunden.
- [x] Telefonnummern werden international normalisiert; eingehende Calls matchen deterministisch und
mehrdeutige Treffer werden sichtbar statt still gewählt.
- [x] Unbekannte Nummern öffnen einen vorbefüllten, bestätigungspflichtigen R-LEADS-Anlageflow.
- [x] Ausgehende und eingehende Calls erscheinen mit Status/Dauer/Teilnehmern in der gemeinsamen AdminActivity.
- [x] Notiz, Rückruf-Aufgabe und Ergebnis sind während/nach dem Call atomar speicherbar.
- [x] Startkatalog der Dispositions umfasst alle elf gelieferten Ergebnisse und bleibt administrierbar,
ohne historische Werte umzudeuten.
- [x] Recordings werden nur nach bestätigter Consent-/Retention-Policy ingestiert, AV-geprüft, verschlüsselt
gespeichert und permission-gegatet im Kontakt-Thread abgespielt.
- [x] Power-Dialer startet den nächsten Eintrag erst nach gespeichertem Ergebnis oder bewusstem Skip und
respektiert DNC-/Consent-, Arbeitszeit- und Rate-Limit-Regeln.
- [ ] Admin-RBAC, Audit, Timeline, i18n, Klartextzustände, Unit-/Fixture-/DB-/RLS-/Smoke-/Hot-Swap-/Visual-Tests
und ein kontrollierter Live-Provider-Proof sind grün.
**Fortschritt:** **8/9 DoD = ~89 % done** · offen: 1 kontrollierter Aircall-Live-Proof,
davon 1 extern durch `EXT-08` blockiert → **0 im Code selbst machbar**.
## Umsetzungs-Notiz 2026-07-25
- Der tenant-lose Telefonie-Kern, internationale Rufnummernnormalisierung, deterministisches
Contact-/Lead-Matching, gemeinsame `AdminActivity`, Provider-Events und RLS wurden mit
`9a0959f34` umgesetzt.
- Ergebnis, Gesprächsnotiz und Rückruf-Aufgabe werden atomar gespeichert. Der vollständige
Startkatalog der **elf tatsächlich gelieferten** Ergebnisse bleibt über Code-Snapshots
historisch stabil; Outbound-Policy und Power-Dialer sperren ohne DNC-/Consent-Regeln,
Arbeitszeit und Tageslimit fail-closed. Proof: `f69df912f`.
- Recording-Ingestion ist standardmäßig aus, verlangt eine versionierte Consent-Fassung und
eine dokumentierte Zustimmung pro Call, scannt fail-closed mit ClamAV, speichert
AES-GCM-verschlüsselt im privaten EU-Bucket und löscht nach 90 Tagen. Die Wiedergabe im
Kontakt-Thread prüft Permission, Owner, Status, Retention, Bucket, Auth-Tag und SHA-256 und
wird auditiert. Proof: `f93d930df`, `bed890091`.
- Der Aircall-Adapter nutzt den offiziellen OAuth-/Public-API-Vertrag hinter
`AdminDataConnection`. Webhooks sind connection-gebunden, tokengeprüft, rate-limited,
idempotent und replay-sicher; der Outbound-Worker verarbeitet ausschließlich freigegebene
Requests. Proof: `d5a5beb61`.
- Die AD-28-Interim-UI ist permission-gegatet über Sidebar und Breadcrumbs erreichbar:
`/sales/calls`, `/sales/calls/dialer`, Kontakt-/Deal-Click-to-Call,
bestätigungspflichtiger R-LEADS-Flow und `/sales/settings/telephony`.
View-Models bleiben Prisma-frei, Routes injizieren ausschließlich Actions.
- Lokaler Proof: `pnpm typecheck`, `pnpm lint`, `pnpm test`
(**1063 Dateien / 7475 Tests grün**), `verify:i18n` (**14138 Keys**),
`verify:sidebar-routes` (**41 Tests**), `verify:phase-c-boundaries`,
`verify:tenant-policy-contract` (**365/365**), `verify:ui-visual`
(**130/130**), `test:hot-swap`, `verify:a11y-coverage`, `test:a11y`
(**14 Dateien / 44 Tests**), `verify:source-health`, `verify:ci-baseline`
und Prisma Validate.
- Dependency-Proof: Die bestehenden `VA-P28e`-/`VA-P28h`-Konsumenten und der komplette
Workspace-Testbestand bleiben grün. Offen bleibt ausschließlich der echte Aircall
OAuth-/Click-to-Call-/Webhook-Proof nach Partnerfreigabe; Fixtures werden nicht als
Live-Proof gewertet.
## Technische Bausteine
- **Schema:** `prisma/schema/adminTelephony.prisma`.
- **Modelle:** `AdminPhoneConnection`, `AdminPhoneNumber`, `AdminCallSession`,
`AdminCallParticipant`, `AdminCallEvent`, `AdminCallDisposition`, `AdminCallRecording`,
`AdminDialerList`, `AdminDialerEntry`.
- **Disposition-Startsatz:** Erreicht, Mailbox, kein Interesse, Interesse, interessiert in 1–3 Monaten,
schlechter Fit, weggedrückt, Gatekeeper, falsche/alte Nummer, Kunde, Rescheduling.
- **Wiederverwendung:** Aircall-Adapter/Normalizer aus Tenant-Telefonie nur hinter providerneutralen Ports;
keine `TelephonyConnection` mit tenantId als Admin-Verbindung verwenden.
## Slices und Rollback
Provider/Events → Matching/Call-UI → Notizen/Disposition/Tasks → Recording → Power-Dialer.
Provider und Recording sind separat abschaltbar. Webhook-Replays bleiben idempotent; Rollback löscht keine
Call-Historie oder Recordings.
## Quellen
- `.planning/ticket-docs/VA-P28b.md`, `VA-P28c.md`, `EXT-08.md`, `VD-P28.md`
- AGENTS.md — Admin-Grenze, Audit, Storage/ClamAV, AD-21/AD-28
## Dev-Nachzug
- [x] Consent-, Retention-, Download- und Löschregeln aus der Block-Review festschreiben:
Recording standardmäßig aus, expliziter Consent, 90 Tage Retention.
- [x] Admin-spezifische Aircall-Redirect-/Webhook-Registrierung dependency-aware in `EXT-08` ergänzen.
- [x] Interim-Screens aus bestehenden `~/ui`-Komponenten mit reinen View-Models,
Action-Callbacks, Visual- und A11y-Baselines ausliefern.
- [ ] Kontrollierten Aircall-Live-Proof nach `EXT-08` dokumentieren.
- [ ] Davids `VD-P28`-Delta integrieren und Visual-Baselines erneuern.