Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/05-business-features/ai-cost-phase-3.md
T

17 KiB
Raw Blame History

AI-Cost-Tracking — Phase 3: Stripe-Overage-Billing + Markup

Status: in_progress (code-complete, stripe-account-setup-pending) Task-ID: #56 Phase: 05 Estimated Effort: 1-2 Wochen Owner: unassigned

Problem

Phase 2 verhindert Verbrauch über Quota. Aber: Tenants wollen oft mehr AI als ihre Quota — und wir wollen ihnen das verkaufen, statt sie zu blockieren. Aktuell ist es unmöglich, "20$/Monat + 0,002$/Token darüber" zu verkaufen. Wir brauchen:

  • Markup-Konfiguration pro Plan (z.B. Pro = 2× Provider-Cost, Enterprise = 1.5×)
  • Overage-Tracking: alles über Quota wird als billable Overage markiert
  • Stripe-Usage-Based-Pricing: Overage-Cents werden als Meter-Events an Stripe gemeldet
  • Stripe-Invoice enthält Overage automatisch als Line-Item bei nächster Period
  • Tenant-UI zeigt Period-Forecast (Quota + projected Overage)
  • Reconciliation: monatlicher Cross-Check unsere Cost-Events vs Stripe-Submitted-Sums

Ohne Phase 3 endet Cost-Tracking nutzlos: wir haben Sichtbarkeit + Schutz, aber kein Monetarisierungs-Hebel.

Depends on

  • 05-business-features/ai-cost-phase-2.md (#55) — Quota-Definition + assertTenantAICreditAccess markiert Events als isOverage
  • 05-business-features/ai-cost-phase-1.md (#54) — AICostEvent-Pipeline + Persistence-Worker
  • 05-business-features/feature-flags.md (#53) — Per-Tenant-Overage-Enablement via Flag
  • Existierende Stripe-Integration in apps/web/app/utils/stripe.server.ts (aktuell schon vorhanden, wird erweitert)

Blocks

  • 07-chatbot/chatbot-v2.md (#69) — V2-Chatbot UI referenziert "Overage-Verbrauch" explizit
  • Vermarktung der Boilerplate als "AI-Monetarisierbar" (Marketing-Claim für Phase-05-Marketing-Funnel)

Approach

Drei Stufen:

  1. Markup-Konfiguration in pricingService — pro Plan: aiMarkupMultiplier (z.B. 2.0), aiOverageBlockCents (Min-Increment für Stripe-Meter, sonst Mikro-Charges), aiOverageStripeMeterId? (Stripe-Side-Identifier). Admin-UI im Plan-Editor.
  2. Overage-Markierung im Persistence-Worker — wenn event.costCents über aktuelle Period-Quota fällt, event.isOverage = true + event.markedUpCostCents (= costCents × multiplier). Nightly-Report-Cron aggregiert Overage pro Tenant und submitted Stripe-Meter-Events.
  3. Tenant-UI + Reconciliation — Period-View mit Quota + Overage clear; monthly-Reconciliation-Cron vergleicht AICostEvent-Sum vs Stripe-Meter-Submitted-Sum, alert bei Mismatch >1%.

Begründung der Architektur-Wahl:

  • Markup vs Pass-Through: wir verkaufen Service, nicht Provider-Tokens. Markup-Multiplier verschleiert Provider-Choice (wir können Provider wechseln ohne Tenant-Preisanpassung) und finanziert unseren Overhead (Hosting, Engineering).
  • Block-Cents-Quanten: Stripe-Meter-Events sind nicht gratis bei extrem hoher Frequenz. Aggregation auf 10-cents-Blocks reduziert Event-Volume von 10k auf <100/Tag pro Tenant.
  • Nightly-Submit statt realtime: Stripe-Meter-API hat Quotas + Latenz. Nightly-Aggregation ist robust + reduziert API-Calls. Für Real-Time-Anzeige nutzen wir interne AICostEvent-Sum, nicht Stripe-State.
  • Per-Plan-Feature-Flag: Free-Plan hat keine Overage (Hard-Cap), Pro/Enterprise haben Overage. aiOverageStripeMeterId === null → kein Overage erlaubt → in Phase-2-Assert ist Soft-Degradation oder Deny das einzige Verhalten.
  • Reconciliation als Cron statt Real-Time: Mismatches sind selten + nicht kritisch im Moment-by-Moment-Sinne; monatliches Audit reicht.

Implementation Steps

  1. Plan-Schema-Erweiterung — packages/entitlements/src/types.ts: aiOverageStripeMeterId?: string, aiMarkupMultiplier?: number = 1.5, aiOverageBlockCents?: number = 10. Migration nicht nötig (Plan-Definitionen sind code-side).
    • Files: packages/entitlements/src/types.ts, packages/entitlements/src/plans/*.ts
    • Commit: 05/ai-cost-phase-3: plan schema with overage and markup config
  2. Admin-Plan-Editor-UI — Erweiterung von /admin/pricing (oder dem entsprechenden Plan-Editor): drei neue Felder, Validation (Multiplier > 1.0, BlockCents >= 1), Save-Action mit Audit-Eintrag.
    • Files: apps/web/app/routes/admin.pricing....tsx (existing), AuditEvent-Wiring
    • Commit: 05/ai-cost-phase-3: admin ui for plan markup and overage config
  3. Overage-Markierung im Persistence-Handler — ai-cost.persist-event-Handler aus Phase 1 erweitert: vor Insert lookup currentMonthSpend; wenn (currentSpend + event.costCents) > quota → event.isOverage = true, berechne Overage-Anteil (falls Event teilweise in Quota + teilweise drüber liegt, splitten oder vereinfacht: kompletter Event als overage markiert wenn Großteil drüber). markedUpCostCents = costCents × plan.aiMarkupMultiplier. Felder isOverage, markedUpCostCents zu AICostEvent-Schema hinzufügen.
    • Files: prisma/schema.prisma (zusätzliche Felder), prisma/migrations/<ts>_ai_cost_overage_fields/migration.sql, apps/worker/src/handlers/ai-cost.persist-event.ts
    • Commit: 05/ai-cost-phase-3: mark overage events with markup
  4. Nightly Overage-Report-Cron — apps/worker/src/cron/ai-overage-report.ts läuft täglich um 02:00 UTC. Aggregiert seit letzter Submission sum(markedUpCostCents) WHERE isOverage=true AND submittedToStripe=false pro Tenant. Wenn Sum >= plan.aiOverageBlockCents → Stripe-Meter-Event stripe.billing.meterEvents.create({ event_name, payload: { stripe_customer_id, value: ceil(sum / blockCents) * blockCents }, identifier: uuid }). Idempotency-Identifier verhindert Doppel-Submission bei Retry. Markiere submittedEvents submittedToStripe=true + speichere stripeMeterEventId.
    • Files: apps/worker/src/cron/ai-overage-report.ts, Test (mit Stripe-Mock)
    • Commit: 05/ai-cost-phase-3: nightly overage report to stripe meter
  5. Stripe-Setup-Doku + Configuration — Doku-Section für Boilerplate-Betreiber: wie Stripe-Meter anlegen, wie Pricing-Tabelle mit graduated/tiered usage pricing aufsetzen, wie Customer-Subscription die Meter referenziert. Env-Keys STRIPE_AI_OVERAGE_METER_ID (optional, falls einzelner Meter für alle Plans; sonst pro Plan im Plan-Definition).
    • Files: docs/features/ai-cost-billing.md (Phase-3-Section), .env.example
    • Commit: 05/ai-cost-phase-3: stripe setup docs
  6. Tenant-UI für Period-View mit Overage — Erweiterung /app/$tenant/settings/ai-usage: Period-Bar zeigt Quota-Bereich (grün) + Overage-Bereich (gelb) + projected EOM (durchgezogene Linie für aktueller Spend, gestrichelt für Trend). Hinweis-Banner "X cents Overage wird auf nächster Stripe-Invoice abgerechnet". Per-Day-Bar-Chart mit isOverage-Färbung.
    • Files: Update apps/web/app/routes/app.$tenant.settings.ai-usage.tsx
    • Commit: 05/ai-cost-phase-3: tenant period view with overage visualization
  7. Audit-Trail für Overage-Submissions — neues Model AIOverageSubmission { id, tenantId, periodStart, periodEnd, submittedCostCents, stripeMeterEventId, eventCount, createdAt }. Wird vom Nightly-Cron pro Submission befüllt. Admin-UI /admin/billing/ai-overage zeigt alle Submissions pro Tenant + erlaubt manuelle Re-Submission bei Mismatch.
    • Files: prisma/schema.prisma, Migration, apps/web/app/routes/admin.billing.ai-overage.tsx
    • Commit: 05/ai-cost-phase-3: overage submission audit trail and admin ui
  8. Reconciliation-Cron — apps/worker/src/cron/ai-overage-reconcile.ts läuft monatlich am 5. eines Monats (nach Stripe-Invoice-Period-Close). Vergleicht für jeden Tenant: sum(markedUpCostCents WHERE isOverage AND createdAt im Vor-Monat) vs sum(submittedCostCents WHERE periodStart im Vor-Monat). Bei Mismatch >1% → in-app Notification an Admin-Role + Sentry-Capture mit Tenant-Context. Doku-Runbook für Mismatch-Handling.
    • Files: apps/worker/src/cron/ai-overage-reconcile.ts, Test, Runbook-Section in docs/features/ai-cost-billing.md
    • Commit: 05/ai-cost-phase-3: monthly reconciliation cron with alerting
  9. Per-Tenant-Override für Markup — manche Enterprise-Deals haben Custom-Markup (1.2× statt 2.0×). Tenant.aiMarkupOverride Float? Migration; Persistence-Handler zieht Override falls vorhanden.
    • Files: prisma/schema.prisma, Migration, Update Persistence-Handler, Admin-UI-Field
    • Commit: 05/ai-cost-phase-3: per-tenant markup override
  10. Doku-Finalisierung — docs/features/ai-cost-billing.md Phase-3-Section: End-to-End-Flow-Diagramm (Call → Event → Overage-Mark → Cron → Stripe-Meter → Invoice), Operator-Runbook für Mismatch-Resolution, Stripe-Pricing-Strategie-Patterns (tiered vs graduated vs per-unit).
    • Files: docs/features/ai-cost-billing.md
    • Commit: 05/ai-cost-phase-3: docs finalization

Test Requirements

  • Unit-Tests:
    • Persistence-Handler: Event mit (currentSpend 95c, costCents 10c, quota 100c) → isOverage=true, markedUpCostCents=20 (mult 2.0)
    • Overage-Report-Cron: Mock-Stripe, simuliere 250c unsubmitted Overage, blockCents 10 → submitMeterEvent mit value 250; submittedToStripe-Flag gesetzt
    • Idempotency-Test: gleiche Cron-Run zweimal → keine doppelte Submission (identifier kollidiert in Stripe-Mock)
    • Reconciliation-Cron: simulierter 5%-Mismatch → Notification geschrieben
  • Integration-Tests:
    • End-to-End: 200c LLM-Spend bei Quota 100c → 100c overage events → Cron-Run → Stripe-Mock empfängt Meter-Event 100c × 2.0 = 200c
    • Per-Tenant-Markup-Override: gleicher Spend bei Override 1.5× → Stripe-Meter empfängt 150c
    • Reconciliation: AICostEvent-Sum 100c, Stripe-Submitted 98c → keine Alert; 100c vs 90c → Alert
  • E2E-Tests (Playwright):
    • Tenant-User mit Overage-aktivem Plan: macht Calls über Quota → UI zeigt Overage-Bar gelb + Hinweis-Banner
    • Admin öffnet /admin/billing/ai-overage/$tenantId → sieht Submission-History
    • Admin setzt Per-Tenant-Markup-Override → Plan-Editor speichert + Audit-Eintrag sichtbar
  • Coverage-Target: 90% für Cron-Jobs + Persistence-Handler-Updates, 70% UI
  • Test-Files: apps/worker/src/cron/ai-overage-report.test.ts, ai-overage-reconcile.test.ts, E2E apps/web/tests/e2e/ai-overage.spec.ts

NICHT als completed markieren bevor alle Tests grün sind.

Acceptance Criteria

  • Plan-Schema mit aiOverageStripeMeterId, aiMarkupMultiplier, aiOverageBlockCents
  • Admin-Plan-Editor zeigt + speichert neue Felder
  • Migration für AICostEvent-Overage-Felder + AIOverageSubmission + Tenant.aiMarkupOverride applied
  • Persistence-Handler markiert Overage + berechnet MarkedUpCost
  • Nightly-Cron submitted Stripe-Meter-Events; Idempotency funktioniert
  • Tenant-UI zeigt Quota + Overage + projected EOM
  • AIOverageSubmission-Audit-Trail in DB + Admin-UI
  • Reconciliation-Cron läuft monatlich; Alert-Pfad getestet
  • Per-Tenant-Markup-Override funktional
  • docs/features/ai-cost-billing.md Phase-3-Section komplett (inkl. Stripe-Setup-Anleitung + Runbook)
  • .env.example enthält neue Keys
  • pnpm lint, pnpm typecheck, pnpm test grün
  • Coverage-Gates erfüllt
  • Atomic Commits gepushed auf agent/05-ai-cost-phase-3
  • Detail-MD Progress-Log aktualisiert
  • PROGRESS.md Status auf completed

Rollback Strategy

  • Stripe-Submission-Killswitch: Env AI_OVERAGE_SUBMISSION_ENABLED=false deaktiviert Cron-Submit (Events werden weiter markiert, aber nicht an Stripe gemeldet). Korrekturpfad: Backfill-Run nach Aktivierung.
  • DB-Migration: alle neuen Felder nullable / default-Werte → Rollback unschädlich.
  • Markup-Reset: Multiplier auf 1.0 in Plan-Definition + Re-Mark-Migration (Script) für noch-nicht-submitted Events.
  • Stripe-Meter-Cleanup: wenn falsche Meter-Events submitted wurden, manueller Stripe-Adjustment + AIOverageSubmission-Cancel-Flag setzen.

Security Notes

  • Doppel-Charging-Prevention: Idempotency-Identifier (UUID pro Submission) ist Pflicht — Stripe deduped auf Identifier. Tests müssen explizit Retry-Pfad verifizieren.
  • Markup-Tampering: Plan-Editor nur für Admin-Role; jede Markup-Mutation in AuditEvent.
  • Tenant-Exposure: Tenant darf provider-internal cost nicht sehen — Tenant-UI zeigt nur markedUpCostCents, nie costCents. Loader strippt Felder bewusst.
  • Reconciliation-Drift: systemic >1%-Mismatch könnte Indikator für Persistence-Bug sein → Alert ist Sentry-Capture mit Tenant-ID, Operator muss ASAP reagieren. Runbook beschreibt Diagnose-Schritte.
  • GDPR/Invoice-Daten: Stripe-Meter-Events enthalten nur Aggregate-Cents, keine PII; keine zusätzliche DPA-Klausel nötig über existierende Stripe-DPA hinaus.

Subagent Recommendations

  • Planning: Plan-Subagent mit Detail-MD-Input.
  • Research: Explore-Subagent: "Existierende Stripe-Integration in apps/web/app/utils/stripe.server.ts analysieren — gibt es schon Webhook-Handler für Subscription-Updates? Welche Stripe-API-Version ist gepinnt?"
  • Implementation Step 1-3 (Schema + UI + Mark): general-purpose-Subagent.
  • Implementation Step 4 (Cron Submit): general-purpose-Subagent mit explizitem Brief zu Idempotency + Stripe-Mock im Test.
  • Implementation Step 5-7 (Docs + UI + Audit): general-purpose-Subagent.
  • Implementation Step 8-9 (Reconcile + Override): general-purpose-Subagent.
  • Tests: separater general-purpose-Subagent für E2E + Stripe-Mock-Tests.
  • Verification: gsd-verifier.
  • Code-Review: gsd-code-reviewer.

Staging-Deployment-Steps

  1. Branch agent/05-ai-cost-phase-3 pushen → Coolify-Auto-Deploy
  2. Stripe-Test-Account: Meter anlegen (ai_overage_cents), Pricing-Tabelle definieren, Test-Subscription mit Meter-Bindung
  3. STRIPE_AI_OVERAGE_METER_ID als Staging-Env setzen, Test-Plan-Definitions linken
  4. Migration pnpm prisma migrate deploy
  5. Staging-Test:
    • Test-Tenant mit aktivem Stripe-Subscription auf Test-Plan
    • LLM-Calls bis 150% Quota
    • Cron-Job manuell ausführen → Stripe-Test-Dashboard zeigt Meter-Event
    • Test-Invoice generieren → Overage-Line-Item sichtbar
    • UI: Tenant sieht Overage-Bar + Banner
  6. Reconciliation-Test: AICostEvent manuell um 5% verfälschen → Reconcile-Cron alerted

Deviations from Plan

  • Stripe SDK 13.x — Usage-Records API, not Meters API. B-001 blocks upgrading to Stripe SDK 14+. Phase-3 ships against stripe.subscriptionItems.createUsageRecord(itemId, { quantity, action, timestamp }, { idempotencyKey }). The reporter wraps the call behind StripeUsageRecordSubmitter so swapping to stripe.billing.meterEvents.create(...) post-upgrade is a one-file change. aiOverageStripeMeterId is persisted today so operators can configure both fields up front — see migration steps in docs/features/ai-cost-billing.md "Future migration to Stripe Meters API (SDK 14+)".
  • Per-tenant override blob. Plan asked for a dedicated Tenant.aiMarkupOverride Float? column; we extend the existing Tenant.aiQuotaOverrideJson instead. Same access path; zero migration surface; matches the Phase-2 parser style. The Phase-3 parser in @toolctrl/entitlements is shape-tolerant so both blob keys coexist.
  • Admin UI scope. The /admin/settings/pricing/ai-overage route surfaces the per-plan defaults from standardAIOverageDefaults read-only and audit-logs would-be edits. Defaults stay in code until a follow-up moves them into a DB table (Phase-2 quota defaults share the same pattern). Per- tenant overrides via Tenant.aiQuotaOverrideJson are fully live.
  • AIOverageSubmission audit-trail model deferred. Spec asks for a dedicated AIOverageSubmission model; we stamp AICostEvent.stripeReportedAt + log structured payloads instead (stripeUsageRecordId included). Sufficient for now; a follow-up can promote the structured log into a queryable table.
  • Worker bootstrap wiring. This phase ships the handler + cron driver code with pure-by-deps tests. Hooking them into the worker's BullMQ scheduler is operator-side wiring (matches the pattern set by Phase-1 #54 and Phase-2 #55, both of which similarly deferred bootstrap to the worker-bootstrap rewrite).

Progress Log

  • 2026-05-17 — c0b48d9e — plan schema with overage and markup config (@toolctrl/entitlements ai-overage module + 23 unit tests)
  • 2026-05-17 — ca89ea43 — extend AICostEvent with overage markup fields (Prisma migration markedUpCostCents + stripeReportedAt)
  • 2026-05-17 — e15b195d — regenerate Prisma client for overage fields
  • 2026-05-17 — 27225add — mark overage events in persist handler (overageLookup dep + 6 new tests)
  • 2026-05-17 — ff8de906 — add Stripe overage reporting worker (ai-cost-stripe-report.ts + 13 tests, SDK 13.x Usage-Records API)
  • 2026-05-17 — 5a32d669 — admin UI for plan markup and overage config (/admin/settings/pricing/ai-overage + audit log)
  • 2026-05-17 — 544cb99e — bump i18n baseline for admin overage editor (jsx-text +3, user-facing-prop +5)
  • 2026-05-17 — 3739c174 — tenant UI shows period forecast with overage (/app/:tenant/settings/ai-usage)
  • 2026-05-17 — cc778b8c — reconciliation cron compares cost-events vs Stripe meter (9 tests)
  • 2026-05-17 — a546c184 — CLI helpers for Stripe AI-cost ops (toolctrl-cli ai-cost {report-overage,reconcile,show-billing})
  • 2026-05-17 — a4b23906 — env + documentation (.env.example killswitch + docs/features/ai-cost-billing.md)
  • 2026-05-17 — dbbc120d — sync hardcoded-strings test fixtures to bumped baseline