@saasicat/spec 0.2.0

package/prisma-fragments/03-plan-versions.prisma

@@ -0,0 +1,94 @@
+// =============================================================================
+// SaaS platform Prisma fragment: plan versioning
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// Global catalog tables (no tenantId, no RLS). Write access only via the
+// SUPER_ADMIN guard in the AdminController of the `@saasicat/nest`
+// package.
+//
+// Per identity key (planId):
+//   - at most 1 draft (publishedAt IS NULL) — constraint via a partial unique
+//     index in the migration (the Prisma schema cannot express partial unique:
+//     add it in the SQL migration as
+//     `CREATE UNIQUE INDEX … WHERE published_at IS NULL`).
+//   - multiple published versions, monotonically incrementing `version`.
+//   - `supersededAt` marks "no longer actively marketed"; the version
+//     remains billing-valid for existing subscriptions (contractual plan guarantee).
+
+// -----------------------------------------------------------------------------
+// Plan — root identity of a plan (SPEC_V2 §11.1 M6).
+// `planKey` is the business plan identity (STARTER / STANDARD / PROFESSIONAL),
+// unique per `projectKey`. PlanVersion.planId points **softly** to
+// `Plan.planKey` (no DB FK — the binding is enforced via service logic in M6
+// so that the greenfield cutover can run without a destructive schema
+// migration).
+//
+// Soft-delete via `deletedAt`. A deleted plan root hides its
+// PlanVersions in the UI, but keeps them effective for existing subscriptions
+// (contract protection P1) — analogous to Bundle/BusinessType.
+// -----------------------------------------------------------------------------
+
+model Plan {
+    id          String  @id @default(uuid())
+    projectKey  String
+    planKey     String
+    label       String
+    description String?
+    icon        String?
+    sortOrder   Int     @default(0)
+
+    createdAt DateTime  @default(now())
+    updatedAt DateTime  @updatedAt
+    deletedAt DateTime?
+
+    @@unique([projectKey, planKey])
+    @@index([projectKey, deletedAt])
+    @@map("plans")
+}
+
+// -----------------------------------------------------------------------------
+// PlanVersion — exactly one lineage per `planId` (= plan key from plans.yaml).
+// -----------------------------------------------------------------------------
+
+model PlanVersion {
+    id            String  @id @default(uuid())
+    planId        String // plan key from plans.yaml (`plans[].id`)
+    version       Int
+    baseVersionId String? // predecessor the draft diffs against (nullable for v1)
+
+    // Snapshot of the plan definition at the time of publishing.
+    // `features` is the published feature set as FeatureKey[].
+    // `quotas` is a free-form JSON object; concrete quota keys come from
+    // plans.yaml (`quotaKeys` pattern). Example:
+    //   { "users": 5, "vehicles": 100, "storageGb": 50 }
+    features Json
+    quotas   Json
+
+    monthlyNet Decimal @db.Decimal(10, 2)
+    yearlyNet  Decimal @db.Decimal(10, 2) // net total amount per year for the YEARLY cycle
+    marketed   Boolean @default(true)
+
+    publishedAt      DateTime?
+    supersededAt     DateTime?
+    publishedChanges Json? // VersionChange[] — see @saasicat/types
+    changeNote       String
+    nonRegressive    Boolean @default(true)
+
+    createdByUserId   String?
+    publishedByUserId String?
+
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+
+    baseVersion          PlanVersion?   @relation("PlanVersionLineage", fields: [baseVersionId], references: [id])
+    derivedVersions      PlanVersion[]  @relation("PlanVersionLineage")
+    subscriptionsCurrent Subscription[] @relation("SubscriptionPlanVersion")
+    subscriptionsPending Subscription[] @relation("SubscriptionPendingPlanVersion")
+
+    @@unique([planId, version])
+    @@index([planId, supersededAt])
+    @@index([planId, publishedAt])
+    @@map("plan_versions")
+}

package/prisma-fragments/04-audit-log.prisma

@@ -0,0 +1,38 @@
+// =============================================================================
+// SaaS-Platform Prisma fragment: audit log
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 01-subscription.prisma for conventions.
+//
+// Generic audit log for tenant- and admin-side actions. Consumers
+// can share the log or keep their own parallel logs — the
+// `@saasicat/nest` package writes into this schema.
+//
+// `action` must follow SCREAMING_SNAKE_CASE (see
+// `schemas/audit-event.schema.json` action pattern). Consumer-specific
+// actions are allowed; platform actions are cataloged in the `AuditActionDef`
+// list of the manifest contributions.
+
+model AuditLog {
+    id        String  @id @default(uuid())
+    tenantId  String? // null for platform-global actions (plan publish etc.)
+    userId    String? // actor — null for system cron or pre-auth actions
+    entity    String // e.g. "Subscription", "PromoCode", "PlanVersion"
+    entityId  String
+    action    String // SCREAMING_SNAKE_CASE; e.g. "PROMO_CODE_REDEEM"
+    changes   Json? // { field: { old: …, new: … } }
+    ipAddress String?
+    userAgent String?
+
+    createdAt DateTime @default(now())
+
+    // Relations — the consumer must define `Tenant` and `User` and
+    // enable relations. Userless system actions leave userId null.
+    // tenant Tenant? @relation(fields: [tenantId], references: [id])
+    // user   User?   @relation("AuditLogUser", fields: [userId], references: [id])
+
+    @@index([tenantId, entity, entityId])
+    @@index([tenantId, createdAt])
+    @@index([entity, action, createdAt])
+    @@map("audit_logs")
+}

package/prisma-fragments/05-bundle-business-type.prisma

@@ -0,0 +1,206 @@
+// =============================================================================
+// SaaS platform Prisma fragment: Bundle + BusinessType (plan catalog extension)
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 03-plan-versions.prisma for versioning conventions.
+//
+// Global catalog tables (no tenantId, no RLS). Write access only via the
+// SUPER_ADMIN guard in the AdminController of the `@saasicat/nest`
+// package. Entries are assigned to the respective consumer app via
+// `projectKey`.
+//
+// Versioning pattern identical to PlanVersion:
+//   - at most 1 draft (publishedAt IS NULL) per identity — constraint via a
+//     partial unique index in the migration.
+//   - multiple published versions, monotonically incremental `version`.
+//   - `supersededAt` marks "no longer actively marketed"; existing bookings
+//     stay on the committed version (contractual plan guarantee P1).
+//
+// Naming note: GESCHAEFTSTYP_SPEC §3.1 partly speaks of `BundleDefinition`
+// (with suffix) and `BusinessType` (without) — that is asymmetric. SPEC_V2
+// unified this to a consistent `Bundle` / `BusinessType` (each without the
+// `Definition` suffix). This file follows the V2 convention.
+
+// -----------------------------------------------------------------------------
+// Bundle — reusable component of features + quotas + pricing.
+//
+// Tenants do **not** book bundles directly; they are a SuperAdmin maintenance
+// shell that is referenced in BusinessType versions (m:n via
+// BusinessTypeBundle). Root entity without content — the purchasable fields
+// (features, quotas, pricing) live on BundleVersion.
+// -----------------------------------------------------------------------------
+
+model Bundle {
+    id          String   @id @default(uuid())
+    projectKey  String // e.g. 'clubapp' | 'demoapp' | …
+    bundleKey   String // SCREAMING_SNAKE_CASE, e.g. 'SPORT', 'ACCOUNTING', 'EVERSEND_PEPPOL'
+    label       String
+    description String?
+    icon        String?
+    sortOrder   Int      @default(0)
+
+    // Locale translations { "en": { label, description }, … }. SPEC_V2 §6.4.
+    i18n Json @default("{}")
+
+    createdAt DateTime  @default(now())
+    updatedAt DateTime  @updatedAt
+    deletedAt DateTime?
+
+    versions BundleVersion[]
+
+    @@unique([projectKey, bundleKey])
+    @@index([projectKey, deletedAt])
+    @@map("bundles")
+}
+
+// -----------------------------------------------------------------------------
+// BundleVersion — versioned composition (features, quotas, pricing).
+// `features` is FeatureKey[] (references Discovery / FeatureCatalogEntry).
+// `quotas` is Record<QuotaKey, number>; -1 = unlimited; missing key = 0.
+// `compatibility` is BundleCompatibility (`businessTypeKeys?` /
+// `planIds?` whitelists). Both empty = usable everywhere.
+// `pricingOverrides` is Array<BundlePricingOverride> for context-dependent
+// prices (see GESCHAEFTSTYP_SPEC §6.1, "most-specific wins").
+// -----------------------------------------------------------------------------
+
+model BundleVersion {
+    id            String  @id @default(uuid())
+    bundleId      String
+    version       Int
+    baseVersionId String? // predecessor; null for v1
+
+    features         Json // FeatureKey[]
+    quotas           Json @default("{}") // Record<QuotaKey, number>
+    compatibility    Json @default("{}") // BundleCompatibility
+    pricingOverrides Json @default("[]") // BundlePricingOverride[]
+
+    monthlyNet Decimal? @db.Decimal(10, 2) // default price; null = only via override
+    yearlyNet  Decimal? @db.Decimal(10, 2)
+    marketed   Boolean  @default(true)
+
+    publishedAt      DateTime?
+    supersededAt     DateTime?
+    publishedChanges Json? // VersionChange[] — diff to predecessor version
+    changeNote       String  @default("")
+    nonRegressive    Boolean @default(true)
+
+    createdByUserId   String?
+    publishedByUserId String?
+
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+
+    bundle              Bundle               @relation(fields: [bundleId], references: [id], onDelete: Cascade)
+    baseVersion         BundleVersion?       @relation("BundleVersionLineage", fields: [baseVersionId], references: [id])
+    derivedVersions     BundleVersion[]      @relation("BundleVersionLineage")
+    businessTypeBundles BusinessTypeBundle[]
+
+    @@unique([bundleId, version])
+    @@index([bundleId, supersededAt])
+    @@index([bundleId, publishedAt])
+    @@map("bundle_versions")
+}
+
+// -----------------------------------------------------------------------------
+// BusinessType — business vertical (club type, industry variant).
+//
+// Examples for a club app: SPORT_VEREIN, MOSCHEE_GEMEINDE,
+// KIRCHEN_GEMEINDE, SOZIAL_TRAEGER. Example for a commerce app: AUTO_HANDEL.
+// At **most one** BusinessType is referenced per subscription (via the
+// associated BusinessTypeVersion). Multiple bundles at once = a dedicated
+// BusinessType that composes the bundles internally.
+// -----------------------------------------------------------------------------
+
+model BusinessType {
+    id              String   @id @default(uuid())
+    projectKey      String
+    businessTypeKey String // SCREAMING_SNAKE_CASE
+    label           String
+    description     String?
+    icon            String?
+    sortOrder       Int      @default(0)
+
+    createdAt DateTime  @default(now())
+    updatedAt DateTime  @updatedAt
+    deletedAt DateTime?
+
+    versions BusinessTypeVersion[]
+
+    @@unique([projectKey, businessTypeKey])
+    @@index([projectKey, deletedAt])
+    @@map("business_types")
+}
+
+// -----------------------------------------------------------------------------
+// BusinessTypeVersion — versioned composition of referenced bundles.
+// `quotaOverrides` is Partial<Record<QuotaKey, number>>; missing key →
+// Σ(bundle quotas), set key → replaces the sum (-1 = unlimited).
+// `monthlyNet` null → effective price = Σ(bundle prices). Set → override.
+// -----------------------------------------------------------------------------
+
+model BusinessTypeVersion {
+    id             String  @id @default(uuid())
+    businessTypeId String
+    version        Int
+    baseVersionId  String?
+
+    quotaOverrides Json @default("{}") // Partial<Record<QuotaKey, number>>
+
+    monthlyNet Decimal? @db.Decimal(10, 2) // null = Σ(bundle prices)
+    yearlyNet  Decimal? @db.Decimal(10, 2)
+    marketed   Boolean  @default(true)
+
+    publishedAt      DateTime?
+    supersededAt     DateTime?
+    publishedChanges Json?
+    changeNote       String  @default("")
+    nonRegressive    Boolean @default(true)
+
+    createdByUserId   String?
+    publishedByUserId String?
+
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+
+    businessType    BusinessType          @relation(fields: [businessTypeId], references: [id], onDelete: Cascade)
+    baseVersion     BusinessTypeVersion?  @relation("BusinessTypeVersionLineage", fields: [baseVersionId], references: [id])
+    derivedVersions BusinessTypeVersion[] @relation("BusinessTypeVersionLineage")
+    bundles         BusinessTypeBundle[]
+
+    // Consumers add the Subscription relation in their own schema.prisma.
+    // Example (commented out):
+    //
+    // subscriptionsCurrent Subscription[] @relation("SubscriptionBusinessTypeVersion")
+    //
+    // Prerequisite: in M5 Subscription gets the field
+    // `businessTypeVersionId String?` plus a CHECK constraint
+    // "at least one of planVersionId / businessTypeVersionId set".
+
+    @@unique([businessTypeId, version])
+    @@index([businessTypeId, supersededAt])
+    @@index([businessTypeId, publishedAt])
+    @@map("business_type_versions")
+}
+
+// -----------------------------------------------------------------------------
+// BusinessTypeBundle — m:n junction between BusinessTypeVersion and
+// BundleVersion. Stores the *concrete* BundleVersion (not just the root), so
+// that a published BusinessType stays deterministic — even when the bundle
+// later gets a newer version.
+// onDelete: Restrict for bundleVersion prevents deleting a BundleVersion that
+// is still referenced in an active BusinessTypeVersion (additionally a hard
+// block in the publish strict check).
+// -----------------------------------------------------------------------------
+
+model BusinessTypeBundle {
+    businessTypeVersionId String
+    bundleVersionId       String
+    sortOrder             Int    @default(0)
+
+    businessTypeVersion BusinessTypeVersion @relation(fields: [businessTypeVersionId], references: [id], onDelete: Cascade)
+    bundleVersion       BundleVersion       @relation(fields: [bundleVersionId], references: [id], onDelete: Restrict)
+
+    @@id([businessTypeVersionId, bundleVersionId])
+    @@index([bundleVersionId])
+    @@map("business_type_bundles")
+}

package/prisma-fragments/06-catalog-entries.prisma

@@ -0,0 +1,279 @@
+// =============================================================================
+// SaaS-Platform Prisma fragment: catalog entries (discovery review + marketing)
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 03-plan-versions.prisma for conventions.
+//
+// Three tables:
+//   - CapabilityCatalogEntry  — SuperAdmin review status per code-declared
+//                               capability (discovery projection)
+//   - FeatureCatalogEntry     — ditto for features + marketing fields
+//   - MarketingProjection     — marketing texts/pricing/highlights per
+//                               plan/bundle/business-type version (locale pivot)
+//
+// Approval lifecycle (#20, feature-/quota-centric):
+//   pending → approved (↔ revoke) · outdated (drift) · obsolete
+// Approval happens per FEATURE/QUOTA — capabilities now only carry the
+// read-only code status (active | experimental | deprecated | retired).
+//
+// Backfill when migrating from the old vocabulary (per consumer DB):
+//   feature_/quota_catalog_entries.discoveryStatus:
+//     discovered→pending · accepted→approved · active→approved ·
+//     ignored→pending · deprecated→outdated · retired→obsolete
+//   capability_catalog_entries: rename column discoveryStatus → codeStatus,
+//     values: deprecated→deprecated · retired→retired · everything else→active
+//
+// Global catalog tables (no tenantId, no RLS). Write access only via the
+// SUPER_ADMIN guard in the AdminController.
+
+// -----------------------------------------------------------------------------
+// CapabilityCatalogEntry — read-only code fact per code capability (#20).
+//
+// Every capability declared via @ImplementsCapability(...) appears here after
+// the first discovery scan with its decorator status (`codeStatus`). The sync
+// always overwrites the code status; it sets `retired` when the capability is
+// missing from the new snapshot. There is no longer a business approval at the
+// capability level — that lives on the feature/quota.
+//
+// `featureKey` and `bundleKey` are the aggregation wrappers declared in the
+// decorator — denormalized for fast lookup in the discovery UI; the binding
+// source, however, remains the code annotation, not this DB entry.
+// -----------------------------------------------------------------------------
+
+model CapabilityCatalogEntry {
+    id            String  @id @default(uuid())
+    projectKey    String // e.g. 'clubapp' | 'demoapp' | …
+    capabilityKey String // 'invoice.create' | 'member.archive' | …
+    label         String
+    description   String?
+
+    // Aggregation wrappers from the decorator (denormalized).
+    featureKey String?
+    bundleKey  String?
+
+    // Read-only code status from the decorator (#20); 'retired' = removed from code.
+    codeStatus String @default("active") // active | experimental | deprecated | retired
+
+    // Code owner tag for audit (e.g. 'accounting', 'membership').
+    owner String?
+
+    // Implementation kind (matches decorator.kind):
+    // 'endpoint' | 'service' | 'job' | 'event'
+    kind String
+
+    // When deprecated: target version + planned removal.
+    replacementKey   String?
+    deprecatedAt     DateTime?
+    removalPlannedAt DateTime?
+    reason           String?
+
+    // Locale translations: { "en": { label, description }, "tr": {…} }.
+    // The default locale is deliberately absent — fallback in the UI. SPEC_V2 §6.3.
+    i18n Json @default("{}")
+
+    sortOrder Int @default(0)
+
+    createdAt DateTime  @default(now())
+    updatedAt DateTime  @updatedAt
+    deletedAt DateTime?
+
+    @@unique([projectKey, capabilityKey])
+    @@index([projectKey, codeStatus])
+    @@index([projectKey, featureKey])
+    @@map("capability_catalog_entries")
+}
+
+// -----------------------------------------------------------------------------
+// FeatureCatalogEntry — SuperAdmin review status + marketing master data per
+// feature. Aggregation from the capabilities that declare `feature: 'XYZ'`
+// in the decorator.
+//
+// Marketing texts (`marketingLabel` / `marketingDescription`) are the short
+// slot for the sidebar/comparison matrix; the *long* locale-specific texts
+// live in MarketingProjection (separate table, locale pivot).
+//
+// `plannedOnly = true` lets the SuperAdmin add a feature that does not yet
+// exist in code to a plan (e.g. for roadmap marketing). The blocking strict-
+// mode check (SPEC_V2 §8.1) rejects `plannedOnly` features at plan publish —
+// they may only appear in internal drafts or warn-only builds.
+// -----------------------------------------------------------------------------
+
+model FeatureCatalogEntry {
+    id          String  @id @default(uuid())
+    projectKey  String
+    featureKey  String // 'INVOICE_MANAGEMENT' | 'MEMBER_LIST' | …
+    label       String
+    description String?
+
+    // Marketing short form (for sidebar/comparison). Detailed texts
+    // per locale → MarketingProjection.
+    marketingLabel       String?
+    marketingDescription String?
+    icon                 String?
+
+    // Tier hint for comparison-matrix sorting.
+    // Convention: 'CORE' < 'ADVANCED' < 'PRO' < 'ENTERPRISE'
+    tier String?
+
+    // Approval lifecycle (#20): pending | approved | outdated | obsolete.
+    discoveryStatus String @default("pending")
+
+    // Approval signature (#20): freezes the capability set at approval time
+    // ('capabilityKey@codeStatus', sorted, '|'-separated). The auto-sync
+    // compares against the current snapshot → on drift approved → outdated.
+    approvedAt        DateTime?
+    approvedBy        String?
+    approvedSignature String?
+
+    // True = feature is planned in the SuperAdmin but not yet implemented in
+    // code. Blocking strict mode rejects plan publish with plannedOnly
+    // features.
+    plannedOnly Boolean @default(false)
+
+    // Locale translations { "en": { label, description }, … }. SPEC_V2 §6.3.
+    i18n Json @default("{}")
+
+    sortOrder Int @default(0)
+
+    createdAt DateTime  @default(now())
+    updatedAt DateTime  @updatedAt
+    deletedAt DateTime?
+
+    @@unique([projectKey, featureKey])
+    @@index([projectKey, discoveryStatus])
+    @@index([projectKey, plannedOnly])
+    @@map("feature_catalog_entries")
+}
+
+// -----------------------------------------------------------------------------
+// QuotaCatalogEntry — SuperAdmin review status per code-declared quota
+// (`@DefinesQuota`). `usageProvider` is the class that provides the quota;
+// `null` = referenced (`@EnforceQuota`) but provided by no class. A hard quota
+// without `usageProvider` is not deployable — `yada app preflight` blocks it
+// (SPEC_V2 §6.3 + §8.3).
+// -----------------------------------------------------------------------------
+
+model QuotaCatalogEntry {
+    id          String  @id @default(uuid())
+    projectKey  String
+    quotaKey    String // 'invoicesPerMonth' | 'members' | 'storageGb' | …
+    label       String
+    description String?
+
+    unit       String // Display unit: 'members' | 'GB' | '/month' | …
+    featureKey String? // Aggregation wrapper from the decorator (denormalized)
+
+    // Class that declares the quota via @DefinesQuota (= UsageProvider).
+    usageProvider   String?
+    enforcementMode String  @default("soft") // hard | soft
+
+    // Approval lifecycle (#20): pending | approved | outdated | obsolete.
+    discoveryStatus String @default("pending")
+
+    // Approval signature (#20): code-derived quota facts at approval time
+    // ('unit|enforcementMode|usageProvider|featureKey'); on drift approved →
+    // outdated.
+    approvedAt        DateTime?
+    approvedBy        String?
+    approvedSignature String?
+
+    // Locale translations { "en": { label, unit, description }, … }.
+    i18n Json @default("{}")
+
+    sortOrder Int @default(0)
+
+    createdAt DateTime  @default(now())
+    updatedAt DateTime  @updatedAt
+    deletedAt DateTime?
+
+    @@unique([projectKey, quotaKey])
+    @@index([projectKey, discoveryStatus])
+    @@map("quota_catalog_entries")
+}
+
+// -----------------------------------------------------------------------------
+// MarketingProjection — locale-specific marketing texts per
+// plan/bundle/business-type version.
+//
+// Read and projected by the public catalog controller
+// (`GET /public/catalog?locale=de`). Only versions with status `marketed` and
+// a matching MarketingProjection entry appear in the public list.
+//
+// Polymorphic reference via (`targetType`, `targetVersionId`) instead of three
+// separate FK columns — deliberate, because a cascade delete for three models
+// would be complicated and uniqueness via (targetType, targetVersionId,
+// locale) is sufficient. App logic checks existence on read.
+//
+// MVP: locale `de` is mandatory; further locales (e.g. `en`) are allowed as
+// schema preparation but not enforced (see SPEC_V2 V2-Q1).
+// -----------------------------------------------------------------------------
+
+model MarketingProjection {
+    id         String @id @default(uuid())
+    projectKey String
+
+    // Polymorphic reference to a versioned entity.
+    targetType      String // 'PLAN' | 'BUNDLE' | 'BUSINESS_TYPE'
+    targetVersionId String // PlanVersion.id | BundleVersion.id | BusinessTypeVersion.id
+
+    locale String @default("de") // ISO-639-1, optionally with a region suffix ('de', 'en', 'de-AT')
+
+    displayLabel String
+    description  String
+
+    // Visibility in the public catalog — false = projection exists but does
+    // not appear on the pricing page.
+    visible Boolean @default(true)
+
+    // Optional badge at the top of the card ('Beliebt', 'Neu'). '' = no badge.
+    badge String @default("")
+
+    // Top features for the public catalog card: [{ label, strong }].
+    // Order is the display order.
+    topFeatures Json @default("[]") // { label: string; strong: string }[]
+
+    // Free trial period — controls the auto-generated CTA text.
+    trialEnabled Boolean @default(false)
+    trialDays    Int     @default(30)
+
+    // Optional formatted pricing tag (e.g. "€ 9,90 / Monat" or "auf Anfrage").
+    // If null: pricing is formatted automatically from PlanVersion.monthlyNet
+    // etc. at public-catalog render time.
+    priceTag String?
+
+    // Overrides the auto-generated call-to-action text.
+    ctaLabel String?
+
+    // Sort order in the public list (DESC). Higher values first.
+    priority Int @default(0)
+
+    // "Empfohlen" star / featured highlight in the UI.
+    highlight Boolean @default(false)
+
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+
+    @@unique([targetType, targetVersionId, locale])
+    @@index([projectKey, targetType, locale, priority])
+    @@map("marketing_projections")
+}
+
+// -----------------------------------------------------------------------------
+// MarketingSettings — project-wide, runtime-editable marketing config.
+// One row per project (`projectKey` unique). Currently exactly one field:
+// `activeLocales` — the subset of the `availableLocales` pool activated in the
+// marketing catalog (the pool comes from the app config, SPEC_V2 §6.5).
+// If the row is missing, the full pool counts as active.
+// -----------------------------------------------------------------------------
+
+model MarketingSettings {
+    id         String @id @default(uuid())
+    projectKey String @unique
+
+    activeLocales Json @default("[]") // string[]
+
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+
+    @@map("marketing_settings")
+}

package/prisma-fragments/07-promotion.prisma

@@ -0,0 +1,65 @@
+// =============================================================================
+// SaaS-Platform Prisma fragment: Promotion (time-scheduled pricing campaigns)
+// =============================================================================
+//
+// REFERENCE SNIPPET — see 03-plan-versions.prisma for conventions.
+//
+// A Promotion is a catalog-side, time-limited pricing campaign.
+// It overrides the pricing-page price automatically (without entering a code,
+// unless `requiresCoupon`). Separate from `PromoCode` (a redeemable
+// checkout voucher, 02-promo-code.prisma) — `requiresCoupon = true`
+// couples a Promotion to existing PromoCode codes via `codes`.
+//
+// Global catalog table (no tenantId, no RLS). Write access only
+// via the SUPER_ADMIN guard in the AdminController.
+
+model Promotion {
+    id         String @id @default(uuid())
+    projectKey String // e.g. 'clubapp' | 'demoapp' | …
+
+    // Internal label (not public).
+    internalLabel String
+
+    // Campaign type: percent | amount | intro | freeMonths
+    type String
+
+    // Type-dependent value:
+    //   percent/amount → number
+    //   intro          → { price, months }
+    //   freeMonths     → number
+    value Json
+
+    // Target type of the keys in `appliesTo`: PLAN | BUNDLE | OFFER.
+    // Null/missing in legacy records is interpreted as PLAN.
+    targetType String @default("PLAN")
+
+    // Target keys the campaign applies to.
+    appliesTo Json @default("[]") // string[]
+
+    // Billing cycle: monthly | yearly | both
+    billingCycle String @default("both")
+
+    validFrom DateTime
+    validTo   DateTime
+
+    // On overlap, the highest value wins.
+    priority Int @default(0)
+
+    // Language restriction; null = all locales.
+    onlyLocales Json? // string[] | null
+
+    requiresCoupon Boolean @default(false)
+    codes          Json    @default("[]") // string[] — referenced PromoCode codes
+
+    // UI accent color (timeline/ribbon).
+    color String @default("#2563eb")
+
+    // Locale texts { "de": { badge, fineprint }, … }.
+    i18n Json @default("{}")
+
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+
+    @@index([projectKey, targetType, validFrom, validTo])
+    @@map("promotions")
+}