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

11 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 Regression-Fix live · automatischer Staging-Proof grün · Browser-Bestätigung offen · 6/6 fachliche DoD

🎨 design-nachzug: offen — die providerneutrale Interim-UI nutzt ~/ui; Davids finale D-P33-/Subframe-Optik wird separat nachgezogen und blockiert nach AD-28 nicht die Dev-DoD.

✅ VEXT-2 abgeschlossen (2026-08-01): HalloPetra ist API-Key- und manuell-webhook-basiert. Der belastbare Telefonie-Vertrag ist post_call für abgeschlossene Inbound-Anrufe. Es gibt aktuell keinen belegten öffentlichen Outbound-Trigger und keine Recording-URL; diese Fähigkeiten werden explizit nicht erfunden. Details und Payload stehen in VEXT-2.

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.
  • Contract-Auswirkung 2026-07-15: Aircall nutzt in v1 einen permanenten Technology-Partner-Access-Token und Webhook-Token-Abgleich, keine HMAC-Signatur und keinen Refresh-Token. Das Interface bleibt deshalb bewusst providerneutral: HalloPetra darf seinen noch zu erhebenden Auth-/Signaturvertrag in VEXT-2 implementieren, ohne Aircall-Annahmen zu kopieren.

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 [/:tenant/settings/integrations/telephony] Provider-Connect: HalloPetra per API-Key neben AirCall-OAuth, Verbindungs-Test, einmalige Webhook-Einrichtung
User-Bindings [im Telefonie-Setup] AirCall-User-Zuordnung; für HalloPetra mangels öffentlicher User-Ressource ausgeblendet
Call-Session-Detail [/:tenant/calls/:id] Anruf-Daten (Richtung/Dauer/Provider/Match auf Contact/Lead/Projekt + Match-Confidence), optionaler 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/validateWebhook/parseWebhookEvent/getRecordingUrl) ohne Kern-Umbau; validateWebhook setzt den in VEXT-2 erhobenen Provider-Vertrag um
  • 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; derzeit belegter Vertrag ohne URL)
  • ⚠ 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), data_connection_id, Provider-/Webhook-Metadaten, max. 1 aktiv/Tenant, [RLS]); verschlüsselte Credentials liegen providerabhängig in DataConnection.credentials. 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, provider_auth_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
  • Historische Milestone-Zuordnung: 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)
  • 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 (API: erledigt; Davids Delta: offen)
  • REQUIREMENTS/ROADMAP nachgezogen
  • Plane-Ticket VR-P33 aktualisiert

Umsetzungs-Notiz

  • 2026-08-02 · Regression-Fix live · automatischer Staging-Proof grün: PR #345 wurde mit erhaltener Feature-Historie normal gemergt (f4b78178a). Alle elf Pflichtchecks sind grün; ein fachfremder Traefik-Dateisystemtest lief unter Runner-Last einmal ins Timeout und bestand im isolierten Rerun. Der automatische Staging-Deploy 11732 ist erfolgreich. Web und API liefern auf /healthz und /readyz HTTP 200 mit exakt dieser Revision. Die Live-Datenbank führt die Migration als abgeschlossen und enthält für starter, pro und business jeweils genau ein inkludiertes telephony-Entitlement; SubscriptionProduct und SubscriptionFeature behalten FORCE RLS. Die geschützte Route redirectet unauthentifiziert korrekt zum Login, und die Web-Logs enthalten seit dem Deploy keinen neuen Telefonie-CatalogError, Modul-404 oder HTTP 500. Offen ist nur der erneute Klick mit der bestehenden authentifizierten Browser-Session.
  • 2026-08-02 · 6/6 fachliche DoD implementiert: Der erste echte Tenant-Klick hat einen Katalog-Nachzug aufgedeckt: Auf Staging existierten die vier telephony.*-Permissions, aber auf keinem der drei Standardpläne ein telephony- SubscriptionFeature. Dadurch meldete das Modulgate foundation.not_found; der nicht als Router-Response normalisierte CatalogError erschien im Browser fälschlich als HTTP 500. Der Regression-Fix ergänzt den eng begrenzten, idempotenten Entitlement-Backfill für starter/pro/business und erhält den 404-Status an Loader und Action. Lokal grün: Root-Typecheck/Lint, Prisma-Validate, Tenant-Policy-Vertrag 377/377, Migrations-Parität, acht fokussierte Regressionstests sowie ein PostgreSQL-Harness für Backfill, Wiederholung, Mehrdeutigkeit, leeren Katalog und FORCE RLS. Der vollständige Root-Lauf auf aktuellem main besteht mit 1.176 Testdateien und 8.275 Tests; 60 Tests sind bewusst übersprungen.
  • 2026-08-01 · 6/6 fachliche DoD = 100 % done: API-Key-App und providerneutraler Adapter, separater Bearer-Webhook-Secret-Vertrag, öffentlicher RLS-gesicherter post_call-Ingress, Auto-Match/Lead/Activity/Automation, Provider-Auswahl/-Wechsel, Click-to-Call-Fallback, providerneutrale Call-Details und Interim-/Visual-Baselines umgesetzt.
  • Proof: Commits 001f56a6e (Adapter), fb07d6c25 (Ingress/RLS/Worker), a99feb1b5 (Setup/UI) und f27875781 (Merge-Migration/RLS-Vertrag). Root-Typecheck, Lint, i18n, Hot-Swap, Source-Health, CI-Baseline, Secret-Scan, Prisma-Migrations-Parität und Tenant-Policy-Contract sind grün. Der vollständige Testlauf besteht mit 1.174 Dateien und 8.267 Tests; 60 Tests sind bewusst übersprungen.
  • Merge-Gate 2026-08-01 · grün: Die forward-only Phasenmigrationen 20260801221000_vr_p33_hallopetra_provider_enum und 20260801221500_vr_p33_hallopetra_telephony ergänzen TelephonyProvider.hallopetra, den RLS-Bootstrap-Resolver, providerfähige Connection-Policies und kommentiertes Inverse-SQL. Alle 32 Migrationen wurden erfolgreich gegen eine leere temporäre PostgreSQL-Datenbank angewendet; vollständige Legacy-Adoption, partieller Legacy-Nachzug und Fresh-Baseline sind kataloggleich. Der vollständige Forced-RLS-Lauf inklusive realem HalloPetra-Connection-Create/Delete unter der App-Rolle besteht mit 48/48 Kernprüfungen; Schema und Migration-Chain sind identisch.
  • Merge-/Staging-Proof 2026-08-01 · grün: PR #340 wurde mit erhaltener Commit-Historie normal gemergt (e7c6a138a). Alle 12 PR-Checks einschließlich SDK-Drift, Docker-Smoke und Database-Checks sind grün; der automatische Staging-Deploy 11719 ist erfolgreich. Web und API melden auf /healthz und /readyz die Revision e7c6a138a; die geschützte Telefonie-Route redirectet unauthentifiziert zum Login. Der öffentliche HalloPetra-Ingress antwortet bei fehlendem oder unbekanntem Bearer-Secret neutral mit 202, ohne einen Tenant offenzulegen oder Daten anzulegen. Der bereitgestellte HalloPetra-Key passiert weiterhin das Provider-Auth-Gateway, ein falscher Key wird mit 401 abgewiesen.
  • Betriebsübergabe: Der Tenant-Owner verbindet den Key einmalig in /:tenant/settings/integrations/telephony und hinterlegt danach URL plus separat erzeugtem Bearer-Secret als post_call-Webhook im HalloPetra-Dashboard. Ohne authentifizierten Tenant-Zugang wurde bewusst kein Staging-Secret erzeugt und keine Provider-Konfiguration verändert. Davids finale Optik bleibt design-nachzug und blockiert nach AD-28 nicht die fachliche DoD.