@saasicat/spec 0.2.0

package/prisma-fragments/08-subscription-contract.prisma

@@ -0,0 +1,92 @@
+// =============================================================================
+// SaaS platform Prisma fragment: SubscriptionContract + ContractLineItem
+// =============================================================================
+//
+// REFERENCE SNIPPET — not a standalone schema. Consumers copy the models into
+// their `schema.prisma` and add FK relations to Tenant/User.
+//
+// V3 rule: billing and entitlement must not depend on live-mutable catalog
+// tables. `SubscriptionContract` and `ContractLineItem` therefore store full
+// snapshots. Catalog FKs are optional and only audit/trace references.
+
+enum SubscriptionContractStatus {
+    active
+    scheduled
+    terminated
+    superseded
+}
+
+enum ContractLineItemKind {
+    plan
+    bundle
+    quota
+    feature
+    discount
+}
+
+model SubscriptionContract {
+    id         String @id @default(uuid())
+    projectKey String
+    tenantId   String
+
+    status         SubscriptionContractStatus @default(active)
+    effectiveFrom  DateTime
+    effectiveUntil DateTime?
+
+    // Optional trace back to the offer/catalog. The contract stays valid even
+    // when these target objects are archived or physically deleted.
+    originalOfferId          String?
+    originalPlanVersionId    String?
+    originalBundleVersionIds Json @default("[]")
+
+    // Full snapshots for runtime, billing, and later display.
+    entitlementSnapshot Json?
+    priceSnapshot       Json
+    promotionSnapshots  Json @default("[]")
+    promoCodeSnapshots  Json @default("[]")
+    termsSnapshot       Json?
+
+    lineItems ContractLineItem[]
+
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+
+    // tenant Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+    @@index([tenantId, status, effectiveFrom])
+    @@index([projectKey, status])
+    @@index([originalOfferId])
+    @@map("subscription_contracts")
+}
+
+model ContractLineItem {
+    id         String @id @default(uuid())
+    contractId String
+
+    kind            ContractLineItemKind
+    sourceKey       String
+    sourceVersionId String?
+
+    titleSnapshot       String
+    descriptionSnapshot String?
+
+    quantity     Int     @default(1)
+    unit         String?
+    priceNet     Decimal @db.Decimal(10, 2)
+    priceGross   Decimal @db.Decimal(10, 2)
+    billingCycle String // monthly | yearly
+
+    minimumTermUntil DateTime?
+
+    featuresSnapshot     Json @default("[]")
+    quotaEffectsSnapshot Json @default("{}")
+    metadata             Json?
+
+    createdAt DateTime @default(now())
+
+    contract SubscriptionContract @relation(fields: [contractId], references: [id], onDelete: Cascade)
+
+    @@index([contractId, kind])
+    @@index([sourceVersionId])
+    @@map("contract_line_items")
+}

package/prisma-fragments/09-pending-registration.prisma

@@ -0,0 +1,96 @@
+// =============================================================================
+// SaaS Platform Prisma fragment: PendingRegistration + PaymentEventLog
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// Persistence of the multi-step registration and onboarding flow
+// (`PendingRegistrationService`). A PendingRegistration holds the
+// intermediate state between step 1 (capturing sign-up data) and the final
+// activation (step 4: payment). Only after successful payment does it become
+// User + Tenant + Subscription — until then the record deliberately stays
+// without a foreign key to consumer models.
+//
+// Unlike the other fragments, WITHOUT `@@map`: the model was adopted back from
+// the reference implementation, whose tables already live under the Prisma
+// default names — a subsequent `@@map` would only force a table rename.
+//
+// Contract: saas-platform-types/registration.types.ts (PendingRegistration,
+//           PendingRegistrationRepository, PaymentEventLog).
+// Service logic: saas-platform-nest/registration/PendingRegistrationService.
+
+// Multi-step registration flow: status of a PendingRegistration
+// between sign-up-data capture (step 1) and final activation
+// after payment (step 4).
+enum RegistrationStatus {
+    PENDING_EMAIL_VERIFICATION
+    EMAIL_VERIFIED
+    PLAN_SELECTED
+    CHECKOUT_STARTED
+    EXPIRED
+    DELETED
+}
+
+model PendingRegistration {
+    id String @id @default(cuid())
+
+    tenantName   String
+    tenantSlug   String?
+    salutation   String?
+    firstName    String
+    lastName     String
+    email        String  @unique
+    passwordHash String
+    locale       String  @default("de")
+
+    status      RegistrationStatus @default(PENDING_EMAIL_VERIFICATION)
+    currentStep Int                @default(2)
+
+    emailVerifiedAt DateTime?
+
+    otpHash       String?
+    otpExpiresAt  DateTime?
+    otpSendCount  Int       @default(1)
+    lastOtpSentAt DateTime?
+    // Persistent failed-attempt counter of the OTP verification. From
+    // OTP_VERIFY_MAX_ATTEMPTS on, verifyOtp() throws OTP_LOCKED — even with
+    // a correct code afterwards. A newly generated OTP resets it to 0
+    // (sending is rate-limited separately via otpSendCount).
+    otpAttemptCount Int @default(0)
+
+    selectedPlanId String?
+    // Configurator selection (Step 3):
+    // - configJson: JSON snapshot of the RegistrationConfigSelection.
+    // - billingCycle: 'MONTHLY' | 'YEARLY' — determines the price calculation.
+    // - appliedPromoCode: last-applied code (plaintext, only for UI display;
+    //   validation runs fresh every time via PromoCodesService).
+    configJson        Json?
+    billingCycle      String?
+    appliedPromoCode  String?
+    checkoutSessionId String?
+    checkoutStartedAt DateTime?
+
+    expiresAt DateTime
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+
+    @@index([status, expiresAt])
+    @@index([tenantSlug])
+}
+
+// PaymentEventLog — idempotency key for payment webhooks.
+// Prevents a doubly delivered webhook (Stripe at-least-once) from triggering
+// the final activation more than once. `eventId` is the provider event ID
+// (Stripe `event.id`), `tryClaim` uses a @unique INSERT as race protection.
+model PaymentEventLog {
+    id          String   @id @default(cuid())
+    eventId     String   @unique
+    provider    String
+    sessionId   String?
+    status      String
+    payload     Json?
+    processedAt DateTime @default(now())
+
+    @@index([sessionId])
+    @@index([status, processedAt])
+}

package/prisma-fragments/README.md

@@ -0,0 +1,115 @@
+---
+doc_title: SaaS Platform Prisma Fragments
+status: living document
+related:
+    - ../schemas/plan-catalog.schema.json
+    - ../schemas/promo-code.schema.json
+    - ../schemas/audit-event.schema.json
+    - ../../saas-platform-types/src/subscription.types.ts
+---
+
+# Prisma Fragments
+
+Reference snippets that document the **canonical database schema** of the SaaS
+platform. Consumer apps copy the models into their own `schema.prisma` and add
+FK relations to their project-specific `Tenant`/`User` models.
+
+## Files
+
+| File                                                                 | Models                                                                                 |
+| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| [`01-subscription.prisma`](01-subscription.prisma)                   | `Subscription`, `SubscriptionPaymentMethod`, `CheckoutOffer` + Enums                   |
+| [`02-promo-code.prisma`](02-promo-code.prisma)                       | `PromoCode`, `PromoCodeRedemption`, `PromoCodeValidationLog` + Enums                   |
+| [`03-plan-versions.prisma`](03-plan-versions.prisma)                 | `Plan`, `PlanVersion`                                                                  |
+| [`04-audit-log.prisma`](04-audit-log.prisma)                         | `AuditLog`                                                                             |
+| [`05-bundle-business-type.prisma`](05-bundle-business-type.prisma)   | `Bundle`, `BundleVersion`, `BusinessType`, `BusinessTypeVersion`, `BusinessTypeBundle` |
+| [`06-catalog-entries.prisma`](06-catalog-entries.prisma)             | `CapabilityCatalogEntry`, `FeatureCatalogEntry`, `MarketingProjection`                 |
+| [`07-promotion.prisma`](07-promotion.prisma)                         | `Promotion`                                                                            |
+| [`08-subscription-contract.prisma`](08-subscription-contract.prisma) | `SubscriptionContract`, `ContractLineItem`                                             |
+| [`09-pending-registration.prisma`](09-pending-registration.prisma)   | `PendingRegistration`, `PaymentEventLog` + `RegistrationStatus`                        |
+
+## How the consumer uses the fragments
+
+Prisma does **not** support real schema merging — there is no include mechanism.
+Consumers must add the models into their own `schema.prisma`. There are two
+pragmatic approaches:
+
+### Variant A — Copy-Paste (recommended)
+
+1. Add the required models from the fragments into your own `schema.prisma`.
+2. Enable the commented-out FK relations to consumer models (`Tenant`, `User`)
+   and adapt them to your own model names.
+3. Plan/feature keys stay as `String` — the source of truth is the set of plans
+   maintained in the SuperAdmin UI (DB) and the feature/quota catalog published
+   via Discovery.
+
+### Variant B — Schema stitching via codegen
+
+Tools such as [`prisma-import`](https://github.com/ajmnz/prisma-import) allow
+include directives; they generate a merged `schema.prisma`. For today's
+single-repo consumers, Variant A is simpler.
+
+## Conventions
+
+### 1. Keys are strings, not enums
+
+`plan` (`Subscription.plan`, `Subscription.pendingPlan`, …) and
+`featureKey` are declared as `String`. The source of truth is the plan master
+records (`plans` table, maintained in the SuperAdmin UI) and the feature catalog
+(`feature_catalog_entries`).
+
+If you prefer **Postgres enums**: declare an enum locally and cast the field
+via `@db.<EnumName>`. Not a platform requirement — the platform services only
+read strings.
+
+### 2. FKs to consumer models are documented but commented out
+
+Fields such as `tenantId String` and `userId String?` remain as plain
+string columns in the fragments; the corresponding `@relation` is left as a
+comment. The consumer enables them using their own `Tenant`/`User` model names.
+
+### 3. Table names (`@@map`) are canonical
+
+`subscriptions`, `plan_versions`, `promo_codes`, `promo_code_redemptions`,
+`promo_code_validation_logs`, `audit_logs`, `bundles`, `bundle_versions`,
+`business_types`, `business_type_versions`, `business_type_bundles`,
+`capability_catalog_entries`, `feature_catalog_entries`,
+`marketing_projections`, `subscription_contracts`, `contract_line_items`.
+Please do **not change** them — otherwise platform migration scripts and the
+`@saasicat/cli` commands that rely on these names will break.
+
+### 4. Decimal precision
+
+All monetary amounts are `Decimal(10, 2)` (max ±99,999,999.99 €), promo-code
+values are `Decimal(8, 2)` (percentage or amount). Consumers should not relax
+this precision.
+
+### 5. Partial unique index for drafts
+
+`PlanVersion`, `BundleVersion`
+and `BusinessTypeVersion` allow **exactly one** draft per
+identity key (`publishedAt IS NULL`). The Prisma schema cannot express this —
+add it in the SQL migration:
+
+```sql
+CREATE UNIQUE INDEX plan_versions_draft_per_plan
+    ON plan_versions (plan_id) WHERE published_at IS NULL;
+```
+
+Likewise for:
+
+- `bundle_versions` (per `bundle_id`)
+- `business_type_versions` (per `business_type_id`)
+
+## Design decisions
+
+- **No fixed quota columns** (`maxUsers`, `maxStorageGb`, …) — limits
+  live generically in `quotas Json`; the allowed keys are declared in code
+  via `@DefinesQuota`.
+- **No `SubscriptionPlan`/`FeatureKey` enums** — both fields are declared
+  as `String` (see Convention 1).
+- **No add-on tables (#49)** — `subscription_addons`,
+  `unit_addon_versions`, `feature_addon_versions` are not a
+  sales surface; only plan versions + bundles are sold.
+- **App-specific tables** (e.g. invoice or bank master data)
+  belong in the schema of the consuming app, not in the platform.

package/schemas/admin-manifest.schema.json

@@ -0,0 +1,328 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://saasicat.dev/schemas/admin-manifest.schema.json",
+    "title": "AdminManifest",
+    "description": "UI discovery projection of a SaaS app. Served by the app backend under GET /api/v1/admin/manifest and consumed by the shared UI shell.",
+    "type": "object",
+    "required": [
+        "schemaVersion",
+        "project",
+        "build",
+        "planCatalogSnapshot",
+        "capabilities",
+        "navigation"
+    ],
+    "additionalProperties": false,
+    "properties": {
+        "schemaVersion": {
+            "type": "integer",
+            "const": 1
+        },
+
+        "project": {
+            "type": "object",
+            "required": ["key", "displayName"],
+            "additionalProperties": false,
+            "properties": {
+                "key": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,30}$" },
+                "displayName": { "type": "string", "minLength": 1, "maxLength": 60 },
+                "label": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 60,
+                    "description": "Tag/subtitle (e.g. \"SuperAdmin\"). From saas.yaml#app.label."
+                },
+                "icon": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 8,
+                    "description": "Short abbreviation for the logo badge (e.g. \"ma\", \"da\"). From saas.yaml#app.icon."
+                },
+                "logoUrl": { "type": "string" },
+                "environment": {
+                    "type": "string",
+                    "enum": ["production", "staging", "development"]
+                },
+                "availableLocales": {
+                    "type": "array",
+                    "items": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" },
+                    "minItems": 1,
+                    "uniqueItems": true,
+                    "description": "Locales allowed by the app catalog (saas.yaml marketing.availableLocales). First = default. SPEC_V2 §6.5."
+                },
+                "defaultLocale": {
+                    "type": "string",
+                    "pattern": "^[a-z]{2}(-[A-Z]{2})?$",
+                    "description": "Default locale; corresponds to availableLocales[0]."
+                }
+            }
+        },
+
+        "build": {
+            "type": "object",
+            "required": ["platformPackageVersion", "appVersion", "manifestHash"],
+            "additionalProperties": false,
+            "properties": {
+                "platformPackageVersion": { "type": "string" },
+                "appVersion": { "type": "string" },
+                "manifestHash": { "type": "string", "pattern": "^sha256-[A-Za-z0-9+/=_-]{32,}$" }
+            }
+        },
+
+        "planCatalogSnapshot": {
+            "type": "object",
+            "required": ["source", "hash", "currency", "vatRate", "plans"],
+            "additionalProperties": false,
+            "properties": {
+                "source": {
+                    "type": "string",
+                    "description": "Path to the source, e.g. 'config/saas.yaml'"
+                },
+                "hash": { "type": "string", "pattern": "^sha256-[A-Za-z0-9+/=_-]{32,}$" },
+                "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
+                "vatRate": { "type": "number", "minimum": 0, "maximum": 100 },
+                "features": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "required": ["key"],
+                        "additionalProperties": false,
+                        "properties": {
+                            "key": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]+$" },
+                            "label": { "type": "string" },
+                            "tier": { "type": "string" }
+                        }
+                    }
+                },
+                "plans": {
+                    "type": "array",
+                    "items": { "$ref": "#/$defs/PlanDef" },
+                    "minItems": 1
+                }
+            }
+        },
+
+        "capabilities": {
+            "type": "object",
+            "description": "Backend capabilities. Naming convention: domain.action or domain.resource.action. Values are boolean (true = active in the build).",
+            "patternProperties": {
+                "^[a-z][a-zA-Z0-9]*\\.[a-z][a-zA-Z0-9]*(?:\\.[a-z][a-zA-Z0-9]*)?$": {
+                    "type": "boolean"
+                }
+            },
+            "additionalProperties": false
+        },
+
+        "navigation": {
+            "type": "object",
+            "required": ["standardPages"],
+            "additionalProperties": false,
+            "properties": {
+                "standardPages": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "dashboard": { "$ref": "#/$defs/StandardPageDef" },
+                        "tenants": { "$ref": "#/$defs/StandardPageDef" },
+                        "subscriptions": { "$ref": "#/$defs/StandardPageDef" },
+                        "promoCodes": { "$ref": "#/$defs/StandardPageDef" },
+                        "plans": { "$ref": "#/$defs/StandardPageDef" },
+                        "planVersions": { "$ref": "#/$defs/StandardPageDef" },
+                        "audit": { "$ref": "#/$defs/StandardPageDef" },
+                        "users": { "$ref": "#/$defs/StandardPageDef" },
+                        "pilots": { "$ref": "#/$defs/StandardPageDef" },
+                        "discovery": { "$ref": "#/$defs/StandardPageDef" },
+                        "bundles": { "$ref": "#/$defs/StandardPageDef" },
+                        "businessTypes": { "$ref": "#/$defs/StandardPageDef" },
+                        "marketingCatalog": { "$ref": "#/$defs/StandardPageDef" },
+                        "platformEmail": { "$ref": "#/$defs/StandardPageDef" },
+                        "platformEmailHistory": { "$ref": "#/$defs/StandardPageDef" }
+                    }
+                },
+                "projectPages": {
+                    "type": "array",
+                    "items": { "$ref": "#/$defs/ProjectPageDef" }
+                }
+            }
+        },
+
+        "dashboard": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "kpiCards": {
+                    "type": "array",
+                    "items": { "$ref": "#/$defs/KpiCardDef" }
+                }
+            }
+        },
+
+        "tenants": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "columns": {
+                    "type": "array",
+                    "items": { "$ref": "#/$defs/TenantColumnDef" }
+                },
+                "actions": {
+                    "type": "array",
+                    "items": { "$ref": "#/$defs/TenantActionDef" }
+                }
+            }
+        },
+
+        "audit": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "actions": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "required": ["key", "label"],
+                        "additionalProperties": false,
+                        "properties": {
+                            "key": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]+$" },
+                            "label": { "type": "string" },
+                            "severity": {
+                                "type": "string",
+                                "enum": ["info", "low", "medium", "high"]
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    },
+
+    "$defs": {
+        "CapabilityKey": {
+            "type": "string",
+            "pattern": "^[a-z][a-zA-Z0-9]*\\.[a-z][a-zA-Z0-9]*(?:\\.[a-z][a-zA-Z0-9]*)?$"
+        },
+
+        "StandardPageDef": {
+            "type": "object",
+            "required": ["enabled"],
+            "additionalProperties": false,
+            "properties": {
+                "enabled": { "type": "boolean" },
+                "requiredCapability": { "$ref": "#/$defs/CapabilityKey" }
+            }
+        },
+
+        "ProjectPageDef": {
+            "type": "object",
+            "required": ["id", "label", "route", "componentKey"],
+            "additionalProperties": false,
+            "properties": {
+                "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]+\\.[a-z][a-zA-Z0-9-]*$" },
+                "label": { "type": "string", "minLength": 1 },
+                "icon": { "type": "string" },
+                "route": { "type": "string", "pattern": "^/[A-Za-z0-9-/]+$" },
+                "navSection": { "type": "string" },
+                "componentKey": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9-]+\\.[a-z][a-zA-Z0-9-]*$"
+                },
+                "requiredCapability": { "$ref": "#/$defs/CapabilityKey" },
+                "prefetchOnIdle": { "type": "boolean", "default": false }
+            }
+        },
+
+        "KpiCardDef": {
+            "type": "object",
+            "required": ["id", "label", "endpoint", "displayHint"],
+            "additionalProperties": false,
+            "properties": {
+                "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]+\\.[a-z][a-zA-Z0-9.-]*$" },
+                "label": { "type": "string", "minLength": 1 },
+                "endpoint": {
+                    "type": "string",
+                    "pattern": "^/api(/v[0-9]+)?/admin/(extras|dashboard)/"
+                },
+                "displayHint": {
+                    "type": "object",
+                    "required": ["type"],
+                    "additionalProperties": false,
+                    "properties": {
+                        "type": {
+                            "type": "string",
+                            "enum": ["value", "value+timestamp", "value+spark8w", "value+delta"]
+                        },
+                        "icon": { "type": "string" }
+                    }
+                },
+                "slotPriority": { "type": "integer", "minimum": 0, "maximum": 100 },
+                "requiredCapability": { "$ref": "#/$defs/CapabilityKey" }
+            }
+        },
+
+        "TenantColumnDef": {
+            "type": "object",
+            "required": ["key", "label", "endpoint"],
+            "additionalProperties": false,
+            "properties": {
+                "key": { "type": "string", "pattern": "^[a-z][a-zA-Z0-9]*$" },
+                "label": { "type": "string", "minLength": 1 },
+                "endpoint": {
+                    "type": "string",
+                    "pattern": "^/api(/v[0-9]+)?/admin/extras/[A-Za-z0-9/-]+$",
+                    "not": { "pattern": "\\{slug\\}|\\{tenantId\\}" },
+                    "description": "Required: batch-capable endpoint, no tenant slug in the path. UI calls it with ?tenantIds=... See SPEC §4.4.1."
+                },
+                "requiredCapability": { "$ref": "#/$defs/CapabilityKey" }
+            }
+        },
+
+        "TenantActionDef": {
+            "type": "object",
+            "required": ["id", "label", "actionKey"],
+            "additionalProperties": false,
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9-]+(?:\\.[a-z][a-zA-Z0-9-]*)+$"
+                },
+                "label": { "type": "string", "minLength": 1 },
+                "actionKey": {
+                    "$ref": "#/$defs/CapabilityKey",
+                    "description": "Lookup in the frontend action registry. NO endpoint/method here."
+                },
+                "requiredCapability": { "$ref": "#/$defs/CapabilityKey" },
+                "requiresMfa": { "type": "boolean" },
+                "confirmType": {
+                    "type": "string",
+                    "enum": ["none", "simple", "typed-slug", "typed-production", "date"]
+                }
+            }
+        },
+
+        "PlanDef": {
+            "type": "object",
+            "required": ["id", "quotas", "features"],
+            "additionalProperties": false,
+            "properties": {
+                "id": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]+$" },
+                "name": { "type": "string" },
+                "tagline": { "type": "string" },
+                "marketed": { "type": "boolean", "default": true },
+                "popular": { "type": "boolean", "default": false },
+                "monthlyNet": { "type": ["number", "null"], "minimum": 0 },
+                "yearlyNet": { "type": ["number", "null"], "minimum": 0 },
+                "quotas": {
+                    "type": "object",
+                    "patternProperties": {
+                        "^[a-z][A-Za-z0-9]*$": { "type": "integer" }
+                    },
+                    "additionalProperties": false
+                },
+                "features": {
+                    "type": "array",
+                    "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]+$" }
+                }
+            }
+        }
+    }
+}