@saasicat/spec 0.2.0

package/cli-conventions.md

@@ -0,0 +1,158 @@
+---
+doc_title: SaaS Platform CLI Conventions
+status: spec
+date: 2026-05-08
+related:
+    - admin-api.openapi.yaml
+    - schemas/audit-event.schema.json
+---
+
+# CLI Conventions
+
+Binding conventions for every consumer-specific CLI that serves the
+SaaS platform services (each app picks its own binary name,
+e.g. `myapp`). Embedded platform commands (`@saasicat/cli`) follow
+the same rules; consumer-specific plugin commands are required to inherit
+them.
+
+## 1. Identity
+
+Every writing CLI invocation needs a **unique actor identity**
+for the audit log:
+
+- **Env var** with an app-specific prefix (e.g. `MYAPP_ADMIN_EMAIL`)
+  or the generic `SAAS_ADMIN_EMAIL` as the platform default.
+- **Flag** `--as <email>` overrides the env var ad hoc (e.g. when
+  several SUPER_ADMINs share the same shell).
+- Without an identity → writing commands are rejected with exit code `2`
+  (see §6).
+
+Read commands (e.g. `… mandant list`) are allowed without an identity, but
+write `actor=anonymous` to the local log.
+
+## 2. Mandatory MFA for Critical Operations
+
+The following operations **MUST** prompt for a TOTP code
+(Google Authenticator) before execution:
+
+- `… paket apply` (PlanCatalog mutation)
+- `… pilot create|grant|revoke` (pilot override)
+- `… mandant suspend|impersonate` (tenant security operations)
+- `… plan-version publish` (PlanVersion publication)
+- `… user reassign-admin` (last-admin escalation)
+- `… admin mfa-reset` (MFA reset of another SUPER_ADMIN)
+
+Setup via `… admin mfa-setup` (generates a secret, shows a QR code, persists
+`MfaPort.setSecret`). Without MFA setup → the first critical invocation forces
+setup. Wrong code → exit code `3`.
+
+`isMfaSetupRequired` and `verifyMfaCode` are passed through via the platform
+`MfaPort` interface (see `@saasicat/types/ports.types.ts`)
+— consumers implement the persistence.
+
+## 3. Production Confirm
+
+When the CLI runs against a **production environment** (default: anything that
+is not `NODE_ENV=development` and not a localhost DB), every
+writing command must be confirmed interactively:
+
+```text
+? Tippe production zur Bestätigung: production
+```
+
+- Alternative: `--yes` / `-y` skips the confirmation (for CI/CD).
+- Plus `--dry-run` is the default for destructive commands like
+  `… paket apply` and `… rabatt delete`. Only `--apply` or
+  `--yes` applies.
+
+`production` detection should run through the consumer's implementation of the
+`isProductionEnvironment()` helper function (the consumer checks the
+`DATABASE_URL` host, `process.env.APP_ENV`, etc.).
+
+## 4. Output Formats
+
+Every command supports three output formats via `--output / -o`:
+
+- `--output=table` (default) — human-readable ASCII table.
+- `--output=json` — structured JSON (for `jq` pipelines, CI scripts).
+- `--output=plain` — one line per record, tab-separated (for
+  `awk`/`cut` pipelines).
+
+Error output goes to `stderr`, data output to `stdout` — pipe-stable.
+
+## 5. Mandatory Audit
+
+Every writing operation **MUST** create an `AuditLog` entry with the following
+required fields (see `schemas/audit-event.schema.json`):
+
+- `action` — SCREAMING_SNAKE_CASE (`PROMO_CODE_CREATED`, `PILOT_GRANTED`,
+  `PLAN_CATALOG_UPDATE`, …).
+- `entity` + `entityId` — the changed object.
+- `userId` — resolvable from `--as` / env var via `UserPort.findByEmail`.
+- `changes` — before/after diff for mutations (Ajv-validated via the
+  schema).
+
+Consumers may define their own `action` values, but must keep the
+SCREAMING_SNAKE_CASE pattern and declare them in the audit catalog of the
+respective ManifestContribution.
+
+## 6. Exit Codes
+
+Binding exit codes — consumer CLIs **must not**
+redefine them, because cron/CI scripts pattern-match on them:
+
+| Code | Meaning                                                                                                                              |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| 0    | Success (including dry-run with no changes)                                                                                          |
+| 1    | User error (wrong argument, missing required field, validation error)                                                                |
+| 2    | Identity/auth error (no email, invalid user, not a SUPER_ADMIN)                                                                      |
+| 3    | MFA error (wrong TOTP code, MFA setup missing)                                                                                       |
+| 4    | Connectivity error (DB unreachable, sidecar service down)                                                                            |
+| 5    | Permission error (user is not allowed to perform this operation — e.g. a SUPER_ADMIN operation, but the user is only a TENANT_ADMIN) |
+| 6    | Conflict (optimistic-lock mismatch, idempotency violation)                                                                           |
+| 7    | Drift detected (e.g. `paket diff` finds differences; `manifest check` finds inconsistencies)                                         |
+| 99   | Internal error (uncaught exception, bug reports welcome)                                                                             |
+
+Read commands return `0` even for an empty result set (no drift =
+no error). Drift-detection commands (`paket diff`, `manifest check`)
+return `7` when drift is found — CI gates can react to that.
+
+## 7. Consumer Plugin API
+
+The platform CLI loads consumer plugins via the `extensions:` field of the
+ManifestContribution. Each plugin registers its own commands
+under its own namespace (`extras:`, `billing:`, or similar).
+
+Plugin commands automatically inherit:
+
+- identity resolution (§1)
+- MFA enforcement (§2 — the plugin author marks a command as `requireMfa: true`)
+- production confirm (§3 — automatic when `mutates: true`)
+- output format flags (§4)
+- audit logging (§5 — the plugin supplies `action` + `entity` stub, the platform writes the rest)
+- exit codes (§6 — the plugin throws `CliError` subclasses)
+
+## 8. Example Workflow
+
+```bash
+# Read operation, no identity required
+$ myapp mandant list --output=json | jq '.[] | select(.status=="ACTIVE")'
+
+# Writing with identity, dry-run as default
+$ myapp paket apply config/plans.yaml
+ℹ Diff: 2 Pläne aktualisiert, 1 Bundle neu.
+ℹ Dry-run — nutze --apply zum Schreiben.
+
+# Writing with mandatory MFA
+$ myapp paket apply config/plans.yaml --apply
+ℹ Erfordert MFA-Bestätigung.
+? TOTP-Code: 482 159
+✓ PlanCatalog aktualisiert. AuditLog: PLAN_CATALOG_UPDATE.
+
+# Production confirm
+$ NODE_ENV=production myapp pilot grant pilot-schmidt --as=admin@example.com
+? Tippe production zur Bestätigung: production
+ℹ Erfordert MFA-Bestätigung.
+? TOTP-Code: 217 998
+✓ Pilot-Grant gespeichert.
+```

package/index.cjs

@@ -0,0 +1,18 @@
+// @saasicat/spec — CommonJS-Entrypoint
+const adminManifestSchema = require('./schemas/admin-manifest.schema.json');
+const planCatalogSchema = require('./schemas/plan-catalog.schema.json');
+const promoCodeSchema = require('./schemas/promo-code.schema.json');
+const auditEventSchema = require('./schemas/audit-event.schema.json');
+
+module.exports = {
+    adminManifestSchema,
+    planCatalogSchema,
+    promoCodeSchema,
+    auditEventSchema,
+    SCHEMAS: {
+        adminManifest: adminManifestSchema,
+        planCatalog: planCatalogSchema,
+        promoCode: promoCodeSchema,
+        auditEvent: auditEventSchema,
+    },
+};

package/index.d.cts

@@ -0,0 +1,13 @@
+// @saasicat/spec — TS-Definitionen für CommonJS-Konsumenten.
+
+export declare const adminManifestSchema: Record<string, unknown>;
+export declare const planCatalogSchema: Record<string, unknown>;
+export declare const promoCodeSchema: Record<string, unknown>;
+export declare const auditEventSchema: Record<string, unknown>;
+
+export declare const SCHEMAS: {
+    readonly adminManifest: Record<string, unknown>;
+    readonly planCatalog: Record<string, unknown>;
+    readonly promoCode: Record<string, unknown>;
+    readonly auditEvent: Record<string, unknown>;
+};

package/index.d.ts

@@ -0,0 +1,14 @@
+// @saasicat/spec — TS definitions for the schema export.
+// Schemas are loaded at runtime as JSON; this is only the type shell.
+
+export declare const adminManifestSchema: Record<string, unknown>;
+export declare const planCatalogSchema: Record<string, unknown>;
+export declare const promoCodeSchema: Record<string, unknown>;
+export declare const auditEventSchema: Record<string, unknown>;
+
+export declare const SCHEMAS: {
+    readonly adminManifest: Record<string, unknown>;
+    readonly planCatalog: Record<string, unknown>;
+    readonly promoCode: Record<string, unknown>;
+    readonly auditEvent: Record<string, unknown>;
+};

package/index.js

@@ -0,0 +1,17 @@
+// @saasicat/spec — ESM entrypoint
+// Exports all JSON schemas of the platform.
+// Consumed by Nest and (prospectively) Django implementations
+// as well as by CI tools (`<app> manifest check`) that validate against the schemas.
+import adminManifestSchema from './schemas/admin-manifest.schema.json' with { type: 'json' };
+import planCatalogSchema from './schemas/plan-catalog.schema.json' with { type: 'json' };
+import promoCodeSchema from './schemas/promo-code.schema.json' with { type: 'json' };
+import auditEventSchema from './schemas/audit-event.schema.json' with { type: 'json' };
+
+export { adminManifestSchema, planCatalogSchema, promoCodeSchema, auditEventSchema };
+
+export const SCHEMAS = {
+    adminManifest: adminManifestSchema,
+    planCatalog: planCatalogSchema,
+    promoCode: promoCodeSchema,
+    auditEvent: auditEventSchema,
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@saasicat/spec",
+  "version": "0.2.0",
+  "description": "Language-neutral spec of the SaaS platform: JSON Schemas, OpenAPI contract, Prisma fragments, acceptance scenarios.",
+  "type": "module",
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      },
+      "require": {
+        "types": "./index.d.cts",
+        "default": "./index.cjs"
+      }
+    },
+    "./schemas/*.json": "./schemas/*.json",
+    "./prisma-fragments/*.prisma": "./prisma-fragments/*.prisma",
+    "./prisma-fragments/": "./prisma-fragments/"
+  },
+  "files": [
+    "index.js",
+    "index.cjs",
+    "index.d.ts",
+    "index.d.cts",
+    "schemas/",
+    "admin-api.openapi.yaml",
+    "cli-conventions.md",
+    "acceptance/",
+    "prisma-fragments/"
+  ],
+  "devDependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  },
+  "keywords": [
+    "saas",
+    "platform",
+    "json-schema",
+    "openapi",
+    "saasicat"
+  ],
+  "license": "Apache-2.0",
+  "author": "Taci Uelker",
+  "homepage": "https://github.com/uelker70/saasicat",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uelker70/saasicat.git",
+    "directory": "packages/saas-platform-spec"
+  },
+  "bugs": {
+    "url": "https://github.com/uelker70/saasicat/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test tests/schemas.test.js"
+  }
+}

package/prisma-fragments/01-subscription.prisma

@@ -0,0 +1,216 @@
+// =============================================================================
+// SaaS-Platform Prisma fragment: Subscription + Payment method
+// =============================================================================
+//
+// REFERENCE SNIPPET — not a standalone schema. Consumers copy
+// models into their `schema.prisma` and adapt the FK relations to their own
+// `Tenant`/`User` models.
+//
+// Conventions:
+//   - Plan/feature keys as `String` — source of truth is the
+//     consumer's `config/plans.yaml`, validated via
+//     `@saasicat/spec/schemas/plan-catalog.schema.json`.
+//     Whoever prefers Postgres enums can declare an enum locally and
+//     cast the field via `@db.<EnumName>` — not a platform requirement.
+//   - FK columns to consumer models are declared as `String` with a
+//     commented-out example relation. The consumer adds the `@relation`
+//     with their own `Tenant`/`User` model.
+//   - `@@map` names are the canonical table names — please do not
+//     change them, otherwise the shared migration path breaks in P1.5+.
+//
+// Accompanying fragments:
+//   - 03-plan-versions.prisma  (PlanVersion — referenced here)
+//   - 02-promo-code.prisma     (PromoCodeRedemption has 1:1 to Subscription)
+
+// -----------------------------------------------------------------------------
+// Universal enums — project-independent, identical in every consumer.
+// -----------------------------------------------------------------------------
+
+enum BillingCycle {
+    MONTHLY
+    YEARLY
+}
+
+enum SubscriptionStatus {
+    TRIAL
+    ACTIVE
+    PAST_DUE
+    CANCELED
+    PENDING_SALES
+}
+
+enum SubscriptionPaymentType {
+    CARD
+    SEPA
+    PAYPAL
+    KLARNA
+    INVOICE
+}
+
+// -----------------------------------------------------------------------------
+// Subscription — one per Tenant. Binds to PlanVersion (see 03-plan-versions).
+// -----------------------------------------------------------------------------
+
+model Subscription {
+    id       String @id @default(uuid())
+    tenantId String @unique
+    // Plan key from plans.yaml (`plans[].id`). Whoever wants an enum: declare locally.
+    plan         String
+    billingCycle BillingCycle       @default(YEARLY)
+    status       SubscriptionStatus @default(TRIAL)
+
+    trialEndsAt DateTime?
+    startedAt   DateTime?
+    canceledAt  DateTime?
+
+    // Renewal period (maintained by PlanVersionRenewalService).
+    currentPeriodStart DateTime?
+    currentPeriodEnd   DateTime?
+
+    // Plan versioning — binds to a published PlanVersion.
+    // `pendingPlanVersion*` concern a version change within the
+    // same plan; `pendingPlan` the change to a different plan. Both
+    // can coexist.
+    //
+    // Since SPEC_V2 §11.1 M5, `planVersionId` is **nullable**: a
+    // Subscription may have either `planVersionId` or
+    // `businessTypeVersionId` (or both) set. The DB CHECK
+    // constraint "at least one of the two set" is added by the consumer in
+    // the SQL migration (Prisma cannot express this directly):
+    //   ALTER TABLE subscriptions ADD CONSTRAINT subscriptions_plan_or_bt_check
+    //     CHECK (plan_version_id IS NOT NULL OR business_type_version_id IS NOT NULL);
+    planVersionId                      String?
+    pendingPlanVersionId               String?
+    pendingPlanVersionEffectiveAt      DateTime?
+    pendingPlanVersionAccepted         Boolean   @default(false)
+    pendingPlanVersionAcceptedAt       DateTime?
+    pendingPlanVersionAcceptedByUserId String?
+    pendingPlanVersionNotifiedAt       DateTime?
+    pendingPlanVersionReminderSentAt   DateTime?
+
+    // BusinessType composition (SPEC_V2 §11.1 M5). Optional per app: apps
+    // with a pure plan model leave the field at null; apps with domain
+    // verticals (e.g. club types)
+    // set the Subscription to a concrete published BusinessTypeVersion.
+    // Aggregation in EntitlementService.computeLimits see
+    // GESCHAEFTSTYP_SPEC.md §6.
+    businessTypeVersionId String?
+
+    // Trial / scheduled plan changes
+    trialEntitlementPlan String? // Default entitlement during TRIAL
+    postTrialPlan        String? // Target package after trial
+    pendingPlan          String? // Downgrade/change at period end
+    pendingBillingCycle  BillingCycle?
+    pendingEffectiveAt   DateTime?
+
+    // Special contract / pilot — audit (who/when) lives in the AuditLog.
+    customMonthlyNet Decimal?  @db.Decimal(10, 2)
+    customLimits     Json? // { maxUsers?, maxVehicles?, maxStorageGb?, features?: string[] }
+    customNote       String?
+    isPilot          Boolean   @default(false)
+    pilotEndsAt      DateTime?
+    pilotNote        String?
+
+    // Package consistency (METAMODELL §17a) — references the CheckoutOffer
+    // from which the Subscription originated; `packageSnapshot` is the offer
+    // frozen at closing time (plan + promo + bundles +
+    // quotas + price breakdown). Price-fixed billing
+    // basis; null for legacy/direct subscriptions without an onboarding offer.
+    checkoutOfferId String?
+    packageSnapshot Json?
+
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+
+    // Relations — consumer must define `Tenant` and enable the relation.
+    // tenant             Tenant                    @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+    paymentMethod       SubscriptionPaymentMethod?
+    promoRedemption     PromoCodeRedemption? // see 02-promo-code.prisma
+    planVersion         PlanVersion?                @relation("SubscriptionPlanVersion", fields: [planVersionId], references: [id])
+    pendingPlanVersion  PlanVersion?                @relation("SubscriptionPendingPlanVersion", fields: [pendingPlanVersionId], references: [id])
+    businessTypeVersion BusinessTypeVersion?        @relation("SubscriptionBusinessTypeVersion", fields: [businessTypeVersionId], references: [id])
+
+    @@index([tenantId])
+    @@index([planVersionId])
+    @@index([pendingPlanVersionId])
+    @@index([businessTypeVersionId])
+    @@index([currentPeriodEnd])
+    @@map("subscriptions")
+}
+
+// -----------------------------------------------------------------------------
+// SubscriptionPaymentMethod — masked payment data per Subscription.
+// -----------------------------------------------------------------------------
+
+model SubscriptionPaymentMethod {
+    id             String                  @id @default(uuid())
+    subscriptionId String                  @unique
+    type           SubscriptionPaymentType
+
+    // Card (masked)
+    cardName  String?
+    cardBrand String?
+    cardLast4 String?
+    cardExp   String?
+
+    // SEPA (masked)
+    ibanLast4 String?
+    ibanName  String?
+
+    // PayPal
+    paypalEmail String?
+
+    // Klarna
+    klarnaPlan String? // "invoice" | "instalments"
+
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+
+    subscription Subscription @relation(fields: [subscriptionId], references: [id], onDelete: Cascade)
+
+    @@map("subscription_payment_methods")
+}
+
+// -----------------------------------------------------------------------------
+// CheckoutOffer — immutable package snapshot from the website through to the
+// Subscription (METAMODELL §17a).
+//
+// On a package click on the pricing page, `POST /public/checkout-offer` creates
+// an offer; its `id` travels as `?offer=<id>` into onboarding. There
+// the tenant customizes it (bundles/quotas) — `PATCH` writes
+// the delta back. On subscription creation the offer becomes `consumed` and
+// is frozen as `Subscription.packageSnapshot`.
+//
+// Global table (no RLS) — the offer is created before the tenant is created.
+// -----------------------------------------------------------------------------
+
+model CheckoutOffer {
+    id         String @id @default(uuid())
+    projectKey String
+
+    planKey       String
+    planVersionId String?
+    billingCycle  String // monthly | yearly
+
+    promotionId String?
+    promoCode   String?
+
+    bundles Json @default("[]") // string[]
+    bundleVersionIds Json @default("[]") // concrete BundleVersion IDs (V3)
+
+    priceBreakdown     Json
+    lineItems          Json @default("[]") // ContractLineItem snapshot shape before contract conclusion
+    promotionSnapshots Json @default("[]")
+    promoCodeSnapshot  Json?
+    locale             String @default("de")
+    validUntil         DateTime?
+
+    status     String    @default("open") // open | consumed | expired
+    consumedAt DateTime?
+
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+
+    @@index([projectKey, status])
+    @@map("checkout_offers")
+}

package/prisma-fragments/02-promo-code.prisma

@@ -0,0 +1,145 @@
+// =============================================================================
+// SaaS-Platform Prisma fragment: promo codes
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// Accompanying fragments:
+//   - 01-subscription.prisma  (PromoCodeRedemption is 1:1 with Subscription)
+
+// -----------------------------------------------------------------------------
+// Universal enums.
+// -----------------------------------------------------------------------------
+
+enum PromoCodeValueType {
+    PERCENT
+    ABSOLUTE
+}
+
+enum PromoCodeDurationType {
+    ONCE
+    MONTHS
+    BILLING_CYCLES
+}
+
+enum PromoCodeStatus {
+    ACTIVE
+    PAUSED
+    EXHAUSTED
+    EXPIRED
+}
+
+enum PromoCodeRedemptionStatus {
+    ACTIVE
+    REVERSED
+    EXPIRED
+}
+
+// -----------------------------------------------------------------------------
+// PromoCode — marketing discount code for onboarding checkout.
+// -----------------------------------------------------------------------------
+
+model PromoCode {
+    id        String             @id @default(uuid())
+    code      String             @unique // case-insensitive, stored in UPPER
+    valueType PromoCodeValueType
+    value     Decimal            @db.Decimal(8, 2) // % for PERCENT, EUR for ABSOLUTE
+
+    // Duration
+    durationType  PromoCodeDurationType @default(ONCE)
+    durationValue Int? // null for ONCE; 1–24 for MONTHS / BILLING_CYCLES
+
+    validFrom      DateTime?
+    validUntil     DateTime?
+    maxRedemptions Int? // null = unlimited
+
+    // Availability-relevant — counts only redemptions with status=ACTIVE.
+    // Incremented atomically in the redeem() path, decremented on trial cancellation.
+    redemptionsCount Int @default(0)
+
+    // Plan whitelist as String[] — values are plan IDs from plans.yaml.
+    // Consumers using a Postgres enum can cast the field locally.
+    appliesToPlans   String[] // empty = all plans; otherwise whitelist
+    appliesToBilling BillingCycle? // null = both; otherwise only MONTHLY or YEARLY
+
+    // Anti-abuse
+    firstTimeCustomersOnly Boolean  @default(true)
+    minimumPlanAmountGross Decimal? @db.Decimal(10, 2)
+    allowZeroInvoice       Boolean  @default(false)
+
+    status      PromoCodeStatus @default(ACTIVE)
+    description String?
+    campaignTag String?
+
+    // Accounting — SKR account no. (e.g. "4736"); if null, the
+    // consumer falls back to the system default (configurable in the consumer).
+    revenueDeductionAccount String?
+
+    createdById String // SUPER_ADMIN user ID (consumer FK, see header)
+    createdAt   DateTime  @default(now())
+    updatedAt   DateTime  @updatedAt
+    deletedAt   DateTime? // soft delete; never hard-delete for audit reasons
+
+    redemptions    PromoCodeRedemption[]
+    validationLogs PromoCodeValidationLog[]
+
+    @@index([status, validFrom, validUntil])
+    @@index([campaignTag])
+    @@map("promo_codes")
+}
+
+// -----------------------------------------------------------------------------
+// PromoCodeRedemption — a subscription can have only one active code.
+// -----------------------------------------------------------------------------
+
+model PromoCodeRedemption {
+    id             String @id @default(uuid())
+    promoCodeId    String
+    subscriptionId String @unique
+    tenantId       String
+
+    // Snapshot of the code rule at redemption time.
+    appliedValueType     PromoCodeValueType
+    appliedValue         Decimal               @db.Decimal(8, 2)
+    appliedDurationType  PromoCodeDurationType
+    appliedDurationValue Int?
+
+    // Validity window — endsAt null for ONCE, otherwise computed from the snapshot.
+    startsAt DateTime
+    endsAt   DateTime?
+
+    status     PromoCodeRedemptionStatus @default(ACTIVE)
+    redeemedAt DateTime                  @default(now())
+    reversedAt DateTime?
+
+    promoCode    PromoCode    @relation(fields: [promoCodeId], references: [id])
+    subscription Subscription @relation(fields: [subscriptionId], references: [id], onDelete: Cascade)
+    // tenant       Tenant       @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+    @@index([tenantId])
+    @@index([promoCodeId, status])
+    @@index([startsAt, endsAt])
+    @@map("promo_code_redemptions")
+}
+
+// -----------------------------------------------------------------------------
+// PromoCodeValidationLog — audit trail of all validation attempts
+// (including failed NOT_FOUND/EXPIRED), for anti-abuse analysis.
+// -----------------------------------------------------------------------------
+
+model PromoCodeValidationLog {
+    id          String   @id @default(uuid())
+    promoCodeId String? // null for NOT_FOUND attempts
+    codeAttempt String // input in UPPER (retained even for NOT_FOUND)
+    ipHash      String? // hash of the IP, no plaintext (data protection)
+    sessionId   String? // onboarding session / CSRF token
+    result      String // "VALID" | "EXPIRED" | "EXHAUSTED" | "NOT_FOUND" | "PLAN_MISMATCH" | …
+    createdAt   DateTime @default(now())
+
+    promoCode PromoCode? @relation(fields: [promoCodeId], references: [id], onDelete: SetNull)
+
+    @@index([codeAttempt, createdAt])
+    @@index([ipHash, createdAt])
+    @@index([sessionId, createdAt])
+    @@map("promo_code_validation_logs")
+}