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

14 KiB
Raw Blame History

AK-P15a · P15 Telefonie (AirCall)

Typ Dev (Code)
Owner Akeshan
Phase P15 — Telefonie & Team-Chat
Cycle/Fenster W3 — Kern-Kette & Kommunikation (Demo 2) · fällig 2026-07-01 · Gate W3
Status in Umsetzung · 8/9 DoD · Live-Verifikation durch EXT-08 blockiert

🎨 design-nachzug: offen · Nach AD-28 wird eine Interim-UI aus ~/ui mit VM als Prop gebaut. Das ausstehende finale D-P15-Delta blockiert den Dev-Abschluss mit Interim-UI nicht.

Aircall-Vertragskorrektur 2026-07-15: HiveGrid nutzt Technology-Partner-OAuth, nicht Basic Auth. Der Authorization-Code wird gegen einen permanenten, nicht ablaufenden Access Token getauscht. Es gibt in diesem Flow keinen Refresh-Token. Details und externe Live-Voraussetzungen stehen in EXT-08.

Abhängigkeiten & Parallelität

  • Blocked by: EXT-08 nur für den Live-Proof (Technology-Partner-App, Company-Admin, Test-Nummer); R-P5 (Apps-Engine — Telefonie läuft als DataConnection) und R-P6 (CRM — Auto-Lead, Match + Activity) sind die technischen Vorbedingungen. Fixture-first-Umsetzung kann ohne echten Aircall-Zugang beginnen.
  • Kein technischer Blocker für AK-P15b: Der interne Team-Chat wird parallel umgesetzt und hängt nicht vom Aircall-Adapter oder dessen externem Live-Proof ab.
  • Design-Abhängigkeit: D-P15 liefert das finale Delta, ist nach AD-28 aber kein harter Dev-Blocker. Bis dahin gilt die Interim-UI-Regel inklusive Visual-Baseline und späterem Re-Baseline-Nachzug.
  • Läuft parallel zu: Raffaels Kern-Kette. Telefonie ist ein Adapter hinter der Apps-Engine — DataConnection-Credentials/DEK-Verschlüsselung/Health-Monitoring kommen von dort, nicht selbst gebaut. Eigene prisma/schema/telephony.prisma (AD-21). Match/Auto-Lead braucht R-P6 (Kontakt/Lead).
  • Konflikt-Risiko: gering — additive Tabellen; apps.prisma + crm.prisma nur lesend für Relationen.
  • Auswirkung auf Abhängige (2026-07-15): Die historische Blockade von AK-P15b wurde entfernt, weil zwischen Chat und Telefonie kein Contract besteht; der offene EXT-08-Live-Proof blockiert nur Telefonie. VR-P33 implementiert später dasselbe providerneutrale Interface, darf aber keine Aircall-spezifische HMAC-/Refresh-Annahme erben.
  • Schnittstelle zu VA-P27a (2026-07-15): AK-P15a verdrahtet nur den für eingehende Aircall-Anrufe nötigen, fixture-testbaren Web-Push-Pfad für Browser mit bereits erteilter Berechtigung. Der allgemeine Berechtigungs-Pre-Prompt, A2HS und die übrige PWA-/Offline-Härtung bleiben vollständig Scope von VA-P27a.
  • Auswirkung des VR-P33-Regression-Fixes (2026-08-02): Der fehlende deploy-seitige telephony-Entitlement-Eintrag betraf die gemeinsame Telefonie-Oberfläche und damit auch Aircall. Der eng begrenzte Backfill für starter/pro/business stellt das bestehende AK-P15a-Modulgate wieder her; Provider-Interface, Aircall-OAuth-Vertrag und der offene EXT-08-Live-Proof bleiben unverändert.

Was wir bauen

Den AirCall-Adapter als Referenz-Implementierung hinter dem TelephonyProviderInterface (HalloPetra dockt v2 an → P33): Click-to-Call und Inbound-Anrufe über eine Apps-Engine-DataConnection. Der globale Technology-Partner-Client (client_id/client_secret) kommt aus der Environment; pro Tenant speichert die DataConnection den permanenten Aircall-access_token und den beim automatischen Webhook-Anlegen gelieferten Webhook-token per Tenant-DEK verschlüsselt. Unbekannte Nummern legen automatisch einen Lead an, bekannte werden auf Kontakt/Lead/Projekt gematcht (Hard/Soft mit Confidence + Override). Anrufe landen im Activity-Stream (in/out/verpasst), nach dem Anruf gibt es einen Markdown-Notiz-Editor und eine Recording-Anzeige. Whisper-Diktat entfällt nach AD-26. Anruf-Events stehen als Automation-Trigger bereit (verpasster Anruf → Rückruf-Aufgabe, verdrahtet in P12).

Verbindlicher OAuth-/Endpoint-Vertrag

  • Initiator braucht in HiveGrid Tenant-Admin/telephony.manage und muss zugleich Aircall-Company-Admin sein.
  • Install URI: Produktion https://app.hivegrid.de/integrations/aircall/oauth/install, Staging https://staging-app.hivegrid.de/integrations/aircall/oauth/install.
  • Callback: Produktion https://app.hivegrid.de/integrations/aircall/oauth/callback, Staging https://staging-app.hivegrid.de/integrations/aircall/oauth/callback. Ein signierter, kurzlebiger state bindet Tenant, initiierenden User und Nonce; der Tenant steht nicht im Callback-Pfad.
  • Der Install-Endpunkt leitet zu https://dashboard.aircall.io/oauth/authorize mit client_id, festem redirect_uri, response_type=code, scope=public_api und state. Der Callback tauscht den zehn Minuten gültigen Code über POST https://api.aircall.io/v1/oauth/token gegen den permanenten Bearer-Token.
  • Webhook: Produktion https://api.hivegrid.de/v1/webhooks/telephony/aircall, Staging https://staging-api.hivegrid.de/v1/webhooks/telephony/aircall. Die Connection wird über den von Aircall beim Anlegen gelieferten Webhook-token identifiziert. Aircall liefert hier keine HMAC-Signatur; geprüft werden Token-Zuordnung, erlaubte Eventtypen, Payload-Schema, Idempotenz und Rate-Limit.
  • Der Aircall-Admin wählt beim OAuth-Install die Aircall-Nummern, deren Call-Events HiveGrid erhält.

Benötigte Screens (Backend bedient — Design liefert D-CHAT + D-P15)

Screen [Route] Kern-Inhalt
AirCall-Setup [/settings/integrations/telephony] Technology-Partner-OAuth-Connect; Hinweis „HiveGrid-Tenant-Admin und Aircall-Company-Admin erforderlich"; Connect-Card (connecting/active/error/revoked), User-Binding-Liste (AirCall-User ↔ HiveGrid-User mit Email-Auto-Match + manueller Korrektur), „Verbindung testen", Trennen/Reinstall mit Bestätigung
Anruf-Liste + -Detail [/calls] Liste (Nummer/Richtung/Dauer/gematchter Kontakt mit Confidence/Notiz-Snippet/verpasst-Marker); Detail mit Match-Override, Markdown-Notiz-Editor, Aufnahme-Link, Click-to-Call + eingehender-Anruf-Notification

(Click-to-Call-Buttons leben außerdem in Kontakt-/Lead-/Projekt-Detail aus P6/P7/P8.)

Definition of Done

  • AirCall-Connect per Technology-Partner-OAuth über die Apps-Engine: CSRF-sicherer state, Callback/ Code-Tausch, permanenter Access Token und Webhook-Token per Tenant-DEK verschlüsselt, Company-Admin-Prüfung, /v1/ping und Klartext-Status-Diagnose; kein Basic Auth/Refresh-Token/HMAC-Scheinvertrag
  • User-Bindings mit Email-Auto-Match-Vorschlag + manueller Zuordnung
  • Click-to-Call aus Kontakt-/Lead-/Projekt-Detail; Mehrfach-Nummern → Auswahl-Modal; Klartext-Edge-Cases (kein Binding / keine Connection / API-Fehler / ungültige Nummer); tel:-Fallback ohne Connection
  • Inbound: Auto-Match (Hard/Soft mit Confidence), unbekannte Nummer → Auto-Lead, Push-Notification beim Klingeln
  • Anruf-Logging in Activity-Stream + Markdown-Notiz-Editor + Recording-Anzeige + Match-Override
  • Anruf-Events als Automation-Trigger (verpasster Anruf → Rückruf-Aufgabe — Verdrahtung P12)
  • TelephonyProviderInterface mit AirCall als Referenz-Adapter (HalloPetra dockt v2 an)
  • Konnektor tenantHasModule('telephony'); RLS auf allen Tenant-Tabellen
  • Fixture-first + Live-Proof: deterministische OAuth-/API-/Webhook-Fixtures und HTTP-Fakes grün; danach echter Install/Callback, Nummernauswahl, Click-to-Call und mindestens ein Call-Webhook auf Staging mit EXT-08

Technische Bausteine

  • Entities (eigene prisma/schema/telephony.prisma): TelephonyConnection (provider=aircall, data_connection_id, provider_company_id, webhook_id, webhook_token_hash — max. 1 aktiv/Tenant), TelephonyUserBinding (tenant_user_id ↔ provider_user_id), TelephonyCallSession (direction, status, from/to_number E.164, matched_kontakt/lead/projekt_id polymorph, note, recording_url), TelephonyWebhookEvent (event_type, provider_auth_valid, [append-only][30d]). Permanenter Access Token und Webhook-Token liegen verschlüsselt in DataConnection.credentials; apps.prisma/crm.prisma nur lesend für Relationen (AD-21). webhook_token_hash ist nur ein lokaler, einwegiger Lookup-Digest für den öffentlichen Endpoint und keine von Aircall gelieferte HMAC-Signatur.
  • Telefonie = Apps-Engine-Adapter (R-P5): DataConnection-Lifecycle/Credential-Verschlüsselung/Health vom Framework; hier nur der TelephonyProviderInterface-Adapter. Für Aircall gibt es keinen Token-Refresh.
  • Webhook-Verarbeitung mit Webhook-Token-Zuordnung statt HMAC-Signatur, Event-Allowlist, Idempotenz und Rate-Limit; Match-Heuristik (E.164-Normalisierung, Hard/Soft).
  • Activity-Write (in/out/verpasst) + Automation-Trigger-Emit.
  • Provider-Interface: providerneutral connect/disconnect/listProviderUsers/triggerOutboundCall/ subscribeToWebhooks/validateWebhook/parseWebhookEvent/getRecordingUrl; validateWebhook erlaubt Aircalls Token-Abgleich und bei anderen Providern eine tatsächliche Signaturprüfung.
  • RLS überall; permanente Aircall-Credentials per Tenant-DEK (AD-8, via Apps-Engine). is_demo_data auf Demo-Anrufen.
  • Teststrategie: zuerst versionierte Fixtures für OAuth-Responses, Users, Calls und alle verwendeten Webhook-Events; Netzwerkzugriffe via HTTP-Fake/Contract-Test. Der echte Account ist ausschließlich der letzte Live-Verifikationsschritt und darf Unit-/Integrationstests nicht flakey machen.

Quellen (granular)

  • ENTITY-MODEL.md → Domäne 8: Kommunikation (TelephonyConnection/UserBinding/CallSession/WebhookEvent; HalloPetra = v2)
  • REQUIREMENTS.md → REQ-telefonie-datenmodell, REQ-telefonie-provider-adapter
  • ROADMAP.md → Phase 15 · Milestones: (M106-aircall, M107-anruf-eingang, M108-anruf-ausgang, M109-voicemail-notizen; M105 HalloPetra → v2)
  • designer-briefs/P15-telefonie-chat.md (AirCall-Setup, Anruf-Liste/Detail, Provider-Interface)
  • Aircall OAuth für Technology Partners
  • Aircall API Reference

Dev-Nachzug (nach Davids D-CHAT/D-P15-Delta)

  • Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
  • REQUIREMENTS/ROADMAP nachgezogen
  • Plane-Ticket AK-P15a aktualisiert

Umsetzungs-Notiz

  • 2026-07-15 · 0/9 DoD = 0 % done: Planungsvertrag auf Aircall Technology-Partner-OAuth korrigiert und Fixture-first/Live-Grenze festgelegt. Keine DoD als umgesetzt markiert. Selbst machbar: Fixture-first-Bau; extern blockiert: Live-Proof aus EXT-08; finales Design läuft nach AD-28 als Nachzug.
  • 2026-07-15 · 7/9 DoD = ~78 % done: Fixture-first-Implementierung in der separaten Worktree HiveGrid-Cloud-aircall auf feature/ak-p15a-aircall: providerneutrales Interface und Aircall-Adapter, OAuth/DataConnection-Lifecycle, User-Bindings, Click-to-Call, Webhook-Inbox mit Wiederanlauf und Idempotenz, Inbound-Matching/Auto-Lead, Activity/Notiz/Recording/Match-Override, Automation-Trigger, Web-Push sowie die AD-28-Interim-UI umgesetzt. Proof: kompletter Testlauf 5054 passed, Typechecks für Web/API/Worker/Integrations/Queue/View-Models, Prisma-Validierung, RLS-Vertrag 268/268, Cross-Cutting-Registries 266/266 und 187/187, UI-Visual 72 passed sowie Hot-Swap grün. Offen und selbst machbar beim Merge: Forward-only-Migration inklusive RLS-Policies und anschließender Forced-RLS-Proof; die Paritätsprüfung weist bis dahin erwartungsgemäß nur die vier neuen Telefonie-Tabellen aus. Extern blockiert durch EXT-08: echter Aircall-Install/Callback, Nummernauswahl, Click-to-Call und Call-Webhook auf Staging.
  • 2026-07-15 · 8/9 DoD = ~89 % done: Forward-only-Migration 20260715035000_ak_p15a_aircall_telephony ergänzt. Sie legt die sechs Telefonie-Enums und vier typisierten Tabellen an, aktiviert und erzwingt RLS auf allen vier Tabellen, installiert den engen hivegrid_resolve_aircall_webhook-Resolver und enthält die kommentierte Inverse-SQL. Proof gegen frisches PostgreSQL: Migrations-Parität ohne Drift, RLS-Release-Readiness 225/225 für ENABLE/FORCE/Policies, Runtime-Vertrag 268/268, Restricted-Role-Live-Suite 39 passed inklusive Tenant-A/B-Isolation, Cross-Tenant-Write-Abweisung sowie verweigertem Worker-/Authentik-JIT-Resolverzugriff. Selbst machbar offen: nichts. Extern blockiert durch EXT-08: echter Aircall-Install/Callback, Nummernauswahl, Click-to-Call und Call-Webhook auf Staging. Atomare Implementierungs-Commits: 431757ddb, be01b2c18, a2bbc3fa1, 70e8dd93e, d3bc9550f, f93f749ee, 6fa2224c6, f5a34ea82, b17a089cb.
  • 2026-07-17 · Stand-Audit bestätigt 8/9 DoD = ~89 % done: Vollaudit (Code auf main gegen jede DoD einzeln geprüft) bestätigt alle acht abgehakten Punkte inhaltlich; keine fehlenden DoD-Punkte gefunden. Proof-Korrektur: Die oben genannten atomaren Commits stammen aus dem separaten Worktree-Branch und sind im Squash-Merge aufgegangen — der auflösbare Proof auf main ist PR #117 = 083f3cd69 (feat(AK-P15a): Aircall-Telefonie integrieren). Zentrale Belege: HMAC-state (aircallOAuthState.server.ts), DEK-verschlüsselte Credentials (AircallConnectionService.server.ts), Click-to-Call-Edge-Cases (click-to-call.vm.ts), Inbound-Match/Auto-Lead (apps/worker/src/jobs/telephony-webhook.ts), Activity via logActivity und Klingel-Benachrichtigung via notify() (telephony-webhook-prisma.ts), Webhook-Endpoint mit Token-Zuordnung/Allowlist/Idempotenz/Rate-Limit (aircall-webhook-route.ts), FORCE-RLS-Migration mit Inverse-SQL, Smoke tests/e2e/telephony-aircall-interim.smoke.spec.ts, Interim-Visual-Baseline und Hot-Swap. Der damalige Milestone-Tracker M106–M109 wurde auf diesen Stand nachgezogen (er stand fälschlich auf „NICHT-GESTARTET"). Hinweis für P12: telephony.call.missed/completed wird als Workflow-Outbox-Event emittiert, hat aber noch keinen kuratierten Eintrag im Automation-Trigger-Katalog/UI — Verdrahtung gehört laut DoD 6 zu P12. Offen bleibt allein DoD 9 (Live-Proof), extern blockiert durch EXT-08; das Aircall-Konto ist beantragt (2026-07-17), Freischaltung ausstehend.