Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M12-telefonie.md
T

16 KiB

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.