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