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

118 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`.
</content>