169 lines
11 KiB
Markdown
169 lines
11 KiB
Markdown
# VA-P24a · P24 Self-Service-Abo-Baukasten-UI (M28-Delta)
|
|
|
|
> ⚠️ **Billing-Recut 2026-07-04 ([[AD-27]]):** Self-Service-Billing baut auf
|
|
> **Lago + Mollie + HiveGrid-Entitlements** auf. Payment-Checkout, Legacy-Provider-Webhooks und Legacy-Provider-Customer-Portal werden
|
|
> nicht wiederverwendet. v1 bleibt Plans + Seats; die funktionale Self-Service-Checkout-Basis wurde am 2026-07-05 in
|
|
> `BILL-10` vorgezogen. Dieses Ticket bleibt fuer finale Screens, Preisvorschau-UX und Produkt-/Wizard-Delta.
|
|
|
|
> ⚠️ **KI→MCP-Pivot ([[AD-26]]):** Das **„AI-Credits"-Add-On entfällt**. Kein LLM-Gateway/AiCredits in v1.
|
|
|
|
| | |
|
|
| ----------------- | ------------------------------------------------------------ |
|
|
| **Typ** | Dev (Code) |
|
|
| **Owner** | Raffael |
|
|
| **Phase** | P24 — Self-Service-Billing & Onboarding-Wizard · v2-P3 |
|
|
| **Cycle/Fenster** | v2-W1 — Public-API/Postfach/Abo/KI-Start · fällig 2026-07-15 |
|
|
| **Status** | Plane Done · 100 % ursprüngliche DoD · separater AD-30-Nachzug **1/1 erfüllt** |
|
|
|
|
**🎨 design-nachzug: offen** (seit 2026-07-15) — `VD-P24` enthaelt noch kein Davids Delta; die
|
|
ticket-faehige Vorschau ist gemaess AD-28 als Interim-UI aus `~/ui` umgesetzt.
|
|
|
|
## Abhängigkeiten & Parallelität
|
|
|
|
- **Blocked by:** `BILL-02` bis `BILL-07` plus `BILL-09` bis `BILL-12`
|
|
(Plans/Seats-Domain, Provider-Gateways, Sync/Entitlements, Kunden-Rechnungszugriff,
|
|
Self-Service-Checkout, Pricing-Katalog und konsistente Kundennamen) — erfuellt;
|
|
externe Production-Aktivierung bleibt separat in `BILL-08` / `EXT-16`.
|
|
- **Blocks:** `VA-P24b` nur fuer gemeinsame Onboarding-/Plan-Kontexte, nicht fuer den Wizard-Kern; `VA-P24b` ist in Plane aktuell Cancelled.
|
|
- **Erfüllter Downstream-Handoff:** `VA-P26c` hat den Vertrag fuer ein pauschales Portal-Add-on und eine einmalige Custom-Domain-Einrichtung auf Staging konsumiert; daraus besteht kein offener Block mehr.
|
|
- **Läuft parallel zu:** `VA-P23` im selben v2-Fenster, sofern Billing-Interfaces stabil sind
|
|
- **Konflikt-Risiko:** mittel — Self-Service berührt Billing-State, Payment-Callbacks und Entitlements; keine Legacy-Provider-Altpfade erweitern
|
|
|
|
## Uebernahme-Notiz
|
|
|
|
2026-07-15 · Raffael: Ticket war bei Übernahme in Plane Raffael zugewiesen und stand auf `In Progress`;
|
|
aktuell steht es auf `In Review`. Isolierter Arbeitsstand auf
|
|
Branch `feat/va-p24a-self-service-billing` im Worktree `HiveGrid-Cloud-va-p24a`. Die Upstream-Billing-Blocker
|
|
sind erfuellt; der fruehere Downstream-Konsument `VA-P24b` ist in Plane Cancelled. Durch die Uebernahme
|
|
werden keine Billing-Contracts oder Schemas geaendert.
|
|
|
|
**Startstand:** `VA-P24a`: 2/6 DoD = rund 33 % done · 4 Punkte offen.
|
|
|
|
**Pre-Flight 2026-07-15:** Workspace-Struktur und EU-Import-Check sind gruen. Der erste interaktive
|
|
Volltest lief unter Last in `users.mfa.test.ts` in einen 20-Sekunden-Timeout; der direkte Wiederholungslauf
|
|
war mit 11/11 Tests gruen. Der anschliessende saubere CI-Modus-Lauf aus Typecheck und Volltest war
|
|
vollstaendig gruen: 777 Testdateien bestanden, 8 uebersprungen, 5061 Tests bestanden.
|
|
|
|
## Umsetzungs-Notiz
|
|
|
|
2026-07-15 · Raffael: Der Self-Service-Abo-Baukasten ist auf
|
|
`feat/va-p24a-self-service-billing` umgesetzt. Die Route baut ein reines View-Model aus dem kanonischen
|
|
Lago-/Mollie-/Entitlement-State und injiziert es in eine AD-28-Interim-UI. Plan, Abrechnungszeitraum und
|
|
Seats werden serverseitig validiert; die Preisvorschau beruecksichtigt Flat- und Per-Seat-Preise. Trial,
|
|
sofortige oder zum Periodenende wirksame Aenderungen, Mollie-Return/Webhook-Sync und der lokale
|
|
Billing-/Entitlement-State sind tenant- und RLS-gebunden. Es wurden keine Prisma-Schemas oder Migrationen
|
|
geaendert. Der finale Subframe-Nachzug bleibt als `design-nachzug` offen.
|
|
|
|
**Proof:** ursprünglicher P24-Commit `81b321d16`
|
|
(`feat(billing): add self-service subscription builder`, übernommen über `a456b8dc4`); `pnpm typecheck`, `pnpm lint` und `pnpm test`
|
|
gruen (780 Testdateien bestanden, 8 uebersprungen; 5084 Tests bestanden, 46 uebersprungen).
|
|
`verify:test-coverage`, `verify:i18n`, `verify:ui-visual` (79 Checks), `verify:ui-hot-swap`,
|
|
`verify:a11y-coverage`, `verify:ci-baseline` und `verify:source-health` sind gruen. Der neue Chromium-Smoke
|
|
ist im Playwright-Projekt registriert; dieser Nachweis behauptet keinen Live-Lauf gegen localhost oder
|
|
Staging.
|
|
|
|
**VA-P24a: 6/6 DoD = 100 % done.**
|
|
|
|
## Was wir bauen
|
|
|
|
Das **Self-Service-Delta auf dem v1-Billing**: Die Basis fuer Plan-/Seat-Auswahl, Mollie-Zahlungsstart und
|
|
Return/Webhook-Sync existiert in `BILL-10`. Dieses Ticket klaert/ergaenzt darauf aufbauend finale Screens,
|
|
Preisvorschau-UX, pauschale Add-on-/Einmalpositions-Checkout-Verträge, Wizard-/Onboarding-Kontext und noch fehlende Produktentscheidungen. Lago bleibt
|
|
Billing-Source-of-Truth fuer Subscription und Invoice, HiveGrid bleibt Entitlement-Source fuer Feature-Gates.
|
|
|
|
Nicht im Scope dieses Recut-Standes:
|
|
|
|
- Credits
|
|
- Add-on-Metering/Usage-Billing. **Pauschale** Monats-Add-ons und einmalige Einrichtungspositionen sind nach AD-30 erlaubt und werden von `VA-P26c` konsumiert.
|
|
- Legacy-Provider-Kompatibilitaet
|
|
- finale Rechnungssteller-/Steuerfreigabe
|
|
|
|
## Benötigte Screens (Backend bedient — Design liefert `VD-P24`)
|
|
|
|
| Screen [Route] | Kern-Inhalt |
|
|
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
|
|
| Self-Service-Plan-Wechsel [`/:tenant/settings/subscription`] | Aktueller Plan, Seats, verfügbare Pläne, Preis-Vorschau, Mollie-Zahlungsstart, Checkout-Return-/Payment-Status |
|
|
| Seat-Verwaltung [`/:tenant/settings/subscription`] | Seat-Anzahl erhöhen/reduzieren, sofortige Vorschau, serverseitige Validierung, Audit/Reason bei Sonderfällen |
|
|
| Billing-Status [`/:tenant/settings/billing`] | Lago-Invoice-Status, Mollie-Payment-Status, Fehlzahlung/Expired/Refund-Klartext |
|
|
|
|
## Definition of Done
|
|
|
|
- [x] Self-Service-Trial ohne Vertriebs-Freigabe ist fachlich entschieden und serverseitig modelliert.
|
|
- [x] Basis-Plan-Wechsel und Seat-Auswahl nutzen Lago-Subscription-State, nicht Legacy-Provider-Checkout. (`BILL-10`)
|
|
- [x] Zahlung wird ueber Mollie erzeugt und nach Return/Webhook idempotent verarbeitet. (`BILL-10`)
|
|
- [x] Preis-Vorschau ist serverseitig validiert und nutzt keine oeffentlich hartkodierten Preisversprechen.
|
|
- [x] `tenantHasModule()`/Entitlements reagieren auf den lokalen Billing-State.
|
|
- [x] RLS/Tenant-Scope auf allen Tenant-Tabellen, globale Produkt-/Preisdefinitionen bewusst getrennt.
|
|
|
|
## Separater AD-30-Nachzug fuer den neuen Downstream-Konsumenten `VA-P26c`
|
|
|
|
- [x] Der generische Produktvertrag fuer pauschale Monats-Add-ons und einmalige
|
|
Einrichtungspositionen ist geliefert. `SubscriptionProductKind` trennt Basispaket,
|
|
wiederkehrendes Add-on, einmaliges Setup und Contract-Override; das idempotente
|
|
`TenantProductAcquisition`-Ledger bindet den Erwerb an einen `scopeKey`. Fehler eines Add-ons oder
|
|
One-offs kündigen weder das Basispaket noch andere Produkte und setzen nicht den gesamten Tenant
|
|
auf `past_due`. Dieser nach Abschluss hinzugekommene Consumer-Contract erweitert nicht
|
|
rueckwirkend die sechs urspruenglichen DoD-Punkte.
|
|
|
|
**Fortschritt 2026-07-16:** ursprünglicher Ticket-Scope **6/6 DoD = 100 % done**; separater
|
|
AD-30-Nachzug **1/1 = 100 % done**. Repository-Proof: `18dfd4825` (gemeinsames Produkt-Ledger und
|
|
Schema-Vertrag) sowie `355eead8e` (Billing-, Webhook-, Provider-Adapter- und Entitlement-Vertrag). Generische
|
|
Ledger-, Idempotenz-, Webhook-Replay-, Refund-/Failure-Isolation- und Entitlement-Tests sind lokal gruen. Es
|
|
wurde dafür kein Migrationsfile angelegt und kein Billing-Provider-, Staging- oder Produktionszustand
|
|
mutiert. Die portalspezifischen externen Kaufnachweise bleiben DoD von `VA-P26c`, nicht von P24a.
|
|
|
|
**Downstream-Entscheidung 2026-07-16:** Business erhält das Portal inklusive und bezahlt die
|
|
Custom-Domain als einmalige 299,99-EUR-Einrichtung; Enterprise erhält Portal plus eine Domain über einen
|
|
separaten Override. Der generische P24-Vertrag bleibt unverändert: pauschales Add-on, einmalige Position
|
|
und Entitlement ohne Null-Euro-Checkout. Die portalspezifische Abbildung bleibt vollständig in `VA-P26c`.
|
|
|
|
**Downstream-Handoff 2026-07-21:** `VA-P26c` hat den generischen Vertrag auf Staging erfolgreich
|
|
konsumiert: Starter-Add-on, Business-Inklusivrecht, Enterprise-Override und genau eine
|
|
operatorseitig audit-verknüpfte Lago-One-off-Rechnung samt duplikatfreiem Replay sind belegt.
|
|
Prometheus-, Kill-Switch-, Deprovisionierungs- und finaler 404-Nachweis wurden anschließend vollständig
|
|
in `VA-P26c` abgeschlossen und verändern den bereits erfüllten P24-Vertrag nicht.
|
|
`VA-P24a` bleibt **6/6 ursprüngliche DoD plus 1/1 AD-30-Nachzug = 100 % done**.
|
|
|
|
**Praesentations-Nachzug 2026-08-02:** `BILL-20` ordnet die bestehende aktive
|
|
Self-Service-Flaeche in Uebersicht, Tarif/Nutzer und Zusatzmodule. Serverseitige
|
|
Preisvorschau, Checkout, Payment-Return, Add-on-Ledger und Entitlements aus
|
|
`VA-P24a` bleiben unveraendert; es entsteht kein neuer P24-Backend-Contract.
|
|
|
|
**Praesentations-Nachzug 2026-07-29:** `BILL-12` gleicht die bestehende
|
|
Interim-UI mit dem versionierten `BILL-11`-Katalog ab: Die Kundennamen sind
|
|
Core / Swarm / Colony, waehrend technische Codes und der bestehende
|
|
`pro` -> `team`-Vertrag unveraendert bleiben. Es entsteht keine neue
|
|
Abhaengigkeit fuer View-Model, Checkout oder Entitlements.
|
|
|
|
## Technische Bausteine
|
|
|
|
- Delta auf `BILL-02` bis `BILL-05` und Rechnungsanzeige aus `BILL-09`, keine neue Legacy-Provider-Domain.
|
|
- Funktionale Self-Service-Checkout-Basis aus `BILL-10`.
|
|
- `BillingGateway`/`LagoBillingGateway` fuer Plans, Seats, Subscriptions, Invoices.
|
|
- `PaymentGateway`/`MolliePaymentGateway` fuer Zahlungsstart und Payment-Status.
|
|
- Checkout-Return-Handler aktualisiert lokalen Billing-State nur ueber idempotente Sync-Events.
|
|
- Generischer Produktvertrag für pauschale wiederkehrende Add-ons und einmalige Setups; kein Portal-spezifischer Domain-Code in P24.
|
|
- PWA-only: reiner Web-Flow, kein App-Store-Billing.
|
|
|
|
## Quellen (granular)
|
|
|
|
- `docs/ARCHITECTURE-DECISIONS.md` → `AD-27`
|
|
- `docs/ARCHITECTURE-DECISIONS.md` → `AD-30` · Konsument `VA-P26c`
|
|
- `BILL-README.md`, `BILL-02` bis `BILL-07`, `BILL-09`
|
|
- `ROADMAP-V2.md` → v2-P3 Self-Service-Billing
|
|
- `ENTITY-MODEL.md` → Domäne 12, nach AD-27 zu recutten
|
|
- `designer-briefs/P24-self-service-billing-wizard.md` muss nach AD-27 aktualisiert werden
|
|
|
|
## Dev-Nachzug (nach Davids `VD-P24`-Delta)
|
|
|
|
**Interim-UI (Vorschau, Stand 2026-07-15):** Self-Service-Screen aus `~/ui` in
|
|
`apps/web/app/components/screens/billing/SelfServiceSubscriptionPage.tsx`; die markierte
|
|
Interim-Baseline liegt unter `packages/ui-mock/visual-baseline/va-p24a-interim.snapshot.json`.
|
|
Visual-/Hot-Swap-Proof ist lokal dokumentiert; der Browser-Smoke ist registriert und wird nicht als
|
|
Staging-/Live-Lauf ausgegeben. Refactor-Nachzug: finale Subframe-Optik aus `VD-P24` und Re-Baseline.
|
|
|
|
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
|
- [ ] REQUIREMENTS/ROADMAP nachgezogen
|
|
- [x] Plane-Ticket `VA-P24a` aktualisiert und nach dem Abschlusskommentar auf Done gesetzt
|
|
(`fd270011-4271-4d4d-bf5e-4a635fd214dc`, 2026-07-16)
|