Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -8,15 +8,25 @@
| **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)** |
| **Status** | Regression-Fix live · automatischer Staging-Proof grün · Browser-Bestätigung offen · 6/6 fachliche DoD |
> 🟠 **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.
> 🎨 **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.
@@ -24,22 +34,29 @@ Bindet **HalloPetra als zusätzlichen Provider** hinter dem bestehenden `Telepho
## 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 |
| 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`/`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
- [x] **HalloPetra-Adapter** implementiert `TelephonyProviderInterface` (`connect`/`triggerOutboundCall`/
`subscribeToWebhooks`/`validateWebhook`/`parseWebhookEvent`/`getRecordingUrl`) **ohne Kern-Umbau**;
`validateWebhook` setzt den in `VEXT-2` erhobenen Provider-Vertrag um
- [x] **Webhook-Auto-Match** auf Contact/Lead/Projekt → Activity + Automation-Trigger (`call.*`)
- [x] Click-to-Call + Inbound + Logging providerunabhängig (E.164-Normalisierung, Match-Confidence, Notiz-Editor)
- [x] Provider-Auswahl/-Wechsel im Setup (HalloPetra neben AirCall)
- [x] Recording-Abruf über `getRecordingUrl` (sofern HalloPetra-API liefert; derzeit belegter Vertrag ohne URL)
- [x] ⚠ **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]).
- **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.
@@ -49,13 +66,66 @@ Bindet **HalloPetra als zusätzlichen Provider** hinter dem bestehenden `Telepho
## 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)
- 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)
- `_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
- [ ] Spec/ENTITY-MODEL an reale HalloPetra-API + Davids UI-Entscheidungen angepasst *(API: erledigt; Davids Delta: offen)*
- [x] REQUIREMENTS/ROADMAP nachgezogen
- [x] 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.