Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,194 @@
# Phase 10 — Verification Report
**Scope:** Compliance + Polish (10 files)
**Verifier:** Read-only structural + content audit
**Status:** PASS with minor follow-ups (no blocking issues)
---
## 1. Template-Konformität
Alle 9 Task-Detail-MDs befolgen das DETAIL-MD-Template aus `../DETAIL-MD-TEMPLATE.md` mit verbindlicher Section-Reihenfolge:
| File | Frontmatter | Problem | Depends on | Blocks | Approach | Impl-Steps | Tests | AC | Rollback | Security | Subagents | Staging | Dev/Progress/LL |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| react-email.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK |
| compliance-audit-export.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK |
| dsgvo-bulk-ops.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK |
| security-docs.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK |
| lighthouse.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK |
| bundle-budget.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK |
| i18n-foundation.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK |
| wcag-internal.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK |
| test-coverage.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK |
Alle 15 Sections in korrekter Reihenfolge present. README.md ist Phase-Overview (kein Detail-MD), entspricht aber den anderen Phase-README-Conventions (Done-Definition, Task-Reihenfolge-Table, Dependency-Graph).
---
## 2. Dependencies Konsistenz
**Korrekt modelliert:**
- `react-email.md` (#75) ist als „vorgezogen" markiert, blockt `05-business-features/marketing-funnel-phase-3.md` — wie gewünscht
- `compliance-audit-export.md` (#67) blockt `dsgvo-bulk-ops.md` (#68) wegen gemeinsamer AuditEvent-Schema-Updates — korrekt sequenziell
- `test-coverage.md` (#76) hat explizit „Alle vorherigen Phasen" als Dependency — korrekt am Ende
- Lighthouse/Bundle-Budget/i18n/WCAG/Security-Docs (#69-#73) sind als parallel ausgewiesen, sharen aber bewusst Vite-Config (Lighthouse↔Bundle-Budget) — Koordination dokumentiert
- `wcag-internal.md` depends on `lighthouse.md` + `i18n-foundation.md` (Translation-Strings für ARIA) — semantisch konsistent
**Numbering Hinweis:** Task-IDs sind nicht sequenziell (#67, #68, #69, #70, #71, #72, #73, #75, #76 — #74 fehlt offenbar, vermutlich in anderer Phase aufgeteilt). Reihenfolge im README (1-9) ist trotzdem konsistent durchgängig benutzt.
---
## 3. Implementation-Steps-Qualität
### react-email.md
- **Migration aller transactional templates:** 8 Templates explizit benannt (Welcome, MagicLink, PasswordReset, SubscriptionSuccess, SubscriptionFailed, Invitation, InvoiceSent, TenantNotification) + 1 Marketing-Campaign-Base → **vollständig**.
- ESLint-Rule für `dangerouslySetInnerHTML`-Verbot, `actionUrl` https-Validation, automatisches React-Escaping — solide Security-Posture.
### compliance-audit-export.md
- **AuditEvent-Schema-Erweiterung:** alle SOC2/HIPAA/GDPR-relevanten Felder vorhanden: `actorType`, `actorId`, `actorEmail`, `actorIp`, `actorUserAgent`, `resourceType/Id`, `action`, `outcome`, `sourceModule`, `dataSensitivity`, `regulatoryScope`, `metadata`, `prevHash`, `hash`, `createdAt` mit korrekten Indizes → **vollständig**.
- **Tamper-Evidence Hash-Chain:** HMAC-SHA-256 über `(prevHash || serializedEvent)` mit `AUDIT_CHAIN_SECRET`. Versionsfeld für Key-Rotation erwähnt. **Kryptografisch korrekt.** Hinweis: Key-Rotation-Schema (Versionsfeld in hash-Spalte) sollte als Implementation-Step expliziter sein — aktuell nur in Security-Notes (Section 5).
- 5 Pre-Built Reports + PDF-Generator mit Signature-Hash decken Standard-SOC2-Auditor-Anforderungen.
### dsgvo-bulk-ops.md
- **Datasubject-Export-Worker:** 12 Tabellen explizit aufgelistet (User, UserRole, TenantUser, AuditEvent, Row, CrmContact, Notification, OutboundEmail, ChatMessage, FormSubmission, EventWebhookAttempt, ImpersonationAudit). Storage-Files-ZIP für hochgeladene Files — **vollständig** für aktuellen Schema-Stand. Hinweis: Phase 04 (Search/RAG) und Phase 07 (Chatbot) bringen ggf. weitere PII-haltige Models (Chunk-Embeddings mit User-Content, Chatbot-Sessions) — sollte als „Update-Pflicht bei Schema-Änderungen" in der Cascade-Doku verewigt werden.
- **30-Tage-Grace-Period:** User-Schema-Erweiterung mit `pendingDeletion`, `scheduledDeletionAt`, `deletionRequestedAt`, `pseudonymized`, `pseudonymizedAt`. Login-Path-Erweiterung in Step 8. Grace-Cron in Step 9. Reactivation-Flow mit Reactivation-Screen und signed-Token (30-Min-Validity, AUDIT_CHAIN_SECRET-ähnlicher Key) — **korrekt und robust**.
- **Pseudonymisierungs-Layer mit verschlüsselter Map:** Separates `PseudonymizationMap`-Model, verschlüsselt mit `PSEUDONYMIZATION_KEY` (Platform-Admin only, Vault/AWS-KMS in Production gefordert), CLI-Reveal mit Audit-Trail. **Sicher**, aber: Encryption-Schema (Key-Derivation, IV-Handling, Algorithmus-Wahl AES-256-GCM vs ähnlich) bleibt in Step 2 abstrakt — sollte explizit AES-256-GCM oder libsodium-secretbox spezifizieren.
- **Verification-Pass:** Schema-Reflection via Prisma-DMMF iteriert ALLE Models mit User-Reference, läuft 1h nach Cascade, generiert `DsgvoVerificationReport` mit Hash. **Robust.** Hinweis: 1h-Window könnte für sehr große Tenants zu kurz sein wenn Cascade asynchron läuft; sollte konfigurierbar sein.
### security-docs.md
- **STRIDE-Threat-Model:** 7 Komponenten (Web, API, Worker, DB, Plugins, AI-Pipeline, Webhooks) mit allen 6 STRIDE-Achsen, plus 5 Mermaid-Datenfluss-Diagramme → **vollständig**.
- **IR-Runbook mit GDPR-72h-Notification:** 4 Severity-Levels, 6 Phasen, separate Section für GDPR-Breach-Notification mit Aufsichtsbehörde-Template, Datasubject-Notification (Art. 34 High-Risk), Communication-Templates für Internal/External/Regulator/Press → **vollständig**.
- `security.txt`-Pfad: `apps/web/public/.well-known/security.txt` → korrekt (statisches Asset, von Web-App ausgeliefert unter `https://app.toolctrl.de/.well-known/security.txt`). Vite serves `public/` standardmäßig.
- Expires-Renewal-Cron als zusätzliche Verteidigung gegen abgelaufene security.txt.
### lighthouse.md
- **12 Routes** explizit in `.lighthouserc.json`-Config: 4 Public (`/`, `/pricing`, `/contact`, `/blog`), 5 Internal (`dashboard`, `crm`, `crm/contacts`, `settings/members`, `settings/billing`), 3 Admin (`dashboard`, `analytics`, `tenants`) → **passt zu User-Wunsch „Lighthouse für alles, auch internal"**. Hinweis: `settings/profile`, `settings/privacy`, `email-marketing` werden in wcag-internal.md Step 9 als Routes erwähnt aber nicht in den 12 Lighthouse-URLs — Inkonsistenz, sollte angeglichen werden (entweder Lighthouse-Liste erweitern oder WCAG-Liste auf 12 reduzieren).
- Critical-CSS-Inlining (Step 3), Font-Preload (Step 3), Code-Splitting/manualChunks (Step 4) — **konfiguriert**.
- PWA als „warn"-Level (0.80) statt „error" (0.95) — pragmatisch.
### bundle-budget.md
- **Per-Route-Limits als Soft-Tool:** Step 2 + Test-Requirements explizit: „Size > Limit → red Output, **exit code 0** (kein Block, nur Warning), aber Report-Flag setzen". PR-Comment statt PR-Block. → **korrekt nach User-Wunsch „Soft-Tool ohne Hard-Gate"**.
- 12 Routes + Vendor-Chunks im Config, gzip-bytes als Measurement.
- Δ-Vergleich gegen `main`-Baseline via CI-Artifact.
### i18n-foundation.md
- **ICU-Plurals:** i18next + i18next-icu, explicit Plural-Pattern-Example, Tests für DE/EN/PL → **vorhanden**.
- **Intl-Helpers:** 5 Helpers (Currency, Date, Number, RelativeTime, List) mit 4-Locale-Tests (de/en/ar/ja) → **vollständig**.
- **RTL-Foundation:** Tailwind-RTL-Variants, `<html dir>` server-side, 2 RTL-Smoke-Tests (Sidebar, Card) → **etabliert** als Foundation (nicht vollständig RTL-konvertiert, aber das ist konsistent mit „B i18n DE/EN solide").
- **Locale-Picker:** in `/app/$tenant/settings/profile.tsx`, mit `User.locale` Schema-Migration → **vorhanden**.
- Keine 5+ Sprachen jetzt, nur Framework + DE/EN → **korrekt nach User-Wunsch**.
### wcag-internal.md
- **axe-core ≥ 80% Coverage:** explizit als Target in beiden Packages (`packages/ui-app`, `packages/ui-subframe`) → **korrekt**.
- **jsx-a11y strict:** ESLint-Plugin-Strict-Preset + 3 zusätzliche Custom-Rules (`no-autofocus`, `no-noninteractive-element-interactions`, `anchor-is-valid`) → **vorhanden**.
- **Color-Contrast-Audit:** `scripts/contrast-audit.mjs` mit `wcag-contrast`-Lib, Light + Dark Mode, WCAG-AA 4.5:1/3:1 → **robust**.
- **NVDA/VoiceOver Smoke-Tests:** 6 Major-Flows (Login, Magic-Link, Dashboard, CRM, Settings-Members, DSGVO-Export) in Step 10 → **vorhanden**.
### test-coverage.md
- **Per-Path-Thresholds:** Critical 90 / Standard 70 / ui-subframe 50 → **korrekt nach User-Wunsch**.
- **5 Golden-Path-E2E:** Auth, Tenant-Create, Member-Invite, Billing-Subscribe, CRM-Workflow → **vollständig**.
- Sprint-Reihenfolge: Auth → Tenant-Isolation → Billing → Permissions/Entitlements → DB-Package (Steps 5-9) — sicherheits-priorisiert.
---
## 4. Test-Requirements
**Coverage-Tests:**
- DSGVO-Export-Worker: ≥ 90 % im DSGVO-Code (Test-Requirements Section), End-to-End-Integration-Test mit Test-User in jeder Tabelle → **vorhanden**.
- Tamper-Evidence-Hash-Chain-Verifikation: CLI-Test mit Happy-Path und Tampering-Detection, Coverage ≥ 85 % → **vorhanden**.
- WCAG-Smoke-Tests mit NVDA/VoiceOver: Step 10 dokumentiert 6 Flows, Reports werden in `docs/accessibility/screen-reader-smoke-tests-<date>.md` gespeichert → **vorhanden**.
---
## 5. Security-Notes
### DSGVO-Pseudonymisierung-Map-Encryption-Key-Management
- `PSEUDONYMIZATION_KEY` als Platform-Level-Secret, Vault/AWS-KMS in Production gefordert, nie pro Tenant → **adressiert**.
- **Lücke:** Encryption-Schema (Algorithmus, IV-Generierung, Authentication-Tag) bleibt abstrakt. Empfehlung: in Step 2 Algorithmus konkret festlegen (z.B. `libsodium secretbox` oder `AES-256-GCM mit random 96-bit IV pro Record`).
- Key-Rotation: nicht explizit erwähnt für `PSEUDONYMIZATION_KEY` (im Gegensatz zu `AUDIT_CHAIN_SECRET` mit Versionsfeld). Empfehlung: gleicher Rotation-Mechanismus.
### Tamper-Evidence-HMAC-Key-Management
- `AUDIT_CHAIN_SECRET` als Platform-Level-Secret, Rotation via Versionsfeld in Hash → **adressiert**.
- **Lücke:** Rotation-Workflow-Schritte (Re-Hash der gesamten Chain bei Rotation? Oder Versions-Markierung pro Event?) bleiben abstrakt. Empfehlung: in Step 2 expliziter — vorgeschlagen wäre `hash = HMAC(secret_v_N, ...)` mit N als zusätzlicher Spalte, Verifier kennt alle aktiven Keys.
### Audit-Event-Auto-Capture vermeidet PII-Leaks in audit-Logs selbst
- Default `dataSensitivity=internal`, explizite `dataSensitivity=pii` für PII-Models, IP-Anonymisierung bei Pseudonymisierung (/24-Subnetz) → **adressiert**.
- **Lücke:** `metadata`-Field (Json, max 8KB) kann beliebige PII enthalten wenn Auto-Capture leichtfertig konfiguriert. Empfehlung: Validation-Layer der `metadata` gegen eine Allowlist von erlaubten Keys pro `sourceModule` prüft.
---
## 6. Staging-Deployment-Steps
### Lighthouse-CI-Setup auf Coolify-Preview-Deploys
- `.lighthouserc.json` mit `extraHeaders` für Auth-Cookie, Test-Session-Token via Repo-Secret `LIGHTHOUSE_STAGING_SESSION`, Token-Rotation täglich via Cron — **vorhanden**.
- **Lücke:** „Coolify-Preview-Deploys"-Integration ist nicht explizit. Aktuell läuft Lighthouse-CI gegen `https://staging.toolctrl.de` (Single-Staging-URL). Wenn Coolify PR-Preview-URLs pro Branch generiert, sollte die URL dynamisch sein (`{{PR_PREVIEW_URL}}`-Substitution im Workflow). Empfehlung: Workflow-Step ergänzen der Preview-URL aus Coolify-API zieht.
### WCAG-Audit-Workflow
- Lokaler Audit-Run pro Route (Chrome + axe-DevTools, Lighthouse-Headless), `pnpm contrast:audit`, manuelle Screen-Reader-Tests durch Operator, Lighthouse-CI-Run auf Staging → **vorhanden und gut strukturiert**.
### Performance-Regression-Comments auf PRs
- Bundle-Budget hat dedizierten PR-Comment-Workflow (`.github/workflows/bundle-budget.yml`) mit Upsert-Marker → **vorhanden**.
- Lighthouse-CI: `treosh/lighthouse-ci-action@v11` mit `uploadArtifacts: true` und `temporaryPublicStorage: true` postet Lighthouse-Report-Link, aber **kein expliziter Per-Route-Performance-Comparison-Comment**. Empfehlung: zusätzlich `lhci-server` oder Custom-Action für Δ-Comments wie bei Bundle-Budget. Aktuell wird die Verschlechterung nur via Score-Threshold-Fail sichtbar, nicht als delta-tabelle im PR.
---
## 7. Konsistenz mit User-Wünschen
| User-Wunsch | Status |
|---|---|
| A für Audit-Trail-Export Voll-Compliance | OK — compliance-audit-export.md mit allen SOC2/HIPAA/GDPR-Feldern + Hash-Chain |
| A für DSGVO-Bulk-Operations | OK — dsgvo-bulk-ops.md mit Self-Service + Admin + Pseudonymisierung + Verification |
| A für Security-Docs-Pack | OK — security-docs.md mit 7 Doku-Files + security.txt + IR-Runbook |
| Lighthouse für alles, auch internal | OK mit Inkonsistenz — 5 Internal-Routes drin, aber `settings/profile`, `settings/privacy`, `email-marketing` aus wcag-internal-Audit-Liste fehlen in Lighthouse-Config (siehe Section 3) |
| Bundle-Budget Soft-Tool ohne Hard-Gate | OK — explizit exit code 0 + PR-Comment-Warning statt Block |
| B i18n DE/EN solide | OK — DE/EN als `supportedLngs`, RTL nur als Foundation (2 Smoke-Tests), Framework offen für Erweiterung |
| B WCAG Internal-Audit erst, dann später extern | OK — wcag-internal.md macht Internal; externer Audit nicht erwähnt (sollte in `11-backlog/README.md` ergänzt werden — nicht in Phase 10, aber als Erwartung) |
| B Test-Coverage Per-Module-Gates → Per-Path-Thresholds | OK — Per-Path-Thresholds mit Critical 90/Standard 70/UI 50 |
| A React-Email Migration | OK — alle 8 Templates portiert, Marketing-Base + Audit-Export-Ready-Template als zusätzliche werden in compliance-audit-export.md/dsgvo-bulk-ops.md angekoppelt |
---
## 8. Fehlende Aspekte
### DSGVO-Self-Service-UI-Email-Confirmation-Flow
- **Adressiert.** dsgvo-bulk-ops.md Step 6 + Sub-Component (a) erwähnen Email-Verifikation mit signed-token, 30-Min-Validity, dedicated `AccountDeletionConfirmationEmail.tsx`-Template (Step 10). Security-Notes erklären Schutz gegen Account-Hijack-Lösch-Attacken.
### Security-Docs `security.txt`-Path
- **Korrekt.** `apps/web/public/.well-known/security.txt` — Vite/React-Router servt `public/` als statische Assets unter Root, also URL wird `https://app.toolctrl.de/.well-known/security.txt` (RFC-9116-konform).
### Lighthouse-CI Performance-Regression-Comments auf PRs
- **Teilweise.** Score-basiertes Threshold-Fail ist da, aber kein expliziter Δ-Comment wie bei Bundle-Budget. **Empfehlung:** in lighthouse.md Step 9 ergänzen — Custom-Action die LHCI-Report-JSON gegen Main-Baseline vergleicht und Δ-Tabelle als PR-Comment postet (analog zu bundle-budget.md).
### Weitere kleine Lücken
- **AuditEvent-Cleanup-Lock:** dsgvo-bulk-ops.md erwähnt Concurrency-Schutz für Cascade (Idempotency-Key + DB-Lock auf user.id), aber compliance-audit-export.md erwähnt nicht explizit dass Retention-Cleanup nicht parallel mit Export-Job laufen darf — Empfehlung: Lock-Mechanismus oder Manual-Pause-Flag (in Security-Notes erwähnt aber nicht als Implementation-Step).
- **i18n-Audit-Output-Persistierung:** Audit-Report (`docs/contributing/i18n-audit-<date>.md`) wird in Step 1 erzeugt; sollte als CI-Artifact persistiert werden für Trend-Tracking, nicht nur als one-shot-Doku.
- **react-email Storybook-Stories:** als „sobald Phase 08 Storybook fertig" konditional — wenn Phase 08 vor Phase 10 abgeschlossen ist (laut README), sollten Stories nicht optional sein. Empfehlung: in Acceptance-Criteria als bedingtes „falls Phase 08 fertig: Stories existieren".
---
## 9. Verbesserungs-Vorschläge (nicht blockierend)
1. **Lighthouse ↔ WCAG Routen-Konsistenz:** wcag-internal.md listet in Step 9 zusätzliche Routes (`settings/profile`, `settings/privacy`, `email-marketing`, `auth/login`, `auth/register`, `auth/magic-link`, `auth/password-reset`). Diese sollten auch in `.lighthouserc.json` aufgenommen werden, damit Lighthouse-Accessibility-Score-Pflicht ≥ 0.95 für genau diese Routes gilt. Aktuelles Lighthouse hat 12 URLs, WCAG impliziert 17+ Routes. Empfehlung: Routen-Liste konsolidieren in `docs/performance/lighthouse-targets.md` und beide Tasks referenzieren.
2. **Encryption-Algorithmus für PseudonymizationMap explizit machen:** AES-256-GCM oder libsodium secretbox als konkrete Wahl, IV-Strategy, Authentication-Tag-Handling — als Implementation-Step in dsgvo-bulk-ops.md Step 2.
3. **AUDIT_CHAIN_SECRET-Rotation-Workflow als Implementation-Step:** Versionsfeld pro Event oder pro Chain-Segment, Verifier-Logik für Multi-Version-Validation — als Sub-Step in compliance-audit-export.md Step 2.
4. **Lighthouse-Performance-Δ-PR-Comment** analog zu Bundle-Budget — als Step 9b in lighthouse.md.
5. **Coolify-Preview-URL-Integration für Lighthouse-CI** wenn Coolify PR-Preview-Deployments unterstützt — Workflow-Dynamik.
6. **Cross-Reference zu Phase 11 Backlog für extern-pen-test + externer WCAG-Audit** im README.md Verweise-Section ergänzen.
---
## 10. Gesamt-Bewertung
**PASS.**
Die Phase ist vollständig, template-konform und mit dokumentierten User-Wünschen konsistent. Implementation-Steps sind atomar und committable, Test-Requirements sind konkret (Coverage-Targets, E2E-Flows benannt), Security-Notes adressieren die wichtigsten Risiken. Kleinere Lücken (Encryption-Algorithmus-Spezifikation, Key-Rotation-Workflow, Lighthouse-Δ-PR-Comments, Routen-Liste-Konsistenz zwischen Lighthouse und WCAG) sind nicht-blockierend und können während Implementation oder via einem kleinen Follow-up-Commit der Detail-MDs adressiert werden.
Keine kritischen Compliance-Lücken. Hash-Chain ist kryptografisch korrekt aufgesetzt, DSGVO-Cascade ist vollständig (12 Tabellen explizit), Pseudonymisierung mit verschlüsselter Map ist sicher konzipiert (mit der oben genannten Empfehlung zur Algorithmus-Konkretisierung).
**Empfehlung:** Phase 10 kann zur Implementation freigegeben werden. Die in Section 9 aufgeführten Verbesserungen sollten vor Start der jeweiligen Detail-MDs (insbesondere compliance-audit-export.md Step 2, dsgvo-bulk-ops.md Step 2, lighthouse.md Step 9) als kleine Detail-MD-Edits eingearbeitet werden, um Implementation-Subagents keine Architektur-Entscheidungen treffen zu lassen.