Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -0,0 +1,156 @@
# 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.