472 lines
29 KiB
Markdown
472 lines
29 KiB
Markdown
# Phase 05 — Verification Report
|
|
|
|
> **Historical report:** This file verified the Phase-05 plan quality on
|
|
> 2026-05-16. It is not the production-readiness source of truth. Later
|
|
> closeout docs, feature docs, runbooks, and `docs/ops/asset-cdn.md` supersede
|
|
> claims that read like live status, especially CDN/SRI and email-sequence
|
|
> delivery.
|
|
|
|
**Verifier:** Phase-05-Verifier (Read-Only)
|
|
**Datum:** 2026-05-16
|
|
**Scope:** README.md + 9 Task-Detail-MDs (10 Files total)
|
|
**Result:** PASS mit Minor-Findings — keine Blocker; einige inhaltliche Lücken adressierbar während Execution.
|
|
|
|
---
|
|
|
|
## 1. Template-Konformität
|
|
|
|
### Section-Reihenfolge (laut `DETAIL-MD-TEMPLATE.md`)
|
|
|
|
| File | Frontmatter | Problem | Depends on | Blocks | Approach | Impl Steps | Tests | Acceptance | Rollback | Security | Subagents | Staging | Deviations | Progress Log | Lessons Learned |
|
|
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
| feature-flags.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | — (optional, fehlt) |
|
|
| ai-cost-phase-1.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | — |
|
|
| ai-cost-phase-2.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | — |
|
|
| ai-cost-phase-3.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | — |
|
|
| form-widget.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | — |
|
|
| realtime-collab.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | — |
|
|
| marketing-funnel-phase-1.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | — |
|
|
| marketing-funnel-phase-2.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | — |
|
|
| marketing-funnel-phase-3.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | — |
|
|
|
|
**Lessons Learned** ist laut Template optional (Z. 128: "Lessons Learned (optional)"). Konsistent über alle 9 Files weggelassen → akzeptabel.
|
|
|
|
**Finding T1 (Info):** Alle 9 Detail-MDs erfüllen die 14 Pflicht-Sections in korrekter Reihenfolge. README.md folgt eigenem Phase-Schema (kein Detail-MD-Template) — wie geplant.
|
|
|
|
---
|
|
|
|
## 2. Dependencies-Konsistenz
|
|
|
|
### feature-flags.md zuerst → blocked-by-Liste
|
|
|
|
`feature-flags.md` ist als Foundation deklariert. Tatsächliche Konsumenten:
|
|
- `ai-cost-phase-1.md` Depends: `feature-flags.md` (für `ai-usage-dashboard` Flag) ✓
|
|
- `ai-cost-phase-2.md` Depends: `feature-flags.md` (für `ai-quota-soft-degradation`) ✓
|
|
- `ai-cost-phase-3.md` Depends: `feature-flags.md` (für Per-Tenant-Overage-Enablement) ✓
|
|
- `form-widget.md` Depends: `feature-flags.md` (für Turnstile-Gradual-Rollout) ✓
|
|
- `realtime-collab.md` Depends: `feature-flags.md` (für Plan-Tier-Gating) ✓
|
|
- `marketing-funnel-phase-1.md` Depends: `feature-flags.md` (Turnstile Gradual-Rollout) ✓
|
|
- `marketing-funnel-phase-2.md` Depends: `feature-flags.md` (Outbound-Integration opt-in) ✓
|
|
- `marketing-funnel-phase-3.md` Depends: `feature-flags.md` (Sequence-Aktivierung) ✓
|
|
|
|
→ konsistent.
|
|
|
|
### AI-Cost-Phasen sequenziell (1 → 2 → 3)
|
|
|
|
- Phase 2 Depends on Phase 1 ✓ (Z. 24: "AICostEvent-Pipeline + TenantAICostSummary als Datengrundlage")
|
|
- Phase 3 Depends on Phase 2 + Phase 1 ✓ (Z. 24-25)
|
|
- Phase 1 Blocks Phase 2 + Phase 3 ✓
|
|
- Phase 2 Blocks Phase 3 ✓
|
|
|
|
### Marketing-Funnel-Phasen sequenziell (1 → 2 → 3)
|
|
|
|
- Phase 2 Depends on Phase 1 (Z. 23) ✓
|
|
- Phase 3 Depends on Phase 2 (Z. 23) + Phase 1 ✓
|
|
- Phase 1 Blocks Phase 2 + Phase 3 ✓
|
|
- Phase 2 Blocks Phase 3 ✓
|
|
|
|
### React-Email aus Phase 10 für `marketing-funnel-phase-3.md`
|
|
|
|
- Z. 28: "MUSS aus Phase 10 vorgezogen werden ... Alternative: minimaler HTML-Fallback bis React-Email regulär kommt, dann Migration." ✓
|
|
- Implementation-Step 1 (Z. 56-59): explicit "React-Email-Vorziehung (aus Phase 10)" als optionaler Stub ✓
|
|
- README.md verweist auf `../10-compliance-polish/react-email.md` (Z. 109) ✓
|
|
- Konsistent mit `00-execution-order.md` Z. 106: "react-email.md kann früher gezogen werden falls Phase 05 Marketing-Funnel-Phase-3 sie braucht" ✓
|
|
|
|
### AI-Cost-Phase-1 braucht Outbox aus Phase 03
|
|
|
|
- Phase 1 Depends: `03-scaling-infrastructure/outbox-pattern.md` (#42) ✓ (Z. 29)
|
|
- Phase 1 Depends: `worker-queues.md` (#43) ✓
|
|
- Phase 1 Depends: `read-write-split.md` (#41) ✓
|
|
- Phase 1 Depends: `metrics-grafana.md` (#14) ✓
|
|
|
|
### feature-flags.md braucht SharedStore aus Phase 03
|
|
|
|
- Depends: `03-scaling-infrastructure/shared-store-package.md` (#37) ✓ (Z. 29)
|
|
- Depends: `03-scaling-infrastructure/pubsub-cache-invalidation.md` (#39) ✓
|
|
- Depends: `02-observability/sentry-wiring-api-worker.md` (#11) ✓
|
|
|
|
**Finding D1 (Info):** Alle Dependencies konsistent zwischen README.md, 00-execution-order.md und den einzelnen Detail-MDs. Keine zirkulären Verweise.
|
|
|
|
**Finding D2 (Minor):** `realtime-collab.md` referenziert `02-observability/opentelemetry.md` (#13) — korrekt, aber die `Blocks`-Sektion ist sehr dünn ("Spätere Erweiterung auf andere Editoren ... sind out-of-scope"). Kein echter Folge-Task wird hard-blockiert; akzeptabel, weil README Track-B als "Standalone" markiert.
|
|
|
|
---
|
|
|
|
## 3. Implementation-Steps-Qualität
|
|
|
|
### Feature-Flags-Targeting-Engine
|
|
|
|
**Erwartet:** Composite-Rules (AND/OR-tree), Percentage-Sticky via SHA1-Hash, JSON-Variants.
|
|
|
|
- Step 2 (Z. 64): "Targeting-Engine ... evaluateRule(rule, ctx) mit Support für: boolean, allowlist, percentage (sticky-hash), plan-tier, role-based, time-based, composite (AND/OR/NOT mit Child-Rules). Pure Function, vollständig unit-testbar ohne DB." ✓
|
|
- Step 3 (Z. 67): "evaluateFlag + getFeatureFlagVariant Public-API ... orchestriert Storage-Load, Dependency-Resolution (Parent-Flag-Check), Targeting-Eval, Variant-Auswahl. Strikt typisierte Return-Werte." ✓
|
|
- Approach Z. 56: "Percentage-Rollout via SHA1(`userId+flagName`) % 100: sticky pro User-Flag-Kombi" ✓
|
|
- Step 5 (Z. 73): Visueller Rule-Builder, Percentage-Slider, Allowlist-Search, Variant-JSON-Editor mit Monaco + Schema-Validation ✓
|
|
- Test Z. 90: "percentage-hash.test.ts — sticky-Test: gleicher (userId, flagName) liefert immer gleichen Bucket; Distribution-Test über 10k Sample-IDs liegt bei N% innerhalb ±2%" ✓
|
|
|
|
**Finding I1 (Minor):** Hash-Algo wird in Approach als "SHA1" benannt, in Tests aber nicht explizit als SHA1 vs SHA256 fixiert. Empfehlung: in Step 2 explizit fixieren (SHA-256 wäre moderner — SHA1 ist aber für Bucket-Hashing vollkommen ausreichend; egal welche Wahl, sollte konsistent dokumentiert sein).
|
|
|
|
### AI-Cost-Wrapper um LLM-Calls
|
|
|
|
**Erwartet:** Wrapper in allen Pfaden — chatbot-stream, generate-action, PromptBuilderService, RAG-Embedding.
|
|
|
|
- ai-cost-phase-1.md Problem-Section Z. 20-23 listet alle 4 Stellen mit Datei + Line ✓
|
|
- Implementation Step 4 (Z. 67-73) instrumentiert alle 4 atomisch (eigener Commit pro Call-Site) ✓
|
|
- Wrapper-Signatur explizit (Z. 64): `executeLLMCall({ provider, model, capability, ctx, run })` mit Idempotency-Key ✓
|
|
- Provider-Wrapper liefert sinnvolle Inheritance: Provider-Usage-Numbers nutzen wenn vorhanden, sonst countTokens ✓
|
|
|
|
**Finding I2 (Info):** Vollständige Coverage der vier bekannten LLM-Pfade. Subagent-Recommendation (Z. 146-148) erinnert explizit, weitere Stellen mit `Explore`-Subagent zu suchen — guter Defensive-Step.
|
|
|
|
### Stripe-Meter-Events mit Reconciliation-Cron
|
|
|
|
- Implementation Step 4 (Z. 61-63): Nightly Cron, Idempotency-Identifier (UUID), `submittedToStripe=true`-Flag, `stripeMeterEventId` gespeichert ✓
|
|
- Implementation Step 7 (Z. 70-72): AIOverageSubmission-Audit-Trail-Model ✓
|
|
- Implementation Step 8 (Z. 73-75): Monatlicher Reconciliation-Cron, >1% Mismatch → Alert + Sentry-Capture, Runbook in Doku ✓
|
|
- Approach Z. 47-48: Begründung Nightly statt Realtime (Stripe-Quotas) + Block-Cents-Aggregation (Mikro-Charges vermeiden) ✓
|
|
- Security Note Z. 131: "Idempotency-Identifier (UUID pro Submission) ist Pflicht — Stripe deduped auf Identifier. Tests müssen explizit Retry-Pfad verifizieren." ✓
|
|
- Rollback-Strategy Z. 124-127 inkl. `AI_OVERAGE_SUBMISSION_ENABLED=false` Killswitch + Backfill-Run ✓
|
|
|
|
→ Robust dokumentiert.
|
|
|
|
### Form-Widget mit CSP-safe iframe + SRI
|
|
|
|
- Approach Z. 45-47: "CDN-served loader-Script <3KB ... sandboxed iframe ... CSP-safe ... SRI für Tamper-Detection" ✓
|
|
- Implementation Step 3 (Z. 66-68): Bootstrap-Loader mit SRI-Hash-Output für Embed-Code-Generator ✓
|
|
- Implementation Step 4 (Z. 69-71): Embedded-Form-App im iframe (separater Bundle <80KB gzipped) ✓
|
|
- Implementation Step 8 (Z. 81-83): Embed-Code-Generator mit `integrity="sha384-..."` Attribute ✓
|
|
- Security Note Z. 151: CSP-Header für Embed-iframe definiert ("default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'") ✓
|
|
- Security Note Z. 145: XSS-Mitigation (React default + Zod-Validation, kein freier HTML in Labels) ✓
|
|
- Acceptance-Criterion Z. 122: PostMessage-Events `toolctrl:form:submitted/error/resize` ✓
|
|
|
|
**Finding I3 (Minor — siehe Lücken-Section 8):** Step 3 erwähnt `toolctrl:form:resize` für dynamic-height aber kein detailliertes Protokoll. Empfehlung siehe Lücken-Section.
|
|
|
|
### Hocuspocus mit Graceful-Degradation
|
|
|
|
- Approach Z. 40-41: "Graceful-Degradation — wenn HOCUSPOCUS_URL nicht gesetzt oder Service unreachable, Editor läuft als Single-User mit existing REST-Save" ✓
|
|
- Implementation Step 8 (Z. 73-75): "Editor-Wrapper prüft Connection-State: bei disconnected > 10s zeige subtilen Status ... fallback auf REST-Save ... Wenn HOCUSPOCUS_URL env nicht gesetzt: Editor läuft komplett Single-User wie vorher (kein Provider initialisiert)" ✓
|
|
- Acceptance-Criterion Z. 113: "Graceful-Degradation: ohne HOCUSPOCUS_URL läuft Editor Single-User, mit Service-Down zeigt Offline-Indikator" ✓
|
|
- Rollback Z. 125-128: drei Disable-Optionen (Flag, Env, Container-Removal) ✓
|
|
- E2E-Test Z. 97: "Offline-Test: Hocuspocus-Container stoppen → User sieht Offline-Indikator → Tippt weiter → Container zurück → Re-Sync ohne Datenverlust" ✓
|
|
|
|
→ Vollständig adressiert.
|
|
|
|
### Marketing-Funnel Lead-Capture (CORS + Anti-Spam)
|
|
|
|
- Implementation Step 2 (marketing-funnel-phase-1.md Z. 56): CORS-Whitelist gegen `MARKETING_DOMAINS` env, Honeypot, Turnstile, Rate-Limit (5/min/IP + 3/min/Email), Duplicate-Dedup-Logic ✓
|
|
- Approach Z. 45-48: explicit Defense-in-Depth-Begründung ✓
|
|
- Security Notes Z. 130-135: PII-Handling, Honeypot-Field-Naming aus Env, CORS als nur-Browser-Defense (Server-Bots umgehen → Rate-Limit zwingend), Email-Enumeration-Schutz, GDPR-Consent-Mechanismus, IP-Logging-Doku ✓
|
|
|
|
→ Robust.
|
|
|
|
### Self-Service-Conversion-Flow (Lead → Tenant via signed-Token)
|
|
|
|
- marketing-funnel-phase-2.md Implementation Step 1 (Z. 53-55): Signed-Lead-Token mit HMAC-SHA256, 7d-TTL ✓
|
|
- Step 3 (Z. 59-61): Atomic Conversion-Service in Postgres-Transaction mit (a) Tenant-Create (b) Lead-Update (c) TenantAcquisition (d) Outbox-Event (e) Audit ✓
|
|
- Step 5 (Z. 65-67): Signup-Action-Integration ruft Conversion-Service ✓
|
|
- Security Notes Z. 141-147 adressieren: Token-Replay (Idempotency via `convertedToTenantId`-Check), Email-Read-Only-bei-Pre-Fill (Lead-Hijacking-Schutz), Race-Condition (Unique-Index auf `Lead.convertedToTenantId`) ✓
|
|
|
|
→ Sicher.
|
|
|
|
---
|
|
|
|
## 4. Test-Requirements-Qualität
|
|
|
|
### Per-Feature Konkretheit
|
|
|
|
Alle 9 Files haben strukturierte Test-Sections: Unit / Integration / E2E mit konkreten Cases. Coverage-Targets numerisch (z.B. 90% für `packages/ai/src/cost/`, 80% für Worker-Handlers).
|
|
|
|
### E2E-Tests für Lead-Conversion-Flow
|
|
|
|
- marketing-funnel-phase-2.md Z. 101-105 spezifiziert:
|
|
- SDK + Form-Submit → Lead → Admin "Convert to Tenant" → Tenant erscheint
|
|
- Self-Service-Flow: Capture → signed-Token-Link → pre-filled Signup → completed → Tenant + Welcome-Email
|
|
- Integration-UI: Slack-Webhook → Test-Send-Button → Mock-Slack empfängt
|
|
- Funnel-Report: Test-Daten mit definierter Source/Campaign → Reports zeigen korrekte Conversion-Rates ✓
|
|
|
|
### Multi-User-Tests für Realtime-Collab
|
|
|
|
- realtime-collab.md Z. 91-93 (Integration) + Z. 95-98 (E2E):
|
|
- Two-Browser-Tab-Test: User A tippt → User B sieht innerhalb 1s; Cursor sichtbar
|
|
- Awareness mit zwei User-States
|
|
- Offline/Re-Sync-Test
|
|
- Permission-Refusal-Test ✓
|
|
- Staging-Test Z. 174: "Last-Test: 10 simultane Connections auf gleichem Doc — Sync-Latenz <300ms p95" ✓
|
|
|
|
**Finding T2 (Info):** Test-Sections sind konsistent qualitativ hochwertig. Coverage-Gates klar pro Modul-Scope.
|
|
|
|
---
|
|
|
|
## 5. Staging-Deployment-Steps
|
|
|
|
### Hocuspocus-Container
|
|
|
|
- realtime-collab.md Z. 155-168: docker-compose-Snippet mit Image, Env, Ports, depends_on, Traefik-Label für `wss://collab.staging.toolctrl.de` ✓
|
|
- TLS-Termination + Subdomain-Routing dokumentiert ✓
|
|
- Last-Test-Anweisung 10 concurrent connections ✓
|
|
|
|
### Form-Widget CDN-Upload
|
|
|
|
- form-widget.md Z. 169: "Asset-CDN (aus Phase 03 #46) muss bereit sein; Loader-Build-Output dorthin deployed (CI-Step)" ✓
|
|
- form-widget.md Implementation Step 3 (Z. 66-68): Build via esbuild/vite, SRI-Hash-Output ✓
|
|
- Bundle-Size-Verify: `widget.js` < 3KB gzipped via curl-Check ✓
|
|
- Cross-Browser-Smoke ✓
|
|
|
|
### Marketing-SDK-CDN
|
|
|
|
- marketing-funnel-phase-1.md Z. 152: "Asset-CDN für marketing.js deployed (CI-Step)" ✓
|
|
- Implementation Step 4 (Z. 62-64): CI-Step erweitert mit versioniertem Pfad (`marketing.v1.js`) + Latest-Symlink + SRI-Hash ✓
|
|
- Bundle-Size-Verify <5KB gzipped via curl ✓
|
|
|
|
**Finding S1 (Info):** Alle drei Externe-Asset-Deployments haben klare Staging-Steps. CI-Workflow-Files (`.github/workflows/deploy.yml`) als Touchpoint dokumentiert.
|
|
|
|
---
|
|
|
|
## 6. Konsistenz mit User-Wünschen
|
|
|
|
### "Vollausbau Feature-Flags" — 9 Aspekte
|
|
|
|
Original-Wunsch laut Phase-Scope: Gradual-Rollouts, Plan-Tier-Gating, A/B-Tests (Multi-Variant), Killswitches mit Time-Boxing, Dependency-Hierarchien.
|
|
|
|
Spec liefert 7 Targeting-Rule-Types (Z. 64) + 5 Killer-Patterns (Z. 82):
|
|
1. boolean ✓
|
|
2. allowlist (tenantIds/userIds/emails) ✓
|
|
3. percentage (sticky-hash) ✓ → Gradual-Rollouts
|
|
4. plan-tier ✓ → Plan-Tier-Gating
|
|
5. role-based ✓
|
|
6. time-based (enabledFrom/until) ✓ → Killswitches mit Time-Boxing
|
|
7. composite (AND/OR/NOT mit Child-Rules) ✓
|
|
- Variants ✓ → A/B-Tests
|
|
- parentFlagId / Dependency-Resolution ✓ → Dependency-Hierarchien
|
|
- Audit-Trail ✓
|
|
|
|
→ **Alle 9 Aspekte abgedeckt** (7 Rule-Types + Variants + Dependencies + Audit als Bonus).
|
|
|
|
### "AI-Cost alle 3 Phasen"
|
|
|
|
- Phase 1 (Sichtbarkeit): 10 Implementation-Steps, Token-Counter + Wrapper + Outbox + Worker + Aggregator + 2 Dashboards + Metrics + Doku ✓
|
|
- Phase 2 (Schutz): 10 Implementation-Steps, Estimate + Assert + 402-Handling + Cron-Alerts + On-Demand-Trigger + Tenant-UI + Admin-Override + Doku ✓
|
|
- Phase 3 (Monetarisierung): 10 Implementation-Steps, Markup + Overage-Mark + Nightly-Cron-Submit + Stripe-Docs + Period-UI + Audit + Reconcile + Tenant-Override + Doku ✓
|
|
|
|
Alle drei Phasen detailliert (15k+ Zeichen pro Datei), sequenziell mit klaren Übergaben.
|
|
|
|
### "A für Marketing-Funnel + Email-Sequences + Self-Service-Conversion"
|
|
|
|
- marketing-phase-1: Lead-Capture-API + Marketing-SDK + Admin-Inbox ✓
|
|
- marketing-phase-2: Self-Service-Conversion + Attribution + Outbound-Webhooks ✓
|
|
- marketing-phase-3: Email-Sequence-Engine + 4 Pre-Built Sequences + Statistics ✓
|
|
|
|
Alle drei User-Wünsche jeweils in eigener Phase abgedeckt.
|
|
|
|
### "Form-Widget für Lead-Capture im CRM" — korrekt routed?
|
|
|
|
- form-widget.md Implementation Step 6 (Z. 75-77): Worker-Handler routet je nach `targetType`:
|
|
- `form-submission` → Generic-Row
|
|
- `crm-contact` → upsert via existing CRM-Service mit Field-Mapping
|
|
- `entity-row` → insert Row in Target-Entity ✓
|
|
- Form-Builder-UI hat Field-Mapping-Builder bei `crm-contact`/`entity-row` (Z. 78) ✓
|
|
- README.md Z. 39 listet form-widget als Block für marketing-funnel-phase-1: "Form-Widget liefert Patterns für Cross-Origin + Anti-Spam, die wiederverwendet werden" ✓
|
|
|
|
→ Routed.
|
|
|
|
### "Hocuspocus Self-Hosted mit Graceful-Degradation"
|
|
|
|
→ Bereits in Section 3 ausführlich verifiziert. Architektur-Wahl, Container-Setup, Env-Disable, Container-Removal alle dokumentiert.
|
|
|
|
---
|
|
|
|
## 7. Security-Notes-Coverage
|
|
|
|
### Self-loop MCP von Chatbot-V1/V2 → Capability-System
|
|
|
|
Nicht explizit in Phase-05-Files adressiert — gehört in Phase 07. Phase 05 liefert nur die Feature-Flag-Engine, die als "Capability-Gating" verwendet werden kann.
|
|
|
|
**Finding SEC1 (Info):** Self-loop-MCP-Schutz ist Phase-07-Konzern (`chatbot-v1.md`/`chatbot-v2.md`). Phase 05 erwähnt korrekterweise in `feature-flags.md` Blocks-Section: "06-plugin-system/hooks-lifecycle.md (#61) — Plugin-Capability-Gating" — Feature-Flag-Engine ist die Foundation. Kein explizites Self-loop-Issue zu adressieren in Phase 05.
|
|
|
|
### Lead-Capture-Anti-Spam — Honeypot + Turnstile + Rate-Limit
|
|
|
|
marketing-funnel-phase-1.md Z. 130-135 + 56:
|
|
- Honeypot ✓
|
|
- Turnstile (opt-in via Flag) ✓
|
|
- Rate-Limit (5/min/IP + 3/min/Email) ✓
|
|
- IP-Logging dokumentiert + DSGVO-Doku-Update verwiesen ✓
|
|
- Honeypot-Field-Name aus Env (HONEYPOT_FIELD_NAME) randomized — sehr nice ✓
|
|
|
|
→ Ausreichend.
|
|
|
|
### Form-Submissions-CORS — strict whitelist
|
|
|
|
form-widget.md Z. 72 + 146-151:
|
|
- Per-Form `allowedOriginDomains` String[] ✓
|
|
- Origin-Header-Check im Submission-API ✓
|
|
- Wildcard-Support (`*.example.com`) getestet ✓
|
|
- Webhook-SSRF-Check (keine internen IPs) ✓
|
|
- CSP-Header für iframe ✓
|
|
|
|
→ Strict.
|
|
|
|
---
|
|
|
|
## 8. Fehlende Aspekte (Lücken-Findings)
|
|
|
|
### Finding L1 (Minor) — AI-Cost Provider-Pricing-Tables Update-Strategie
|
|
|
|
ai-cost-phase-1.md Z. 54-55 + 86-89: Pricing-Tables sind versioniert (`pricing/v2026-05-16.ts`) und im Repo-Commit (kein DB-Override). Security-Note Z. 140: "Pricing-Files im Repo-Commit, kein DB-Override → Audit-Trail über git-history."
|
|
|
|
**Was fehlt:** Update-Workflow ist nicht explizit dokumentiert. Wenn OpenAI z.B. am 1. Juni einen neuen Preis veröffentlicht, was ist der Operator-Workflow?
|
|
- Wer triggert Pricing-Update?
|
|
- Wie wird historische Cost-Migration für past-events gehandhabt (Z. 132: "neue Pricing-Datei mit Korrektur + Cron-Job zur Neuberechnung historischer Events (separater fix-Task)" — bleibt vage)?
|
|
- Gibt es einen "Pricing-Drift-Detector" der bei großen Sprüngen warnt?
|
|
|
|
**Empfehlung:** In `docs/features/ai-cost-billing.md` (Phase-1-Doku, Z. 89) explizit einen "Pricing-Update-Runbook" hinzufügen. Beispiel-Sections:
|
|
1. Wann updaten (monatlicher Provider-Doc-Check)
|
|
2. Wie updaten (neue Pricing-File hinzufügen, alte nicht überschreiben)
|
|
3. Backfill-Strategie (nur falls Pricing-Bug korrigiert; Provider-Preisänderung wirkt nur prospektiv)
|
|
4. Tests für Pricing-File-Loading
|
|
|
|
Kein Blocker — kann während Step 10 (Doku) ergänzt werden.
|
|
|
|
### Finding L2 (Minor) — Form-Widget iframe-Size-Negotiation via postMessage
|
|
|
|
form-widget.md Z. 67 erwähnt: "hört auf PostMessage `toolctrl:form:resize` für dynamic-height". Auch in Z. 127 als Acceptance-Criterion (`toolctrl:form:resize` funktional).
|
|
|
|
**Was fehlt:** Detailliertes Protokoll für iframe-Auto-Resize. Bei Form-Builder-Flexibilität (Felder werden hinzugefügt/entfernt, Conditional-Logic zeigt/versteckt Felder) kann iframe-Höhe stark variieren.
|
|
|
|
**Empfehlung:** Step 4 (Embedded-Form-App) sollte ResizeObserver auf Body verwenden + PostMessage mit `{ type: 'toolctrl:form:resize', height: number }` an Parent emittieren. Step 3 (Loader) muss diesen Event empfangen und `iframe.style.height = ...px` setzen. Width sollte 100% bleiben (responsive).
|
|
|
|
**Konkrete Spec-Ergänzung:**
|
|
```
|
|
PostMessage-Protokoll:
|
|
- Child → Parent: { type: 'toolctrl:form:resize', height: number }
|
|
- Child → Parent: { type: 'toolctrl:form:submitted', leadId?: string, redirectUrl?: string }
|
|
- Child → Parent: { type: 'toolctrl:form:error', message: string }
|
|
- Parent → Child: { type: 'toolctrl:form:theme-update', themeJson: object } (optional)
|
|
```
|
|
|
|
Kann in Step 3+4 ergänzt werden; kein Blocker, aber implementer wird sonst raten.
|
|
|
|
### Finding L3 (Minor) — `Lessons Learned`-Section optional aber nirgends gefüllt
|
|
|
|
Alle 9 Detail-MDs lassen `Lessons Learned` weg. Template Z. 128: "Lessons Learned (optional, am Ende des Tasks für nachfolgende Tasks)" → wird vom ausführenden Agent post-completion gefüllt. Keine Aktion nötig vor Execution.
|
|
|
|
### Finding L4 (Info) — Phase-3 Cron-Trigger benötigt eigenen Trigger-Event-Pfad
|
|
|
|
marketing-funnel-phase-3.md Z. 78 erwähnt "Lost Lead Re-Activation" Trigger als "Cron-Job 60d-stale-leads scheint matching trigger". Implementation Step 11 (Z. 92-94) konkretisiert: Cron emit-Outbox-Event `lead.stale_60d` + `tenant.trial_expiring`.
|
|
|
|
**Konsistenz-Prüfung:** Step 2 (Z. 60) listet `triggerEvent` enum: `lead.captured|lead.qualified|tenant.signup|tenant.trial_expiring|tenant.cancelled|custom`. **`lead.stale_60d` fehlt im Enum!**
|
|
|
|
**Empfehlung:** Enum erweitern um `lead.stale_60d` oder als `custom` mit Custom-Trigger-Name behandeln. Andere Cron-emittierte Events ähnlich. Kann während Implementation korrigiert werden, aber sollte als Deviation festgehalten werden.
|
|
|
|
### Finding L5 (Minor) — Form-Widget: File-Upload nicht in Phase 1
|
|
|
|
form-widget.md Security-Note Z. 147: "File-Upload (out-of-scope Phase 1): wenn File-Field später hinzukommt, dann AV-Scan-Layer aus Phase 01 Tasks #31/#32 einbinden."
|
|
|
|
→ Akzeptable Einschränkung. Klar als out-of-scope markiert. Field-Type-Liste in Step 2 (Z. 64) erwähnt `file optional`. Konsistent.
|
|
|
|
### Finding L6 (Info) — Realtime-Collab Plan-Tier-Gating nicht detailliert
|
|
|
|
realtime-collab.md Depends Z. 25 erwähnt "Plan-Tier-Gating", aber Implementation-Steps spezifizieren keine konkrete Plan-Tier-Quota (z.B. "Free: keine Collab, Pro: 5 concurrent Collab-Editors, Enterprise: unlimited"). Security-Note Z. 137: "Limit per Tenant via Hocuspocus-onConnect-Hook prüft Concurrent-Connection-Count gegen Plan-Quota. Default 50/Tenant."
|
|
|
|
**Empfehlung:** Wäre wünschenswert, Plan-Tier-Quota in Entitlements-Schema (`packages/entitlements/`) wie in ai-cost-phase-2 zu definieren — z.B. `collabConcurrentEditorsPerTenant`. Kann während Implementation als Deviation ergänzt werden.
|
|
|
|
---
|
|
|
|
## 9. Phase-übergreifende Konsistenz
|
|
|
|
### `.env.example`-Keys
|
|
|
|
README Done-Definition (Z. 81) listet: `HOCUSPOCUS_URL`, `HOCUSPOCUS_SECRET`, `MARKETING_DOMAINS`, `FORM_WIDGET_CDN_URL`, `STRIPE_AI_OVERAGE_METER_ID` (optional), `TURNSTILE_SITE_KEY`, `TURNSTILE_SECRET_KEY`.
|
|
|
|
Cross-check pro File:
|
|
- feature-flags.md: keine neuen Keys (Cache via SharedStore = existing Redis) — implicit, kein Issue
|
|
- ai-cost-phase-1.md: keine Keys explizit — `AI_COST_TRACKING_ENABLED` in Rollback erwähnt aber nicht in `.env.example`-Step
|
|
- ai-cost-phase-2.md: `AI_QUOTA_ENFORCEMENT_ENABLED`, `AI_QUOTA_ALERTS_ENABLED` in Rollback — nicht explizit ins `.env.example` aufgenommen
|
|
- ai-cost-phase-3.md: `STRIPE_AI_OVERAGE_METER_ID` ✓ + `AI_OVERAGE_SUBMISSION_ENABLED`
|
|
- form-widget.md: `FORM_WIDGET_CDN_URL`, `TURNSTILE_SITE_KEY`, `TURNSTILE_SECRET_KEY` ✓ (Z. 129)
|
|
- realtime-collab.md: `HOCUSPOCUS_URL`, `HOCUSPOCUS_SECRET` ✓ (Z. 116)
|
|
- marketing-funnel-phase-1.md: `MARKETING_DOMAINS`, `TURNSTILE_*`, `MARKETING_SDK_CDN_URL`, `HONEYPOT_FIELD_NAME` ✓
|
|
- marketing-funnel-phase-2.md: `MARKETING_TOKEN_SECRET`, `LEAD_CONVERSION_ENABLED`, `MARKETING_WEBHOOKS_ENABLED` ✓
|
|
- marketing-funnel-phase-3.md: `MARKETING_SEQUENCES_ENABLED` (Rollback)
|
|
|
|
**Finding ENV1 (Minor):** Rollback-Killswitch-Env-Vars (`AI_COST_TRACKING_ENABLED`, `AI_QUOTA_ENFORCEMENT_ENABLED`, `LEAD_CONVERSION_ENABLED`, etc.) erscheinen nur in Rollback-Sections, sind aber nicht in `.env.example`-Acceptance-Criteria gelistet. Empfehlung: Per Detail-MD ein expliziter Acceptance-Criterion "`.env.example` enthält {alle Toggle-Keys}" hinzufügen — sonst werden sie vergessen.
|
|
|
|
### Outbox-Event-Naming-Konsistenz
|
|
|
|
Verwendete Event-Namen über die Files:
|
|
- `ai-cost.persist-event` (Phase 1/2/3)
|
|
- `ai-cost.aggregate-summary` (Phase 1)
|
|
- `ai-quota.alert` (Phase 2)
|
|
- `form.submission.process` (Form-Widget)
|
|
- `marketing.lead.webhook` (Marketing-Phase-2)
|
|
- `marketing.sequence.start` / `marketing.sequence.send` (historical Marketing-Phase-3 spec names; current #80 docs use `email-sequence-trigger` / `email-sequence-scheduler`, with production send still deferred)
|
|
- `lead.captured`, `lead.qualified`, `lead.converted_to_trial`, `lead.converted_to_customer` (Phase 2 → Phase 3)
|
|
- `lead.stale_60d`, `tenant.trial_expiring`, `tenant.signup`, `tenant.cancelled` (Phase 3 Cron)
|
|
|
|
Naming-Pattern: `{domain}.{entity}.{action}` (kebab/dot) vs `{entity}.{action}` (für Lifecycle-Events).
|
|
|
|
**Finding EVT1 (Info):** Naming-Konvention nicht 100% einheitlich (z.B. `ai-cost.persist-event` mit dash vs `ai-quota.alert` mit dot vs `lead.captured`). Akzeptabel, da intuitiv lesbar — aber könnte in einem späteren Cleanup vereinheitlicht werden.
|
|
|
|
---
|
|
|
|
## 10a. 2026-05-27 Status-Reconciliation
|
|
|
|
This original verification report remains useful as a pre-execution spec audit,
|
|
but several rows are now historical. Current status must be read from
|
|
`../PROGRESS.md` plus `../OPERATOR-CHECKLIST.md`.
|
|
|
|
- Marketing Funnel Phase 3 / #80 is still `in_progress`. The shipped surface is
|
|
the data model, pure engine, four template definitions, scheduler foundation,
|
|
tracking, unsubscribe, admin UI/CLI, live stats dashboard, and
|
|
stale-lead/trial-expiring runner functions. It is **not** production
|
|
marketing-sequence delivery until the delayed producer, sequence renderer,
|
|
`@toolctrl/mail` adapter, seed data, stats aggregation cron, Playwright E2E,
|
|
and production scheduled-job registration/deploy evidence land.
|
|
- The canonical email-sequence status is `docs/features/email-sequences.md`.
|
|
Use its model names (`EmailSequence`, `EmailSequenceRun`,
|
|
`EmailSequenceStepDelivery`) and admin route (`/admin/email-sequences`) when
|
|
reconciling stale references in this report or downstream plans.
|
|
- The original "Lead-Capture -> ... -> erste Email versendet" expectation
|
|
remains a future acceptance target, not current live proof. Current safe
|
|
wording is: lead capture/conversion can create or display sequence state;
|
|
production mail sending is deferred behind #80 follow-ups.
|
|
|
|
## 10. Zusammenfassung
|
|
|
|
### Pass-Status
|
|
|
|
**PASS.** Alle 10 Files waren zum Zeitpunkt dieser historischen Planprüfung plan-quality-ready für Execution: Template-Konformität 100%, Dependencies konsistent, Implementation-Steps atomar und konkret genug für Subagent-Implementation, Test-Requirements präzise, Staging-Steps machbar. Das ist keine Aussage, dass Email-Sequences runtime-production-ready sind; der aktuelle Runtime-Status steht in `docs/features/email-sequences.md`.
|
|
|
|
### Findings-Übersicht
|
|
|
|
| ID | Severity | Datei | Beschreibung |
|
|
|---|---|---|---|
|
|
| T1 | Info | alle | Template-Konformität korrekt; Lessons-Learned optional weggelassen |
|
|
| D1 | Info | alle | Dependencies konsistent |
|
|
| D2 | Minor | realtime-collab.md | `Blocks`-Section dünn — akzeptabel |
|
|
| I1 | Minor | feature-flags.md | Hash-Algo (SHA1) sollte in Step 2 explizit fixiert sein |
|
|
| I2 | Info | ai-cost-phase-1.md | LLM-Pfad-Coverage vollständig |
|
|
| I3 | Minor | form-widget.md | PostMessage-Resize-Protokoll nicht spezifiziert (siehe L2) |
|
|
| T2 | Info | alle | Test-Sections konsistent qualitativ hochwertig |
|
|
| S1 | Info | 3 Files | Staging-Steps für externe Assets vollständig |
|
|
| SEC1 | Info | feature-flags.md | Self-loop-MCP-Schutz korrekt nach Phase 07 verschoben |
|
|
| L1 | Minor | ai-cost-phase-1.md | Pricing-Update-Runbook fehlt explizit |
|
|
| L2 | Minor | form-widget.md | iframe-Resize-PostMessage-Protokoll konkretisieren |
|
|
| L3 | Info | alle | `Lessons Learned` post-Execution füllen |
|
|
| L4 | Minor | marketing-funnel-phase-3.md | `lead.stale_60d` fehlt im triggerEvent-Enum |
|
|
| L5 | Info | form-widget.md | File-Upload explizit out-of-scope (OK) |
|
|
| L6 | Info | realtime-collab.md | Plan-Tier-Quota Detail wünschenswert |
|
|
| ENV1 | Minor | mehrere | Rollback-Killswitch-Env-Vars nicht in Acceptance-Criteria gelistet |
|
|
| EVT1 | Info | mehrere | Outbox-Event-Naming nicht 100% einheitlich (akzeptabel) |
|
|
|
|
### Konkrete Empfehlungen vor Execution-Start
|
|
|
|
1. **L4 (Pflicht):** `marketing-funnel-phase-3.md` Z. 60 — Enum-Erweiterung um `lead.stale_60d` (oder Cron-Trigger-Custom-Variante explizit definieren) — sonst Mismatch zwischen Step 2 und Step 11.
|
|
2. **L2 (Empfohlen):** `form-widget.md` Step 3+4 — PostMessage-Protokoll-Detail spezifizieren (4 Message-Types).
|
|
3. **ENV1 (Empfohlen):** Detail-MDs um zusätzlichen Acceptance-Criterion "`.env.example` enthält alle Killswitch-Env-Vars" ergänzen.
|
|
4. **L1 (Empfohlen):** `ai-cost-phase-1.md` Step 10 (Doku) — explizit "Pricing-Update-Runbook" als Pflicht-Section.
|
|
5. **I1 (Optional):** `feature-flags.md` Step 2 — Hash-Algo (SHA-256 empfohlen) explizit fixieren.
|
|
|
|
Alle anderen Findings sind Info-Level oder können während Implementation als Deviations dokumentiert werden.
|
|
|
|
### Bereitschaftserklärung
|
|
|
|
Phase 05 ist **executable**. Subagents können auf Basis der Spec ohne weitere Architektur-Entscheidungen implementieren. Vor allem die Cross-File-Konsistenz (Dependencies, README-Done-Definition, Track-Aufteilung) ist sauber. Die ~16 Findings sind allesamt iterativ während der Execution behebbar — keine architectural redesigns nötig.
|