Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,110 @@
# Boilerplate-Abgleich: M12 — Telefonie (AirCall + HalloPetra)
| Feld | Wert |
|---|---|
| **Modul-ID** | M12 |
| **Name** | Telefonie (AirCall + HalloPetra) |
| **Milestones** | M105 (HalloPetra-Adapter), M106 (AirCall-Adapter), M107 (Anruf-Eingang + Auto-Match), M108 (Anruf-Ausgang / Click-to-Call), M109 (Voicemail + Notizen + Automation-Trigger) |
| **Block** | Block 5 — Kommunikation (Pflichtenheft Modul 12, [N16, 09.05.2026]) |
| **Sidebar-Gruppe** | KOMMUNIKATION → Telefonie (INTEGRATION-CONTRACTS §1) |
| **Reuse-Level** | **medium** |
> **Verifikations-Hinweis:** Alle Befunde wurden per Grep/Read direkt in `/Users/raffaelsheikh/Documents/GitHub/boilerplate` geprüft, nicht nur aus der Inventur übernommen. Das Kern-Ergebnis: **Es gibt KEINE Telefonie-, Call-, Phone-, VoIP-, AirCall- oder HalloPetra-Artefakte** in der Boilerplate (weder Prisma-Modell, noch Service, noch Route, noch UI). Die gesamte Telefonie-Domäne ist neu zu bauen. Was die Boilerplate liefert, sind **starke Querschnitts-Fundamente und ein direkt passendes Adapter-Registry-Pattern** (`marketing-outbound`), das als Vorlage für den `TelephonyProviderInterface` dient.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `packages/marketing-outbound/src/types.ts` (`MarketingOutboundAdapter`, `parseConfig`/`send`, `AdapterContext`, `AdapterResult`, `MarketingAdapterConfigError`) + `packages/marketing-outbound/src/index.ts` (`adapterRegistry`, `resolveAdapter(type)`, `ADAPTER_TYPES`) | Adapter-Interface + Registry + Resolver — strukturell exakt das, was der Spec-Block H `TelephonyProviderInterface` (connect/disconnect/listProviderUsers/triggerOutboundCall/subscribeToWebhooks/verifyWebhookSignature/parseWebhookEvent/getRecordingUrl) braucht | **als-vorlage** (Form 1:1 übernehmbar, AirCall-/HalloPetra-spezifische Methoden/Configs ergänzen) |
| `packages/foundation/src/adapters.ts` (`defineAdapter()`, `getAdapter()`, `AdapterStatus`) | Globales Adapter-Register-Primitiv (von AGENTS.md M008-M010 als Apps-Engine-Seam referenziert); `AdapterStatus` = `not_configured/configured/healthy/degraded/unavailable` deckt `connection_status` + Health-Check ab | **1:1** (Status-Enum auf Telephony-Connection mappen) |
| `apps/web/app/utils/api/.server/CryptoApi.ts` (`encrypt`/`decrypt`, AES-256-GCM, versioniert, `CRYPTO_SECRET`) | Verschlüsselung der OAuth-Tokens + Webhook-Secret (`oauth_access_token_encrypted`, `oauth_refresh_token_encrypted`, `webhook_secret_encrypted`) | **1:1** |
| `packages/api-client-ts/src/webhooks.ts` (`verifyWebhookSignature`, `signWebhookPayload`, HMAC-SHA256 über `${timestamp}.${payload}`, 5-Min-Replay-Fenster, `timingSafeEqual`) | Webhook-Signatur-Verifikation für eingehende AirCall/HalloPetra-Webhooks (Spec Block D, `signature_valid`) | **anpassen** (AirCall nutzt eigenes Signatur-Schema/Header — Logik als Vorlage, Provider-Format einsetzen) |
| `apps/web/app/routes/oauth/github/start.server.ts` (`createGitHubOAuthPkceChallenge`, state/verifier/PKCE) + `apps/web/app/routes/oauth/github/callback.tsx` (state-Validierung, code→token-Exchange, Session-Roundtrip) | OAuth-Authorization-Code-Flow-Template für AirCall-Connect (Spec Block B, Schritt 1) | **als-vorlage** (GitHub-spezifisch; AirCall-OAuth-Endpunkte/Scopes `public_api`, Token-Storage encrypted ersetzen) |
| `apps/worker/src/jobs/push-notification.ts` (provider-pluggable FCM/APNs/WebPush-Fan-out, `revokedAt`-Invalidierung) + `prisma/schema/notifications.prisma` (`DeviceToken`, `NotificationDelivery`, `UserNotificationPreference`) + `packages/foundation/src/notifications.ts` (`NotificationInput`-Typen) | Push-Benachrichtigung bei eingehendem Anruf (`call.ringing_on_agent`, Spec Block D + 12.5.7) + verpasster-Anruf-Notification — **kein Direkt-Push, sondern über M011-Pipeline** | **1:1** (Notify-Aufruf gemäß INTEGRATION-CONTRACTS §7; Telephony liefert nur `notify({...})`) |
| `apps/worker/src/jobs/workflow-trigger.ts` + `workflow-trigger-store.ts` + `workflow-trigger-native-executor.ts` (`WorkflowTriggerJobData`, `findLiveEventWorkflows`, Outbox-Queue `outbox.workflow`, Filter/Condition-Auswertung) + `prisma/schema/workflows.prisma` (`Workflow`, `WorkflowBlock`, `WorkflowBlockCondition`) | Automation-Engine-Trigger-Auslösung für `call.received/answered/completed/missed` (Spec Block F) — M12 publiziert nur Outbox-Events, der Trigger-Apparat existiert | **1:1** (Trigger-Event-Typen + Payload aus M12 in bestehende Workflow-Trigger-Pipeline einspeisen) |
| `packages/db/src/outbox.ts` (`publishOutboxEvent(tx, args)`, `OUTBOX_EVENT_TYPE_PATTERN` `<domain>.<entity>.<verb>`) + `prisma/schema/outbox.prisma` (`OutboxEvent`, `dispatchKey @unique`) | Transaktionale Event-Auslieferung für Webhook-Verarbeitung → Activity / Notification / Automation-Trigger (atomarer Side-Effect) | **1:1** |
| `packages/queue/*` (`queueNames`, `enqueueJob`, `buildIdempotentJobId`, `createWorker`, Prioritäten) | Async-Verarbeitung: Webhook-Event-Processing, Token-Refresh-Worker (24h-Cron, Spec Block B Reconnect), Health-Check | **1:1** (neue Queue-Namen + Job-Payloads ergänzen) |
| `apps/web/app/utils/leads/marketingIntegrations.db.server.ts` + `apps/web/app/routes/admin/marketing-integrations.tsx` (verschlüsselte `configJson`-Integration + Setup-/Verbindungs-UI) | Vorlage für Integration-Setup-Route `/settings/integrations/telephony/` (Connect, Test, Disconnect, encrypted Config) | **als-vorlage** |
| `prisma/schema/appsEngine.prisma` (`App` mit `@@unique([tenantId, type])`, `DataConnection` mit encrypted `config`, `AppSyncRun`/`AppSyncRunLog`/`AppSyncItem`) | Datenmodell-Muster für „1 Connection pro Tenant" + verschlüsselte Credentials + Sync-Lauf-Log. **Achtung:** nur Schema, KEIN Service/Worker — siehe Lücken | **als-vorlage** (Muster für `TelephonyConnection` `@@unique([tenant_id, provider])`; nicht direkt verwendbar) |
| `apps/web/app/application/sidebar/AppSidebar.tsx` + `SidebarGroupDto.ts` + `SidebarItem.ts` + `packages/ui/src/navigation.ts` (`AppSidebar`-Adapter, shadcn/radix `SidebarPrimitives`) | Sidebar-Wiring (KOMMUNIKATION → Telefonie) mit Permission-Gate (DoD §B-6/7) | **anpassen** (HiveGrid nutzt eigene `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` gemäß AGENTS.md — Boilerplate-Sidebar ist Referenz, nicht Ziel-Ort) |
| `prisma/schema/accounts.prisma` (`TenantUser`, `User`, `Tenant`) | FK-Anker für `TelephonyUserBinding.tenant_user_id`, `TelephonyCallSession.tenant_user_id`, `connected_by_user_id` | **1:1** (existierende Identity-Modelle referenzieren) |
| `prisma/schema/core.prisma` (`AuditEvent` Hash-Kette) + `packages/db/src/audit-hash.ts` + `packages/foundation/src/audit.ts` | Audit-Trail für Connection-Setup, User-Bindings, Notiz-Edits (Spec AV #6, DoD §C-13) — automatisch via M001-Prisma-Middleware | **1:1** |
| `packages/db/src/dsgvo/user-fk-map.ts` | Pflicht-Eintrag für jeden neuen User-FK der Telephony-Modelle (`tenant_user_id`, `manual_override_user_id`, `note_updated_by_user_id`, `connected_by_user_id`) — CI bricht sonst | **1:1** (Wartung beim Modellbau) |
| `packages/foundation/src/idempotency.ts` + `apps/worker/src/jobs/legacy-event-receiver.ts` (`withOutboxIdempotency`) | Idempotenz für Webhook-Events (`TelephonyWebhookEvent.provider_event_id`, Spec Block A) | **1:1** |
| `apps/web/app/routes/api.embed.forms.$formKey.submit.tsx` (public inbound-POST-Endpoint mit Origin/Anti-Spam-Verarbeitung) | Strukturvorlage für Webhook-Endpoint `/api/v1/webhooks/telephony/aircall/{tenant_slug}` (Spec Block D) | **als-vorlage** |
---
## Vorhandene Daten-Modelle (konkret)
**Direkt referenzierbar (existieren):**
- `prisma/schema/accounts.prisma` — `Tenant`, `TenantUser`, `User` → FK-Ziele für alle Telephony-Modelle. (Hinweis: `Tenant.country` existiert **nicht** — Default-Country für E.164-Normalisierung muss neu modelliert/aus Tenant-Setting kommen.)
- `prisma/schema/notifications.prisma` — `NotificationDelivery`, `UserNotificationPreference`, `DeviceToken` (APNs/FCM/WebPush) → Push bei Inbound/Missed.
- `prisma/schema/workflows.prisma` — `Workflow`, `WorkflowBlock`, `WorkflowBlockCondition*` → Automation-Trigger-Konsum.
- `prisma/schema/outbox.prisma` — `OutboxEvent` → transaktionale Event-Auslieferung.
- `prisma/schema/core.prisma` — `AuditEvent`, `IdempotencyKey`, `Credential` (globaler Secret-Store) → Audit + Idempotenz.
- `prisma/schema/appsEngine.prisma` — `App`/`DataConnection`/`AppSyncRun*` → **nur als Schema-Muster** (kein Service-/Worker-Layer dahinter).
**Telephony-spezifische Modelle — KOMPLETT NEU (existieren nicht in der Boilerplate):**
- `TelephonyConnection` — neu (Spec Block A). Muster aus `App`/`DataConnection` übernehmbar (`@@unique([tenant_id, provider])`, encrypted config).
- `TelephonyUserBinding` — neu (AirCall/HalloPetra-User ↔ TenantUser).
- `TelephonyCallSession` — neu (zentrales Anruf-Modell, inkl. `matched_contact_id/lead_id/deal_id/project_id`).
- `TelephonyWebhookEvent` — neu (append-only Webhook-Roh-Log, Retention 30/90 Tage).
- Enums (`provider`, `direction`, `call status`, `match_confidence`, `event_type`, `processing_status`) — neu.
- Alle neuen Telephony-Modelle gehören in `prisma/schema/app.prisma` (HiveGrid-Platzhalter) oder ein neues `prisma/schema/telephony.prisma`.
---
## Lücken / komplett neu zu bauen
1. **Gesamte Telefonie-Domäne** — Verifiziert: 0 Treffer für `telephon|aircall|hallopetra|sipgate|voicemail|click-to-call|call-session` in `prisma/schema/`, `apps/web/app`, `packages/ui*`, `packages/view-models`. Datenmodelle, Domain-Logik, Routes, View-Models, UI: alles neu.
2. **AirCall-Adapter** (M106) — AirCall-OAuth (`public_api`-Scope), `POST /users/{id}/calls`, `GET /users`, Webhook-Subscription-Anlage, Recording-URL-Abruf, AirCall-Signatur-Verifikation. Kein AirCall-SDK/Code vorhanden.
3. **HalloPetra-Adapter** (M105) — kein Code, keine Referenz. Eigene Implementierung des `TelephonyProviderInterface`; Click-to-Call-Detection mit `tel:`-Fallback; Vorqualifikations-Tag → Lead/Activity.
4. **Telefonnummer-Normalisierung (E.164)** — `libphonenumber`/`awesome-phonenumber` ist **keine** Dependency (verifiziert: leer in allen package.json). Library + Normalisierungs-Helfer komplett neu; Default-Country-Quelle ebenfalls neu (kein `Tenant.country`).
5. **Activity-Stream** — Kein `Activity`-Modell, kein `logActivity`-Service in der Boilerplate (M045 ist HiveGrid-eigener Querschnitt, noch nicht gebaut). Anruf-Activities (`call_inbound/outbound/missed/note_added/note_edited`) hängen an M045. **Vorbedingung, nicht aus BP übernehmbar.**
6. **CRM-Entitäten zum Matchen fehlen** — `Contact`, `ContactPhone`, `Deal`, `Project` existieren **nicht** in der Boilerplate (nur operator-scoped `Lead` aus `marketingLeads.prisma`, ohne `phone`-Feld). Auto-Match (Spec Block D) hängt vollständig an HiveGrid-CRM (M042-M046 Kontakte, M059-M064 Sales, M065-M070 Aufträge, Lead-Inbox M047-M051). **Harte Vorbedingung.**
7. **appsEngine ist Schema-only** — Verifiziert: kein Worker-Job/Service konsumiert `AppSyncRun`/`DataConnection`. Die „Apps-Engine" mit Code ist das `marketing-outbound`-Pattern + WASM-`plugin-runtime` (in Prod nur `log`/`audit`-Capabilities aktiv, `http.outbound` ist `productionAvailable: false`). → Provider-Adapter müssen als regulärer Server-/Worker-Code laufen (Pattern: `marketing-outbound`), **nicht** im WASM-Sandbox.
8. **Outbound HTTP zu Provider-APIs** — `adapterFetch()` (SSRF-Guard, Timeout) existiert in `marketing-outbound`, ist aber auf das interne Adapter-Set gemünzt. AirCall/HalloPetra-API-Clients (Auth-Header, Rate-Limit-/Quota-Handling, Klartext-Diagnose pro HTTP-Code laut Spec Block H) neu.
9. **Token-Refresh-Worker** (24h-Cron, <72h-Restlaufzeit → erneuern; Refresh-Fehler → `revoked` + Notify) — Cron-Worker-Muster vorhanden (`*-cron.ts`), Logik neu.
10. **Notiz-Editor + Markdown** (M109, Spec Block E) — UI + `note_text`-Persistenz + Audit-on-Edit; kein vorgefertigter Anruf-Notiz-Baustein.
11. **Permissions** — `telephony.*`-Keys (`click_to_call`, `read_own/all`, `write_notes_own/all`, `admin`) + Bundle-Mapping neu in `packages/entitlements/src/permissions.ts`; RBAC-Fundament (`permissions.prisma`, `withTenantScope`/`withPermission`) existiert.
12. **i18n-Keys** — Keine `telephony`-Locale-Datei; i18n-Runtime (`packages/i18n`) vorhanden, aber `packages/i18n/src/locales/de/telephony.json` neu (DoD §B-10).
13. **View-Models** — `packages/view-models/src/` ist Skelett (nur `index.ts`). Alle Telephony-VMs (Connection-Status, Call-Liste, Call-Detail, User-Binding-Liste) neu.
14. **Subframe-UI** — Spec nennt Designs explizit als offen; UI komplett zu entwerfen + via Adapter integrieren (DoD §A-4, Subframe-Pflicht laut User-Memory).
---
## Empfohlenes Vorgehen (Reihenfolge)
**Phase 0 — Vorbedingungen prüfen (nicht aus BP, hängt an anderen HiveGrid-Modulen):**
- CRM-Kontakt/`ContactPhone`/Lead/Deal/Project (M042-M070) müssen existieren, bevor Auto-Match (M107) sinnvoll ist.
- Activity-Stream-Querschnitt M045 (`logActivity`) muss stehen (M107/M109 schreiben darauf).
- Notification-Service M011 (`notify`) + Permission-Querschnitt M004 + i18n M003 sind harte Querschnitt-Voraussetzungen (laut AGENTS.md vorhanden bzw. zu bauen).
**Phase 1 — Fundament aus BP übernehmen (zuerst):**
1. `TelephonyProviderInterface` definieren — Form aus `packages/marketing-outbound/src/types.ts` + `foundation/adapters.ts` (`defineAdapter`) übernehmen, Telephony-Methoden ergänzen (Spec Block H).
2. Datenmodelle (`TelephonyConnection/UserBinding/CallSession/WebhookEvent` + Enums) in `prisma/schema/` anlegen, Muster `@@unique([tenant_id, provider])`/encrypted-config aus `appsEngine.prisma`; FK auf `TenantUser`; `user-fk-map.ts` ergänzen; Forward-Only-Migration mit Inverse-SQL (DoD §F-28).
3. Token-Verschlüsselung 1:1 aus `CryptoApi.ts`; Webhook-HMAC-Verify-Logik aus `api-client-ts/src/webhooks.ts` als Vorlage.
4. Permissions (`telephony.*`) + Bundles in `packages/entitlements`; i18n-Keys; Sidebar-Eintrag (KOMMUNIKATION → Telefonie) mit Gate.
**Phase 2 — Adapter + Connect-Flow (M106 AirCall, dann M105 HalloPetra):**
5. AirCall-Adapter implementieren; OAuth-Flow nach Vorlage `oauth/github/start.server.ts`/`callback.tsx` (PKCE/state/Session); Setup-Route nach Vorlage `routes/admin/marketing-integrations.tsx`; Token-Refresh-Cron nach `*-cron.ts`-Muster.
6. HalloPetra-Adapter (gleiches Interface), Click-to-Call-Detection + `tel:`-Fallback.
**Phase 3 — Anruf-Verarbeitung:**
7. Webhook-Endpoint (Vorlage `api.embed.forms.$formKey.submit.tsx`) → `TelephonyWebhookEvent` (idempotent via `withOutboxIdempotency`) → `publishOutboxEvent` → Worker (Queue-Pattern).
8. E.164-Normalisierung (neue `libphonenumber`-Dependency) + Auto-Match (M107) gegen CRM; Push via `notify()` (M011); verpasste Anrufe + Rückruf-Aufgabe.
9. Click-to-Call (M108) aus Kontakt/Deal/Lead über Adapter `triggerOutboundCall`; ausgehender Anruf auto-protokolliert.
**Phase 4 — Notizen, Voicemail, Automation (M109):**
10. Notiz-Editor + Audit-on-Edit; Recording-Link (kein Re-Hosting); Automation-Trigger als Outbox-Events in die bestehende `workflow-trigger`-Pipeline einspeisen.
**Querschnitt durchgehend:** View-Models (M013), Klartext-Fehler (M002), Empty/Loading-States, Smoke- + Hot-Swap-Tests, Visual-Regression, Feature-Flag (M006) — alle gemäß DoD.
---
## Reuse-Level-Begründung: medium
Die **Telefonie-Domäne selbst existiert zu 0%** (kein Modell, kein Service, kein UI). Aber die Boilerplate liefert **mehr als nur Fundament**: ein strukturell direkt passendes Adapter-Registry-Pattern (`marketing-outbound`), einen verwendbaren OAuth-Flow, fertige Verschlüsselung, HMAC-Webhook-Verify, eine komplette Push-/Notification-Pipeline, die Automation-Trigger-Pipeline und das Outbox/Queue/Audit/Idempotenz-Querschnitt-Set. Das hebt M12 über „low" (nur Querschnitt) — die nennenswerten Lücken (Provider-Adapter, CRM-Match-Abhängigkeit, E.164-Normalisierung, Activity-Stream-Abhängigkeit, gesamtes UI) verhindern „high". → **medium**.