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

212 lines
17 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.
# 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