Files
HiveGrid-Wireframes/hivegrid-cloud/.planning/ticket-docs/AK-P15a.md
T

5.0 KiB

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