# 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 - [x] **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 - [x] **User-Bindings** mit Email-Auto-Match-Vorschlag + manueller Zuordnung - [x] **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 - [x] **Inbound**: Auto-Match (Hard/Soft mit Confidence), unbekannte Nummer → **Auto-Lead**, Push-Notification beim Klingeln - [x] **Anruf-Logging** in Activity-Stream + Markdown-Notiz-Editor + Recording-Anzeige + Match-Override - [x] **Anruf-Events als Automation-Trigger** (verpasster Anruf → Rückruf-Aufgabe — Verdrahtung P12) - [x] `TelephonyProviderInterface` mit AirCall als **Referenz-Adapter** (HalloPetra dockt v2 an) - [x] 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](https://developer.aircall.io/tutorials/how-aircall-oauth-flow-works/) - [Aircall API Reference](https://developer.aircall.io/api-references/) ## 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.