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

8.8 KiB
Raw Blame History

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

  • 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.
  • Telefonnummern werden international normalisiert; eingehende Calls matchen deterministisch und mehrdeutige Treffer werden sichtbar statt still gewählt.
  • Unbekannte Nummern öffnen einen vorbefüllten, bestätigungspflichtigen R-LEADS-Anlageflow.
  • Ausgehende und eingehende Calls erscheinen mit Status/Dauer/Teilnehmern in der gemeinsamen AdminActivity.
  • Notiz, Rückruf-Aufgabe und Ergebnis sind während/nach dem Call atomar speicherbar.
  • Startkatalog der Dispositions umfasst alle elf gelieferten Ergebnisse und bleibt administrierbar, ohne historische Werte umzudeuten.
  • Recordings werden nur nach bestätigter Consent-/Retention-Policy ingestiert, AV-geprüft, verschlüsselt gespeichert und permission-gegatet im Kontakt-Thread abgespielt.
  • 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

  • Consent-, Retention-, Download- und Löschregeln aus der Block-Review festschreiben: Recording standardmäßig aus, expliziter Consent, 90 Tage Retention.
  • Admin-spezifische Aircall-Redirect-/Webhook-Registrierung dependency-aware in EXT-08 ergänzen.
  • 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.