Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/VR-P33.md
T
2026-07-08 16:15:37 +02:00

5.7 KiB

VR-P33 · Telefonie-Erweiterung HalloPetra (M105)

⚠️ KI→MCP-Pivot (AD-26): Der Whisper-Voicemail-Transkriptions-Andock entfällt (kein Whisper/LLM mehr — alter VR-P25-Scope zurückgestellt, HiveGrid wird MCP-Server, VR-MCP). Der restliche Telefonie-Teil (HalloPetra-Provider hinter TelephonyProviderInterface) ist unberührt. Whisper-Stellen unten durchgestrichen.

Typ Dev (Code)
Owner Raffael
Phase Phase 33 (v2-P11, NUR Telefonie-Teil) — Telefonie-Erweiterung (HalloPetra)
Cycle/Fenster Backlog/agil (Trigger, Ziel 2026-07-31)
Status geplant · 🟠 block-2 (Partner-API offen, agil — Spec offen)

🟠 block-2 — Partner-API offen, agil (Spec offen): HalloPetra kommt in keiner Spec vor — M12 ist eine reine AirCall-Spec. HalloPetra ist ein zweiter Telefonie-Provider hinter dem vorhandenen TelephonyProviderInterface — mechanisch klar, inhaltlich unspezifiziert. Vor Bau: eigene Vorlauf-Spec (API-Vertrag: Auth/Webhook-Events/Recording/Call-Lifecycle) erheben → VEXT-2. Agil vorziehbar, sobald spezifiziert. Voicemail-Transkription via Whisper koppelt an v2-P4 (VR-P25). → Whisper-Voicemail-Andock entfällt (AD-26). Der AirCall-Adapter (v1-P15) ist die Referenz.

Abhängigkeiten & Parallelität

  • Blocked by: AK-P15a (v1-TelephonyProviderInterface + AirCall-Adapter als Referenz), VEXT-2 (HalloPetra-Spec/API-Vertrag erheben — Pflicht-Vorlauf)
  • Blocks: — (Backlog/agil)
  • Läuft parallel zu: VR-P31 (DSGVO) — die ROADMAP-V2-Phase v2-P11 bündelt beide; dieses Doc deckt ausschließlich Telefonie/HalloPetra ab. Kein Schema-Konflikt: nutzt die v1-Telefonie-Domäne über das Provider-Interface, kein Kern-Umbau.
  • Konflikt-Risiko: keines auf Schema-Ebene.

Was wir bauen

Bindet HalloPetra als zusätzlichen Provider hinter dem bestehenden TelephonyProviderInterface an — ohne Kern-Umbau (zweiter Adapter neben AirCall). Eingehende Webhooks werden auto-gematcht (auf Contact/Lead/Projekt), landen im Activity-Stream und triggern Automationen (call.*). Click-to-Call, Inbound und Logging bleiben providerunabhängig: E.164-Normalisierung, Match-Confidence, Notiz-Editor. Aus Tenant-Sicht ist HalloPetra einfach eine weitere wählbare Telefonie-Anbindung neben AirCall.

Benötigte Screens (Backend bedient — Design liefert D-P33/D-Telefonie-Erw.)

Screen [Route] Kern-Inhalt
Telefonie-Setup [/settings/telephony] Provider-Connect (HalloPetra neben AirCall), Credential-/OAuth-Eingabe (maskiert), Verbindungs-Test
User-Bindings [/settings/telephony/bindings] Zuordnung User ↔ Telefonie-Nummer/-Account, providerunabhängig
Call-Session-Detail [/calls/:id] Anruf-Daten (Richtung/Dauer/Match auf Contact/Lead/Projekt + Match-Confidence), Aufnahme-Link, Notiz-Editor

(Click-to-Call ist ein Quick-Action-Element auf Contact/Lead/Projekt-Detail aus v1 — providerunabhängig, kein neuer Screen.)

Definition of Done

  • HalloPetra-Adapter implementiert TelephonyProviderInterface (connect/triggerOutboundCall/subscribeToWebhooks/verifyWebhookSignature/parseWebhookEvent/getRecordingUrl) ohne Kern-Umbau
  • Webhook-Auto-Match auf Contact/Lead/Projekt → Activity + Automation-Trigger (call.*)
  • Click-to-Call + Inbound + Logging providerunabhängig (E.164-Normalisierung, Match-Confidence, Notiz-Editor)
  • Provider-Auswahl/-Wechsel im Setup (HalloPetra neben AirCall)
  • Recording-Abruf über getRecordingUrl (sofern HalloPetra-API liefert)
  • ⚠ Vorlauf-Spec VEXT-2 liegt vor (API-Vertrag erhoben) — sonst kein Bau

Technische Bausteine

  • Entities (v1-Telefonie-Domäne, AD-21 — kein neues Schema nötig): TelephonyConnection (v1: provider (aircall → +hallopetra), oauth_token (verschlüsselt), webhook_secret, max. 1 aktiv/Tenant, [RLS]), TelephonyCallSession (v1: direction, status, from/to_number (E.164), matched_kontakt/lead/projekt_id, note, recording_url, [RLS][Soft-Delete][polymorph match]), TelephonyWebhookEvent (v1: event_type, signature_valid, processing_status, [append-only][30d]).
  • Provider-Pattern: HalloPetra = neuer Adapter hinter dem v1-TelephonyProviderInterface; kein Kern-Umbau — nur Adapter-Implementierung + provider-Enum-Erweiterung.
  • Auto-Match: Webhook → E.164-Normalisierung → Match auf Contact/Lead/Projekt (Match-Confidence) → Activity-Stream + Automation-Trigger (call.*).
  • Konnektor: tenantHasModule('telephony'); Provider-Auswahl im Setup.
  • Whisper-Kopplung: Voicemail-Transkription via altem VR-P25-Scope (Whisper-EU), optional/später. → entfällt (AD-26: kein Whisper/LLM; alter VR-P25-Scope zurückgestellt).
  • is_demo_data: Demo-Call-Sessions seedbar.

Quellen (granular)

  • ROADMAP-V2.md → §v2-P11 (NUR Telefonie-Teil: Success-Criteria 1/2, Telefonie-Setup/Call-Session-Screens) — Hauptquelle
  • ROADMAP.md → Phase 33
  • PHASE-SOURCES.md → Phase 33 (M105; Scope-Schnitt 11.06.: M105 HalloPetra → v2, AirCall = v1-Provider, Interface für 2. Adapter gebaut; Block-2: Partner-API offen)
  • ENTITY-MODEL.md → Domäne 10 Telefonie (TelephonyConnection/TelephonyCallSession/TelephonyWebhookEvent)
  • designer-briefs/P33-telefonie-hallopetra.md (alle Screens, Provider-Interface-Methoden, Block-2/Spec-offen)
  • _bmad-output/specs/M12-telefonie.md (Provider-Pattern, AirCall als Referenz)
  • abhängig: VEXT-2 (HalloPetra-Spec/API-Vertrag)

Dev-Nachzug (nach Davids D-P33-Delta + VEXT-2-Spec)

  • Spec/ENTITY-MODEL an reale HalloPetra-API + Davids UI-Entscheidungen angepasst
  • REQUIREMENTS/PHASE-SOURCES nachgezogen
  • Plane-Ticket VR-P33 aktualisiert