157 lines
8.8 KiB
Markdown
157 lines
8.8 KiB
Markdown
# 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.
|