Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M07-angebot-signatur.md
T

18 KiB
Raw Blame History

Boilerplate-Abgleich: M07 — Angebot + Signatur

Feld Wert
Modul-ID M07 (Modul 7)
Name Angebot + elektronische Signatur
Milestones M130 (Angebot-Erstellung / PDF-Upload + Send-Wizard), M131 (PandaDoc/DocuSign via Apps-Engine + Status-Webhooks), M132 (Status-Tracking + Auto-Stage-Wechsel + Detail-Sicht)
Pflichtenheft-Block Block 6, Modul 7 (_bmad-output/pflichtenheft/blocks/block6.md §7.1–7.9)
Detail-Spec _bmad-output/specs/M07-angebot-signatur.md
Reuse-Level low

Reuse-Verdikt (Kurzfassung)

Das Signatur-Fachdomäne selbst existiert NICHT in der Boilerplate: kein PandaDoc/DocuSign-Adapter, kein DealSignatureDocument/-Signer/-StatusTransition, kein SignatureProviderConnection, kein SignatureWebhookEvent, und — fundamental — kein Deal/Sales/Pipeline-Modell (M3), an dem das Angebot überhaupt hängt. Verifiziert per Grep über alle *.prisma/*.ts/*.tsx: die einzigen signature-Treffer sind (a) HMAC-Webhook-Verify für Stripe/MailerSend, (b) Ed25519-Plugin-Signaturen — beides themenfremd.

Wiederverwendbar ist ausschließlich das Querschnitt-Fundament + Infrastruktur-Pattern: Adapter-Registry, SSRF-sicherer Outbound-HTTP-Client, Inbound-Webhook-Handler-Vorlage (Stripe/MailerSend), HMAC-Verify, Idempotenz, Transactional-Outbox, File-Storage (Source-/Signed-PDF), appsEngine.prisma (App/DataConnection) als OAuth-Connection-Träger, sowie der komplette UI-/View-Model-/i18n-/Notification-Stack. Damit ist M07 kein "Felder einfüllen", sondern ein Neubau auf solidem Fundament — daher low (nicht none, weil die Querschnitt-Hülle und das Adapter-/Webhook-Pattern erheblich Arbeit sparen).


Übernehmbar aus Boilerplate

Boilerplate-Wurzel (NUR LESEN): /Users/raffaelsheikh/Documents/GitHub/boilerplate

Boilerplate-Pfad Was Wie nutzbar
packages/foundation/src/adapters.ts defineAdapter() / getAdapter() + AdapterStatus — Registry für den SignatureProvider-Interface-Pattern (PandaDoc/DocuSign) 1:1 als Registry-Mechanik; die konkreten Provider-Adapter (createDocument/sendDocument/getDocumentStatus/revokeDocument/handleWebhook) sind neu zu schreiben
packages/foundation/src/outbound-http.ts fetchOutboundHttpWithRedirects() mit Timeout, Redirect-Limit, SSRF-Schutz (Blockliste interner Hosts), Response-Byte-Cap 1:1 für alle PandaDoc/DocuSign-REST-Calls (PDF-Upload, Send, Status-Poll, Revoke, Reminder)
packages/foundation/src/idempotency.ts IdempotencyClient/IdempotencyResponse + Catalog-Errors, gestützt auf IdempotencyKey-Modell 1:1 für idempotente Webhook-Verarbeitung (Spec verlangt M007-Idempotenz im Webhook-Empfänger)
packages/foundation/src/errors.ts CatalogError / foundationErrors — Klartext-Diagnostik-Basis (AGENTS.md DoD §22, LP-10/AV#1) als-vorlage — HiveGrid-Klartext-Texte (PDF >25 MB, Signer ohne Email, Provider nicht erreichbar) als eigene Catalog-Einträge ergänzen
packages/foundation/src/{audit,notifications,permissions,flags}.ts Querschnitt-Hooks: Audit, notify, Permission-Checks, Feature-Flags 1:1 als Service-Aufrufe (DoD-Pflicht: Audit, Notification via notify(), Permission-Filter, Feature-Flag-fähig)
apps/api/src/billing/stripe-webhook-route.ts Vollständiger Inbound-Webhook-Handler: Signatur-Header lesen → HMAC-Verify → 400/503 bei invalid/missing → $transaction mit Outbox-Publish atomar → Metrik als-vorlage — exakte Blaupause für /api/v1/webhooks/pandadoc/{tenant_id}/{connection_id} und …/docusign/… (Provider-spezifischer Verify + Event-Mapping einsetzen)
apps/api/src/email-sequences/provider-webhook-route.ts Inbound-Provider-Webhook mit Event-Type-Mapping (MAILERSEND_BOUNCE_EVENT_TYPES-Set → Domain-Aktion) als-vorlage — gleiche Mechanik für document.viewed/signed/declined/completed/expired → DealSignatureDocument/-Signer-Update
apps/api/src/webhooks/mailersend-signature.ts verifyMailerSendWebhookSignature() (Header-Kandidaten, konstantzeit) als-vorlage für provider-spezifischen Webhook-Verify (PandaDoc/DocuSign HMAC)
packages/api-client-ts/src/webhooks.ts verifyWebhookSignature() / signWebhookPayload() — generisches konstantzeit-HMAC-SHA256 mit Replay-Window 1:1/anpassen als HMAC-Verify-Helper, falls Provider HMAC-SHA256 nutzen
apps/api/src/route-access-inventory.ts Auth-Klasse webhook-signature für Inbound-Webhook-Routen (Quelle der Wahrheit der API-Auth-Matrix) 1:1 — Signatur-Webhook-Routen unter webhook-signature registrieren
prisma/schema/appsEngine.prisma — App, DataConnection, AppSyncRun Apps-Engine-Daten-Sync-Modell: App (@@unique([tenantId, type]), config-JSON), DataConnection (verschlüsselte Credentials, type "oauth2"/"webhook"), AppSyncRun (Status/Mode/Metriken/Rollback) anpassen — SignatureProviderConnection (Spec Block A) kann auf App/DataConnection aufsetzen (data_connection_id referenziert M33a). Verschlüsselte OAuth-Tokens passen in DataConnection.config
packages/storage/src/index.ts + signed/index.ts createS3StorageAdapter() (Scaleway-S3), createSignedDownloadUrl/createSignedUploadUrl, Virus-Scan, Quarantäne 1:1 für Source-PDF-Upload (M23) + automatischen Download des signierten PDF nach document.completed (Spec §7.4.6)
prisma/schema/core.prisma — FileObject Datei-Metadaten (provider/bucket/key/contentType/byteSize/checksum/signedUrl-Timestamps) 1:1 als Speicher-Referenz für source_pdf_file_id / signed_pdf_file_id (sofern M23/Files dieses Modell adoptiert)
prisma/schema/outbox.prisma + packages/db/src/outbox.ts (publishOutboxEvent) + apps/worker/src/outbox/event-router.ts Transactional-Outbox: atomares Event-Publish in $transaction, longest-prefix-Routing (webhook., notification., mail., …) 1:1 für signature.sent/signed/declined/expired-Trigger an M17 (Spec Block G) und Notification-Fan-out an Vertriebler
apps/worker/src/jobs/form-submission-webhook-delivery.ts + packages/queue (WebhookDeliveryJob, enqueueJob, buildIdempotentJobId) Worker-Job-Pattern für (a) Reminder-Versand über Provider, (b) Status-Refresh-Poll, (c) Signed-PDF-Download als Hintergrund-Job als-vorlage — neuen Worker-Job + Queue-Payload für Signatur-Async-Arbeit anlegen
packages/queue/src/{names,payloads,producers,priority}.ts BullMQ-Wrapper: typisierte Job-Payloads, enqueueJob(), buildIdempotentJobId(), plan-basierte Prioritäten 1:1/anpassen — neue signature.*-Job-Payloads in die Map ergänzen
prisma/schema/notifications.prisma (NotificationDelivery, DeviceToken, UserNotificationPreference) + packages/realtime + apps/worker notification-Job Push/In-App-Notification-Stack (Spec §7.4: Push an Vertriebler bei Status-Änderung) 1:1 via notify()-Service (M011), NIE direkt Mail/Push
packages/view-models/src/index.ts VMState<T>, ActionCallbacks<T>, SidebarRegistryItem, BreadcrumbRegistryItem, RegistryGate{permission,flag} — die VM-/Action-Callback-Konvention (M013/M014) 1:1 — Signatur-VMs (Document-Liste, Send-Wizard, Detail) bauen auf diesen Typen
packages/ui-app/src/index.ts AppShell + createSidebarRegistry/createBreadcrumbRegistry/createMobileRegistry/createPortalRegistry/createShellRegistries, EmptyPage 1:1 — Reachability-Wiring (Sidebar-Eintrag, Breadcrumb, Empty-State) erfolgt über diese Registries. Hinweis: Paket heißt @toolctrl/ui-app, nicht das in AGENTS.md genannte ui-hivegrid — Naming-Diskrepanz (siehe Lücken)
packages/ui-subframe + packages/ui-mock Subframe-Adapter-Ziel + Hot-Swap-Mock (M015/M017) als-vorlage — Send-Wizard/Detail-Sicht via Adapter integrieren; Mock-Variante für Hot-Swap-Drill
packages/i18n/src/index.ts + useTranslate.ts (ICU) i18n-Engine mit ICU + useTranslate (M003) 1:1 — alle UI-Texte + Klartext-Fehler als i18n-Keys
packages/feature-flags/src/{evaluate,cache,publisher}.ts + prisma/schema/featureFlags.prisma Feature-Flag-Engine (M006) — Modul ohne Deploy abschaltbar (DoD-Pflicht) 1:1 — featureFlag('signature', tenant)-Gate
packages/db/src/{client.server,transactions.server,audit-hash}.ts + prisma/schema/app.prisma DB-Boundary, runDbTransaction, Audit-Hash-Kette; app.prisma = leerer Platzhalter für HiveGrid-eigene Modelle 1:1 Infrastruktur; app.prisma ist der vorgesehene Ort für alle neuen M07-Modelle
prisma/schema/permissions.prisma (Role/Permission/RolePermission/UserRole) RBAC-Fundament 1:1 — signature.read/send/revoke/admin (Spec Block H) als Permission-Einträge + Rollen-Defaults seeden
apps/api Error-Envelope + Request-ID-Middleware (middleware/error-envelope.ts, request-id.ts) Konsistentes API-Fehler-Envelope (code/message/requestId) für Webhook-Routen 1:1

Vorhandene Daten-Modelle (konkret, mit Pfad)

Direkt relevant / als Träger nutzbar:

  • prisma/schema/appsEngine.prisma → App, DataConnection, AppSyncRun, AppSyncRunLog, AppSyncItem — Apps-Engine-Connection + Sync-Lauf-Tracking. Kandidat-Basis für SignatureProviderConnection (über data_connection_id) und ggf. Status-Sync-Runs.
  • prisma/schema/core.prisma → FileObject (Source-/Signed-PDF-Metadaten), IdempotencyKey (Webhook-Idempotenz), AuditEvent (tamper-evidente Hash-Kette, Audit-Trail für Status-Transitions — Spec AV#6), Event + EventWebhookAttempt (outbound-Webhook-Delivery, NICHT inbound — Achtung), Credential.
  • prisma/schema/notifications.prisma → NotificationDelivery, UserNotificationPreference, DeviceToken — Push/In-App an Vertriebler.
  • prisma/schema/outbox.prisma → OutboxEvent — atomare signature.*-Events.
  • prisma/schema/permissions.prisma → Role, Permission, RolePermission, UserRole, Group, GroupUser — Permissions Block H.
  • prisma/schema/featureFlags.prisma → FeatureFlag, FeatureFlagFilter, FeatureFlagAudit.
  • prisma/schema/queue.prisma → QueueFailedJob (DLQ), ExportJob.
  • prisma/schema/app.prisma → leerer Platzhalter (// custom database models) — vorgesehener Ort für alle neuen M07-Modelle.

NICHT vorhanden (Kern der Lücke):

  • Kein Deal / Sale / Pipeline / Verkaufsfall / Stage / Opportunity-Modell (verifiziert per Grep). M07 hängt komplett an M3 (M059–M064), das ebenfalls neu gebaut wird. → deal_id, Auto-Stage-Wechsel und Activity-Stream-Anker existieren noch nicht.
  • Kein SignatureProviderConnection, DealSignatureDocument, DealSignatureSigner, DealSignatureStatusTransition, SignatureWebhookEvent (alle aus Spec Block A) — komplett neu.
  • Kein Contact/Kontakt-Modell (für linked_contact_id / Signer-Vorbefüllung aus M1) — neu in M042–M046.
  • Kein Activity-Stream-Modell (logActivity / M045) — neu.

Lücken / komplett neu zu bauen

  1. Daten-Modell (Block A) — komplett neu in prisma/schema/app.prisma:
    • SignatureProviderConnection (tenant, data_connection_id→DataConnection, provider pandadoc|docusign, is_default)
    • DealSignatureDocument (deal_id, provider_connection_id, provider_document_id, title, status-Enum draft|sent|viewed|signed|declined|expired|revoked, sent/signed/expires_at, source_pdf_file_id, signed_pdf_file_id, archived_at)
    • DealSignatureSigner (document_id, position, email/name/role, linked_contact_id, status pending|viewed|signed|declined, signed_at, ip_at_signing, user_agent_at_signing)
    • DealSignatureStatusTransition (from/to_status, transitioned_at, triggered_by user|provider_webhook|system_timeout, metadata) — Audit-Historie
    • SignatureWebhookEvent (provider_connection_id, received_at, event_type, payload, signature_validation_status, processed_at) — Inbound-Log
    • Pflicht-Begleitung: packages/db/src/dsgvo/user-fk-map.ts ergänzen (sonst CI-Bruch), Forward-Only-Migration mit Inverse-SQL-Kommentar.
  2. PandaDoc-Provider-Adapter — neu: createDocument(pdf, signers), sendDocument, getDocumentStatus, revokeDocument, handleWebhook, OAuth2-Connect über M33a, Reminder-Email-Trigger. Nur die Adapter-Registry-Mechanik (defineAdapter) + Outbound-HTTP-Client sind vorhanden.
  3. DocuSign-Provider-Adapter — neu (analog).
  4. Inbound-Webhook-Routen /api/v1/webhooks/pandadoc/{tenant_id}/{connection_id} + …/docusign/… — neu, aber Stripe/MailerSend-Route als 1:1-Blaupause. Provider-spezifischer HMAC-Verify + Event-Mapping (document.viewed|signed|declined|completed|expired) neu.
  5. Send-Flow-Wizard (Block C, 5 Schritte) im Deal-Detail — neue UI (PDF-Picker reuse aus M046, Signer-Konfig, Sequenz seriell/parallel, Provider-Auswahl, Send) + View-Models + Action-Callbacks.
  6. Status-Tracking-Verarbeitung (Block D) — neuer Worker-/Service-Pfad: Webhook → Status-Update + StatusTransition + Activity-Stream + Notification + (bei completed) Signed-PDF-Download in M23 + signature.signed-Trigger für M17.
  7. Auto-Stage-Wechsel (M132) — neu, hängt an M3-Deal-Stage (existiert noch nicht); Tenant-Konfig-Toggle „Auto-Stage-Wechsel" neu.
  8. Multi-Signer-Sequenz-Logik (Block E) seriell/parallel — neu.
  9. Detail-Sicht im Deal (Block D/§7.5): Document-Liste, Pro-Signer-Status, Original-/Signed-PDF-Download, Reminder/Revoke/Resend/Refresh-Operationen — neue UI.
  10. Permissions seeden: signature.read/send/revoke/admin + Rollen-Defaults (GF→admin; Vertrieb→read+send+revoke).
  11. Activity-Stream-Wiring (logActivity/M045) — Service existiert in der Boilerplate nicht als HiveGrid-@hivegrid/activity; HiveGrid baut M045 selbst (außerhalb M07-Scope, aber Abhängigkeit).
  12. Naming-Diskrepanz Boilerplate↔HiveGrid-Contracts: AGENTS.md/INTEGRATION-CONTRACTS referenzieren Pakete @hivegrid/* (packages/ui-hivegrid, @hivegrid/notifications, @hivegrid/activity, @hivegrid/audit) und sidebar.config.ts; in der Boilerplate heißen sie @toolctrl/* (ui-app, foundation, view-models) mit Registry-Funktionen statt sidebar.config.ts. → Vor M07 klären, ob die EU-Sterilisierung/Rebranding @toolctrl/*→@hivegrid/* bereits erfolgt ist oder M07 die Boilerplate-Namen nutzt.

Empfohlenes Vorgehen (Reihenfolge)

Vorbedingungen (außerhalb M07, müssen stehen): M3-Deal-Modell (M059–M064), M23-Files (M052–M055), M33a-Apps-Engine-Adapter (M008–M010), M045-Activity-Stream, M001-Audit, M011-Notifications, M002-Error-Catalog. M07 dockt daran an — ohne Deal-Modell kein deal_id.

  1. Daten-Layer zuerst (M130-Basis): Die 5 Block-A-Modelle in prisma/schema/app.prisma definieren; SignatureProviderConnection auf appsEngine.prisma-DataConnection aufsetzen (OAuth-Token in config verschlüsselt). FileObject für Source-/Signed-PDF referenzieren. user-fk-map.ts ergänzen, Forward-Only-Migration + Inverse-SQL-Kommentar. Permissions seeden.
  2. Querschnitt 1:1 übernehmen, nicht nachbauen: foundation (adapters/outbound-http/idempotency/errors/audit/notifications/permissions/flags), db (client/transactions/outbox), view-models, ui-app-Registries, i18n, feature-flags, storage, queue, notifications. Feature-Flag signature als erstes Gate.
  3. M130 — Send-Flow-UI: 5-Schritt-Wizard im Deal-Detail. PDF-Picker aus M046 reusen. VMs nach view-models-Konvention, Action-Callbacks, Subframe-Adapter, i18n + Klartext-Catalog (25-MB-/Email-/Provider-Hinweise). Sidebar/Breadcrumb-Wiring via ui-app-Registries (bzw. Inline-Verlinkung aus Deal — Modul ist deal-kontextuell, kein eigener Top-Level-Sidebar-Eintrag nötig, das im Milestone dokumentieren).
  4. M131 — Provider-Adapter + Webhooks: PandaDoc zuerst (Standard), DocuSign analog, je via defineAdapter + fetchOutboundHttpWithRedirects. Inbound-Webhook-Routen nach Stripe-/MailerSend-Blaupause (webhook-signature-Auth-Klasse, HMAC-Verify, $transaction+Outbox, Idempotenz via IdempotencyKey). SignatureWebhookEvent-Log schreiben.
  5. M132 — Status-Tracking + Auto-Aktionen: Worker-Job (nach form-submission-webhook-delivery-Vorlage) für Signed-PDF-Download (storage signed-URL → FileObject → M23), StatusTransition-Audit, notify() an Vertriebler, signature.*-Outbox-Events für M17, optional Auto-Stage-Wechsel (Tenant-Toggle, hängt an M3-Stage). Detail-Sicht im Deal mit Reminder/Revoke/Resend/Refresh.
  6. DoD-Abschluss: Unit-Tests für VM-Builder (Zod), Smoke-Test (e2e/smoke/signature.spec.ts), Hot-Swap-Drill gegen ui-mock, Visual-Regression-Snapshot, Permission-Denied→404, Empty-/Loading-States mit Klartext, Rollback-Pfad dokumentiert.

Quellen (verifiziert per Read/Grep am 2026-06-04)

  • Boilerplate: prisma/schema/{appsEngine,core,notifications,outbox,permissions,featureFlags,queue,app}.prisma; packages/foundation/src/{adapters,outbound-http,idempotency,errors}.ts; packages/{view-models,ui-app,i18n,feature-flags,storage,queue}/src/; apps/api/src/billing/stripe-webhook-route.ts, apps/api/src/email-sequences/provider-webhook-route.ts, apps/api/src/webhooks/mailersend-signature.ts, apps/api/src/route-access-inventory.ts; packages/api-client-ts/src/webhooks.ts; apps/worker/src/outbox/event-router.ts.
  • Negativ-Befund (Grep, kein Treffer als Domäne): pandadoc|docusign|esignature|DealSignature|SignatureProviderConnection; model (Deal|Sale|Pipeline|Verkauf|Opportunity|Stage).
  • HiveGrid: _bmad-output/specs/M07-angebot-signatur.md, _bmad-output/pflichtenheft/blocks/block6.md, docs/milestones/M13{0,1,2}-*/PLAN.md, AGENTS.md, docs/INTEGRATION-CONTRACTS.md, docs/boilerplate-inventory/{domain-packages,integrations-ki,data-layer,apps-infra}.md.