62 lines
5.7 KiB
Markdown
62 lines
5.7 KiB
Markdown
# VR-P33 · Telefonie-Erweiterung HalloPetra (M105)
|
|
|
|
> ⚠️ **KI→MCP-Pivot ([[AD-26]]):** Der **Whisper-Voicemail-Transkriptions-Andock entfällt** (kein Whisper/LLM mehr — VR-P25 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/Deal), 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/Deal + Match-Confidence), Aufnahme-Link, Notiz-Editor |
|
|
|
|
*(Click-to-Call ist ein Quick-Action-Element auf Contact/Lead/Deal-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/Deal → 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/Deal (Match-Confidence) → Activity-Stream + Automation-Trigger (`call.*`).
|
|
- **Konnektor:** `tenantHasModule('telephony')`; Provider-Auswahl im Setup.
|
|
- ~~**Whisper-Kopplung:** Voicemail-Transkription via VR-P25 (Whisper-EU), optional/später.~~ → **entfällt ([[AD-26]]: kein Whisper/LLM; VR-P25 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
|