10 KiB
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 todocs/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-generalfür AI-Cost-Aggregation/Outbox-Fanout undworker-mailfür Marketing-Email-Sequencer sowie Sequence-Send-Job-Verträge. Production delivery stays behindMARKETING_SEQUENCES_ENABLED=falseuntil #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-widgetund#59 realtime-collabsind 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
completedinPROGRESS.md pnpm lint,pnpm typecheck,pnpm testglobal grünpackages/feature-flags/exportiert stabile öffentliche API (evaluateFlag,getFeatureFlagVariant,useFeatureFlag-Hook) mit publizierter Typen-Surfacepackages/ai/src/cost/exportiertcountTokens,countCallCost,estimateLLMCost,assertTenantAICreditAccesspackages/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 indocs/features/email-sequences.md. - Hocuspocus-Container läuft auf Staging, Y.js-Doc-Persistence in Postgres
.env.exampleenthä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ürmarketing-funnel-phase-3.md)