Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -6,7 +6,9 @@
| **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 |
| **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
@@ -31,12 +33,13 @@
## 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] **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.
- [ ] **Blockiert durch D-P16:** finales Subframe-/David-Design für den Signatur-Wizard; aktuell funktionaler Fallback im Projekt-Detail.
- [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
@@ -54,14 +57,59 @@
- 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 · `PHASE-SOURCES.md` → Phase 16 (M130-erstellung, M131-self-hosted-e-signatur, M132-status-tracking)
- `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)
- `_bmad-output/specs/M07-angebot-signatur.md` (⚠ teils pre-pivot — ENTITY-MODEL hat Vorrang)
## 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/PHASE-SOURCES nachgezogen
- [ ] Plane-Ticket `AK-P16d` aktualisiert
- [ ] 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.**