# Phase 05 — Business-Features > **Docs-sidecar status:** Historical phase plan with live closeout notes. > Use `docs/feature-inventory.md`, `docs/feature-manifests/*.json`, > `docs/features/plugins.md`, and the focused docs linked below for current > runtime ownership. Do not treat unchecked items in this file as proof that a > route, worker, provider, or package still needs to be added. > Email Sequences status is deliberately delegated to > `docs/features/email-sequences.md`; this phase README must not be used as a > production-delivery claim for marketing mail. **Dauer:** 5+ Wochen (parallelisiert; rein sequenziell ~10-12 Wochen) **Tasks:** 9 (Feature-Flags + 3× AI-Cost + Form-Widget + Realtime-Collab + 3× Marketing-Funnel) **Ziel:** Differenzierende Produkt-Features etablieren, die aus der Boilerplate ein vermarktbares SaaS-Produkt machen. Feature-Flags als zentrale Steuerungs-Engine, end-to-end AI-Cost-Tracking inkl. Quota + Stripe-Overage, embeddable Form-Widget für Marketing-Sites, Realtime-Collaboration für Multi-User-Editing und ein Marketing-Funnel von Lead-Capture bis vorbereitetem Email-Sequence-Status. Production-Mailversand bleibt hinter `MARKETING_SEQUENCES_ENABLED=false`, bis die Email-Sequences-Follow-ups abgeschlossen sind. ## Warum diese Phase nach Phase 04 - **SharedStore (#37 aus Phase 03)** wird für Feature-Flag-Eval-Cache und für AI-Quota-Cache gebraucht — beide Tasks würden ohne tenant-konsistenten verteilten Cache pro Worker-Instanz auseinanderlaufen. - **Outbox-Pattern (#42 aus Phase 03)** ist Pflicht für AI-Cost-Event-Persistierung. Jeder LLM-Call darf nicht synchron in die DB schreiben (Latenz + Provider-Timeouts), sondern landet als Outbox-Event und wird vom Worker persistiert. - **Worker-Queues (#43 aus Phase 03)** liefern `worker-general` für AI-Cost-Aggregation/Outbox-Fanout und `worker-mail` für Marketing-Email-Sequencer sowie Sequence-Send-Job-Verträge. Production delivery stays behind `MARKETING_SEQUENCES_ENABLED=false` until #80 closeout evidence exists. - **React-Email (aus Phase 10)** wird vom Marketing-Funnel-Phase-3-Task benötigt. Diese Detail-MD ist explizit so geschrieben, dass React-Email vorgezogen werden kann, ohne die Phase-10-Reihenfolge zu sprengen. - **Search/RAG (Phase 04)** wird in dieser Phase nicht direkt konsumiert, ist aber Voraussetzung für Phase 07 — und Phase 05 blockt wiederum Phase 06 + 07, deshalb läuft Phase 05 nach Phase 04. ## Warum diese Phase vor Phase 06 - **Plugin-System** nutzt Feature-Flags für Plugin-Capability-Gating (jeder Plugin-Hook kann hinter einem Flag liegen). - **Plugin-Lifecycle-Events** registrieren sich an der Outbox + werden für AI-Kostenzuordnung Plugin-aware sein müssen (Plugin verursacht Tokens → Tenant-Cost-Bucket erweitert um Plugin-Dimension). ## Task-Reihenfolge | Reihenfolge | Task-ID | Datei | Parallelisierbar mit | |---|---|---|---| | 1 | #53 | `feature-flags.md` | — (Foundation; blockt mehrere Folgetasks weich) | | 2 | #54 | `ai-cost-phase-1.md` | #58, #59, #78 | | 3 | #55 | `ai-cost-phase-2.md` | #58, #59, #78, #79 (sequenziell zu #54) | | 4 | #56 | `ai-cost-phase-3.md` | #58, #59, #79, #80 (sequenziell zu #55) | | 5 | #58 | `form-widget.md` | gesamte AI-Cost-Reihe + Marketing-Funnel | | 6 | #59 | `realtime-collab.md` | gesamte AI-Cost-Reihe + Marketing-Funnel + Form-Widget | | 7 | #78 | `marketing-funnel-phase-1.md` | AI-Cost-Reihe, Form-Widget, Realtime | | 8 | #79 | `marketing-funnel-phase-2.md` | sequenziell zu #78 | | 9 | #80 | `marketing-funnel-phase-3.md` | sequenziell zu #79 (braucht React-Email) | ## Dependency-Graph (intern) ``` Phase 03 (SharedStore #37, Outbox #42, Worker-Queues #43) │ ▼ #53 feature-flags │ ┌──────────────────────────┼──────────────────────────────────┐ ▼ ▼ ▼ #54 ai-cost-phase-1 #58 form-widget #78 marketing-phase-1 │ │ │ ▼ │ ▼ #55 ai-cost-phase-2 │ #79 marketing-phase-2 │ │ │ ▼ │ ▼ #56 ai-cost-phase-3 #59 realtime-collab #80 marketing-phase-3 (braucht React-Email aus Phase 10 vorgezogen) │ ▼ Phase 06 Plugin-System Phase 07 Chatbot V1/V2 ``` Drei echte Parallel-Tracks: - **Track A — AI-Cost (sequenziell):** `#54 → #55 → #56`. Phase-2 baut auf der Cost-Event-Pipeline aus Phase-1 auf; Phase-3 baut auf der Quota-Definition aus Phase-2 auf. - **Track B — Standalone-Features:** `#58 form-widget` und `#59 realtime-collab` sind in sich abgeschlossen, brauchen nur Feature-Flags. Können parallel mit AI-Cost-Track laufen. - **Track C — Marketing-Funnel (sequenziell):** `#78 → #79 → #80`. Phase-2 baut auf dem Lead-Modell aus Phase-1 auf; Phase-3 erweitert um Sequence-Engine und braucht React-Email-Templates. Empfohlene Parallelisierung mit 3 Agents: Track A, B (beide Tasks nacheinander oder zwei Sub-Agents) und C laufen gleichzeitig nach Abschluss von `#53`. ## Phase Done-Definition **2026-05-27 status note:** Phase 05 is not complete as a full original phase contract. Marketing email sequences currently have the data model, pure engine, admin UI/CLI, tracking, unsubscribe, live admin stats, unit-tested stale-lead/trial-expiring runner functions, delayed-step enqueueing, bundled template rendering, and the `@toolctrl/mail` Mailjet adapter. They do **not** yet prove production email delivery end to end. Signed Mailjet bounce/rejection ingress is shipped, but production delivery remains gated on seed data, stats aggregation cron/persistence, provider delivery/open/click reconciliation evidence beyond the in-repo tracking routes, Playwright E2E, and production scheduled-job registration/deploy evidence. Diese Phase ist `completed` wenn: - [ ] Alle 9 Tasks `completed` in `PROGRESS.md` - [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` global grün - [ ] `packages/feature-flags/` exportiert stabile öffentliche API (`evaluateFlag`, `getFeatureFlagVariant`, `useFeatureFlag`-Hook) mit publizierter Typen-Surface - [ ] `packages/ai/src/cost/` exportiert `countTokens`, `countCallCost`, `estimateLLMCost`, `assertTenantAICreditAccess` - [ ] `packages/marketing-sdk-js/` ist als gebundleder Asset-Output (`marketing.js`) origin-served und CDN-ready; CDN-Provisioning bleibt A7/B2/#51-Backlog - [ ] Prisma-Models live: `FeatureFlag`, `FeatureFlagAudit`, `AICostEvent`, `TenantAICostSummary`, `Lead`, `TenantAcquisition`, `EmailSequence`, `EmailSequenceRun`, `EmailSequenceStepDelivery` - [ ] Tenant-UI live: `/app/$tenant/settings/ai-usage`, Form-Builder unter `/app/$tenant/forms` - [ ] Admin-UI live: `/admin/feature-flags`, `/admin/analytics/ai-costs`, `/admin/marketing/leads`, `/admin/email-sequences`, `/admin/marketing/funnels`, `/admin/marketing/integrations` - [ ] Worker registriert mindestens die Job-Handler `ai-cost.persist-event`, `ai-cost.aggregate-summary`, `ai-quota.alert`, `marketing.lead.webhook`, `email-sequence-trigger`, `email-sequence-scheduler`, `lead-stale-trigger`, `trial-expiring-trigger` — for Email Sequences this is foundation registration only; production scheduler/deploy evidence, seed data, stats aggregation cron/persistence, provider delivery/open/click reconciliation evidence beyond the in-repo tracking routes, and E2E remain tracked as open follow-ups in `docs/features/email-sequences.md`. - [ ] Hocuspocus-Container läuft auf Staging, Y.js-Doc-Persistence in Postgres - [ ] `.env.example` enthält neue Keys: `HOCUSPOCUS_URL`, `HOCUSPOCUS_SECRET`, `MARKETING_DOMAINS`, `FORM_WIDGET_CDN_URL`, `STRIPE_AI_OVERAGE_METER_ID` (optional), `TURNSTILE_SITE_KEY`, `TURNSTILE_SECRET_KEY` - [ ] Doku-Files vorhanden: `docs/features/feature-flags.md`, `docs/features/ai-cost-billing.md`, `docs/features/embeddable-forms.md`, `docs/features/realtime-collaboration.md`, `docs/features/marketing-funnel.md` - [ ] Staging-Deployment auf `agent/phase-05-final`: Hocuspocus-Container hochgefahren, Form-Widget gegen externe Test-Domain getestet, Lead-Capture-Endpoint per CORS-Whitelist getestet, AI-Cost-Pipeline End-to-End mit echter OpenAI-Call → Event → Summary - [ ] Integration-Test-Flows: - Feature-Flag-Toggle in Admin-UI → Eval in Client innerhalb 60s (Pub/Sub-Invalidation) - LLM-Call → AICostEvent in Outbox → Persistenz → Summary-Aggregation → Dashboard-Sichtbarkeit - Quota-Überschreitung → Soft-Degradation oder HTTP 402 + Alert - Lead-Capture via Form-Widget → Lead in DB → Conversion zu Tenant → Email-Sequence-Run sichtbar; erste Produktions-Mail erst nach #80 seed/stats/webhook/E2E/deploy closeout - [ ] Tenant-Isolation-Tests: Feature-Flag-Allowlist greift nur für Ziel-Tenant; AICostEvent nie cross-tenant lesbar; Lead-Daten nie cross-tenant exposed - [ ] `gsd-code-reviewer`-Subagent hat alle Phase-05-Commits reviewed; Findings adressiert - [ ] Phase-Summary in dieser README.md ergänzt (siehe unten) ## Phase Summary _(Wird nach Abschluss der Phase vom ausführenden Agent ergänzt.)_ ### Lessons Learned _(Wird nach Abschluss ergänzt — insbesondere: Targeting-Rule-Komplexitäts-Findings, AI-Cost-Accuracy-Vergleich tiktoken-Estimation vs Provider-Billing, Hocuspocus-Skalierung-Findings, Marketing-Sequence-Open-Rates der Pre-Built-Templates.)_ ## Verweise - Detail-MD-Template: `../DETAIL-MD-TEMPLATE.md` - Agent-Workflow: `../AGENT-INSTRUCTIONS.md` - Execution-Order: `../00-execution-order.md` - Live-Status: `../PROGRESS.md` - Current feature classification: `../../feature-inventory.md` - Current feature manifest contracts: `../../feature-manifests/README.md` - Vorgänger-Phase: `../04-search-rag/README.md` - Nachfolger-Phasen im Originalplan: `../06-plugin-system/README.md`, `../07-chatbot/README.md` - Vorgezogen aus Phase 10: `../10-compliance-polish/react-email.md` (für `marketing-funnel-phase-3.md`)