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(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.
- 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-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.
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 ·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-P16daktualisiert