17 KiB
17 KiB
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 +assertTenantAICreditAccessmarkiert Events als isOverage05-business-features/ai-cost-phase-1.md(#54) — AICostEvent-Pipeline + Persistence-Worker05-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:
- 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. - 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. - 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
- 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
- Files:
- 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
- Files:
- 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. FelderisOverage,markedUpCostCentszu 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
- Files:
- Nightly Overage-Report-Cron —
apps/worker/src/cron/ai-overage-report.tsläuft täglich um 02:00 UTC. Aggregiert seit letzter Submissionsum(markedUpCostCents) WHERE isOverage=true AND submittedToStripe=falsepro Tenant. Wenn Sum >=plan.aiOverageBlockCents→ Stripe-Meter-Eventstripe.billing.meterEvents.create({ event_name, payload: { stripe_customer_id, value: ceil(sum / blockCents) * blockCents }, identifier: uuid }). Idempotency-Identifier verhindert Doppel-Submission bei Retry. Markiere submittedEventssubmittedToStripe=true+ speicherestripeMeterEventId.- 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
- Files:
- 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
- Files:
- 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
- Files: Update
- 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-overagezeigt 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
- Files:
- Reconciliation-Cron —
apps/worker/src/cron/ai-overage-reconcile.tslä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)vssum(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 indocs/features/ai-cost-billing.md - Commit:
05/ai-cost-phase-3: monthly reconciliation cron with alerting
- Files:
- 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
- Files:
- Doku-Finalisierung —
docs/features/ai-cost-billing.mdPhase-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
- Files:
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, E2Eapps/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.mdPhase-3-Section komplett (inkl. Stripe-Setup-Anleitung + Runbook).env.exampleenthält neue Keyspnpm lint,pnpm typecheck,pnpm testgrü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=falsedeaktiviert 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, niecostCents. 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
- Branch
agent/05-ai-cost-phase-3pushen → Coolify-Auto-Deploy - Stripe-Test-Account: Meter anlegen (
ai_overage_cents), Pricing-Tabelle definieren, Test-Subscription mit Meter-Bindung STRIPE_AI_OVERAGE_METER_IDals Staging-Env setzen, Test-Plan-Definitions linken- Migration
pnpm prisma migrate deploy - 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
- 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 behindStripeUsageRecordSubmitterso swapping tostripe.billing.meterEvents.create(...)post-upgrade is a one-file change.aiOverageStripeMeterIdis persisted today so operators can configure both fields up front — see migration steps indocs/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 existingTenant.aiQuotaOverrideJsoninstead. Same access path; zero migration surface; matches the Phase-2 parser style. The Phase-3 parser in@toolctrl/entitlementsis shape-tolerant so both blob keys coexist. - Admin UI scope. The
/admin/settings/pricing/ai-overageroute surfaces the per-plan defaults fromstandardAIOverageDefaultsread-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 viaTenant.aiQuotaOverrideJsonare fully live. - AIOverageSubmission audit-trail model deferred. Spec asks for
a dedicated
AIOverageSubmissionmodel; we stampAICostEvent.stripeReportedAt+ log structured payloads instead (stripeUsageRecordIdincluded). 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/entitlementsai-overage module + 23 unit tests) - 2026-05-17 —
ca89ea43— extend AICostEvent with overage markup fields (Prisma migrationmarkedUpCostCents+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.examplekillswitch +docs/features/ai-cost-billing.md) - 2026-05-17 —
dbbc120d— sync hardcoded-strings test fixtures to bumped baseline