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

116 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
- [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. · *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)*
- [x] **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)
- [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.
- [x] **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.
- [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.
## 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.**