Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/AK-P16d.md
T

13 KiB
Raw Blame History

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

  • 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 den webhookSharedKey der 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 via E2E_TENANT_PROJECT_PATH → Panel-Marker ui.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 ~/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.
  • 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.