@saasicat/spec 1.0.0-rc.2 → 1.0.0-rc.21

package/prisma-fragments/11-subscription-bundle.prisma

@@ -29,6 +29,23 @@ model SubscriptionBundle {
     // only at `minimumTermEndsAt`.
     minimumTermEndsAt DateTime?
 
+    // The rhythm this booking is billed in, and the window it is billed for.
+    //
+    // A bundle may run in a shorter rhythm than its plan but never a longer
+    // one, so a yearly bundle exists only beside a yearly plan. Its periods end
+    // on the day the plan's do: the first one is short, from the booking to the
+    // next occurrence of that day, and every one after it runs anchor to
+    // anchor. Aligned at booking rather than trimmed at the end, because a trim
+    // means somebody was committed to more than they received.
+    //
+    // Null on a booking made before these columns existed, and on one whose
+    // plan has no period at all — a trial, or a subscription awaiting sales.
+    // Readers fall back to the plan's cycle, which is what every booking used
+    // before this.
+    billingCycle       String?
+    currentPeriodStart DateTime?
+    currentPeriodEnd   DateTime?
+
     // Cancellation: requested at `canceledAt`, effective at
     // `canceledEffectiveAt` (period/term end). Both null = active booking.
     canceledAt          DateTime?

package/prisma-fragments/12-applied-settings.prisma

@@ -0,0 +1,55 @@
+// =============================================================================
+// SaaS-Platform Prisma fragment: the applied settings, and their changes
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// `config/saas.yaml` says what should be true. These two tables say what IS
+// true: the settings the installation applied at its last start, and every
+// start that found them changed. The platform writes both at boot and reads
+// them for the read-only settings screen — and for nothing else. The record is
+// a mirror of the file, never a source: no setting is ever read out of it.
+//
+// One row per installation. An installation serves one application and owns
+// its database (see docs/explanation/data-model.md), so the row's identity is
+// the installation's, and a constant primary key is what expresses that. The
+// `CHECK` in sql/constraints.postgres.sql is what holds it to one row; the
+// default only lands a caller that omits the id on the right one.
+
+model AppliedSettings {
+    id          String   @id @default("installation")
+    // `sha256-<hex>` over the canonical JSON of `settings`.
+    fingerprint String
+    // The resolved settings subtree of the catalogue — everything but the
+    // plans and features, with environment references already substituted.
+    settings    Json
+    // The absolute path of the file, or the phrase saying they came in as code.
+    source      String
+    // When these values became the running configuration. Left alone by a
+    // start that finds them unchanged.
+    appliedAt   DateTime
+
+    @@map("applied_settings")
+}
+
+model SettingsChange {
+    id             String    @id @default(uuid())
+    // The order the changes were recorded in, numbered by the database at the
+    // write that recorded each one, and the order the list is read in. Not
+    // `noticedAt`: that is the recording start's own clock, and a start delayed
+    // between reading it and writing would be listed before a move that landed
+    // earlier. Never set by the platform.
+    seq            Int       @unique @default(autoincrement())
+    // The start that found the fingerprint moved.
+    noticedAt      DateTime
+    source         String
+    previous       Json
+    current        Json
+    // Null while an operator still owes it a look.
+    acknowledgedAt DateTime?
+    // An actor tag, as the audit log writes it.
+    acknowledgedBy String?
+
+    @@index([acknowledgedAt, noticedAt])
+    @@map("settings_changes")
+}

package/prisma-fragments/13-subscriber.prisma

@@ -0,0 +1,94 @@
+// =============================================================================
+// SaaS platform Prisma fragment: Subscriber, its tenants, its corrections
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// A tenant is where the application keeps a customer's data. The subscriber is
+// the party the contract is with: a customer number and the master data a
+// contract names. A tenant can be deleted; its subscriber stays for as long as
+// a document that has to be kept belongs to it (ADR 0012). That is why nothing
+// here points at the application's `Tenant` model with a cascade — the link
+// below names the tenant as a value and stays after the tenant row is gone.
+//
+// Every model carries `Subscriber` in its name, so it cannot collide with a
+// `Customer` an application already keeps for the people it sells to.
+
+model Subscriber {
+    id String @id @default(uuid())
+
+    // The customer number, counted per installation. The number orders; the
+    // prefix is the one `config/saas.yaml` named when the subscriber was
+    // created, kept beside it so a later prefix renames nobody. Counting starts
+    // at 10001 (sql/constraints.postgres.sql), so numbers have five digits long
+    // before they need a sixth.
+    customerSequence     Int    @unique @default(autoincrement())
+    customerNumberPrefix String @default("")
+
+    // The legal identity. Only the name is required until invoicing requires
+    // the rest; under a running contract these change only as a correction,
+    // recorded in `SubscriberCorrection`.
+    legalName String
+    vatId     String?
+    taxNumber String?
+
+    // Contact details, which change at any time.
+    addressLine1 String?
+    addressLine2 String?
+    postalCode   String?
+    city         String?
+    country      String? // ISO 3166-1 alpha-2
+    invoiceEmail String?
+
+    // Created by the migration that gave every existing tenant its subscriber,
+    // from the application's own tenant record.
+    migrated Boolean @default(false)
+
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+
+    tenants        SubscriberTenant[]
+    corrections    SubscriberCorrection[]
+    contracts      SubscriptionContract[]
+    paymentMethods      SubscriberPaymentMethod[] // see 14-payments.prisma
+    paymentMethodSetups SubscriberPaymentMethodSetup[]
+
+    @@map("subscribers")
+}
+
+// Which tenant a subscriber is live for, and which it was before. A subscriber
+// has at most one live tenant and a tenant at most one live subscriber — two
+// partial unique indexes in sql/constraints.postgres.sql, which Prisma cannot
+// express. `unlinkedAt` stays null while the link is live.
+model SubscriberTenant {
+    id           String    @id @default(uuid())
+    subscriberId String
+    tenantId     String
+    linkedAt     DateTime  @default(now())
+    unlinkedAt   DateTime?
+
+    subscriber Subscriber @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
+
+    @@index([tenantId])
+    @@index([subscriberId])
+    @@map("subscriber_tenants")
+}
+
+// A correction of a subscriber's legal identity: the values it replaced, the
+// values it wrote, why, and who made it. Only the fields that moved are in the
+// two JSON objects. Written in the same transaction as the change, and never
+// rewritten.
+model SubscriberCorrection {
+    id           String   @id @default(uuid())
+    subscriberId String
+    previous     Json
+    corrected    Json
+    reason       String
+    correctedBy  String
+    correctedAt  DateTime
+
+    subscriber Subscriber @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
+
+    @@index([subscriberId, correctedAt])
+    @@map("subscriber_corrections")
+}

package/prisma-fragments/14-payments.prisma

@@ -0,0 +1,108 @@
+// =============================================================================
+// SaaS platform Prisma fragment: SubscriberPaymentMethod, its setups, PaymentEventLog
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// How a subscriber pays, as the payment gateway's reference to it. The card
+// number or the IBAN never reaches this table: the person enters them in the
+// gateway's own form, and what is kept is the gateway's reference and the
+// masked details that tell one payment method from another (ADR 0012).
+//
+// A reference means something only to the gateway account that issued it —
+// the merchant account named in `config/saas.yaml#payments.accounts` — so
+// every row records that account. A subscriber has at most one `ACTIVE`
+// payment method, a partial unique index in sql/constraints.postgres.sql;
+// the one a newer payment method replaced stays as `REPLACED`.
+//
+// Within an account a reference belongs to exactly one subscriber, which is
+// what `@@unique([gatewayAccount, paymentMethodRef])` below holds. The port
+// draws the same boundary for reading: a confirmation carrying a reference
+// another subscriber holds is refused rather than recorded, and a read by
+// reference names the subscriber it asks about. Both are reached on the
+// gateway's callback, which arrives without a session — an installation that
+// keeps its tenants apart with a policy on this table lifts it there.
+//
+// Contract: @saasicat/core (SubscriberPaymentMethodRepository, PaymentEventLog).
+// Both are needed wherever payment methods are taken — self-registration or
+// not — because every gateway callback is claimed in `PaymentEventLog`.
+
+model SubscriberPaymentMethod {
+    id           String @id @default(uuid())
+    subscriberId String
+
+    // The account the references below belong to, and its provider when the
+    // payment method was confirmed.
+    gatewayAccount   String
+    provider         String
+    customerRef      String
+    paymentMethodRef String
+
+    // What tells the payment method apart, never enough to pay with it.
+    type             String // card | sepa_debit
+    brand            String?
+    last4            String
+    expiryMonth      Int?
+    expiryYear       Int?
+    country          String? // ISO 3166-1 alpha-2
+    bankCode         String?
+    mandateReference String?
+
+    status      String    @default("ACTIVE") // ACTIVE | REPLACED
+    confirmedAt DateTime
+    replacedAt  DateTime?
+    createdAt   DateTime  @default(now())
+
+    subscriber Subscriber @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
+
+    @@unique([gatewayAccount, paymentMethodRef])
+    @@index([subscriberId, status])
+    @@index([gatewayAccount, status])
+    @@map("subscriber_payment_methods")
+}
+
+// A change of payment method a tenant started: the gateway session opened for
+// the subscriber. A confirmation is recorded only against the setup whose
+// account, session and subscriber it names, and completes it on the same
+// transaction — so a callback naming another subscriber than the session was
+// opened for changes nobody's payment method. A setup nobody finishes stays
+// open; it holds no reference that could be charged.
+model SubscriberPaymentMethodSetup {
+    id             String    @id @default(uuid())
+    subscriberId   String
+    gatewayAccount String
+    sessionRef     String
+    customerRef    String
+    startedAt      DateTime  @default(now())
+    completedAt    DateTime?
+
+    subscriber Subscriber @relation(fields: [subscriberId], references: [id], onDelete: Restrict)
+
+    @@unique([gatewayAccount, sessionRef])
+    @@index([subscriberId])
+    @@map("subscriber_payment_method_setups")
+}
+
+// PaymentEventLog — every payment gateway event, handled once.
+// Gateways deliver at least once. An event is claimed on the transaction that
+// writes what it changes, so a retry after a rollback is handled and a retry
+// after a commit finds the claim. `eventId` is unique only within the gateway
+// account that sent it — two accounts side by side never take each other's
+// event for a duplicate. `status` holds the event's kind as SaaSiCat read it
+// (`payment-method-confirmed`, …) and `payload` a summary that names no person.
+// One session is confirmed once, however many events report it: a partial
+// unique index in sql/constraints.postgres.sql, where the reasoning is.
+model PaymentEventLog {
+    id             String   @id @default(cuid())
+    gatewayAccount String
+    eventId        String
+    provider       String
+    sessionId      String?
+    status         String
+    payload        Json?
+    processedAt    DateTime @default(now())
+
+    @@unique([gatewayAccount, eventId])
+    @@index([sessionId])
+    @@index([status, processedAt])
+}

package/prisma-fragments/README.md

@@ -11,7 +11,7 @@ related:
 # Prisma Fragments
 
 Prisma-DSL rendering of the SaaSiCat data model, **derived from the normative
-sources**: the logical data model in [`docs/data-model.md`](../../../docs/data-model.md)
+sources**: the logical data model in [`docs/explanation/data-model.md`](../../../docs/explanation/data-model.md)
 and the PostgreSQL artifacts in [`../sql/`](../sql/)
 (`reference-schema.postgres.sql` is generated FROM these fragments via
 `pnpm run gen:sql`; `constraints.postgres.sql` carries the invariants Prisma
@@ -28,19 +28,22 @@ regenerated after fragment changes (`tests/reference-sql-drift.test.js`).
 
 ## 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.prisma`](05-bundle.prisma)                               | `Bundle`, `BundleVersion`                                            |
-| [`06-catalog-entries.prisma`](06-catalog-entries.prisma)             | Capability, feature, quota and marketing catalog models              |
-| [`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`      |
-| [`10-super-admin.prisma`](10-super-admin.prisma)                     | `SuperAdminUser`, `SuperAdminMfa`                                    |
-| [`11-subscription-bundle.prisma`](11-subscription-bundle.prisma)     | `SubscriptionBundle`                                                 |
+| File                                                                 | Models                                                                                |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| [`01-subscription.prisma`](01-subscription.prisma)                   | `Subscription`, `CheckoutOffer` + Enums                                               |
+| [`02-promo-code.prisma`](02-promo-code.prisma)                       | `PromoCode`, `PromoCodeRedemption`, `PromoCodeHold`, `PromoCodeValidationLog` + Enums |
+| [`03-plan-versions.prisma`](03-plan-versions.prisma)                 | `Plan`, `PlanVersion`                                                                 |
+| [`04-audit-log.prisma`](04-audit-log.prisma)                         | `AuditLog`                                                                            |
+| [`05-bundle.prisma`](05-bundle.prisma)                               | `Bundle`, `BundleVersion`                                                             |
+| [`06-catalog-entries.prisma`](06-catalog-entries.prisma)             | Capability, feature, quota and marketing catalog models                               |
+| [`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` + `RegistrationStatus`                                          |
+| [`10-super-admin.prisma`](10-super-admin.prisma)                     | `SuperAdminUser`, `SuperAdminMfa`                                                     |
+| [`11-subscription-bundle.prisma`](11-subscription-bundle.prisma)     | `SubscriptionBundle`                                                                  |
+| [`12-applied-settings.prisma`](12-applied-settings.prisma)           | `AppliedSettings`, `SettingsChange`                                                   |
+| [`13-subscriber.prisma`](13-subscriber.prisma)                       | `Subscriber`, `SubscriberTenant`, `SubscriberCorrection`                              |
+| [`14-payments.prisma`](14-payments.prisma)                           | `SubscriberPaymentMethod`, `SubscriberPaymentMethodSetup`, `PaymentEventLog`          |
 
 ## How the consumer uses the fragments
 
@@ -82,16 +85,24 @@ 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.
 
+Two models deliberately carry no such pointer: `SubscriptionContract` and
+`SubscriberTenant`. A contract belongs to its subscriber and outlives the tenant
+it was concluded for, so its `tenantId` is a trace — a cascade from the tenant
+would delete the tax record with it, and a restriction would keep the tenant
+from ever being deleted.
+
 ### 3. Table names (`@@map`) are canonical
 
-`subscriptions`, `subscription_payment_methods`, `checkout_offers`, `plans`,
-`plan_versions`, `promo_codes`, `promo_code_redemptions`,
-`promo_code_validation_logs`, `audit_logs`, `bundles`, `bundle_versions`,
-`capability_catalog_entries`, `feature_catalog_entries`,
+`subscriptions`, `checkout_offers`, `plans`, `plan_versions`, `promo_codes`,
+`promo_code_redemptions`, `promo_code_holds`, `promo_code_validation_logs`, `audit_logs`, `bundles`,
+`bundle_versions`, `capability_catalog_entries`, `feature_catalog_entries`,
 `quota_catalog_entries`, `marketing_projections`, `marketing_settings`,
 `promotions`, `subscription_contracts`, `contract_line_items`,
-`pending_registrations`, `payment_event_logs`, `super_admin_users`,
-`super_admin_mfa`, `subscription_bundles`.
+`super_admin_users`, `super_admin_mfa`, `subscription_bundles`, `subscribers`,
+`subscriber_tenants`, `subscriber_corrections`, `subscriber_payment_methods`,
+`subscriber_payment_method_setups`.
+`PendingRegistration` and `PaymentEventLog` carry no `@@map` and keep Prisma's
+default names, `"PendingRegistration"` and `"PaymentEventLog"`.
 Please do **not change** them — otherwise platform migration scripts and the
 `@saasicat/cli` commands that rely on these names will break.
 
@@ -124,5 +135,12 @@ CREATE UNIQUE INDEX plan_versions_draft_per_plan
 - **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.
+- **The application's own invoicing** — invoices to the people it sells to, fees
+  it collects from its members, their bank details — belongs in the schema of the
+  consuming app. The subscription business is the platform's: subscribers, their
+  invoices and their payments are decided in
+  [ADR 0012](../../../docs/explanation/adr/0012-the-subscriber-owns-the-commercial-record.md),
+  and every model added for them carries `Subscription` or `Subscriber` in its name,
+  which keeps it clear of the names applications use for their own invoicing. A
+  prefix cannot rule out a name nobody has seen, so `saasicat schema check` reports
+  an application model that carries a platform model's name with a different shape.

package/schemas/admin-manifest.schema.json

@@ -76,11 +76,17 @@
             "properties": {
                 "source": {
                     "type": "string",
-                    "description": "Path to the source, e.g. 'config/saas.yaml'"
+                    "description": "Where the plans and features were read from: 'database' for the ones an operator publishes, 'given' for a catalogue passed in at start"
                 },
                 "hash": { "type": "string", "pattern": "^sha256-[A-Za-z0-9+/=_-]{32,}$" },
                 "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
-                "vatRate": { "type": "number", "minimum": 0, "maximum": 100 },
+                "vatRate": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 100,
+                    "not": { "exclusiveMinimum": 0, "exclusiveMaximum": 1 },
+                    "description": "VAT rate as a percentage: 19 means 19 %."
+                },
                 "features": {
                     "type": "array",
                     "items": {
@@ -134,7 +140,8 @@
                         "bundles": { "$ref": "#/$defs/StandardPageDef" },
                         "marketingCatalog": { "$ref": "#/$defs/StandardPageDef" },
                         "platformEmail": { "$ref": "#/$defs/StandardPageDef" },
-                        "platformEmailHistory": { "$ref": "#/$defs/StandardPageDef" }
+                        "platformEmailHistory": { "$ref": "#/$defs/StandardPageDef" },
+                        "settings": { "$ref": "#/$defs/StandardPageDef" }
                     }
                 },
                 "projectPages": {