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/boilerplategeprü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 denTelephonyProviderInterfacedient.
Ü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.countryexistiert 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 ausApp/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 neuesprisma/schema/telephony.prisma.
Lücken / komplett neu zu bauen
- Gesamte Telefonie-Domäne — Verifiziert: 0 Treffer für
telephon|aircall|hallopetra|sipgate|voicemail|click-to-call|call-sessioninprisma/schema/,apps/web/app,packages/ui*,packages/view-models. Datenmodelle, Domain-Logik, Routes, View-Models, UI: alles neu. - 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. - HalloPetra-Adapter (M105) — kein Code, keine Referenz. Eigene Implementierung des
TelephonyProviderInterface; Click-to-Call-Detection mittel:-Fallback; Vorqualifikations-Tag → Lead/Activity. - Telefonnummer-Normalisierung (E.164) —
libphonenumber/awesome-phonenumberist keine Dependency (verifiziert: leer in allen package.json). Library + Normalisierungs-Helfer komplett neu; Default-Country-Quelle ebenfalls neu (keinTenant.country). - Activity-Stream — Kein
Activity-Modell, keinlogActivity-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. - CRM-Entitäten zum Matchen fehlen —
Contact,ContactPhone,Deal,Projectexistieren nicht in der Boilerplate (nur operator-scopedLeadausmarketingLeads.prisma, ohnephone-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. - appsEngine ist Schema-only — Verifiziert: kein Worker-Job/Service konsumiert
AppSyncRun/DataConnection. Die „Apps-Engine" mit Code ist dasmarketing-outbound-Pattern + WASM-plugin-runtime(in Prod nurlog/audit-Capabilities aktiv,http.outboundistproductionAvailable: false). → Provider-Adapter müssen als regulärer Server-/Worker-Code laufen (Pattern:marketing-outbound), nicht im WASM-Sandbox. - Outbound HTTP zu Provider-APIs —
adapterFetch()(SSRF-Guard, Timeout) existiert inmarketing-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. - Token-Refresh-Worker (24h-Cron, <72h-Restlaufzeit → erneuern; Refresh-Fehler →
revoked+ Notify) — Cron-Worker-Muster vorhanden (*-cron.ts), Logik neu. - Notiz-Editor + Markdown (M109, Spec Block E) — UI +
note_text-Persistenz + Audit-on-Edit; kein vorgefertigter Anruf-Notiz-Baustein. - Permissions —
telephony.*-Keys (click_to_call,read_own/all,write_notes_own/all,admin) + Bundle-Mapping neu inpackages/entitlements/src/permissions.ts; RBAC-Fundament (permissions.prisma,withTenantScope/withPermission) existiert. - i18n-Keys — Keine
telephony-Locale-Datei; i18n-Runtime (packages/i18n) vorhanden, aberpackages/i18n/src/locales/de/telephony.jsonneu (DoD §B-10). - View-Models —
packages/view-models/src/ist Skelett (nurindex.ts). Alle Telephony-VMs (Connection-Status, Call-Liste, Call-Detail, User-Binding-Liste) neu. - 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):
TelephonyProviderInterfacedefinieren — Form auspackages/marketing-outbound/src/types.ts+foundation/adapters.ts(defineAdapter) übernehmen, Telephony-Methoden ergänzen (Spec Block H).- Datenmodelle (
TelephonyConnection/UserBinding/CallSession/WebhookEvent+ Enums) inprisma/schema/anlegen, Muster@@unique([tenant_id, provider])/encrypted-config ausappsEngine.prisma; FK aufTenantUser;user-fk-map.tsergänzen; Forward-Only-Migration mit Inverse-SQL (DoD §F-28). - Token-Verschlüsselung 1:1 aus
CryptoApi.ts; Webhook-HMAC-Verify-Logik ausapi-client-ts/src/webhooks.tsals Vorlage. - Permissions (
telephony.*) + Bundles inpackages/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.