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

171 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.