18 KiB
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ürSignatureProviderConnection(überdata_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— atomaresignature.*-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ürlinked_contact_id/ Signer-Vorbefüllung aus M1) — neu in M042–M046. - Kein Activity-Stream-Modell (
logActivity/ M045) — neu.
Lücken / komplett neu zu bauen
- Daten-Modell (Block A) — komplett neu in
prisma/schema/app.prisma:SignatureProviderConnection(tenant,data_connection_id→DataConnection,providerpandadoc|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-HistorieSignatureWebhookEvent(provider_connection_id, received_at, event_type, payload, signature_validation_status, processed_at) — Inbound-Log- Pflicht-Begleitung:
packages/db/src/dsgvo/user-fk-map.tsergänzen (sonst CI-Bruch), Forward-Only-Migration mit Inverse-SQL-Kommentar.
- 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. - DocuSign-Provider-Adapter — neu (analog).
- 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. - 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.
- 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. - Auto-Stage-Wechsel (M132) — neu, hängt an M3-Deal-Stage (existiert noch nicht); Tenant-Konfig-Toggle „Auto-Stage-Wechsel" neu.
- Multi-Signer-Sequenz-Logik (Block E) seriell/parallel — neu.
- Detail-Sicht im Deal (Block D/§7.5): Document-Liste, Pro-Signer-Status, Original-/Signed-PDF-Download, Reminder/Revoke/Resend/Refresh-Operationen — neue UI.
- Permissions seeden:
signature.read/send/revoke/admin+ Rollen-Defaults (GF→admin; Vertrieb→read+send+revoke). - 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). - Naming-Diskrepanz Boilerplate↔HiveGrid-Contracts: AGENTS.md/INTEGRATION-CONTRACTS referenzieren Pakete
@hivegrid/*(packages/ui-hivegrid,@hivegrid/notifications,@hivegrid/activity,@hivegrid/audit) undsidebar.config.ts; in der Boilerplate heißen sie@toolctrl/*(ui-app,foundation,view-models) mit Registry-Funktionen stattsidebar.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.
- Daten-Layer zuerst (M130-Basis): Die 5 Block-A-Modelle in
prisma/schema/app.prismadefinieren;SignatureProviderConnectionaufappsEngine.prisma-DataConnectionaufsetzen (OAuth-Token inconfigverschlüsselt).FileObjectfür Source-/Signed-PDF referenzieren.user-fk-map.tsergänzen, Forward-Only-Migration + Inverse-SQL-Kommentar. Permissions seeden. - 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-Flagsignatureals erstes Gate. - 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 viaui-app-Registries (bzw. Inline-Verlinkung aus Deal — Modul ist deal-kontextuell, kein eigener Top-Level-Sidebar-Eintrag nötig, das im Milestone dokumentieren). - 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 viaIdempotencyKey).SignatureWebhookEvent-Log schreiben. - M132 — Status-Tracking + Auto-Aktionen: Worker-Job (nach
form-submission-webhook-delivery-Vorlage) für Signed-PDF-Download (storagesigned-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. - DoD-Abschluss: Unit-Tests für VM-Builder (Zod), Smoke-Test (
e2e/smoke/signature.spec.ts), Hot-Swap-Drill gegenui-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.