171 lines
14 KiB
Markdown
171 lines
14 KiB
Markdown
# 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.
|