Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/05-business-features

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)