56 lines
5.0 KiB
Markdown
56 lines
5.0 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** | geplant |
|
|
|
|
## Abhängigkeiten & Parallelität
|
|
- **Blocked by:** `EXT-08` (AirCall-Account/OAuth-App), `R-P5` (Apps-Engine — Telefonie läuft als `DataConnection`), `R-P6` (CRM — Auto-Lead bei unbekannter Nummer, Match auf Kontakt/Lead/Projekt + Activity)
|
|
- **Blocks:** `AK-P15b` (Team-Chat)
|
|
- **Läuft parallel zu:** Raffaels Kern-Kette. **Sync-Punkt R-P5** (~21.06.): Telefonie ist ein Adapter *hinter* der Apps-Engine — DataConnection/OAuth-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.
|
|
|
|
## 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` (verschlüsselte OAuth-Tokens, Webhook-Secret). 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** (Whisper-Diktat ist v2) und eine Recording-Anzeige. **Anruf-Events** stehen als Automation-Trigger bereit (verpasster Anruf → Rückruf-Aufgabe, verdrahtet in P12).
|
|
|
|
## Benötigte Screens (Backend bedient — Design liefert `D-CHAT` + `D-P15`)
|
|
| Screen [Route] | Kern-Inhalt |
|
|
|---|---|
|
|
| AirCall-Setup [`/settings/integrations/telephony`] | Connect-Card (Status-Ampel connecting/active/error/revoked + Klartext), **User-Binding-Liste** (AirCall-User ↔ HiveGrid-User mit Email-Auto-Match + manueller Korrektur), „Verbindung testen", Trennen 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** (OAuth, verschlüsselte Tokens, Webhook-Secret) **über die Apps-Engine** mit Klartext-Status-Diagnose
|
|
- [ ] **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
|
|
|
|
## Technische Bausteine
|
|
- **Entities** (eigene `prisma/schema/telephony.prisma`): `TelephonyConnection` (provider aircall, oauth_token **verschlüsselt**, webhook_secret — 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, signature_valid, [append-only][30d]). `apps.prisma`/`crm.prisma` nur lesend für Relationen (AD-21).
|
|
- **Telefonie = Apps-Engine-Adapter** (R-P5): DataConnection-Lifecycle/OAuth-Verschlüsselung/Health vom Framework; hier nur der `TelephonyProviderInterface`-Adapter.
|
|
- **Webhook-Verarbeitung** mit Signatur-Check; Match-Heuristik (E.164-Normalisierung, Hard/Soft).
|
|
- **Activity-Write** (in/out/verpasst) + Automation-Trigger-Emit.
|
|
- **RLS** überall; OAuth per-Tenant-DEK (AD-8, via Apps-Engine). `is_demo_data` auf Demo-Anrufen.
|
|
|
|
## 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 · `PHASE-SOURCES.md` → Phase 15 (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)
|
|
- `_bmad-output/specs/M12-telefonie.md`
|
|
|
|
## Dev-Nachzug (nach Davids `D-CHAT`/`D-P15`-Delta)
|
|
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
|
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
|
- [ ] Plane-Ticket `AK-P15a` aktualisiert
|