# AK-P16d · P16 Angebot/Signatur (SES-Default + BYOK-Adapter) | | | |---|---| | **Typ** | Dev (Code) | | **Owner** | Akeshan | | **Phase** | P16 — Kalender, Booking, Forms & Signatur | | **Cycle/Fenster** | W4 — USP, Härtung & Launch · fällig 2026-07-07 · Gate W4 | | **Status** | Done (2026-07-11) · Interim-UI (AD-28) steht, design-nachzug offen · Audit 2026-07-17: PandaDoc-Webhook-Route verdrahtet + Webhook-Activity + Signatur-e2e → 9/9 DoD | **🎨 design-nachzug: offen** (seit 2026-07-11) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-P16` ausstehend. > ⚠️ **Scope-Update (AD-25, 2026-06-21 — Raffael):** Signatur-**Default** ist jetzt der **gehärtete SES-Eigenbau** > (kein PandaDoc-Zwang), umgesetzt über `defineAdapter` (Adapter `ses-selfhosted`). **PandaDoc bleibt nur als > optionaler BYOK-Adapter** (`pandadoc-byok`, Tenant bringt eigenen Key) — Anbindungs-Spec in [[EXT-17]]. Dieses > Ticket bitte entsprechend bauen: **SES als Default** (Touch vor Ort + Fern-Link + OTP + PAdES-Versiegelung + > Zeitstempel + M001-Audit + Completion-Certificate, s. [[EXT-09]]/[[AD-25]]), **PandaDoc als Opt-in** daneben. > (Rechtlich: SES genügt im SHK; QES nur § 650h, später via D-Trust.) ## Abhängigkeiten & Parallelität - **Blocked by:** `EXT-09` (SES-Eigenbau-Spec + Adapter-Modell; PandaDoc nur noch optional via BYOK [[EXT-17]]) - **Blocks:** — (Endpunkt der P16-Schiene) - **Läuft parallel zu:** Raffaels Kern-Kette + den anderen P16-Slices. **Implizit auf R-P5** (Signatur = `DataConnection` über Apps-Engine) und auf den **Projekt-Kern** (R-P8/P9 — Signatur hängt am `Projekt`, NICHT „Deal"). Eigene `prisma/schema/signature.prisma` (AD-21). - **Konflikt-Risiko:** gering — additive Tabellen; `apps.prisma`/`crm.prisma`/`files.prisma` nur über Relationen. ## Was wir bauen **Multi-Signer-Angebots-Signatur über den gehärteten SES-Eigenbau**: PDF-Upload (aus Files oder neu) → Unterzeichner (Name vorausgefüllt aus Kontakt, Email, Rolle, Reihenfolge sequenziell/parallel) → Zustellung per Fern-Link/OTP oder Touch-Signatur vor Ort → PAdES-versiegeltes Signed-PDF + Completion-Certificate. **PandaDoc bleibt optionaler BYOK-Adapter** hinter derselben Apps-Engine-Connection- und Adapter-Schnittstelle. Status-Tracking je Unterzeichner (entwurf/gesendet/angesehen/signiert/abgelehnt), Erinnerung, Widerruf und optionaler Auto-Stage-Wechsel bleiben erhalten. Das signierte PDF landet in Files. **Pivot-Hart:** Signatur hängt am **`Projekt`-Kern** (`ProjektSignatureDocument`/`ProjektSignatureSigner`), kein eigenes „Deal"-Objekt — Einstieg lebt im Projekt-Detail (P8/P9). ## Benötigte Screens (Backend bedient — Design liefert `D-BOOK` + `D-P16`) | Screen [Route] | Kern-Inhalt | |---|---| | Signatur-Wizard [im Projekt-Detail] | PDF-Upload (aus Files/neu) → Unterzeichner (Name aus Kontakt, Email, Rolle, Reihenfolge sequenziell/parallel) → Signaturmodus (Fern-Link/OTP oder Touch vor Ort; PandaDoc nur BYOK-Opt-in) → Senden; **Status-Tracking je Unterzeichner** + Erinnerung + Widerruf; Original-, Signed-PDF- und Completion-Certificate-Download | ## Definition of Done - [x] **AD-25 umgesetzt:** SES-Eigenbau ist Default (`ses-selfhosted`), PandaDoc bleibt optionaler BYOK-Adapter (`pandadoc-byok`) über die Apps-Engine. - [x] **Status-Tracking pro Unterzeichner** für SES-Flow (draft/sent/viewed/signed/revoked) plus PandaDoc-HMAC-Webhook-Helfer für BYOK. · *Seit 2026-07-17 ist der Webhook auch real erreichbar: öffentliche Route `/webhooks/pandadoc/{tenantId}/{connectionId}` mit timing-safe HMAC-Verify gegen den `webhookSharedKey` der Connection (vorher existierten Helfer + Handler ohne HTTP-Endpoint)* - [x] **e2e-Smoke Signatur (fehlender DoD-Punkt, Audit 2026-07-17):** `tests/e2e/signature.spec.ts` (Login → Projekt-Detail via `E2E_TENANT_PROJECT_PATH` → Panel-Marker `ui.projects.operations.signature`; AGENTS.md D.19 — es gab keinen Signatur-e2e) - [x] OTP-Mail via Transactional-Email-Queue, Erinnerung + Widerruf; Signed-PDF- und Completion-Certificate-Artefakte landen in Files. - [x] **Signatur hängt am `Projekt`-Kern** (`ProjektSignatureDocument`/`ProjektSignatureSigner`) — kein „Deal"-Objekt. - [x] Permission-Bundle `signature.*` (read/send/revoke/admin) serverseitig Owner-gefiltert. - [x] Konnektor `tenantHasModule('signature')`; RLS auf allen Tenant-Tabellen. - [x] **Signatur-Wizard-UI (AD-28 Interim):** Interim-Wizard + Signatur-Panel aus `~/ui` im Projekt-Detail (Vorbereiten-Wizard mit PDF-Auswahl/Upload, strukturierten Unterzeichnern mit Kontakt-Prefill und Reihenfolge, Prüfen & Senden; Panel mit Status je Unterzeichner, Erinnern, Widerruf mit Bestätigung, Downloads). Finale Subframe-Optik aus `D-P16` = getrackter `design-nachzug`, nicht Done-blockierend. - [x] **PAdES-/TSA-Produktionspfad:** `@signpdf`-basierte `ETSI.CAdES.detached`-Signatur mit P12-Zertifikat (`SIGNATURE_P12_BASE64` oder `SIGNATURE_P12_PATH`) und optionalem RFC3161-TSA-Request (`SIGNATURE_TSA_URL`). Ohne Zertifikat bleibt Dev-Fallback möglich; mit `SIGNATURE_REQUIRE_PADES=true` schlägt der Abschluss hart fehl, wenn Zertifikatsmaterial fehlt. ## Technische Bausteine - **Entities** (eigene `prisma/schema/signature.prisma`): `SignatureProviderConnection` (data_connection_id → Apps-Engine!, provider `ses-selfhosted` default oder `pandadoc-byok` optional, is_default), `ProjektSignatureDocument` (projekt_id, provider_document_id, source_pdf_file_id, status draft/sent/viewed/signed/declined, signed_pdf_file_id, completion_certificate_file_id — **[Soft-Delete]**), `ProjektSignatureSigner` (document_id, signer_email/name, linked_kontakt_id, status, signed_at, otp_verified_at). `apps.prisma`/`crm.prisma`/`files.prisma` nur über Relationen (AD-21). - **Signatur = Apps-Engine-Connection** (R-P5): OAuth/API-Key + Health vom Framework; hier Provider-Adapter `ses-selfhosted`, optional `pandadoc-byok`. - **Callback-/Webhook-Handler** (Signatur-Check) → Status-Übergänge je Signer + Activity-Write; Auto-Stage-Wechsel über Pipeline (P8/P9, optional). - **RLS** überall; `signature.*`-Bundle; signiertes PDF via FileEntityLink an den Projekt-Kern. - **Konnektor** `tenantHasModule('signature')`; `is_demo_data` auf Demo-Dokumenten. ## Umsetzungsnotiz 2026-07-01 - Branch: `feat/AK-P16d-signature-ses`, abgezweigt von aktuellem `origin/main`. - Gebaut: `prisma/schema/signature.prisma` + RLS-Policy, File-Link-Typ `signature_document`, Permission/Entitlement-Wiring `signature.*`, Tenant-Modell-Registrierung, Apps-Engine-Katalog/Adapter `ses-selfhosted` und `pandadoc-byok`, Projekt-Signatur-VM, Projekt-Detail-Fallback-UI, öffentlicher `/sign/:token`-Flow mit OTP/Intent/Touch-Signatur, OTP-Mail-Queue, Reminder/Widerruf, Signed-PDF-/Completion-Certificate-Ablage in Files. - Proof lokal: `pnpm exec prisma validate` grün; `pnpm --filter @toolctrl/integrations test` grün; `pnpm --filter @toolctrl/view-models test` grün; `pnpm --filter @toolctrl/integrations typecheck` grün; `pnpm --filter @toolctrl/view-models typecheck` grün; `pnpm --filter @toolctrl/web typecheck` grün; `pnpm exec vitest run apps/web/app/modules/signature/services/padesSeal.server.test.ts` grün; `pnpm lint` grün. - Push-Proof: Implementierungs-Commit `2e7e81557` auf `origin/feat/AK-P16d-signature-ses` gepusht; Pre-Push-Hook `i18n` + `typecheck` grün. - Hinweis: `pnpm --filter @toolctrl/config test` fällt lokal auf Windows in `env-access-enforcement.test.ts` wegen bereits bestehender absoluter Baseline-Pfade in anderen Packages; keine AK-P16d-Datei ist in der Unexpected-Liste. - Fortschritt: 7/8 DoD = 87,5 % done. Selbst machbar offen: 0 Punkte. Extern blockiert: D-P16 finales Signatur-Wizard-Design. ## Umsetzungsnotiz 2026-07-11 — Interim-UI (AD-28) - Branch: `akeshan/ak-p16cd-signatur-interim-wizard`, abgezweigt von `origin/main`. - Subframe-MCP geprüft: es existiert **kein** Designer-Flow für die Signatur → Interim-UI nach AD-28, angelehnt an die integrierten Designer-Screens (`screens/forms/`, `screens/automation/`, `ConnectWizardDialog`-Muster). - Neu: `apps/web/app/components/screens/signature/ProjectSignaturePanel.tsx` (ersetzt den Inline-Fallback in `ProjectSubAreasPanel`; Status-Badges je Dokument/Unterzeichner, Erinnern je Unterzeichner, Senden/Widerruf hinter echtem Bestätigungs-Dialog, Downloads Original/Signed-PDF/Completion-Certificate über die AD-23-Media-Proxy-URLs) und `SignatureWizardDialog.tsx` (echter `~/ui`-Dialog M/720 mit `StepperHorizontal`: Dokument → Unterzeichner → Prüfen & senden; PDF-Auswahl aus Files oder Chunked-Upload; strukturierte Unterzeichner-Zeilen mit Kontakt-Prefill aus Projekt-Kontakten und Sortierung = `signingOrder`; Serialisierung in den bestehenden `parseSignatureSigners`-Zeilen-Kontrakt). - VM additiv erweitert (`sourcePdfUrl`/`signedPdfUrl`/`completionCertUrl`, `pdfFileOptions`, `kontaktSuggestions`, `createAndSendActionIntent`); Loader lädt PDF-Optionen via `listFilesForBrowser` und Kontakt-Vorschläge; Route-Action um Kompositions-Intent `createAndSendSignatureDocument` ergänzt. Kein Schema-Delta, keine Migration. - Chunked-Upload-Client aus `files.upload.tsx` nach `apps/web/app/utils/files/uploadFileClient.ts` extrahiert (reiner Refactor); Projekt-Route injiziert `uploadPdf` in den Wizard. - Public `/sign/:token` auf `PublicSignPage.tsx` aus `~/ui` restylt (Alert/TextInput/TextArea/Checkbox/Button; Formular-Kontrakt der Action unverändert). - i18n de+en (`signature.wizard.*`, `signature.roles.*`, `signature.panel.*`, `signature.confirm.*`, Download-/Feld-Keys), chirurgisch gespliced. - Ehrlichkeits-Hinweis: `remindSignatureSigner` vermerkt nur `lastReminderAt` + Event, verschickt keine Mail — UI-Copy sagt das („Erinnern vermerkt den Zeitpunkt …"). Mail-Anbindung = Vorschlag außerhalb Ticket-Scope. - Proof lokal: `pnpm --filter @hivegrid/web typecheck` + `--filter @hivegrid/view-models typecheck` grün; `pnpm run verify:i18n` Exit 0; `verify:cross-cutting-models` Exit 0; vitest grün: `project-signature.vm.test.ts`, `ProjectSignaturePanel.test.tsx` (5), `SignatureWizardDialog.test.tsx` (5), `subframe-layout-boundary.test.ts` (Allowlist um die 3 Signature-Screens erweitert), `padesSeal.server.test.ts`, `FileUploadPage.test.tsx`, projects-Screens-Suiten. `verify:sidebar-routes`-Fails nur in `.codex/worktrees/*`-Kopien (bekannte lokale Verschmutzung); Hot-Swap-Drill + Visual-Baseline laufen CI-seitig (Windows-Limitation). - Fortschritt: **8/8 DoD = 100 %** (Wizard-DoD via AD-28-Interim erfüllt; finale D-P16-Optik als `design-nachzug` getrackt). Done-Status erst nach Freigabe. ## Umsetzungsnotiz 2026-07-17 — Stand-Audit + Restarbeiten - Audit-Befund (Code auf `main` pro DoD-Punkt geprüft): DoD 1–8 real erfüllt, aber der **PandaDoc-BYOK-Webhook war nicht verdrahtet**: `verifyPandaDocWebhookSignature` + `handlePandaDocWebhook` existierten, ohne dass irgendeine Route sie aufrief — der BYOK-Status-Pfad war real unerreichbar (Plane-DoD „Webhook-Verarbeitung"). - Fix (Branch `fix/ak-p16-audit-restwork`): öffentliche Resource-Route `apps/web/app/routes/webhooks.pandadoc.$tenantId.$connectionId.tsx` — rawBody-HMAC über `runWithConnectionCredentials` (expectedAppId `pandadoc-byok`), Quiet-200 für alles Unverifizierbare (Calendar-Webhook-Muster, kein Existenz-Leak). Zusätzlich schreibt der `document.completed`-Zweig jetzt eine System-Activity (`logSignatureActivity`, actorUserId null → system; DoD C.14 — vorher nur SignatureEvent). Route-Test mit 4 Fällen (verifiziert/fehlende+falsche Signatur/unbekannte Connection/405), Signatur-Suite 14 Tests grün, Typecheck web+integrations grün. e2e-Smoke ergänzt (DoD-Punkt oben). ## Quellen (granular) - `ENTITY-MODEL.md` → **Domäne 9** (SignatureProviderConnection, ProjektSignatureDocument/Signer — am Projekt-Kern, AD-20) - `REQUIREMENTS.md` → `REQ-signatur-datenmodell` (⚠ Bezeichner „Deal" pre-pivot — gilt `Projekt`), `REQ-signatur-provider` - `ROADMAP.md` → Phase 16 · Milestones: (M130-erstellung, M131-self-hosted-e-signatur, M132-status-tracking) - `designer-briefs/P16-kalender-booking-forms-signatur.md` (Gruppe 4 Signatur; SES-Default/PandaDoc-BYOK, Pivot-Hinweis Projekt-Kern) ## Dev-Nachzug (nach Davids `D-BOOK`/`D-P16`-Delta) **Interim-UI (Vorschau, Stand 2026-07-11):** Screens aus `~/ui` gebaut — `apps/web/app/components/screens/signature/{ProjectSignaturePanel,SignatureWizardDialog,PublicSignPage}.tsx` (VM als Prop, Route-Intents als Action-Callbacks). Proof: Screen-Tests `ProjectSignaturePanel.test.tsx` + `SignatureWizardDialog.test.tsx`, Boundary-Guard `subframe-layout-boundary.test.ts` grün; Hot-Swap-Drill + Visual-Baseline CI-seitig (als interim markiert). Refactor-Nachzug offen: finale Subframe-Optik aus `D-P16` (Plane-Label `design-nachzug`). Soll-Elemente ohne Backend (bewusst nicht gebaut, kein Fake-Toggle): sequenziell/parallel-Enforcement im Versand, Signaturmodus-Auswahl (Fern-Link vs. Touch — ein Versandpfad, Touch läuft über dieselbe `/sign`-Seite), `linkedKontaktId`-Persistenz (Prefill nur UI-seitig), Reminder-**Mail**-Versand (nur Vermerk + Event), Expiry-Verwaltung (read-only). - [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst - [ ] REQUIREMENTS/ROADMAP nachgezogen - [ ] Plane-Ticket `AK-P16d` aktualisiert (Kommentar + Label `design-nachzug` nach Freigabe) ## Abhängigkeitsnachzug 2026-07-29 — AK-P4a-Upload-CSRF Der vom Signatur-Wizard wiederverwendete Chunk-Upload-Client sendet nun für Init, Chunk und Complete den Session-CSRF-Header. Der bestehende `uploadPdf`-Callback bleibt unverändert; fokussierte Client- und Resource-Route-Regressionstests sowie der Web-Typecheck sind grün. **AK-P16d bleibt 8/8 DoD = 100 % done.**