Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/AK-P16d.md
T
2026-07-08 16:15:37 +02:00

7.3 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 in Umsetzung

⚠️ 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.
  • 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.
  • Blockiert durch D-P16: finales Subframe-/David-Design für den Signatur-Wizard; aktuell funktionaler Fallback im Projekt-Detail.
  • 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.

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 · PHASE-SOURCES.md → Phase 16 (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)
  • _bmad-output/specs/M07-angebot-signatur.md (⚠ teils pre-pivot — ENTITY-MODEL hat Vorrang)

Dev-Nachzug (nach Davids D-BOOK/D-P16-Delta)

  • Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
  • REQUIREMENTS/PHASE-SOURCES nachgezogen
  • Plane-Ticket AK-P16d aktualisiert