132 lines
10 KiB
Markdown
132 lines
10 KiB
Markdown
# 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`)
|