@adaptware/eagles-db 0.6.16 → 0.6.17

package/client/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "prisma-client-cae6b7bb9dff0f97d36dd48dc1e72bf310a22699dfd0845d40f8a3b60f753636",
+  "name": "prisma-client-f0391a01c267ab1f703c4b9658aa0d675b0ffaa064f1069e1a145d0508245379",
   "main": "index.js",
   "types": "index.d.ts",
   "browser": "default.js",

package/client/schema.prisma

@@ -3183,6 +3183,212 @@ model LicensingLedgerEntry {
   @@schema("licensing")
 }
 
+// Org-level platform subscription: a recurring fee per organisation. Each period is a SubscriptionCharge, paid through
+// a Razorpay Order (BillingTransaction with transaction_type SUBSCRIPTION); the tax Invoice (kind SUBSCRIPTION) is issued
+// only once the charge is paid. Prices are all-inclusive (GST and fees are backed out on the invoice). Amounts are minor units.
+// Plan: docs/eagles-db/platform-subscription-implementation-plan.md.
+// Design sheet: https://docs.google.com/spreadsheets/d/1R-EBGAMdju_P78Qs05g4_NouSbCM_7W-IyCd8gyZCUI (Sheet2).
+
+enum BillingCycle {
+  MONTHLY
+  ANNUAL
+
+  @@schema("licensing")
+}
+
+enum SubscriptionPlanType {
+  TRIAL
+  REGULAR
+  /// Internal and demo orgs: amount 0, never charged, never PAST_DUE or SUSPENDED.
+  INTERNAL
+
+  @@schema("licensing")
+}
+
+enum PlatformSubscriptionStatus {
+  TRIALING
+  ACTIVE
+  /// Grace: charge OPEN until due_at; everyone in the org keeps full access.
+  PAST_DUE
+  /// After due_at (or a trial ending unpaid): only org admins can log in, payment screen only.
+  SUSPENDED
+  CANCELLED
+
+  @@schema("licensing")
+}
+
+enum SubscriptionChargeStatus {
+  OPEN
+  PAID
+  VOID
+
+  @@schema("licensing")
+}
+
+/// Tells the payment-captured handler what to do: RENEWAL keeps the current record;
+/// CONVERSION, REACTIVATION and UPGRADE close it and start a new one on the payment day.
+enum SubscriptionChargeKind {
+  RENEWAL
+  CONVERSION
+  REACTIVATION
+  UPGRADE
+
+  @@schema("licensing")
+}
+
+enum SubscriptionAccessAudience {
+  /// Anyone in the suspended org (e.g. candidate-facing flows).
+  ALL_USERS
+  /// Org admins only (e.g. the payment screen).
+  ADMIN_ONLY
+
+  @@schema("licensing")
+}
+
+/// Platform fee catalogue, one row per (currency, billing_cycle, type).
+/// A TRIAL plan has amount 0; trial_days sets the default trial length.
+/// An INTERNAL plan has amount 0 and is never billed (internal and demo orgs, assigned by org id).
+/// GST and fee rates come from the platform billing settings, not the plan.
+model SubscriptionPlan {
+  id            String               @id @default(uuid())
+  name          String
+  /// INR or USD; matched against Organisation.billing_currency.
+  currency      String               @default("INR")
+  /// All-inclusive price per billing cycle, minor units (1000000 = Rs 10,000): exactly what the org pays.
+  amount        Int
+  billing_cycle BillingCycle         @default(MONTHLY)
+  type          SubscriptionPlanType
+  /// TRIAL plans only: default trial length in days, editable by Super Admin. Null otherwise.
+  trial_days    Int?
+  /// Days to pay after a period starts unpaid.
+  grace_days    Int                  @default(7)
+  created_at    DateTime             @default(now())
+  updated_at    DateTime             @updatedAt
+  created_by    String
+  updated_by    String
+  is_active     Boolean              @default(true)
+
+  subscriptions        PlatformSubscription[] @relation("PlatformSubscriptionPlan")
+  pending_downgrades   PlatformSubscription[] @relation("PlatformSubscriptionNextPlan")
+  subscription_charges SubscriptionCharge[]
+
+  @@unique([currency, billing_cycle, type])
+  @@map("subscription_plans")
+  @@schema("licensing")
+}
+
+/// History of an org's subscription: one record per plan/billing-anchor span.
+/// The current record has effective_end_date null and current_organisation_id set; the unique constraint on
+/// current_organisation_id allows at most one current record per org.
+model PlatformSubscription {
+  id                      String                     @id @default(uuid())
+  organisation_id         String
+  /// Equals organisation_id on the current record, null once the record is closed. Unique: one current record per org.
+  current_organisation_id String?                    @unique
+  plan_id                 String
+  /// Pending downgrade, applied at the next billing date (billing date unchanged). Null when none.
+  next_plan_id            String?
+  status                  PlatformSubscriptionStatus @default(TRIALING)
+  /// Org's all-inclusive fee per billing cycle, minor units; copied from the plan, overridable.
+  amount                  Int
+  /// Billing anchor: the payment date that started this record (after a trial, after grace, or an
+  /// upgrade). Unchanged when a renewal is paid within grace.
+  effective_start_date    DateTime
+  /// Null on the current record; set to the date the next record starts.
+  effective_end_date      DateTime?
+  /// TRIAL records only: start + plan.trial_days when the trial starts; Super Admin can change it
+  /// per org. Unpaid at this time: SUSPENDED (no grace after a trial). Null otherwise.
+  trial_ends_at           DateTime?
+  /// Copied from the plan.
+  grace_days              Int
+  created_at              DateTime                   @default(now())
+  updated_at              DateTime                   @updatedAt
+  created_by              String
+  updated_by              String
+  is_active               Boolean                    @default(true)
+
+  organisation Organisation         @relation(fields: [organisation_id], references: [id], onDelete: Restrict, onUpdate: Cascade)
+  plan         SubscriptionPlan     @relation("PlatformSubscriptionPlan", fields: [plan_id], references: [id], onDelete: Restrict, onUpdate: Cascade)
+  next_plan    SubscriptionPlan?    @relation("PlatformSubscriptionNextPlan", fields: [next_plan_id], references: [id], onDelete: Restrict, onUpdate: Cascade)
+  charges      SubscriptionCharge[]
+
+  @@index([organisation_id, effective_end_date])
+  @@index([status, trial_ends_at])
+  @@index([plan_id])
+  @@index([next_plan_id])
+  @@map("platform_subscriptions")
+  @@schema("licensing")
+}
+
+/// What the org owes for one billing period, reactivation or upgrade; paid through one Razorpay Order.
+/// Not a tax invoice: the Invoice (kind SUBSCRIPTION) is issued when the charge is paid and linked via invoice_id.
+/// Total = subscription_amount + grace_amount - credit_amount (all-inclusive, not stored).
+model SubscriptionCharge {
+  /// Sent to Razorpay as billing_transactions.purchase_reference (subscription_charge:{id}).
+  id                     String                   @id @default(uuid())
+  subscription_id        String
+  /// Plan this charge bills for; for an upgrade, the new plan.
+  plan_id                String
+  organisation_id        String
+  kind                   SubscriptionChargeKind
+  status                 SubscriptionChargeStatus @default(OPEN)
+  period_start           DateTime
+  period_end             DateTime
+  /// period_start + grace_days, end of day in the org's timezone. Unpaid after this: SUSPENDED.
+  due_at                 DateTime
+  subscription_amount    Int
+  /// Prorated days used but not paid: grace days when paid after grace, or days from period_start
+  /// to the upgrade date when upgrading with an OPEN charge (which is voided).
+  grace_amount           Int                      @default(0)
+  /// Upgrade only: prorated unused days of the old plan's paid period.
+  credit_amount          Int                      @default(0)
+  /// Successful payment. No FK: payment-service boundary.
+  billing_transaction_id String?                  @unique
+  /// Tax invoice issued when the charge was paid.
+  invoice_id             String?                  @unique
+  paid_at                DateTime?
+  /// Stops the billing job issuing the same charge twice.
+  idempotency_key        String                   @unique
+  created_at             DateTime                 @default(now())
+  updated_at             DateTime                 @updatedAt
+  created_by             String
+  updated_by             String
+
+  subscription PlatformSubscription @relation(fields: [subscription_id], references: [id], onDelete: Restrict, onUpdate: Cascade)
+  plan         SubscriptionPlan     @relation(fields: [plan_id], references: [id], onDelete: Restrict, onUpdate: Cascade)
+  organisation Organisation         @relation(fields: [organisation_id], references: [id], onDelete: Restrict, onUpdate: Cascade)
+  invoice      Invoice?             @relation(fields: [invoice_id], references: [id], onDelete: Restrict, onUpdate: Cascade)
+
+  @@index([organisation_id, status])
+  @@index([subscription_id])
+  @@index([plan_id])
+  @@index([status, due_at])
+  @@map("subscription_charges")
+  @@schema("licensing")
+}
+
+/// Routes that stay open while an org is SUSPENDED (access level ADMIN_PAYMENT_ONLY).
+/// Managed by Super Admin; seeded with defaults (auth, payment screen, candidate portal).
+/// Everything not matched is blocked with 402 SUBSCRIPTION_SUSPENDED.
+model SubscriptionAccessRule {
+  id            String                     @id @default(uuid())
+  /// API path pattern, `*` wildcard, e.g. /candidate/*.
+  route_pattern String
+  /// GET, POST, ... or * for any method.
+  http_method   String                     @default("*")
+  audience      SubscriptionAccessAudience @default(ADMIN_ONLY)
+  description   String?
+  created_at    DateTime                   @default(now())
+  updated_at    DateTime                   @updatedAt
+  created_by    String
+  updated_by    String
+  is_active     Boolean                    @default(true)
+
+  @@unique([route_pattern, http_method])
+  @@map("subscription_access_rules")
+  @@schema("licensing")
+}
+
 /// Historical package purchase by an organisation (independent per transaction).
 model PurchasedLicensePackage {
   id                 String                        @id @default(uuid())
@@ -3883,6 +4089,8 @@ model Organisation {
   license_package_organisations LicensePackageOrganisation[]
   ai_cost_ledger_entries        AiCostLedgerEntry[]
   consent_documents             ConsentDocument[]
+  platform_subscriptions        PlatformSubscription[]
+  subscription_charges          SubscriptionCharge[]
   billing_transactions          BillingTransaction[]
   payment_webhook_events        PaymentWebhookEvent[]
   invoices                      Invoice[]
@@ -3925,6 +4133,8 @@ enum BillingTransactionType {
   PURCHASE
   TOP_UP
   REFUND
+  /// Platform subscription charge (purchase_reference subscription_charge:{id}).
+  SUBSCRIPTION
 
   @@schema("public")
 }
@@ -3943,6 +4153,9 @@ enum BillingTransactionFailureCategory {
 enum BillingPaymentMismatchStatus {
   DETECTED
   UNFULFILLED
+  /// Razorpay captured a different amount or currency than the stored transaction: never applied, never
+  /// recovered or refunded automatically (refund from the Razorpay dashboard).
+  AMOUNT_MISMATCH
 
   @@schema("public")
 }
@@ -3993,11 +4206,13 @@ model BillingTransaction {
   @@schema("public")
 }
 
-// Tax invoices issued by Treadspace. Shared by license package purchases and (later) platform subscriptions.
+// Tax invoices issued by Treadspace. Shared by license package purchases and platform subscriptions.
 
 /// What the invoice was raised for.
 enum InvoiceKind {
   PACKAGE
+  /// A paid platform subscription charge (licensing.subscription_charges.invoice_id).
+  SUBSCRIPTION
 
   @@schema("public")
 }
@@ -4044,6 +4259,7 @@ model Invoice {
   organisation              Organisation             @relation(fields: [organisation_id], references: [id], onDelete: Restrict)
   billing_transaction       BillingTransaction?      @relation(fields: [billing_transaction_id], references: [id], onDelete: Restrict)
   purchased_license_package PurchasedLicensePackage?
+  subscription_charge       SubscriptionCharge?
 
   @@index([organisation_id, issued_at])
   @@map("invoices")