Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,59 @@
|
||||
# Phase 11 — Backlog
|
||||
|
||||
**Status:** dauerhaft im Wartezimmer, nur on-demand vom Operator aktivierbar
|
||||
**Tasks:** 7 dokumentierte Items
|
||||
**Ziel:** Features dokumentieren, die **bewusst nicht jetzt** umgesetzt werden, aber so vorbereitet sind, dass ein späterer Agent sie ohne erneute Architektur-Diskussion starten kann, sobald die jeweilige Trigger-Condition eintritt.
|
||||
|
||||
## Warum es diese Phase überhaupt gibt
|
||||
|
||||
Ein paar Features wurden in der ursprünglichen Boilerplate-Analyse als „eigentlich sinnvoll, aber heute zu früh" eingestuft:
|
||||
|
||||
- Sie skalieren erst ab einem bestimmten Markt-/Kunden-Reifegrad sinnvoll (z.B. Plugin-Marketplace ohne Product-Market-Fit verbrennt nur Entwicklungszeit).
|
||||
- Sie sind politisch/strategisch abhängig (z.B. Multi-Region nur wenn die EU-only-Annahme bricht).
|
||||
- Sie haben hohe Maintenance-Kosten (z.B. WCAG-Zertifizierung muss jährlich reauditiert werden).
|
||||
- Sie sind komplette Sales-/Compliance-Driver, deren Aufwand nicht ohne konkreten Enterprise-Deal gerechtfertigt ist (z.B. Customer-Tenant-SSO).
|
||||
|
||||
Damit der „spätere Agent" nicht bei Null anfängt, dokumentiert jede Backlog-Datei:
|
||||
|
||||
- **Trigger Condition** — was muss passieren, bevor das Item aus dem Backlog kommt
|
||||
- **Approach** — der gewählte technische Weg inkl. Begründung gegen Alternativen
|
||||
- **Implementation Steps** — knapp, aber konkret (nicht so granular wie aktive Tasks)
|
||||
- **Test Requirements + Acceptance Criteria** — kürzer, aber existent
|
||||
- **Depends on** — realistische Vorbedingungen aus früheren Phasen
|
||||
|
||||
## Aktivierungs-Regel
|
||||
|
||||
Ein Backlog-Item wechselt von `backlog: <trigger>` auf `pending` **nur** wenn:
|
||||
|
||||
1. Der Operator explizit das Item zur Aktivierung freigibt (PR / Issue / direkte Anweisung)
|
||||
2. Die im Item dokumentierte Trigger-Condition nachweisbar eingetreten ist
|
||||
3. Alle `Depends on`-Tasks aus früheren Phasen sind `completed`
|
||||
|
||||
Der ausführende Agent **darf nicht** eigenmächtig Backlog-Items ziehen, auch wenn die aktive Roadmap leer ist. Stattdessen: `BLOCKERS.md` aktualisieren und Operator informieren.
|
||||
|
||||
## Übersicht der Backlog-Items
|
||||
|
||||
| Task-ID | Datei | Trigger Condition | Aufwand (wenn aktiviert) | Depends on |
|
||||
|---|---|---|---|---|
|
||||
| #24 | `plugin-marketplace.md` | Plugin-System (Phase 06) fertig + Product-Market-Fit + Bedarf nach Drittentwickler-Ökosystem | 6-8 Wochen | Phase 06 vollständig, Phase 05 (Feature-Flags + AI-Cost) |
|
||||
| #52 | `multi-region.md` | EU-only-Markt-Annahme bricht (z.B. US-Customer relevant) | 4-5 Wochen + laufende Mehrkosten | Phase 03 (PgBouncer + Read-Write-Split + Outbox) |
|
||||
| #57 | `stripe-marketplace-ui.md` | B2B2C-Marketplace-Modell aktiviert (Portal-Owner verkaufen via Plattform an Endkunden) | 3-4 Wochen | Phase 05 (Feature-Flags), bestehendes Stripe-Subscription-Setup |
|
||||
| #64 | `python-sdk.md` | Data-Engineering-Use-Cases oder Python-Backend-Integrations für Tenants werden spürbar | 1 Woche | Phase 08 (`ts-sdk.md` — gleiche OpenAPI-Spec) |
|
||||
| #66 | `customer-tenant-sso.md` | Enterprise-Verkauf ab Deal-Größe ~$50k/Jahr oder Compliance-Anforderungen | 2-3 Wochen | Phase 09 (Authentik + Admin-SSO) — Federation auf gleicher Authentik-Instanz |
|
||||
| #74 | `wcag-external-cert.md` | Enterprise-Sales-Pipeline besteht auf zertifizierter Accessibility-Compliance | 3-4 Wochen + €5-15k externer Audit | Phase 10 (`wcag-internal.md`) muss durch sein |
|
||||
| #77 | `stryker.md` | Coverage-Pflicht (`test-coverage.md`) fertig + Bedarf nach höherer Test-Quality (z.B. nach Critical-Bug-Production-Incident) | 1 Woche Setup + Tuning + Initial-Fix-Sprint | Phase 10 (`test-coverage.md`) |
|
||||
|
||||
## Wann ein Backlog-Item geprüft werden sollte
|
||||
|
||||
- **Quarterly:** Operator + Agent gehen die Liste gemeinsam durch und prüfen, ob ein Trigger eingetreten ist.
|
||||
- **Bei jedem Enterprise-Deal-Pipeline-Update:** `customer-tenant-sso.md` + `wcag-external-cert.md` neu bewerten.
|
||||
- **Bei jedem Plugin-System-Milestone (Phase 06):** `plugin-marketplace.md` neu bewerten.
|
||||
- **Bei Production-Incidents:** `stryker.md` + ggf. weitere reaktiv prüfen.
|
||||
|
||||
## Verweise
|
||||
|
||||
- Detail-MD-Template: `../DETAIL-MD-TEMPLATE.md`
|
||||
- Agent-Workflow: `../AGENT-INSTRUCTIONS.md` (insb. Regel 7 zu Dependencies)
|
||||
- Execution-Order: `../00-execution-order.md`
|
||||
- Live-Status: `../PROGRESS.md`
|
||||
- Vorgänger-Phasen, die Backlog-Items entblocken: `../06-plugin-system/README.md`, `../09-authentik-admin-sso/README.md`, `../10-compliance-polish/README.md`
|
||||
@@ -0,0 +1,173 @@
|
||||
# Phase 11 — Backlog — Verification Report
|
||||
|
||||
**Datum:** 2026-05-16
|
||||
**Verifier:** Verification-Subagent (READ-ONLY)
|
||||
**Scope:** README.md + 7 Backlog-Item-Detail-MDs
|
||||
**Verdict (TL;DR):** PASS mit kleineren Hinweisen (siehe §10). Alle 7 Items erfüllen die Template-Konformität, Status-Format, Trigger-Conditions und Dependency-Konsistenz. README hat eine vollständige Übersichts-Tabelle. Kein Blocker für Übergabe.
|
||||
|
||||
---
|
||||
|
||||
## 1. Template-Konformität (15 Sections + Reihenfolge)
|
||||
|
||||
Erwartete Reihenfolge (DETAIL-MD-TEMPLATE.md §111-128):
|
||||
1 Frontmatter — 2 Problem — 3 Depends on — 4 Blocks — 5 Approach — 6 Implementation Steps — 7 Test Requirements — 8 Acceptance Criteria — 9 Rollback Strategy — 10 Security Notes — 11 Subagent Recommendations — 12 Staging-Deployment-Steps — 13 Deviations from Plan — 14 Progress Log — 15 Lessons Learned (optional).
|
||||
|
||||
| Datei | Frontmatter | Problem | Depends on | Blocks | Approach | Impl-Steps | Test-Req | Accept | Rollback | Security | Subagents | Staging | Deviations | Progress | Lessons | Reihenfolge |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| plugin-marketplace.md | OK | OK | OK | OK | OK | OK (8) | OK | OK | OK | OK | OK | OK | OK | OK | – (opt) | OK |
|
||||
| multi-region.md | OK | OK | OK | OK | OK | OK (8) | OK | OK | OK | OK | OK | OK | OK | OK | – (opt) | OK |
|
||||
| stripe-marketplace-ui.md | OK | OK | OK | OK | OK | OK (8) | OK | OK | OK | OK | OK | OK | OK | OK | – (opt) | OK |
|
||||
| python-sdk.md | OK | OK | OK | OK | OK | OK (7) | OK | OK | OK | OK | OK | OK | OK | OK | – (opt) | OK |
|
||||
| customer-tenant-sso.md | OK | OK | OK | OK | OK | OK (8) | OK | OK | OK | OK | OK | OK | OK | OK | – (opt) | OK |
|
||||
| wcag-external-cert.md | OK | OK | OK | OK | OK | OK (9) | OK | OK | OK | OK | OK | OK | OK | OK | – (opt) | OK |
|
||||
| stryker.md | OK | OK | OK | OK | OK | OK (8) | OK | OK | OK | OK | OK | OK | OK | OK | – (opt) | OK |
|
||||
|
||||
**Ergebnis:** Alle 7 Files halten alle 14 Pflicht-Sections in der vorgeschriebenen Reihenfolge ein. „Lessons Learned" ist laut Template optional und sinnvollerweise weggelassen, weil noch nicht ausgeführt. PASS.
|
||||
|
||||
---
|
||||
|
||||
## 2. Status-Format
|
||||
|
||||
Erwartet: `Status: backlog: <trigger-condition>`
|
||||
|
||||
| Datei | Status-Line |
|
||||
|---|---|
|
||||
| plugin-marketplace.md | `**Status:** \`backlog: Plugin-System (Phase 06) vollständig in Production + nachweisbarer Product-Market-Fit … 3 externe Devs …\`` | OK |
|
||||
| multi-region.md | `**Status:** \`backlog: EU-only-Markt-Annahme bricht …\`` | OK |
|
||||
| stripe-marketplace-ui.md | `**Status:** \`backlog: B2B2C-Marketplace-Modell aktiviert …\`` | OK |
|
||||
| python-sdk.md | `**Status:** \`backlog: Data-Engineering-Use-Cases … 2 Tenant-Anfragen …\`` | OK |
|
||||
| customer-tenant-sso.md | `**Status:** \`backlog: Enterprise-Verkauf ab Deal-Größe ~$50k/Jahr …\`` | OK |
|
||||
| wcag-external-cert.md | `**Status:** \`backlog: Enterprise-Sales-Pipeline besteht auf zertifizierter Accessibility-Compliance …\`` | OK |
|
||||
| stryker.md | `**Status:** \`backlog: test-coverage.md (Phase 10) fertig + Bedarf nach höherer Test-Quality …\`` | OK |
|
||||
|
||||
**Ergebnis:** 7/7 verwenden `backlog: <trigger>` exakt nach Vorgabe. PASS.
|
||||
|
||||
---
|
||||
|
||||
## 3. Trigger-Conditions — Klarheit
|
||||
|
||||
Jede Trigger-Condition ist für einen zukünftigen Operator nachvollziehbar verifizierbar:
|
||||
|
||||
- `plugin-marketplace.md` — quantifizierbar (Phase 06 fertig, mind. 3 Drittentwickler-Anfragen).
|
||||
- `multi-region.md` — quantifizierbar (erster Non-EU-Customer, Latenz/Compliance-Trigger).
|
||||
- `stripe-marketplace-ui.md` — modell-getrieben (B2B2C-Aktivierung).
|
||||
- `python-sdk.md` — quantifizierbar (mind. 2 Tenant-Anfragen).
|
||||
- `customer-tenant-sso.md` — quantifizierbar (Deal-Größe ~$50k/Jahr) und/oder Compliance.
|
||||
- `wcag-external-cert.md` — vertrieblich-getrieben (Pipeline-Anforderung).
|
||||
- `stryker.md` — qualitäts-getrieben (Coverage stabil + Bug-Incident).
|
||||
|
||||
**Ergebnis:** Alle Trigger sind ausreichend konkret. Besonders gut: `plugin-marketplace` und `python-sdk` haben harte Zahlen statt nur „wenn relevant". PASS.
|
||||
|
||||
---
|
||||
|
||||
## 4. Dependencies — Konsistenz mit Operator-Vorgaben
|
||||
|
||||
| Datei | Operator-Vorgabe | Tatsächliche `Depends on` | Match |
|
||||
|---|---|---|---|
|
||||
| plugin-marketplace.md | Phase 06 komplett | `06/wasm-sandbox.md` + `06/hooks-lifecycle.md` + `06/audit-docs.md` + `05/feature-flags.md` + `05/ai-cost-phase-3.md` | OK (Phase 06 vollständig + 2 Phase-05-Ergänzungen sinnvoll begründet) |
|
||||
| multi-region.md | Phase 03 (PgBouncer, R/W-Split, Outbox) | `03/shared-store-package.md` + `03/pgbouncer.md` + `03/read-write-split.md` + `03/outbox-pattern.md` + `03/asset-cdn.md` | OK (alle drei genannten + 2 sinnvolle Ergänzungen) |
|
||||
| stripe-marketplace-ui.md | Phase 05 oder unabhängig? | `05/feature-flags.md` + bestehendes Stripe-Setup + `10/compliance-audit-export.md` | OK (Phase 05 verlinkt, Phase 10 als Audit-Anker — nachvollziehbar) |
|
||||
| python-sdk.md | Phase 08 `ts-sdk.md` | `08/ts-sdk.md` + bestehende OpenAPI-Spec | OK |
|
||||
| customer-tenant-sso.md | Phase 09 (Authentik wiederverwendet, ~1 Woche Ersparnis) | `09/authentik-setup.md` + `09/admin-oidc-login.md` + Tenant-Member-Verwaltung | OK — Authentik-Wiederverwendung **explizit** im Approach §32 erwähnt („spart vs. ursprünglichem Plan ~1 Woche, weil saml-jackson nicht extra aufgesetzt werden muss") |
|
||||
| wcag-external-cert.md | Phase 10 `wcag-internal.md` + Pre-Work-Gate | `10/wcag-internal.md` + `10/i18n-foundation.md` + `10/lighthouse.md` | OK — Pre-Work-Gate **explizit** als „harte Pre-Work-Voraussetzung" (Zeile 21) und Step 1 verlangt Pre-Audit-Baseline-Verify |
|
||||
| stryker.md | Phase 10 `test-coverage.md` | `10/test-coverage.md` + bestehende Vitest-Setup | OK |
|
||||
|
||||
**Ergebnis:** Alle Dependency-Vorgaben sind exakt umgesetzt. Zusätzliche Dependencies sind jeweils kurz begründet (kein „Cargo-Cult"). PASS.
|
||||
|
||||
---
|
||||
|
||||
## 5. Approach-Qualität (Konkretheit + Verworfene Alternativen)
|
||||
|
||||
Alle 7 Files führen explizit „Begründung gegen Alternativen" mit dem Token *Verworfen* / *verworfen*:
|
||||
|
||||
- `plugin-marketplace.md` §29-33 — 3 Alternativen verworfen (In-App, externer SaaS) → eigener Tenant gewählt
|
||||
- `multi-region.md` §29-33 — 2 Alternativen verworfen (Active-Active Multi-Master, Single-Write-Region) → Tenant-Region-Pinning
|
||||
- `stripe-marketplace-ui.md` §27-31 — 2 Alternativen verworfen (manuelle Splits, Stripe-Standard-Redirect) → Embedded-Onboarding
|
||||
- `python-sdk.md` §27-30 — 2 Alternativen verworfen (manuell, Custom-Jinja-Codegen) + 1 Sekundär-Option (openapi-python-client) → openapi-generator-cli
|
||||
- `customer-tenant-sso.md` §27-32 — 1 Alternative verworfen (saml-jackson eigenständig) → Authentik-Federation
|
||||
- `wcag-external-cert.md` §31-34 — 2 Alternativen verworfen (Selbstdeklaration, Nur Lighthouse) + 3 Provider-Optionen aufgeführt
|
||||
- `stryker.md` §26-30 — 2 Alternativen verworfen (PR-Check, andere Mutation-Tools) → Nightly-Job
|
||||
|
||||
Approach-Beschreibungen sind durchgehend konkret genug für einen späteren Subagent: konkrete Libraries, Endpoints, Routing-Mechanismen, Konfig-Schalter sind benannt. PASS.
|
||||
|
||||
---
|
||||
|
||||
## 6. Acceptance Criteria
|
||||
|
||||
Alle 7 Files haben eine ausreichend gefasste Checklist-Section:
|
||||
|
||||
- plugin-marketplace.md — 11 Items
|
||||
- multi-region.md — 8 Items + Latenz-Messgrenzwert (≤150ms TTFB)
|
||||
- stripe-marketplace-ui.md — 10 Items
|
||||
- python-sdk.md — 7 Items
|
||||
- customer-tenant-sso.md — 10 Items
|
||||
- wcag-external-cert.md — 9 Items (inkl. PDF-VPAT + Re-Audit-Reminder)
|
||||
- stryker.md — 9 Items mit Threshold-Enforcement
|
||||
|
||||
Alle Items sind objektiv verifizierbar. PASS.
|
||||
|
||||
---
|
||||
|
||||
## 7. Konsistenz mit User-Wünschen (Operator-Briefing)
|
||||
|
||||
| Operator-Wunsch | Erfüllt? | Beleg |
|
||||
|---|---|---|
|
||||
| „Marketplace ist im Backlog" — Plugin- UND Stripe-Marketplace-UI | OK | `plugin-marketplace.md` (#24) + `stripe-marketplace-ui.md` (#57) beide vorhanden |
|
||||
| „EU-only, Multi-Region im Backlog" | OK | `multi-region.md` (#52), Trigger „EU-only-Annahme bricht" |
|
||||
| „Python-SDK ins Backlog" | OK | `python-sdk.md` (#64) |
|
||||
| „Customer-Tenant-SSO nach Phase 09, Authentik wiederverwendet → ~1 Woche Ersparnis" | OK | `customer-tenant-sso.md` Zeile 32 nennt die Ersparnis explizit, Approach baut auf Phase-09-Authentik auf statt saml-jackson |
|
||||
| „WCAG-Externe-Zertifizierung im Backlog mit Pre-Work-Gate" | OK | `wcag-external-cert.md` Zeile 21 nennt `wcag-internal.md` als „harte Pre-Work-Voraussetzung", Step 1 erzwingt Pre-Audit-Baseline-Verify |
|
||||
| „Stryker als Backlog" | OK | `stryker.md` (#77), Trigger „test-coverage.md fertig + Bug-Incident" |
|
||||
|
||||
**Ergebnis:** Alle sechs Operator-Wünsche eins-zu-eins umgesetzt. PASS.
|
||||
|
||||
---
|
||||
|
||||
## 8. Übersichts-Tabelle in README.md + Re-Check-Cadence
|
||||
|
||||
- README.md §36-44 enthält Tabelle mit allen 7 Items: Task-ID, Datei, Trigger Condition, Aufwand, Depends on. OK.
|
||||
- README.md §46-51 dokumentiert Re-Check-Cadence: **Quarterly** (allgemein) + zusätzliche reaktive Trigger (Enterprise-Deal-Update, Plugin-System-Milestones, Production-Incidents). OK.
|
||||
- README.md verlinkt zurück auf `DETAIL-MD-TEMPLATE.md`, `AGENT-INSTRUCTIONS.md`, `00-execution-order.md`, `PROGRESS.md` und die entblockenden Vorgänger-Phasen 06/09/10. OK.
|
||||
|
||||
PASS.
|
||||
|
||||
---
|
||||
|
||||
## 9. Cross-Check Phasen-Numerierung / Pfad-Referenzen
|
||||
|
||||
Alle relativen Pfade in `Depends on` referenzieren existierende Phasen-Verzeichnisse:
|
||||
|
||||
- `../06-plugin-system/…` (✓)
|
||||
- `../05-business-features/…` (✓)
|
||||
- `../03-scaling-infrastructure/…` (✓)
|
||||
- `../08-mobile-cli-storybook-sdk/…` (✓ Pfad-Naming in 00-execution-order.md §85 bestätigt)
|
||||
- `../09-authentik-admin-sso/…` (✓)
|
||||
- `../10-compliance-polish/…` (✓)
|
||||
|
||||
Keine 404-Pfade. PASS.
|
||||
|
||||
---
|
||||
|
||||
## 10. Hinweise / Nice-to-have (kein Blocker)
|
||||
|
||||
1. **plugin-marketplace.md → `ai-cost-phase-3.md`** als Dep ist tendenziell *nice-to-have* statt *hart*: Marketplace könnte technisch ohne Pricing-Backbone als Free-Only starten und die Stripe-Connect-Integration ist im Step 5 selbständig dokumentiert. Empfehlung: kurzer Halbsatz im Dep-Eintrag, dass `ai-cost-phase-3` *empfohlen* aber nicht *blockierend* ist — sonst denkt ein späterer Agent fälschlich, Free-Only-Launch geht nicht.
|
||||
|
||||
2. **multi-region.md** verweist auf „Fly.io Anycast (oder vergleichbar — Bunny.net / Cloudflare-Load-Balancer)" — sehr gut, dass mehrere Provider-Optionen genannt werden. Könnte zusätzlich erwähnt werden, dass Hetzner Cloud aktuell keine echten Multi-Region-Compute-Optionen hat (nur Multi-DC innerhalb DE), womit beim Trigger ein Provider-Wechsel/Hinzunahme nötig wird. Aktuell implizit, könnte explizit gemacht werden.
|
||||
|
||||
3. **stripe-marketplace-ui.md** „Drei-Phasen-Rollout" (W1-2 / W3 / W4) wird im Approach beschrieben, aber die Implementation-Steps (8) mappen nicht 1:1 auf die 3 Wochen-Phasen. Für einen Subagent wäre eine Kennzeichnung „Step 1-3 = Phase 1, Step 4-5 = Phase 2, Step 6-8 = Phase 3" hilfreich. Klein, nicht blockierend.
|
||||
|
||||
4. **wcag-external-cert.md** Step 4 („Audit-Durchlauf abwarten") hat keinen Commit zugewiesen — das ist konsistent, weil nichts zu committen ist, sollte aber explizit als „(kein Commit — Wartezeit)" markiert werden, sonst denkt ein Agent, dass dort ein Commit fehlt.
|
||||
|
||||
5. **stryker.md** nennt „Score-Target Mutation-Score >70% auf Critical-Paths" und listet 5 Critical-Path-Module. Die AC-Liste sagt „mind. 5 Critical-Path-Module". Empfehlung: in der AC die Modul-Liste explizit benennen (Auth, Billing, Tenant-Isolation, Audit-Logging, AI-Cost), um spätere Interpretations-Drift zu vermeiden.
|
||||
|
||||
6. **README.md Re-Check-Cadence:** „Quarterly" ist allgemein dokumentiert, aber kein einzelnes Item nennt seine eigene Re-Check-Cadence in der Detail-MD. Für reine Backlog-Items ist das ausreichend — der Quarterly-Sweep aus README ist die Single Source of Truth. Optional könnte jede Detail-MD einen Einzeiler `## Re-Check Cadence: quarterly` haben. Nicht blockierend.
|
||||
|
||||
7. **Phase-11-`Lessons Learned`-Section**: optional laut Template (`§108`) — alle 7 Files lassen sie korrekt weg, weil noch nicht ausgeführt. Kein Issue.
|
||||
|
||||
---
|
||||
|
||||
## 11. Final Verdict
|
||||
|
||||
**PASS** — Phase 11 (Backlog) ist abgabereif. Alle harten Anforderungen (Template-Konformität, Status-Format, Trigger-Conditions, Dependency-Konsistenz mit Operator-Vorgaben, Übersichts-Tabelle, Re-Check-Cadence) sind erfüllt. Die unter §10 gelisteten Hinweise sind Verbesserungsvorschläge ohne Blocker-Charakter und können vom späteren ausführenden Agent beim Aktivieren des jeweiligen Items mitgenommen werden.
|
||||
|
||||
Keine Korrekturen nötig, um Phase 10 abzuschließen und in Wartebetrieb für Phase 11 zu gehen.
|
||||
@@ -0,0 +1,122 @@
|
||||
# Customer-Tenant-SSO (Federation mit Okta / AzureAD / Google-Workspace)
|
||||
|
||||
**Status:** `backlog: Enterprise-Verkauf ab Deal-Größe ~$50k/Jahr oder bei expliziter Compliance-Anforderung (z.B. SOC2-Customer-Audit, ISO 27001)`
|
||||
**Task-ID:** #66
|
||||
**Phase:** 11 (Backlog)
|
||||
**Estimated Effort:** 1-2 Wochen Integration + 1 Woche Admin-UI (= 2-3 Wochen total) wenn aktiviert
|
||||
**Owner:** unassigned
|
||||
|
||||
## Problem
|
||||
|
||||
Tenants im Enterprise-Bereich verlangen häufig, dass ihre Mitarbeiter sich nicht mit Email/Passwort einloggen, sondern per SSO ihres bestehenden IdPs (Okta, AzureAD, Google-Workspace, OneLogin). Solange das nicht da ist, scheitern Verkäufe an Security-Reviews oder es entsteht Friction bei Onboarding/Offboarding (keine zentrale Lifecycle-Verwaltung).
|
||||
|
||||
Vor Aktivierung lohnt es sich nicht, weil typische SMB-Tenants kein SSO benötigen und die Wartung pro IdP nicht trivial ist.
|
||||
|
||||
## Depends on
|
||||
|
||||
- `../09-authentik-admin-sso/authentik-setup.md` — Authentik-Instanz muss laufen
|
||||
- `../09-authentik-admin-sso/admin-oidc-login.md` — Authentik-OIDC-Flow ist im Codebase verdrahtet, gleiche Patterns werden für Tenant-SSO wiederverwendet
|
||||
- bestehende Tenant-Member-Verwaltung (`app/modules/tenants/`)
|
||||
|
||||
## Blocks
|
||||
|
||||
- nichts (Backlog-Item, blockt keine aktive Roadmap)
|
||||
|
||||
## Approach
|
||||
|
||||
**Aufbau auf der bereits in Phase 09 hochgezogenen Authentik-Instanz** statt eigenes saml-jackson-Setup. Begründung:
|
||||
|
||||
- *Alternativplan im ursprünglichen Backlog: saml-jackson als separate Tenant-IdP-Brücke aufsetzen*: separater Stack, eigene DB, eigene Maintenance — verworfen, weil Authentik bereits multi-tenant-fähig ist
|
||||
- *Authentik als Federation-Hub (gewählt)*: Authentik kann beliebig viele Source-Provider definieren (SAML, OIDC, OAuth2) und sie als Inbound-Federation in eine bestehende Authentik-Identity-Welt mappen. Wir definieren pro Tenant eine Source (z.B. „Tenant Acme — Okta-SAML") in Authentik, und der Tenant-Login-Flow läuft: Tenant-User → Boilerplate `/auth/login` → Authentik (zweiter OIDC-Provider `toolctrl-tenant-sso`) → Authentik routet anhand der Email-Domain auf die richtige Source → externer IdP-Login → Authentik-Callback → Boilerplate-Session
|
||||
|
||||
Das spart vs. ursprünglichem Plan ~1 Woche, weil saml-jackson nicht extra aufgesetzt werden muss.
|
||||
|
||||
**Per-Tenant-IdP-Config-UI:** unter `/app/$tenant/settings/sso` konfiguriert ein Tenant-Admin seine eigene Source. Die UI nutzt die Authentik-API (Token + REST), um Sources programmatisch anzulegen/zu aktualisieren — der Admin sieht nie das Authentik-UI direkt. Unterstützte Source-Typen: SAML 2.0 + OIDC.
|
||||
|
||||
**Authentik handhabt:**
|
||||
|
||||
- Identity-Mapping (Email als primary Key, Mappings für `name`, `groups`)
|
||||
- JIT-Provisioning der zentralen Authentik-Identity beim ersten externen Login
|
||||
- SCIM-Server-Endpoint für IdPs die User-Provisioning pushen können
|
||||
|
||||
**Boilerplate-Seite muss handhaben:**
|
||||
|
||||
- Domain-Verification für SAML-Pflicht-Durchsetzung (Tenant muss DNS-TXT-Record setzen, damit User mit Email `@acme.com` zwingend per Tenant-SSO einloggen muss, nicht per Email/Passwort)
|
||||
- Tenant-Membership-Synchronisation (Authentik-User → `TenantUser`-Record mit korrekter Rolle, JIT bei erstem Login)
|
||||
- Session-Logout: Boilerplate-Logout triggert Authentik-End-Session, optional IdP-Initiated-SLO durchreichen
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Tenant-SSO-Provider-Definition in Authentik** — den in Phase 09 bereits als Platzhalter angelegten `toolctrl-tenant-sso` OIDC-Provider aktivieren und mit eigenem Client-ID/Secret konfigurieren. Commit: `11-backlog/customer-tenant-sso: enable tenant-sso oidc provider`
|
||||
2. **Tenant-Login-Flow in Boilerplate** — neuer Route `/auth/tenant-sso/start?tenant=...&email=...` → Redirect zu Authentik mit Domain-Hint, Callback-Handler erstellt/updated `TenantUser`. Commit: `11-backlog/customer-tenant-sso: tenant login + callback`
|
||||
3. **Authentik-API-Client** — kleine Wrapper-Lib in `app/utils/authentik/` mit Methods `createSource`, `updateSource`, `listSources` (REST via Authentik-API-Token). Commit: `11-backlog/customer-tenant-sso: authentik api client`
|
||||
4. **Tenant-Admin-UI** — `/app/$tenant/settings/sso` Seite: Source-Typ wählen (SAML/OIDC), Metadata-XML hochladen oder Endpoints manuell eingeben, Test-Connection-Button, Status-Anzeige. Commit: `11-backlog/customer-tenant-sso: tenant sso admin ui`
|
||||
5. **Domain-Verification** — Tenant trägt zu verifizierende Email-Domain ein, App generiert DNS-TXT-Token, Background-Check via DNS-Resolver, bei Erfolg wird Domain als „SSO-Pflicht" markiert (Email/Passwort-Login für diese Domain abgewiesen). Commit: `11-backlog/customer-tenant-sso: domain verification + sso enforcement`
|
||||
6. **JIT-Provisioning + Role-Mapping** — Callback-Handler liest Authentik-Group-Claims, mappt auf Tenant-Rollen (default: alle User werden „Member", Admin-Mapping per Tenant-Config), schreibt Audit-Event. Commit: `11-backlog/customer-tenant-sso: jit provisioning + role mapping`
|
||||
7. **Logout + optionales SLO** — Tenant-Logout triggert Authentik-End-Session; SLO (IdP-Initiated) als opt-in pro Source. Commit: `11-backlog/customer-tenant-sso: logout + slo`
|
||||
8. **Doku** — `docs/operations/tenant-sso-setup.md` (Operator-Sicht), `docs/tenant-admin/sso-configuration.md` (Tenant-Admin-Sicht mit Beispielen für Okta + AzureAD + Google-Workspace). Commit: `11-backlog/customer-tenant-sso: documentation`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
- **Unit-Tests:** Domain-Verification-Logik, Email-Domain-zu-Tenant-Resolver, Role-Mapping-Funktion, Authentik-API-Wrapper (mit gemocktem Authentik-Server)
|
||||
- **Integration-Tests:** Tenant-SSO-Login End-to-End gegen lokale Authentik-Instanz mit gemockter externer Source; JIT-Provisioning erzeugt `TenantUser`; Domain-Verification durchgesetzt
|
||||
- **E2E-Tests (Playwright):** Tenant-Admin konfiguriert SAML-Source, Test-User loggt sich via Source ein, landet im Tenant-Dashboard mit korrekter Rolle
|
||||
- **Coverage-Target:** ≥75% für `app/modules/tenant-sso/` + `app/utils/authentik/`
|
||||
- **Test-Files:** neben Source, E2E unter `apps/web/playwright/tenant-sso/`
|
||||
|
||||
**NICHT als completed markieren bevor alle Tests grün sind.**
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Authentik-OIDC-Provider `toolctrl-tenant-sso` aktiv mit eigenem Client
|
||||
- [ ] Tenant-Admin kann unter `/app/$tenant/settings/sso` eine SAML- oder OIDC-Source anlegen, Test-Connection-Button bestätigt Konfiguration
|
||||
- [ ] Domain-Verification per DNS-TXT funktioniert, verifizierte Domain wird SSO-Pflicht
|
||||
- [ ] Tenant-User mit verifizierter Email-Domain kann sich nur per SSO einloggen (Email/Passwort wird abgewiesen)
|
||||
- [ ] JIT-Provisioning erstellt `TenantUser` mit korrekt gemappter Rolle beim ersten Login
|
||||
- [ ] Logout triggert Authentik-End-Session
|
||||
- [ ] Audit-Events `tenant.sso.login.success/failure/jit_provisioned/source_created/source_updated` werden geschrieben
|
||||
- [ ] Tests grün
|
||||
- [ ] Docs angelegt
|
||||
- [ ] Progress-Log + PROGRESS.md aktualisiert
|
||||
|
||||
## Rollback Strategy
|
||||
|
||||
- Feature-Flag `tenant_sso.enabled` schaltet die SSO-Login-Routes ab, Tenants fallen auf Email/Passwort zurück
|
||||
- Domain-Verification-Pflicht kann pro Tenant deaktiviert werden, ohne dass Source-Definition in Authentik gelöscht werden muss
|
||||
- Authentik-Sources sind in Authentik-DB persistent — Rollback der Boilerplate-Seite löscht sie nicht, sie können manuell oder beim nächsten Tenant-Edit re-aktiviert werden
|
||||
- Bei Notfall: Tenant-Admin kann Source temporär in der UI deaktivieren, Authentik routet dann auf Default-Login
|
||||
|
||||
## Security Notes
|
||||
|
||||
- **Domain-Verification ist kritisch** — ohne sie könnte ein User mit Email einer fremden Domain einen eigenen Tenant aufmachen und SSO mit der fremden Domain forcen. DNS-TXT-Check vor SSO-Pflicht-Aktivierung Pflicht
|
||||
- Authentik-API-Token: Boilerplate-Backend braucht Schreibrechte auf Sources — Token nur in Server-Env, niemals im Client
|
||||
- SAML-Metadata-Upload: XML-Parsing muss XXE-Hardened sein (entweder via DOMPurify-äquivalente Library oder strenges XSD-Validation)
|
||||
- IdP-Initiated-SAML-Logins (vs SP-Initiated) sind anfälliger für Replay-Attacken — als opt-in markieren, Default ist SP-Initiated
|
||||
- Group-Claims von externer IdP nicht blind als Admin-Rolle übernehmen — Tenant-Admin muss Mapping explizit konfigurieren (kein Auto-Promotion)
|
||||
- Session-Fixation-Schutz: nach erfolgreichem SSO-Callback neue Session-ID generieren
|
||||
|
||||
## Subagent Recommendations
|
||||
|
||||
- **Planning:** `Plan`-Subagent mit Phase-09-Outputs als Input (insb. Authentik-Setup-Doku)
|
||||
- **Research:** `Explore`-Subagent für Authentik-Multi-Source-Federation-Best-Practices und konkrete Okta/AzureAD/Google-Workspace-Setup-Schritte
|
||||
- **Implementation:** ein `general-purpose`-Subagent pro Step
|
||||
- **Tests:** separater `general-purpose`-Subagent für SAML-Integration-Tests (XXE-Hardening-Verify)
|
||||
- **Verification:** `gsd-verifier` für Acceptance-Criteria; manueller Test mit echtem Okta-Dev-Account
|
||||
- **Code-Review:** `gsd-code-reviewer` nach Step 5 (Domain-Verification — security-kritisch) und nach Step 8 (final)
|
||||
|
||||
## Staging-Deployment-Steps
|
||||
|
||||
1. Branch `agent/11-backlog-customer-tenant-sso` pushen
|
||||
2. Authentik auf Staging muss laufen (aus Phase 09)
|
||||
3. Okta-Developer-Account (free) als externe SAML-IdP-Test-Source einrichten
|
||||
4. Test-Tenant in Boilerplate-Staging mit verifizierter Domain anlegen
|
||||
5. End-to-End-Login via Okta verifizieren
|
||||
6. Domain-Verification-Pflicht testen (User mit verifizierter Domain darf nicht per Email/Passwort einloggen)
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
_(Wird vom ausführenden Agent gefüllt.)_
|
||||
|
||||
## Progress Log
|
||||
|
||||
_(Wird vom ausführenden Agent gefüllt.)_
|
||||
@@ -0,0 +1,115 @@
|
||||
# Multi-Region-Deployment
|
||||
|
||||
**Status:** `backlog: EU-only-Markt-Annahme bricht (z.B. erster US-Customer mit Latenz-/Compliance-Anforderungen, oder APAC-Pipeline)`
|
||||
**Task-ID:** #52
|
||||
**Phase:** 11 (Backlog)
|
||||
**Estimated Effort:** 4-5 Wochen wenn aktiviert + dauerhafte Mehrkosten + ~2x Ops-Aufwand
|
||||
**Owner:** unassigned
|
||||
|
||||
## Problem
|
||||
|
||||
Die Boilerplate läuft heute single-region auf Hetzner (EU). Solange alle Kunden EU-basiert sind und DSGVO/EU-Datenresidenz das wichtigste Compliance-Argument ist, ist das die richtige Wahl. Sobald ein Kunde mit Anforderungen außerhalb EU dazukommt — Latenz (US-/APAC-User), Datenresidenz-Pflicht (USA, Kanada, Australien) oder Single-Region-SLA-Bruch — muss die Architektur Multi-Region tragen können.
|
||||
|
||||
Vorab-Aktivierung würde dauerhafte Mehrkosten (zweite Hetzner-/Fly-Region + zweite DB-Replikation + zweiter Storage) erzeugen, ohne dass ein Kunde sie rechtfertigt.
|
||||
|
||||
## Depends on
|
||||
|
||||
- `../03-scaling-infrastructure/shared-store-package.md` — Cache muss schon per-region-fähig sein (Redis-Cluster pro Region)
|
||||
- `../03-scaling-infrastructure/pgbouncer.md` — DB-Connection-Pooling muss stehen, bevor regionale DB-Replikation eingeführt wird
|
||||
- `../03-scaling-infrastructure/read-write-split.md` — Routing-Schicht für Read-Replicas wird zu Region-Routing erweitert
|
||||
- `../03-scaling-infrastructure/outbox-pattern.md` — Cross-Region-Event-Replikation läuft über Outbox, nicht direkt
|
||||
- `../03-scaling-infrastructure/asset-cdn.md` — CDN muss bereits global verteilt sein
|
||||
|
||||
## Blocks
|
||||
|
||||
- nichts (Backlog-Item, blockt keine aktive Roadmap)
|
||||
|
||||
## Approach
|
||||
|
||||
**Tenant-Region-Pinning + Anycast-Frontend.** Begründung gegen Alternativen:
|
||||
|
||||
- *Active-Active Multi-Master (Postgres BDR / CockroachDB)*: zu komplex und teuer in Ops; Konflikt-Resolution bei multi-region Writes ist eine eigene Klasse von Bugs. Verworfen.
|
||||
- *Global Read-Replicas, Single-Write-Region*: löst nicht das Datenresidenz-Problem (US-Tenant-Daten würden in EU geschrieben). Verworfen.
|
||||
- *Tenant-Region-Pinning (gewählt)*: jeder Tenant lebt komplett in einer Region. Beim Onboarding wählt Tenant-Admin die Region (EU/US/APAC), danach bleiben alle Daten + Compute dort. Klare Datenresidenz, keine Cross-Region-Writes, einfache Ops-Story.
|
||||
|
||||
**Routing:** Fly.io Anycast (oder vergleichbar — Bunny.net / Cloudflare-Load-Balancer mit Geo-DNS) für die HTTP-Container, die selbst stateless sind. Container halten lokalen Region-Cache (Redis pro Region) und delegieren DB-Calls an die regionale Postgres-Instanz.
|
||||
|
||||
**Region-Routing:** Auth-Cookie + JWT-Header tragen `region-index` als kleinen Claim. Reverse-Proxy / App-Middleware liest das und routet entweder lokal (Tenant ist in der Region) oder gibt 307-Redirect auf die korrekte regionale Subdomain (`eu.<domain>` / `us.<domain>`). Für nicht-authentifizierte Requests: Geo-IP-basiertes Routing auf die nächstgelegene Region, Tenant-Login forciert dann den Switch.
|
||||
|
||||
**Storage:** separate Storage-Buckets pro Region (S3-compatible, z.B. Hetzner Object Storage / AWS S3 / Cloudflare R2 — abhängig von Datenresidenz-Anforderung des Kunden). Asset-CDN aus Phase 03 cached global, Origin-Pulls gehen an den regionalen Bucket des Tenants.
|
||||
|
||||
**Cloudflare-Workers-Edge-Adapter** ist eine **optionale** Erweiterung für noch niedrigere Latenz bei statischen oder cache-baren Endpoints (Auth-Discovery, Pricing-Pages, Marketing-Funnel-Routes). Wird in einer späteren Iteration evaluiert, nicht Pflicht zur Aktivierung.
|
||||
|
||||
**Cross-Region:** absolutes Minimum — nur Audit-Log-Aggregation für Compliance-Reports (read-only, asynchron via Outbox → Kafka/NATS-Stream). Keine Tenant-Daten migrieren.
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Region-Indicator im Tenant-Modell** — `Tenant.region` (enum: `eu`, `us`, `apac`), Default `eu`, in JWT/Session-Cookie als Claim. Commit: `11-backlog/multi-region: add tenant region pinning`
|
||||
2. **DB-Routing-Middleware** — basierend auf JWT-Claim oder Subdomain entscheidet die Middleware, welche Postgres-Connection-Pool genutzt wird. Erweitert die Read-Write-Split-Logik aus Phase 03. Commit: `11-backlog/multi-region: db routing middleware`
|
||||
3. **Storage-Bucket pro Region** — Storage-Adapter erweitert um `region`-Argument; pro Tenant-Region jeweils ein S3-Bucket. Commit: `11-backlog/multi-region: per-region storage buckets`
|
||||
4. **Anycast-Frontend-Routing** — Fly.io (oder vergleichbar) deployt App-Container in EU + US; Geo-DNS für Initial-Routing, Cookie/JWT für authentifizierten Steady-State. Commit: `11-backlog/multi-region: anycast frontend deploy`
|
||||
5. **Region-Wrong-Redirect-Handler** — wenn Request in falscher Region landet, 307-Redirect auf korrekte Subdomain. Commit: `11-backlog/multi-region: cross-region redirect handler`
|
||||
6. **Cross-Region-Audit-Aggregation** — Outbox-Event-Stream pro Region wird in zentralen Compliance-Logging-Sink (eine Region, read-only) repliziert. Commit: `11-backlog/multi-region: audit log aggregation`
|
||||
7. **Tenant-Onboarding-Region-Auswahl** — Wizard fragt beim Sign-up nach Region, schreibt `Tenant.region`, provisioniert in der gewählten Region. Commit: `11-backlog/multi-region: onboarding region picker`
|
||||
8. **Doku + Runbook** — `docs/operations/multi-region.md` (Architektur, Region-Migration-Prozess für Tenant-Wechsel, Failover-Strategie pro Region). Commit: `11-backlog/multi-region: documentation`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
- **Unit-Tests:** Region-Resolver (Tenant.region → DB-Pool), Region-Mismatch-Detector, Cookie/JWT-Region-Claim-Parser
|
||||
- **Integration-Tests:** Tenant-Onboarding mit Region-Auswahl, DB-Call landet in korrekter Region, Storage-Upload landet in korrektem Bucket, Cross-Region-Request triggert 307-Redirect
|
||||
- **E2E-Tests (Playwright):** Sign-up mit Region US → Login von EU-IP → korrekter Redirect; Asset-Upload landet in US-Bucket; Audit-Log-Entry erscheint im Compliance-Sink
|
||||
- **Coverage-Target:** ≥70% für `app/utils/region/*` + alle touched Routing-Module
|
||||
- **Test-Files:** neben Source, E2E unter `apps/web/playwright/multi-region/`
|
||||
|
||||
**NICHT als completed markieren bevor alle Tests grün sind.**
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Tenant kann beim Onboarding zwischen Regionen (mindestens EU + US) wählen
|
||||
- [ ] Alle Tenant-Daten (Postgres, Storage, Cache) liegen physisch in der gewählten Region
|
||||
- [ ] Authentifizierte Requests landen in der korrekten Region; Cross-Region-Requests werden per 307 umgeleitet
|
||||
- [ ] Latenz-Messung: Request von US-Client an US-Tenant unter 150ms TTFB (gegen EU-Tenant von US-Client wäre vergleichbar 200-300ms)
|
||||
- [ ] Audit-Log-Aggregation läuft, alle regionalen Audit-Events landen im zentralen Compliance-Sink
|
||||
- [ ] Tests grün
|
||||
- [ ] `docs/operations/multi-region.md` mit Architektur-Diagramm + Runbook angelegt
|
||||
- [ ] Progress-Log + PROGRESS.md aktualisiert
|
||||
|
||||
## Rollback Strategy
|
||||
|
||||
- Multi-Region kann region-weise zurückgebaut werden — z.B. US-Region down: Geo-DNS-Eintrag entfernen, US-Tenants temporär auf EU-Region failovern (Notfall, mit explizitem Tenant-Consent wegen Datenresidenz-Bruch)
|
||||
- Storage-Buckets pro Region bleiben unabhängig — kein Risiko von Daten-Vermischung
|
||||
- Feature-Flag `multi_region.routing_enabled` schaltet Routing-Logik ab, App fällt auf single-region (EU) zurück
|
||||
- DB-Migration: `Tenant.region` mit Default `eu` kann ohne Datenverlust droppt werden
|
||||
|
||||
## Security Notes
|
||||
|
||||
- **Datenresidenz-Garantie ist Compliance-kritisch** — jede Cross-Region-Datenbewegung muss audit-loggable sein, Penetration-Test sollte Routing-Bypass-Versuche prüfen
|
||||
- JWT-Region-Claim muss server-signed sein (HS256/RS256 wie bisher), Client-Tampering würde sonst Region-Pinning umgehen
|
||||
- Audit-Log-Aggregation: nur Metadaten + Tenant-IDs cross-region replizieren, **niemals Tenant-Inhalt**
|
||||
- Region-Failover-Runbook muss explizit machen, dass Failover Datenresidenz-Bruch ist — Customer-Notification + Consent erforderlich
|
||||
|
||||
## Subagent Recommendations
|
||||
|
||||
- **Planning:** `Plan`-Subagent mit Phase-03-Outputs (PgBouncer, Read-Write-Split, Outbox) als Input
|
||||
- **Research:** `Explore`-Subagent für Fly.io vs Cloudflare-Workers-Anycast-Vergleich, Bunny.net / Cloudflare-Load-Balancer-Optionen
|
||||
- **Implementation:** ein `general-purpose`-Subagent pro Step
|
||||
- **Tests:** separater `general-purpose`-Subagent für E2E (Multi-Region-Setup ist test-lastig)
|
||||
- **Verification:** `gsd-verifier` für Acceptance-Criteria; manueller Latenz-Test via Staging-VM in US-Region
|
||||
- **Code-Review:** `gsd-code-reviewer` nach Step 4 (Anycast) und nach Step 8 (final)
|
||||
|
||||
## Staging-Deployment-Steps
|
||||
|
||||
1. Branch `agent/11-backlog-multi-region` pushen
|
||||
2. Fly.io / vergleichbarer Provider in EU + US einrichten (separater Account / Region für Staging)
|
||||
3. Postgres-Instanzen pro Region provisionieren (Hetzner / Fly Postgres / RDS)
|
||||
4. Storage-Buckets pro Region
|
||||
5. Geo-DNS / Cloudflare-Load-Balancer für Staging-Subdomains konfigurieren
|
||||
6. Test-Tenants in jeder Region anlegen, Cross-Region-Routing manuell verifizieren
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
_(Wird vom ausführenden Agent gefüllt.)_
|
||||
|
||||
## Progress Log
|
||||
|
||||
_(Wird vom ausführenden Agent gefüllt.)_
|
||||
@@ -0,0 +1,117 @@
|
||||
# Plugin-Marketplace
|
||||
|
||||
**Status:** `backlog: Plugin-System (Phase 06) vollständig in Production + nachweisbarer Product-Market-Fit der Boilerplate + spürbarer Bedarf nach Drittentwickler-Ökosystem (mind. 3 externe Devs fragen aktiv nach Distributionskanal)`
|
||||
**Task-ID:** #24
|
||||
**Phase:** 11 (Backlog)
|
||||
**Estimated Effort:** 6-8 Wochen wenn aktiviert
|
||||
**Owner:** unassigned
|
||||
|
||||
## Problem
|
||||
|
||||
Sobald Phase 06 (WASM-Sandbox + Hooks-Lifecycle) live ist, können Tenants Plugins lokal installieren — aber es gibt keinen Weg, sie öffentlich anzubieten, zu entdecken, zu monetarisieren. Ohne Marketplace gibt es keinen Anreiz für Dritt-Entwickler, Plugins zu schreiben, und kein Discovery-Kanal für Tenants. Das Plugin-System bleibt damit nur eine interne Erweiterungs-Schicht statt ein Ökosystem-Hebel.
|
||||
|
||||
Aktivierung lohnt sich erst, wenn die Boilerplate genug Tenants hat, dass ein Plugin-Marketplace wirtschaftlich wird — sonst sind die ~6-8 Wochen Aufwand + die laufenden Review-/Moderation-Kosten verbrannt.
|
||||
|
||||
## Depends on
|
||||
|
||||
- `../06-plugin-system/wasm-sandbox.md` — Plugin-Runtime + Signaturprüfung müssen stehen
|
||||
- `../06-plugin-system/hooks-lifecycle.md` — Lifecycle-Events + Versions-Pinning müssen stehen
|
||||
- `../06-plugin-system/audit-docs.md` — Plugin-Manifest-Schema + Audit-Anforderungen müssen dokumentiert sein
|
||||
- `../05-business-features/feature-flags.md` — Marketplace-Listing-Flags pro Plugin (z.B. Beta-Phase)
|
||||
- `../05-business-features/ai-cost-phase-3.md` — Pricing-Backbone wird für Paid-Plugins wiederverwendet
|
||||
|
||||
## Blocks
|
||||
|
||||
- nichts (Backlog-Item, blockt keine aktive Roadmap)
|
||||
|
||||
## Approach
|
||||
|
||||
**Eigene Marketplace-Site als zweite App-Instanz (eigener Tenant auf eigener Plattform).** Begründung gegen Alternativen:
|
||||
|
||||
- *In-App-Marketplace innerhalb der Boilerplate*: würde die Tenant-Isolation verwässern (Publisher-Accounts wären cross-tenant) und Admin-Panel mit Marketplace-Verwaltung überfrachten. Verworfen.
|
||||
- *Externe SaaS-Marketplace (z.B. ähnlich Stripe Apps)*: zu viel Vendor-Lock-in für eine self-hosted-first Boilerplate. Verworfen.
|
||||
- *Eigener Tenant auf der gleichen Boilerplate-Plattform*: dogfooded das Tenant-System, nutzt Auth/Billing/Search/Audit-Infra die bereits da ist, klare Trennung zwischen Marketplace-Operator und Tenants.
|
||||
|
||||
**Publisher-Onboarding** generiert pro Publisher ein Ed25519-Keypair (Private-Key bleibt nur beim Publisher, Public-Key im Marketplace + jedem ausgelieferten Plugin-Manifest). Plugin-Signaturprüfung erfolgt offline beim Install ohne Marketplace-Roundtrip.
|
||||
|
||||
**Submission-Flow:** Publisher lädt signiertes `.wasm` + `manifest.json` hoch → Marketplace führt automatisierte Static-Analysis (Capability-Whitelist-Check, Manifest-Schema-Validation, AV-Scan via Phase-01-Layer-1+2) durch → manuelle Review-Pipeline (Marketplace-Operator) bevor Listing live geht. Spätere Iteration: mehr Auto-Approval bei verifizierten Publishern.
|
||||
|
||||
**Pricing:** Free, One-Time-Purchase, Subscription. Subscription-Plugins nutzen Stripe-Connect-Splits (Default 70/30 Publisher/Plattform, pro Plugin konfigurierbar). Tenant-Install pinnt Plugin-Version + öffnet Subscription bei Stripe-Connect-Account des Publishers.
|
||||
|
||||
**Update-Pipeline:** Publisher published neue Version → Marketplace-Backend prüft semver-Kompatibilität → Notifications an alle installierten Tenants (Email + In-App). Auto-Update nur für PATCH-Versions opt-in, MAJOR/MINOR immer manual-confirm pro Tenant.
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Marketplace-Tenant-Setup** — eigene Subdomain `marketplace.<domain>`, Boilerplate-Stack mit eigener DB, Branding-Theme. Commit: `11-backlog/plugin-marketplace: bootstrap marketplace tenant`
|
||||
2. **Publisher-Onboarding + Ed25519-Keys** — Publisher-Account-Modell, Key-Generierung im Browser (WebCrypto), Public-Key-Storage. Commit: `11-backlog/plugin-marketplace: add publisher onboarding with ed25519`
|
||||
3. **Plugin-Submission-Flow** — Upload-UI, Static-Analysis-Pipeline (Capability-Check, Manifest-Validation, AV-Scan), Review-Queue für Marketplace-Operator. Commit: `11-backlog/plugin-marketplace: submission + review pipeline`
|
||||
4. **Public Listing-UI** — Such-Index (Meilisearch aus Phase 04), Ratings (1-5 Sterne + Review-Text), Screenshots, Pricing-Anzeige, Capability-Liste. Commit: `11-backlog/plugin-marketplace: public listing pages`
|
||||
5. **Stripe-Connect-Integration** — Connect-Account-Onboarding pro Publisher, application_fee_amount + transfer_data.destination für Splits, Subscription-Plugins als Stripe-Subscription mit Publisher als Destination-Account. Commit: `11-backlog/plugin-marketplace: stripe connect + revenue splits`
|
||||
6. **Tenant-Side Install-Flow** — von Marketplace via Deep-Link in Tenant-Admin → Signature-Verify → Subscription-Confirm → Plugin-Aktivierung mit Capability-Consent-Screen. Commit: `11-backlog/plugin-marketplace: tenant install flow with consent`
|
||||
7. **Update-Pipeline + Notifications** — Version-Diff-Anzeige, Notification via Email + Bell-Icon, opt-in Auto-Patch, Rollback-Button für Tenants. Commit: `11-backlog/plugin-marketplace: update pipeline + notifications`
|
||||
8. **Doku** — `docs/marketplace/publisher-guide.md`, `docs/marketplace/operator-runbook.md` (Review-Standards, Sperren von Plugins, Refund-Handling). Commit: `11-backlog/plugin-marketplace: documentation`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
- **Unit-Tests:** Signaturprüfung (Ed25519 sign/verify mit bekannten Vektoren), Manifest-Schema-Validation, Revenue-Split-Berechnung, Semver-Diff-Logik
|
||||
- **Integration-Tests:** Submission-Flow End-to-End (Upload → Analysis → Approve → Listing), Install-Flow (Listing → Stripe-Checkout → Tenant-Aktivierung), Update-Notification-Fan-out
|
||||
- **E2E-Tests (Playwright):** Publisher-Onboarding, Submit-Plugin-Happy-Path, Tenant-Install + Capability-Consent, Subscription-Cancel mit Stripe-Webhook-Simulation
|
||||
- **Coverage-Target:** ≥75% für Marketplace-spezifische Pakete (`apps/marketplace/`, neue Module unter `app/modules/marketplace/`)
|
||||
- **Test-Files:** neben Source-Files (`*.test.ts`), E2E unter `apps/marketplace/playwright/`
|
||||
|
||||
**NICHT als completed markieren bevor alle Tests grün sind.**
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Marketplace erreichbar unter eigener Subdomain mit eigener Tenant-Datenbank
|
||||
- [ ] Publisher kann sich registrieren, Ed25519-Keypair generieren und ein erstes Plugin submitten
|
||||
- [ ] Review-Queue im Marketplace-Admin-Panel funktional, mit Approve/Reject + Begründung
|
||||
- [ ] Stripe-Connect-Onboarding für Publisher abgeschlossen, KYC-Status sichtbar
|
||||
- [ ] Subscription-Plugin kann gekauft werden, Splits werden korrekt verbucht (70/30 default)
|
||||
- [ ] Tenant kann Plugin installieren, sieht Capability-Consent-Screen, Plugin läuft in WASM-Sandbox
|
||||
- [ ] Update-Notification erreicht Tenants binnen 5 Minuten nach Publish
|
||||
- [ ] Rollback eines aktualisierten Plugins pro Tenant funktioniert
|
||||
- [ ] Tests grün (lint, typecheck, unit, integration, e2e)
|
||||
- [ ] Docs `docs/marketplace/publisher-guide.md` + `docs/marketplace/operator-runbook.md` angelegt
|
||||
- [ ] Progress-Log + PROGRESS.md aktualisiert
|
||||
|
||||
## Rollback Strategy
|
||||
|
||||
- Marketplace ist eine eigene App-Instanz — Take-down ohne Auswirkung auf andere Tenants möglich
|
||||
- Feature-Flag `marketplace.public_listings_enabled` schaltet öffentliche Sichtbarkeit ab, ohne dass bereits installierte Plugins betroffen sind
|
||||
- Stripe-Connect-Onboarding kann pausiert werden, neue Subscriptions verhindert; bestehende laufen ungestört weiter
|
||||
- DB-Migration: alle Marketplace-Tables haben prefix `mp_`, einfacher Drop möglich
|
||||
|
||||
## Security Notes
|
||||
|
||||
- **Ed25519-Private-Keys verlassen nie den Publisher-Browser**, Storage-Empfehlung (Hardware-Token / Password-Manager) im Publisher-Guide
|
||||
- Plugin-Manifest muss Capabilities explizit listen — Marketplace-Review verifiziert, dass die deklarierten Capabilities dem WASM-Modul-Verhalten entsprechen (statische Analyse + Stichproben-Dynamic-Test)
|
||||
- AV-Scan (Phase 01) ist Pflicht für jeden Upload
|
||||
- Stripe-Connect: application_fee_amount und transfer_data.destination müssen serverseitig validiert sein (kein Client-Tampering)
|
||||
- Capability-Consent-Screen muss Capabilities in verständlicher Sprache erklären, nicht nur als Manifest-Keys
|
||||
- Plugin-Revocation: Marketplace kann signiertes Revocation-Statement broadcasten, das Tenants beim nächsten Plugin-Load durchsetzen (Kill-Switch für kompromittierte Plugins)
|
||||
|
||||
## Subagent Recommendations
|
||||
|
||||
- **Planning:** `Plan`-Subagent mit dieser MD + Phase-06-Outputs als Input
|
||||
- **Research:** `Explore`-Subagent für Stripe-Connect-Best-Practices und Plugin-Marketplace-Prior-Art (VSCode-Marketplace, Stripe-Apps, Shopify-Apps)
|
||||
- **Implementation:** ein `general-purpose`-Subagent pro Step (8 Subagents über die Phase)
|
||||
- **Tests:** separater `general-purpose`-Subagent pro Test-Block (unit/integration/e2e separat)
|
||||
- **Verification:** `gsd-verifier` für jede Acceptance-Criteria-Gruppe
|
||||
- **Code-Review:** `gsd-code-reviewer` nach jedem Step, finaler Phase-Review nach Schritt 8
|
||||
|
||||
## Staging-Deployment-Steps
|
||||
|
||||
1. Branch `agent/11-backlog-plugin-marketplace` pushen
|
||||
2. Coolify deployed Marketplace-App als zweite Stack-Instanz auf Hetzner
|
||||
3. Stripe-Connect im Test-Mode mit Test-Keys verkabeln
|
||||
4. Mit Test-Publisher-Account ein Test-Plugin durch den kompletten Flow schicken
|
||||
5. Tenant-Install + Subscription + Cancel verifizieren
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
_(Wird vom ausführenden Agent gefüllt.)_
|
||||
|
||||
## Progress Log
|
||||
|
||||
_(Wird vom ausführenden Agent gefüllt.)_
|
||||
@@ -0,0 +1,111 @@
|
||||
# Python-SDK
|
||||
|
||||
**Status:** `backlog: Data-Engineering-Use-Cases oder Python-Backend-Integrations für Tenants werden spürbar (mind. 2 Tenant-Anfragen, oder eigener Bedarf in Daten-Pipelines / Notebooks)`
|
||||
**Task-ID:** #64
|
||||
**Phase:** 11 (Backlog)
|
||||
**Estimated Effort:** ~1 Woche wenn aktiviert
|
||||
**Owner:** unassigned
|
||||
|
||||
## Problem
|
||||
|
||||
Die Boilerplate liefert mit Phase 08 (`ts-sdk.md`) ein TypeScript-SDK aus, das von Browser-/Node-Konsumenten benutzt werden kann. Tenants mit Python-Stacks (Data-Engineering, Notebooks, FastAPI/Django-Backends, ML-Pipelines, Scraper) müssten heute selbst über `requests` gegen die OpenAPI-Spec arbeiten. Sobald das spürbar wird (Anfragen, Friction-Reports), lohnt sich ein offizielles, generiertes Python-SDK.
|
||||
|
||||
Solange kein Python-Bedarf existiert, ist der Maintenance-Aufwand (Two-SDKs-in-Sync halten, PyPI-Releases bauen, Python-Typing-Edge-Cases) nicht gerechtfertigt.
|
||||
|
||||
## Depends on
|
||||
|
||||
- `../08-mobile-cli-storybook-sdk/ts-sdk.md` — die gleiche OpenAPI-Spec aus dem TS-SDK-Setup ist Quelle der Wahrheit für den Python-Codegen
|
||||
- bestehende OpenAPI-Spec-Generation aus der API-Route-Definition
|
||||
|
||||
## Blocks
|
||||
|
||||
- nichts (Backlog-Item, blockt keine aktive Roadmap)
|
||||
|
||||
## Approach
|
||||
|
||||
**Codegen via `openapi-generator-cli` (Java-basiert, am bequemsten als Docker-Image) gegen die gleiche OpenAPI-Spec wie TS-SDK.** Begründung gegen Alternativen:
|
||||
|
||||
- *Manuell geschriebenes Python-SDK*: doppelter Maintenance-Aufwand, drift-anfällig. Verworfen.
|
||||
- *openapi-python-client (Pythonic Codegen)*: schmaler in Custom-Templates, modernere Typing, aber kleinerer Ökosystem-Support. Sekundär-Option wenn openapi-generator zu verbose ist.
|
||||
- *Custom Codegen via Jinja-Templates*: zu viel Eigenentwicklung. Verworfen.
|
||||
|
||||
**Output:** `packages/api-client-py/` als PyPI-publishable Package, semver-aligned mit dem TS-SDK (gleiche Major-Version pro API-Version).
|
||||
|
||||
**Custom-Templates** liefern Boilerplate-spezifische Helpers:
|
||||
|
||||
- **Auth-Handling:** API-Key (Header `Authorization: Bearer <key>`) und JWT-Bearer, einheitlicher Constructor (`Client(api_key=...)` oder `Client(jwt=...)`)
|
||||
- **Pagination-Iterator:** generierte List-Endpoints geben Python-Iterator zurück, der automatisch über `cursor`/`page` paginiert
|
||||
- **Retry-Logik:** via `tenacity` mit Exponential-Backoff + Jitter, nur für 5xx + 429 + Network-Errors
|
||||
- **Webhook-Verify:** Helper `verify_webhook(secret, payload, signature)` mit HMAC-SHA256 (gleiche Signaturlogik wie TS-SDK)
|
||||
|
||||
**Tests:** `pytest` gegen eine lokal hochgezogene Boilerplate-API (Test-Setup im Repo), Snapshot-Tests für generierten Code (regenerate-Drift erkennen).
|
||||
|
||||
**Release-Pipeline:** GitHub-Actions-Workflow `python-sdk-release.yml` baut bei Tag-Push (`api-client-py-vX.Y.Z`) Wheel + sdist und published auf PyPI via Trusted-Publishing (kein PyPI-Token im Repo).
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Generator-Setup** — `openapi-generator-cli` als Docker-Image-Pinned-Version in `scripts/codegen-python.sh`, OpenAPI-Spec wird aus dem laufenden Dev-Server gezogen oder aus dem schon im TS-SDK gespeicherten JSON. Commit: `11-backlog/python-sdk: add codegen script`
|
||||
2. **Erstes Codegen-Run** — Output in `packages/api-client-py/`, Basis-Generator-Output ohne Customizations committen. Commit: `11-backlog/python-sdk: initial generated client`
|
||||
3. **Custom-Templates: Auth** — Jinja-Templates für Configuration-Class und Auth-Helpers überschreiben, einheitlicher Constructor. Commit: `11-backlog/python-sdk: custom auth templates`
|
||||
4. **Custom-Templates: Pagination** — Iterator-Wrapper um List-Endpoints, automatisches Cursor-Following. Commit: `11-backlog/python-sdk: pagination iterator`
|
||||
5. **Retry + Webhook-Verify-Helper** — `tenacity`-basierter Retry-Decorator, `hmac`-basierter Webhook-Verifier in `api_client/webhooks.py`. Commit: `11-backlog/python-sdk: retry + webhook helpers`
|
||||
6. **pytest-Suite gegen lokale API** — Dev-Server hochfahren, gegen ein paar key Endpoints testen (List + Pagination, Create, Webhook-Verify, Retry-on-503). Commit: `11-backlog/python-sdk: pytest integration suite`
|
||||
7. **PyPI-Release-Workflow + Doku** — GitHub-Actions-Workflow mit Trusted-Publishing, `packages/api-client-py/README.md` mit Quick-Start + Auth-Beispielen + Pagination-Beispiel + Webhook-Verify-Beispiel. Commit: `11-backlog/python-sdk: release workflow + readme`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
- **Unit-Tests:** Auth-Header-Setting, Pagination-Iterator (Cursor-Termination, Empty-Response), Retry-Logik (5xx triggert Retry, 4xx nicht), Webhook-Verify (gültig + ungültig + Replay-Toleranz)
|
||||
- **Integration-Tests:** gegen lokal hochgezogene Boilerplate-API (Pytest-Fixture startet API + Test-DB) — Create + List + Pagination + Auth-Failure-Cases
|
||||
- **Snapshot-Tests:** generierter Code im Repo committed; CI failt wenn Re-Generation ohne Schema-Änderung den Output ändert
|
||||
- **Coverage-Target:** ≥80% für Custom-Helpers (Auth, Pagination, Retry, Webhooks); generierter Code ausgenommen
|
||||
- **Test-Files:** `packages/api-client-py/tests/`
|
||||
|
||||
**NICHT als completed markieren bevor alle Tests grün sind.**
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `packages/api-client-py/` enthält generiertes Client-Package mit Custom-Auth/Pagination/Retry/Webhook-Helpers
|
||||
- [ ] `pytest` Suite läuft grün gegen lokale Boilerplate-API
|
||||
- [ ] Snapshot-Tests detektieren ungewollten Codegen-Drift
|
||||
- [ ] PyPI-Release-Workflow funktioniert (Dry-Run auf TestPyPI verifiziert)
|
||||
- [ ] README mit Quick-Start + Auth + Pagination + Webhook-Beispielen vorhanden
|
||||
- [ ] Tests grün
|
||||
- [ ] Progress-Log + PROGRESS.md aktualisiert
|
||||
|
||||
## Rollback Strategy
|
||||
|
||||
- Python-SDK ist ein zusätzliches Package — Entfernung beeinträchtigt API nicht
|
||||
- Bei brüchiger PyPI-Release: alte Version bleibt verfügbar, neue Version yanken via PyPI-Web-UI
|
||||
- Custom-Templates können stufenweise zurückgenommen werden (z.B. Pagination raus, manueller Cursor wieder); Konsumenten müssen dann auf vorherige Version pinnen
|
||||
|
||||
## Security Notes
|
||||
|
||||
- **API-Keys werden nur über Constructor übergeben, nicht aus ENV gelesen** — Verantwortung bleibt beim Konsumenten, Logging-Filter verhindert versehentliches Logging des Keys
|
||||
- Webhook-Verify-Helper verwendet `hmac.compare_digest` (timing-safe) statt String-Vergleich
|
||||
- Generierter Code wird auf bekannte CVEs in transitiven Deps gescannt (`pip-audit` im CI)
|
||||
- TLS-Verifikation ist Default-On, kein Override-Flag im public API
|
||||
|
||||
## Subagent Recommendations
|
||||
|
||||
- **Planning:** `Plan`-Subagent mit `ts-sdk.md`-Output als Referenz für Feature-Parität
|
||||
- **Research:** `Explore`-Subagent für openapi-generator vs openapi-python-client Vergleich (entscheidet zwischen den beiden falls openapi-generator nicht passt)
|
||||
- **Implementation:** ein `general-purpose`-Subagent pro Step
|
||||
- **Tests:** separater `general-purpose`-Subagent für die Pytest-Suite
|
||||
- **Verification:** `gsd-verifier` für Acceptance-Criteria
|
||||
- **Code-Review:** `gsd-code-reviewer` nach Step 7
|
||||
|
||||
## Staging-Deployment-Steps
|
||||
|
||||
1. Branch `agent/11-backlog-python-sdk` pushen
|
||||
2. Boilerplate-API lokal (oder auf Staging) starten
|
||||
3. `pip install -e packages/api-client-py` im Test-venv
|
||||
4. Manuelles Smoke-Script ausführen (List + Create + Webhook-Verify)
|
||||
5. TestPyPI-Dry-Release vor echtem PyPI-Release
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
_(Wird vom ausführenden Agent gefüllt.)_
|
||||
|
||||
## Progress Log
|
||||
|
||||
_(Wird vom ausführenden Agent gefüllt.)_
|
||||
@@ -0,0 +1,123 @@
|
||||
# Stripe-Marketplace-UI (Connect Onboarding + Splits + Payouts)
|
||||
|
||||
**Status:** `backlog: B2B2C-Marketplace-Modell aktiviert (Portal-Owner verkaufen via Plattform an Endkunden, Plattform nimmt application_fee)`
|
||||
**Task-ID:** #57
|
||||
**Phase:** 11 (Backlog)
|
||||
**Estimated Effort:** 3-4 Wochen wenn aktiviert
|
||||
**Owner:** unassigned
|
||||
|
||||
## Problem
|
||||
|
||||
Die Boilerplate unterstützt heute klassische B2B-Subscriptions (Plattform-Tenant zahlt Plattform-Owner). Sobald das Geschäftsmodell sich Richtung B2B2C öffnet — Portal-Owner verkaufen über die Plattform Subscriptions/One-Time-Purchases an ihre Endkunden, Plattform behält eine application_fee — fehlt die komplette Connect-UI-Schicht: Connect-Onboarding für Portal-Owner, Splits-Konfiguration, Payouts-Dashboard, Refund-/Dispute-Workflow.
|
||||
|
||||
Zusätzlich ist `application_fee_amount` heute auf `0` hardcoded — das funktioniert nur, weil Connect noch gar nicht produktiv genutzt wird. Bei Aktivierung muss diese Stelle gehärtet werden, sonst verschenkt die Plattform jede Connect-Transaktion.
|
||||
|
||||
## Depends on
|
||||
|
||||
- `../05-business-features/feature-flags.md` — Connect-Features hinter Flag `commerce.connect_enabled`, damit nicht-Marketplace-Tenants es nicht sehen
|
||||
- bestehendes Stripe-Subscription-Setup (heute schon im Codebase, siehe `apps/web/app/modules/subscriptions/`)
|
||||
- `../10-compliance-polish/compliance-audit-export.md` — Connect-Onboarding-Verifikations-Status muss audit-loggable sein (KYC-Events)
|
||||
|
||||
## Blocks
|
||||
|
||||
- nichts (Backlog-Item, blockt keine aktive Roadmap; entblockt aber `plugin-marketplace.md` indirekt, weil Connect dort wiederverwendet wird)
|
||||
|
||||
## Approach
|
||||
|
||||
Drei-Phasen-Rollout wenn aktiviert. Begründung gegen Alternativen:
|
||||
|
||||
- *Manuelle Splits via Stripe-Dashboard*: zu fehleranfällig + nicht skalierbar bei vielen Portal-Ownern. Verworfen.
|
||||
- *Stripe-Standard-Account-Onboarding (Redirect)*: schlechter UX-Übergang, brüchige Brand-Experience. Verworfen.
|
||||
- *Embedded-Onboarding (gewählt)*: Stripe-Connect-Embedded-Components rendern direkt in der App, bleiben in der Plattform-Domain, geben strukturierte Status-Events zurück.
|
||||
|
||||
### Phase 1 (Wochen 1-2): Connect-Onboarding-Wizard + Splits-Editor
|
||||
|
||||
- **Connect-Onboarding-Wizard** für Portal-Owner mit Stripe-Connect-Embedded-Onboarding-Components, Verifikations-Status-Polling (KYC pending / verified / restricted), destination-Validation gegen Connect-Account-Owner (cross-check dass übergebene `transfer_data.destination` zum eingeloggten Portal-Owner-Tenant gehört)
|
||||
- **Splits-Editor:** Plattform-Admin setzt globale + per-Plan `application_fee_percent` oder `application_fee_amount` (in basis points), Portal-Owner sieht effective Earnings pro Transaktion in Echtzeit-Preview
|
||||
- **Hardening:** `application_fee_amount` wird serverseitig aus Plan-Konfiguration berechnet, niemals vom Client gesetzt (heute hardcoded `0`, wird durch Settings-driven Berechnung ersetzt)
|
||||
|
||||
### Phase 2 (Woche 3): Payouts-Dashboard + KYC-Monitoring
|
||||
|
||||
- **Payouts-Dashboard** für Portal-Owner: kommende Payouts (Stripe Balance API), Historie der vergangenen Payouts, CSV-Export
|
||||
- **KYC-Status-Monitoring:** Background-Job pollt Connect-Accounts auf Status-Changes (verified → restricted etc.), Notification an Portal-Owner + Plattform-Admin bei Hold/Restriction
|
||||
- **Audit-Events:** `commerce.connect.onboarding.completed`, `commerce.connect.kyc.status_changed`, `commerce.payout.scheduled`
|
||||
|
||||
### Phase 3 (Woche 4): Refund-/Dispute-Flow + Doku
|
||||
|
||||
- **Refund-Flow:** Portal-Owner kann Refunds aus Order-Detail-Seite triggern; application_fee wird Stripe-default proportional zurückerstattet (oder konfigurierbar pro Refund)
|
||||
- **Dispute-Flow:** Dispute-Webhook → Notification an Portal-Owner + Plattform-Admin, Evidence-Upload-UI für Portal-Owner, Status-Tracking
|
||||
- **Doku:** `docs/commerce/connect-setup.md` (Plattform-Admin-Sicht), `docs/commerce/portal-owner-guide.md` (Portal-Owner-Sicht inkl. KYC-FAQ)
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Connect-Module-Skeleton + Feature-Flag** — `app/modules/commerce-connect/`, Feature-Flag `commerce.connect_enabled`. Commit: `11-backlog/stripe-marketplace-ui: scaffold connect module`
|
||||
2. **Embedded-Onboarding-UI** — Connect-Account erstellen (Server-Action), Embedded-Onboarding-Component mounten, Status-Polling. Commit: `11-backlog/stripe-marketplace-ui: connect onboarding wizard`
|
||||
3. **Splits-Editor + Server-side Fee-Calculation** — Settings-UI für Splits, Server berechnet `application_fee_amount` aus Plan-Config, alte hardcoded `0` ersetzt. Commit: `11-backlog/stripe-marketplace-ui: splits editor + fee hardening`
|
||||
4. **Payouts-Dashboard** — Balance + Payout-Liste via Stripe API, CSV-Export. Commit: `11-backlog/stripe-marketplace-ui: payouts dashboard`
|
||||
5. **KYC-Status-Background-Job** — Worker (Phase 03 Worker-Queues) pollt täglich, schreibt Audit-Events, sendet Notifications. Commit: `11-backlog/stripe-marketplace-ui: kyc monitoring`
|
||||
6. **Refund-Flow** — UI + Server-Action + Webhook-Handling für `charge.refunded`. Commit: `11-backlog/stripe-marketplace-ui: refund flow`
|
||||
7. **Dispute-Flow** — Webhook-Handler für `charge.dispute.*`, Evidence-Upload, Status-Tracking. Commit: `11-backlog/stripe-marketplace-ui: dispute flow`
|
||||
8. **Doku** — `docs/commerce/connect-setup.md` + `docs/commerce/portal-owner-guide.md`. Commit: `11-backlog/stripe-marketplace-ui: documentation`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
- **Unit-Tests:** Fee-Calculation (Plan + global Override + per-Plan-Override), destination-Validation (Tenant-Ownership-Check), CSV-Export-Formatter
|
||||
- **Integration-Tests:** Onboarding-Flow End-to-End mit Stripe-Test-Mode, Webhook-Handling für `account.updated` / `charge.refunded` / `charge.dispute.created`, Splits-korrekte-Verbuchung
|
||||
- **E2E-Tests (Playwright):** Onboarding-Wizard Happy-Path, Refund aus Order-Detail-Seite, Dispute-Evidence-Upload
|
||||
- **Coverage-Target:** ≥75% für `app/modules/commerce-connect/`
|
||||
- **Test-Files:** neben Source, E2E unter `apps/web/playwright/commerce-connect/`
|
||||
|
||||
**NICHT als completed markieren bevor alle Tests grün sind.**
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Portal-Owner kann sich via Embedded-Onboarding-Wizard durchführen, Status-Update nach Stripe-Verifikation erscheint im Dashboard
|
||||
- [ ] Splits-Editor: Plattform-Admin setzt Fee, Portal-Owner sieht korrekte Effective-Earnings-Preview
|
||||
- [ ] `application_fee_amount` wird serverseitig aus Plan-Config berechnet (kein hardcoded `0` mehr), Cross-Check mit Stripe-Dashboard zeigt korrekte Verbuchung
|
||||
- [ ] Payouts-Dashboard zeigt kommende + historische Payouts, CSV-Export funktioniert
|
||||
- [ ] KYC-Status-Change-Notification erreicht Portal-Owner binnen 24h
|
||||
- [ ] Refund-Flow funktioniert, application_fee wird proportional erstattet
|
||||
- [ ] Dispute-Webhook erzeugt Notification, Evidence-Upload funktioniert
|
||||
- [ ] Tests grün
|
||||
- [ ] Docs angelegt
|
||||
- [ ] Progress-Log + PROGRESS.md aktualisiert
|
||||
|
||||
## Rollback Strategy
|
||||
|
||||
- Feature-Flag `commerce.connect_enabled` schaltet alle Connect-UIs ab; bestehende Connect-Accounts bleiben in Stripe gültig
|
||||
- Splits-Editor-Wert kann auf `0` zurückgesetzt werden — Plattform nimmt dann keine Fee, ohne dass Transactions brechen
|
||||
- Webhook-Handler für Refund/Dispute können einzeln deaktiviert werden, Stripe queued Webhooks für Retry
|
||||
- DB-Migration: `commerce_connect_account` + `commerce_payout` Tables; Drop-Reihenfolge in der Migration-Down dokumentiert
|
||||
|
||||
## Security Notes
|
||||
|
||||
- **destination-Validation ist sicherheitskritisch** — ohne Cross-Check könnte Tenant-A bei Checkout `destination` auf Connect-Account von Tenant-B setzen und dessen Earnings stehlen. Server-Validation Pflicht
|
||||
- `application_fee_amount` darf niemals vom Client beeinflusst sein
|
||||
- Webhook-Signatur-Verifikation (`stripe-signature`) muss bei jedem Webhook geprüft werden (heute teils schon der Fall, hier auf alle Connect-Webhooks ausweiten)
|
||||
- KYC-Daten sind sensitive: Portal-Owner-Tenant darf nur seine eigenen KYC-Status sehen, Plattform-Admin sieht alle (Rollen-Check)
|
||||
- Refund-Trigger ist privilegierte Action: Audit-Log mit Acting-User + Reason
|
||||
|
||||
## Subagent Recommendations
|
||||
|
||||
- **Planning:** `Plan`-Subagent mit Stripe-Connect-Docs als Input
|
||||
- **Research:** `Explore`-Subagent für Stripe-Connect-Embedded-Onboarding-Patterns (Best-Practices, bekannte Fallstricke bei destination-Validation)
|
||||
- **Implementation:** ein `general-purpose`-Subagent pro Step
|
||||
- **Tests:** separater `general-purpose`-Subagent für E2E (Stripe-Test-Mode benötigt sauberes Test-Account-Setup)
|
||||
- **Verification:** `gsd-verifier` für jede Phase (1/2/3) separat
|
||||
- **Code-Review:** `gsd-code-reviewer` nach Step 3 (Fee-Hardening) und nach Step 8 (final)
|
||||
|
||||
## Staging-Deployment-Steps
|
||||
|
||||
1. Branch `agent/11-backlog-stripe-marketplace-ui` pushen
|
||||
2. Stripe-Test-Mode-Account für Staging mit aktiviertem Connect provisionieren
|
||||
3. Test-Webhook-Endpoint registrieren (Stripe-CLI `stripe listen --forward-to ...`)
|
||||
4. Test-Portal-Owner-Tenant durch kompletten Onboarding-Flow schicken
|
||||
5. Test-Order mit Splits, Refund, Dispute durchspielen
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
_(Wird vom ausführenden Agent gefüllt.)_
|
||||
|
||||
## Progress Log
|
||||
|
||||
_(Wird vom ausführenden Agent gefüllt.)_
|
||||
@@ -0,0 +1,110 @@
|
||||
# Stryker Mutation-Testing
|
||||
|
||||
**Status:** `backlog: test-coverage.md (Phase 10) fertig + Bedarf nach höherer Test-Quality (z.B. nach unentdecktem Critical-Bug in Production der trotz hoher Coverage durchgekommen ist)`
|
||||
**Task-ID:** #77
|
||||
**Phase:** 11 (Backlog)
|
||||
**Estimated Effort:** ~1 Woche Setup + Tuning + Initial-Fix-Sprint wenn aktiviert
|
||||
**Owner:** unassigned
|
||||
|
||||
## Problem
|
||||
|
||||
Coverage-Zahlen aus Phase 10 (`test-coverage.md`) sagen nur, dass Code „ausgeführt" wurde, nicht dass das Verhalten „verifiziert" wurde. Tests, die zwar Coverage erzeugen aber keine echten Assertions machen (z.B. `expect(result).toBeDefined()` statt `expect(result).toEqual({...})`), bleiben unentdeckt. Sobald Coverage > ~80% etabliert ist und trotzdem Bugs in Production rutschen, lohnt sich Mutation-Testing als nächster Quality-Hebel.
|
||||
|
||||
Mutation-Testing ist sehr build-intensiv (Faktor 50-500x normale Test-Laufzeit, weil pro Mutation die volle Test-Suite gegen mutierten Code läuft). Vorab-Aktivierung ohne stabile Coverage-Baseline wäre verfrüht, weil zuerst Coverage hochgezogen werden muss, bevor Mutation-Score sinnvoll wird.
|
||||
|
||||
## Depends on
|
||||
|
||||
- `../10-compliance-polish/test-coverage.md` — Coverage muss erst belastbar sein, sonst ist Mutation-Score nicht aussagekräftig
|
||||
- bestehende Vitest-Setup im Codebase
|
||||
|
||||
## Blocks
|
||||
|
||||
- nichts (Backlog-Item, blockt keine aktive Roadmap)
|
||||
|
||||
## Approach
|
||||
|
||||
**Stryker (`@stryker-mutator/core` + `@stryker-mutator/vitest-runner`) als Nightly-Job, nicht als PR-Check.** Begründung:
|
||||
|
||||
- *Stryker als PR-Check*: würde PR-Builds um Faktor 50+ verlangsamen. Verworfen.
|
||||
- *Stryker als Nightly-Job (gewählt)*: läuft auf separatem CI-Runner über Nacht, Report wird morgens als GitHub-Action-Artifact + Slack/Email-Notification ausgeliefert. Slow-Feedback, aber für Mutation-Testing akzeptabel.
|
||||
- *Andere Mutation-Tools (Pitest für Java, mutmut für Python)*: nicht relevant — TS-Codebase, Stryker ist Standard.
|
||||
|
||||
**Was Stryker macht:** mutiert Code in kleinen Weisen — Operator-Swap (`+` → `-`, `===` → `!==`), Boolean-Flip (`true` → `false`), Return-Value-Replacement (`return x` → `return null`), Conditional-Boundary-Shifts (`<` → `<=`) — und prüft, ob die Test-Suite den mutierten Code „killt" (Test failt). Wenn ein Mutant „überlebt" (alle Tests bleiben grün trotz Mutation), ist das ein Hinweis auf schwache Tests.
|
||||
|
||||
**Score-Target:** Mutation-Score (`killed / total`) **>70% auf Critical-Paths** (Auth, Billing, Tenant-Isolation, Audit-Logging, AI-Cost-Tracking). Niedrigere Schwelle für Non-Critical-Paths (UI-Komponenten, Marketing-Pages) — dort ist Mutation-Testing weniger wertvoll und kostet zu viel CI-Zeit.
|
||||
|
||||
**Tuning:** anfänglich nur ausgewählte Pakete/Module mutieren, nicht den ganzen Monorepo (sonst läuft Nightly-Job über 24h). Inkrementell ausweiten wenn CI-Kapazität es zulässt.
|
||||
|
||||
**Initial-Fix-Sprint:** nach erstem Stryker-Run werden vermutlich viele „überlebende" Mutanten gefunden. Sprint priorisiert Critical-Path-Survivors, fügt fehlende Assertions hinzu, fixt schwache Tests. Pro Modul ein Commit.
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Stryker-Install + Minimal-Config** — `@stryker-mutator/core` + `@stryker-mutator/vitest-runner` als Dev-Deps, `stryker.config.mjs` mit Scope auf zunächst nur 1-2 Critical-Module (z.B. `app/utils/auth/` + `app/modules/billing/`). Commit: `11-backlog/stryker: install + minimal config for auth + billing`
|
||||
2. **Erster Lokal-Run + Baseline-Report** — `npx stryker run` lokal, Output sichten, Baseline-Mutation-Score dokumentieren in `docs/quality/mutation-testing.md`. Commit: `11-backlog/stryker: baseline report`
|
||||
3. **Nightly-CI-Workflow** — GitHub-Actions-Workflow `mutation-testing-nightly.yml`, läuft 03:00 UTC, läuft Stryker für definierten Scope, lädt HTML-Report als Artifact hoch, postet Score in Slack/Discord (oder Issue-Comment). Commit: `11-backlog/stryker: nightly ci workflow`
|
||||
4. **Initial-Fix-Sprint (Auth-Module)** — überlebende Mutanten im Auth-Modul analysieren, fehlende Assertions hinzufügen oder neue Test-Cases. Pro logischem Fix-Block ein Commit `11-backlog/stryker: kill <n> mutants in <module>`
|
||||
5. **Initial-Fix-Sprint (Billing-Module)** — gleiches für Billing
|
||||
6. **Scope-Erweiterung Critical-Path-Module** — Tenant-Isolation-Module, Audit-Logging-Module, AI-Cost-Tracking-Module hinzunehmen. Commit: `11-backlog/stryker: expand scope to tenant + audit + ai-cost`
|
||||
7. **Score-Gate für Critical-Paths** — Stryker-Config: `thresholds.high=80, thresholds.low=70, thresholds.break=70` für Critical-Path-Module, Nightly failt unter 70%. Commit: `11-backlog/stryker: enforce 70% threshold on critical paths`
|
||||
8. **Doku** — `docs/quality/mutation-testing.md`: was Mutation-Testing ist, wie man den Nightly-Report liest, wie man überlebende Mutanten fixt, welche Module im Scope sind. Commit: `11-backlog/stryker: documentation`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
- **Lokaler Stryker-Run** funktioniert auf einem Critical-Path-Modul ohne Crash
|
||||
- **Nightly-CI-Workflow** läuft erfolgreich durch (mind. 1x bestätigt auf Staging-Branch)
|
||||
- **HTML-Report** wird als Artifact gespeichert und ist downloadbar
|
||||
- **Score-Threshold** wird durchgesetzt: ein bewusst eingeführter „leerer Assertion"-Test in Critical-Path muss den Nightly failen lassen
|
||||
- **Coverage-Target:** Mutation-Score >70% auf jedem Critical-Path-Modul (Auth, Billing, Tenant, Audit, AI-Cost) nach Initial-Fix-Sprint
|
||||
- **Test-Files:** keine neuen Test-Files dediziert für Stryker; existing Tests werden verbessert
|
||||
|
||||
**NICHT als completed markieren bevor mind. 2 Critical-Path-Module die 70%-Schwelle erreichen.**
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Stryker installiert + konfiguriert mit Scope auf mind. 5 Critical-Path-Module
|
||||
- [ ] Lokaler Run funktioniert
|
||||
- [ ] Nightly-CI-Workflow läuft stabil, postet Report in Notification-Channel
|
||||
- [ ] HTML-Report als Artifact verfügbar
|
||||
- [ ] Initial-Fix-Sprint: alle Critical-Path-Module erreichen Mutation-Score ≥70%
|
||||
- [ ] Score-Threshold im CI durchgesetzt (Nightly failt bei Threshold-Bruch)
|
||||
- [ ] `docs/quality/mutation-testing.md` mit Erklärung + Report-Reading-Guide + Scope-Liste
|
||||
- [ ] Tests grün
|
||||
- [ ] Progress-Log + PROGRESS.md aktualisiert
|
||||
|
||||
## Rollback Strategy
|
||||
|
||||
- Stryker ist purely additive Quality-Tooling — Entfernen brichtnichts in der App-Funktionalität
|
||||
- Nightly-CI-Workflow kann via GitHub-Actions-UI deaktiviert werden, Default-Build-Pipeline läuft unverändert
|
||||
- Wenn Mutation-Score-Gate falsche Positives produziert: Scope verkleinern statt Tool entfernen
|
||||
- Stryker-Config in einer Datei (`stryker.config.mjs`) — einfacher Revert
|
||||
|
||||
## Security Notes
|
||||
|
||||
- Stryker mutiert Source-Code in temporären Ordnern — sicherstellen, dass `.gitignore` `.stryker-tmp/` enthält (gleich beim Setup)
|
||||
- Nightly-CI-Runner braucht read-only Code-Access, keine Secrets — Stryker macht keine Network-Calls
|
||||
- HTML-Report enthält Source-Code-Snippets — als private GitHub-Action-Artifact halten, nicht öffentlich
|
||||
|
||||
## Subagent Recommendations
|
||||
|
||||
- **Planning:** `Plan`-Subagent mit Critical-Path-Modul-Liste als Input
|
||||
- **Research:** `Explore`-Subagent für Stryker-Best-Practices in Monorepos (insb. wie man Scope sinnvoll begrenzt)
|
||||
- **Implementation:** ein `general-purpose`-Subagent pro Step
|
||||
- **Tests (Fix-Sprint):** ein `general-purpose`-Subagent pro Critical-Path-Modul für das Kill-Mutants-Refactoring
|
||||
- **Verification:** `gsd-verifier` für Threshold-Enforcement-Test (bewusst leerer Test → Nightly muss fail)
|
||||
- **Code-Review:** `gsd-code-reviewer` nach jedem Fix-Sprint-Modul
|
||||
|
||||
## Staging-Deployment-Steps
|
||||
|
||||
1. Branch `agent/11-backlog-stryker` pushen
|
||||
2. Lokaler Stryker-Run auf Auth-Modul, Report sichten
|
||||
3. Nightly-Workflow auf Branch testen (manueller Trigger via `workflow_dispatch`)
|
||||
4. HTML-Report-Artifact downloaden, manuell inspizieren
|
||||
5. Bewusst leeren Test einbauen, Nightly muss failen — danach revertieren
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
_(Wird vom ausführenden Agent gefüllt.)_
|
||||
|
||||
## Progress Log
|
||||
|
||||
_(Wird vom ausführenden Agent gefüllt.)_
|
||||
@@ -0,0 +1,124 @@
|
||||
# WCAG-2.2-AA Externe Zertifizierung
|
||||
|
||||
**Status:** `backlog: Enterprise-Sales-Pipeline besteht auf zertifizierter Accessibility-Compliance (z.B. öffentlicher Sektor, EU-Public-Body-Tender, Konzern-Procurement mit BITV-Pflicht)`
|
||||
**Task-ID:** #74
|
||||
**Phase:** 11 (Backlog)
|
||||
**Estimated Effort:** 3-4 Wochen Fix-Sprint + €5-15k externe Audit-Kosten wenn aktiviert
|
||||
**Owner:** unassigned
|
||||
|
||||
## Problem
|
||||
|
||||
`wcag-internal.md` aus Phase 10 stellt sicher, dass die Boilerplate technisch WCAG-2.2-AA-konform ist (axe-CI, Storybook-A11y-Addon, eigene Audits). Das reicht für die meisten Sales-Situationen. Sobald ein Kunde aber eine **formale WCAG-Konformitätserklärung** oder einen **VPAT-Report** (Voluntary Product Accessibility Template) verlangt — typisch bei Behörden, EU-Public-Body-Tendern oder Konzern-Procurement — braucht es einen externen, zertifizierten Audit.
|
||||
|
||||
Vorab-Aktivierung lohnt nicht, weil:
|
||||
|
||||
- Externe Audits sind teuer (€5-15k)
|
||||
- Sie müssen jährlich reauditiert werden (laufende Kosten)
|
||||
- Ohne konkreten Kunden-Anker ist der ROI negativ
|
||||
|
||||
## Depends on
|
||||
|
||||
- `../10-compliance-polish/wcag-internal.md` — **harte Pre-Work-Voraussetzung**: interner Audit muss durch sein, sonst werden ~€10k externe Audit-Kosten für Findings verbrannt, die wir vorher selber hätten fixen können
|
||||
- `../10-compliance-polish/i18n-foundation.md` — Sprach-Attribute (`lang="..."`) müssen korrekt gesetzt sein (WCAG-Erfolgskriterium 3.1.1/3.1.2)
|
||||
- `../10-compliance-polish/lighthouse.md` — A11y-Score 100 als CI-Gate ist schon erzwungen
|
||||
|
||||
## Blocks
|
||||
|
||||
- nichts (Backlog-Item, blockt keine aktive Roadmap)
|
||||
|
||||
## Approach
|
||||
|
||||
**Externer Audit-Provider + Fix-Sprint + Re-Test + Certificate.** Begründung gegen Alternativen:
|
||||
|
||||
- *Selbstdeklarierte WCAG-Konformitätserklärung*: für viele Behörden + Konzern-Procurement nicht ausreichend, sie verlangen externe Bestätigung. Verworfen für diesen Use-Case.
|
||||
- *Nur Lighthouse-Score reportieren*: deckt nur ein Subset von WCAG ab (~30%), nicht ausreichend als „WCAG-AA-zertifiziert". Verworfen.
|
||||
|
||||
**Provider-Optionen (Auswahl beim Aktivieren):**
|
||||
|
||||
- **BFW Würzburg** (DE, BITV-Erfahrung, Deutsch + Englisch)
|
||||
- **Inclusive Strategies** (UK/EU, gute Brand)
|
||||
- **Deque Systems** (US/global, axe-Maintainer, höchste Preise aber höchste Brand-Anerkennung)
|
||||
|
||||
**Deliverables eines Audits:**
|
||||
|
||||
- VPAT 2.4 Report (für US-Customer-Relevanz, „Section 508-konform"-Sprache)
|
||||
- WCAG-2.2-AA-Conformance-Report
|
||||
- Liste aller Issues mit Severity + Remediation-Empfehlung
|
||||
- nach Fix-Sprint: Re-Test mit aktualisiertem Report
|
||||
- Certificate (Audit-Provider-spezifisches Dokument, kein offizielles Siegel — WCAG hat keine staatlich anerkannte Zertifizierung, nur Audit-Berichte)
|
||||
|
||||
**Re-Audit-Zyklus:** jährlich, weil größere App-Änderungen die Konformität brechen können. Pflicht zur Aufnahme in jährliche Compliance-Roadmap.
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Pre-Work-Verify** — sicherstellen dass `wcag-internal.md` `completed`, axe-CI 0 Errors für 30 Tage stabil, Lighthouse-A11y-Score 100 in PROD. Commit: `11-backlog/wcag-external-cert: pre-audit baseline verification`
|
||||
2. **Provider-Auswahl + Beauftragung** — Angebote einholen, Scope definieren (welche Seiten/Flows werden auditiert: Marketing-Site + Auth-Flow + App-Hauptpfade + Admin-Panel?), Vertrag. Commit: `11-backlog/wcag-external-cert: audit scope definition`
|
||||
3. **Audit-Durchlauf vorbereiten** — Test-Tenant + Test-Accounts für Auditoren bereitstellen, Demo-Daten seeden, Audit-Account-Credentials sicher übergeben. Commit: `11-backlog/wcag-external-cert: audit test environment`
|
||||
4. **Externe Audit-Phase abwarten** (1-2 Wochen) — keine App-Änderungen am audited Scope, Auditoren stellen Rückfragen
|
||||
5. **Findings-Triage** — Initial-Audit-Report bekommen, Findings nach Severity klassifizieren (Critical/Major/Minor), Fix-Plan aufstellen. Commit: `11-backlog/wcag-external-cert: findings triage`
|
||||
6. **Fix-Sprint** — Critical + Major in 2-3 Wochen fixen, Minor priorisieren. Pro Fix: dedizierter Commit `11-backlog/wcag-external-cert: fix <issue-id> <kurzbeschreibung>`
|
||||
7. **Re-Test-Audit** — Auditor verifiziert Fixes, finaler Report. Commit: `11-backlog/wcag-external-cert: incorporate re-audit findings`
|
||||
8. **Doku + Veröffentlichung** — `docs/compliance/accessibility-statement.md` (öffentliche Erklärung mit Audit-Datum, Provider, Scope, Ausnahmen), VPAT-Report als PDF im Repo + auf Website downloadbar. Commit: `11-backlog/wcag-external-cert: accessibility statement + vpat publication`
|
||||
9. **Jahres-Re-Audit-Reminder** — Calendar-Reminder + Issue-Template für `re-audit-YYYY` in 11 Monaten. Commit: `11-backlog/wcag-external-cert: re-audit reminder`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
- **Pre-Audit-Tests:** axe-CI 0 Errors, Lighthouse-A11y 100, Storybook-A11y-Addon 0 Errors auf allen Komponenten — alles aus `wcag-internal.md` schon erzwungen
|
||||
- **Fix-Sprint-Tests:** pro Fix entsprechender Regression-Test (oft RTL/Playwright mit `@axe-core/playwright` assertion auf der betroffenen Seite)
|
||||
- **Re-Audit-Verifikation:** alle Major+Critical-Issues vom Audit-Report müssen mit verlinktem Fix-Commit + Test geschlossen sein
|
||||
- **Coverage-Target:** keine % — qualitativ: jedes Audit-Finding hat einen verlinkten Fix + Regression-Test
|
||||
- **Test-Files:** neben Source, plus `apps/web/playwright/accessibility/` für audit-driven E2E-Tests
|
||||
|
||||
**NICHT als completed markieren bevor Re-Audit-Report sauber ist.**
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Pre-Work-Voraussetzungen verifiziert: `wcag-internal.md` `completed`, axe-CI clean
|
||||
- [ ] Externer Audit von zertifiziertem Provider durchgeführt, Initial-Report vorhanden
|
||||
- [ ] Alle Critical + Major Findings im Fix-Sprint behoben, mit verlinkten Commits + Regression-Tests
|
||||
- [ ] Re-Audit-Report bestätigt WCAG-2.2-AA-Konformität für definierten Scope
|
||||
- [ ] VPAT-2.4-Report als PDF im Repo (`docs/compliance/vpat-YYYY.pdf`) + auf Website downloadbar
|
||||
- [ ] `docs/compliance/accessibility-statement.md` mit Audit-Datum, Provider, Scope, dokumentierten Ausnahmen
|
||||
- [ ] Jahres-Re-Audit als Reminder-Issue im Backlog
|
||||
- [ ] Tests grün (alle Audit-driven Regression-Tests dauerhaft im CI)
|
||||
- [ ] Progress-Log + PROGRESS.md aktualisiert
|
||||
|
||||
## Rollback Strategy
|
||||
|
||||
- Externer Audit ist nicht rollbackbar (Report existiert), aber:
|
||||
- Wenn nach Audit größere App-Änderungen die Konformität brechen, muss `accessibility-statement.md` ehrlich aktualisiert werden („Konformität gilt für Stand DD.MM.YYYY, neue Features X/Y werden im nächsten Re-Audit YYYY+1 erfasst")
|
||||
- VPAT-Report bleibt mit Datum versehen — keine nachträgliche Manipulation
|
||||
- Im Notfall (entdeckter kritischer A11y-Regress nach Veröffentlichung): VPAT-Report mit „Bekannte Issues"-Anhang ergänzen, Fix-Sprint starten, kein Re-Audit nötig wenn Provider zustimmt
|
||||
|
||||
## Security Notes
|
||||
|
||||
- Audit-Account-Credentials sicher übergeben (Bitwarden-Share, kein Email)
|
||||
- Audit-Test-Tenant nach Audit löschen (kann Demo-Daten enthalten, die mit echten Customer-Daten verwechselbar sind)
|
||||
- VPAT-Report öffentlich publishen ist OK — enthält keine sicherheitsrelevanten Details
|
||||
- Audit-Provider-Vertrag sollte NDA-Klauseln enthalten (Audit-Findings sind temporäre Schwächen — public Disclosure vor Fix wäre suboptimal)
|
||||
|
||||
## Subagent Recommendations
|
||||
|
||||
- **Planning:** `Plan`-Subagent mit Wahl des Audit-Providers (Vergleich Preise/Reputation/Region)
|
||||
- **Research:** `Explore`-Subagent für VPAT-2.4-Template-Best-Practices und Beispiel-Accessibility-Statements anderer SaaS
|
||||
- **Implementation (Fix-Sprint):** ein `general-purpose`-Subagent pro Finding-Severity-Block
|
||||
- **Tests:** separater `general-purpose`-Subagent für `@axe-core/playwright`-Regression-Tests
|
||||
- **Verification:** Re-Audit ist die externe Verifikation — kein interner Verifier-Subagent nötig
|
||||
- **Code-Review:** `gsd-code-reviewer` nach jedem Fix-Sprint-Block
|
||||
|
||||
## Staging-Deployment-Steps
|
||||
|
||||
1. Branch `agent/11-backlog-wcag-external-cert` pushen
|
||||
2. Audit-Test-Tenant auf Staging anlegen mit repräsentativen Demo-Daten
|
||||
3. Audit-Account-Credentials an Provider übergeben
|
||||
4. Während Audit: Staging-Branch eingefroren, keine Deploys außer kritische Security-Fixes
|
||||
5. Nach Fix-Sprint: Re-Audit-Run auf gleichem Staging-Branch
|
||||
6. Nach Re-Audit-Confirm: Merge auf main, Production-Deploy, VPAT auf Website veröffentlichen
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
_(Wird vom ausführenden Agent gefüllt.)_
|
||||
|
||||
## Progress Log
|
||||
|
||||
_(Wird vom ausführenden Agent gefüllt.)_
|
||||
Reference in new issue
Block a user