13 KiB
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(Adapterses-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 amProjekt, NICHT „Deal"). Eigeneprisma/schema/signature.prisma(AD-21). - Konflikt-Risiko: gering — additive Tabellen;
apps.prisma/crm.prisma/files.prismanur ü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
- AD-25 umgesetzt: SES-Eigenbau ist Default (
ses-selfhosted), PandaDoc bleibt optionaler BYOK-Adapter (pandadoc-byok) über die Apps-Engine. - 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 denwebhookSharedKeyder Connection (vorher existierten Helfer + Handler ohne HTTP-Endpoint) - e2e-Smoke Signatur (fehlender DoD-Punkt, Audit 2026-07-17):
tests/e2e/signature.spec.ts(Login → Projekt-Detail viaE2E_TENANT_PROJECT_PATH→ Panel-Markerui.projects.operations.signature; AGENTS.md D.19 — es gab keinen Signatur-e2e) - OTP-Mail via Transactional-Email-Queue, Erinnerung + Widerruf; Signed-PDF- und Completion-Certificate-Artefakte landen in Files.
- Signatur hängt am
Projekt-Kern (ProjektSignatureDocument/ProjektSignatureSigner) — kein „Deal"-Objekt. - Permission-Bundle
signature.*(read/send/revoke/admin) serverseitig Owner-gefiltert. - Konnektor
tenantHasModule('signature'); RLS auf allen Tenant-Tabellen. - Signatur-Wizard-UI (AD-28 Interim): Interim-Wizard + Signatur-Panel aus
~/uiim 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 ausD-P16= getrackterdesign-nachzug, nicht Done-blockierend. - PAdES-/TSA-Produktionspfad:
@signpdf-basierteETSI.CAdES.detached-Signatur mit P12-Zertifikat (SIGNATURE_P12_BASE64oderSIGNATURE_P12_PATH) und optionalem RFC3161-TSA-Request (SIGNATURE_TSA_URL). Ohne Zertifikat bleibt Dev-Fallback möglich; mitSIGNATURE_REQUIRE_PADES=trueschlägt der Abschluss hart fehl, wenn Zertifikatsmaterial fehlt.
Technische Bausteine
- Entities (eigene
prisma/schema/signature.prisma):SignatureProviderConnection(data_connection_id → Apps-Engine!, providerses-selfhosteddefault oderpandadoc-byokoptional, 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.prismanur über Relationen (AD-21). - Signatur = Apps-Engine-Connection (R-P5): OAuth/API-Key + Health vom Framework; hier Provider-Adapter
ses-selfhosted, optionalpandadoc-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_dataauf Demo-Dokumenten.
Umsetzungsnotiz 2026-07-01
- Branch:
feat/AK-P16d-signature-ses, abgezweigt von aktuellemorigin/main. - Gebaut:
prisma/schema/signature.prisma+ RLS-Policy, File-Link-Typsignature_document, Permission/Entitlement-Wiringsignature.*, Tenant-Modell-Registrierung, Apps-Engine-Katalog/Adapterses-selfhostedundpandadoc-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 validategrün;pnpm --filter @toolctrl/integrations testgrün;pnpm --filter @toolctrl/view-models testgrün;pnpm --filter @toolctrl/integrations typecheckgrün;pnpm --filter @toolctrl/view-models typecheckgrün;pnpm --filter @toolctrl/web typecheckgrün;pnpm exec vitest run apps/web/app/modules/signature/services/padesSeal.server.test.tsgrün;pnpm lintgrün. - Push-Proof: Implementierungs-Commit
2e7e81557auforigin/feat/AK-P16d-signature-sesgepusht; Pre-Push-Hooki18n+typecheckgrün. - Hinweis:
pnpm --filter @toolctrl/config testfällt lokal auf Windows inenv-access-enforcement.test.tswegen 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 vonorigin/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 inProjectSubAreasPanel; 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) undSignatureWizardDialog.tsx(echter~/ui-Dialog M/720 mitStepperHorizontal: 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 bestehendenparseSignatureSigners-Zeilen-Kontrakt). - VM additiv erweitert (
sourcePdfUrl/signedPdfUrl/completionCertUrl,pdfFileOptions,kontaktSuggestions,createAndSendActionIntent); Loader lädt PDF-Optionen vialistFilesForBrowserund Kontakt-Vorschläge; Route-Action um Kompositions-IntentcreateAndSendSignatureDocumentergänzt. Kein Schema-Delta, keine Migration. - Chunked-Upload-Client aus
files.upload.tsxnachapps/web/app/utils/files/uploadFileClient.tsextrahiert (reiner Refactor); Projekt-Route injiziertuploadPdfin den Wizard. - Public
/sign/:tokenaufPublicSignPage.tsxaus~/uirestylt (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:
remindSignatureSignervermerkt nurlastReminderAt+ 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 typecheckgrün;pnpm run verify:i18nExit 0;verify:cross-cutting-modelsExit 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-nachzuggetrackt). Done-Status erst nach Freigabe.
Umsetzungsnotiz 2026-07-17 — Stand-Audit + Restarbeiten
- Audit-Befund (Code auf
mainpro DoD-Punkt geprüft): DoD 1–8 real erfüllt, aber der PandaDoc-BYOK-Webhook war nicht verdrahtet:verifyPandaDocWebhookSignature+handlePandaDocWebhookexistierten, 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-Routeapps/web/app/routes/webhooks.pandadoc.$tenantId.$connectionId.tsx— rawBody-HMAC überrunWithConnectionCredentials(expectedAppIdpandadoc-byok), Quiet-200 für alles Unverifizierbare (Calendar-Webhook-Muster, kein Existenz-Leak). Zusätzlich schreibt derdocument.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 — giltProjekt),REQ-signatur-providerROADMAP.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-P16daktualisiert (Kommentar + Labeldesign-nachzugnach 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.