Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/05-business-features/README.md
T

132 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`)