@valentine-efagene/qshelter-common 2.0.30 → 2.0.32

package/dist/generated/client/models/index.d.ts

@@ -8,6 +8,7 @@ export * from './ContractPhase';
 export * from './ContractPhaseStep';
 export * from './ContractPhaseStepApproval';
 export * from './ContractPhaseStepDocument';
+export * from './ContractTermination';
 export * from './ContractTransition';
 export * from './DeviceEndpoint';
 export * from './DocumentRequirementRule';

package/dist/generated/client/models/index.js

@@ -8,6 +8,7 @@ export * from './ContractPhase';
 export * from './ContractPhaseStep';
 export * from './ContractPhaseStepApproval';
 export * from './ContractPhaseStepDocument';
+export * from './ContractTermination';
 export * from './ContractTransition';
 export * from './DeviceEndpoint';
 export * from './DocumentRequirementRule';

package/dist/generated/client/models.d.ts

@@ -39,6 +39,7 @@ export type * from './models/ContractPayment.js';
 export type * from './models/ContractDocument.js';
 export type * from './models/ContractTransition.js';
 export type * from './models/ContractEvent.js';
+export type * from './models/ContractTermination.js';
 export type * from './models/Prequalification.js';
 export type * from './models/PaymentMethodChangeRequest.js';
 export type * from './models/DocumentRequirementRule.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentine-efagene/qshelter-common",
-  "version": "2.0.30",
+  "version": "2.0.32",
   "description": "Shared database schemas and utilities for QShelter services",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",

package/prisma/migrations/20260101081428_normalize_schema/migration.sql

@@ -0,0 +1,119 @@
+/*
+  Warnings:
+
+  - You are about to alter the column `status` on the `contract_documents` table. The data in that column could be lost. The data in that column will be cast from `VarChar(191)` to `Enum(EnumId(16))`.
+  - You are about to alter the column `status` on the `contract_installments` table. The data in that column could be lost. The data in that column will be cast from `VarChar(191)` to `Enum(EnumId(14))`.
+  - You are about to alter the column `status` on the `contract_payments` table. The data in that column could be lost. The data in that column will be cast from `VarChar(191)` to `Enum(EnumId(15))`.
+  - You are about to alter the column `decision` on the `contract_phase_step_approvals` table. The data in that column could be lost. The data in that column will be cast from `VarChar(191)` to `Enum(EnumId(13))`.
+  - You are about to drop the column `requiredDocumentTypes` on the `contract_phase_steps` table. All the data in the column will be lost.
+  - You are about to alter the column `stepType` on the `contract_phase_steps` table. The data in that column could be lost. The data in that column will be cast from `VarChar(191)` to `Enum(EnumId(11))`.
+  - You are about to alter the column `status` on the `contract_phase_steps` table. The data in that column could be lost. The data in that column will be cast from `VarChar(191)` to `Enum(EnumId(12))`.
+  - You are about to alter the column `phaseCategory` on the `contract_phases` table. The data in that column could be lost. The data in that column will be cast from `VarChar(191)` to `Enum(EnumId(7))`.
+  - You are about to alter the column `phaseType` on the `contract_phases` table. The data in that column could be lost. The data in that column will be cast from `VarChar(191)` to `Enum(EnumId(8))`.
+  - You are about to alter the column `status` on the `contract_phases` table. The data in that column could be lost. The data in that column will be cast from `VarChar(191)` to `Enum(EnumId(9))`.
+  - You are about to alter the column `status` on the `contracts` table. The data in that column could be lost. The data in that column will be cast from `VarChar(191)` to `Enum(EnumId(6))`.
+  - You are about to alter the column `state` on the `contracts` table. The data in that column could be lost. The data in that column will be cast from `VarChar(191)` to `Enum(EnumId(6))`.
+  - You are about to alter the column `paymentFrequency` on the `payment_plans` table. The data in that column could be lost. The data in that column will be cast from `VarChar(191)` to `Enum(EnumId(0))`.
+  - You are about to drop the column `requiredDocumentTypes` on the `property_payment_method_phases` table. All the data in the column will be lost.
+  - You are about to drop the column `stepDefinitions` on the `property_payment_method_phases` table. All the data in the column will be lost.
+  - You are about to alter the column `phaseCategory` on the `property_payment_method_phases` table. The data in that column could be lost. The data in that column will be cast from `VarChar(191)` to `Enum(EnumId(7))`.
+  - You are about to alter the column `phaseType` on the `property_payment_method_phases` table. The data in that column could be lost. The data in that column will be cast from `VarChar(191)` to `Enum(EnumId(8))`.
+
+*/
+-- AlterTable
+ALTER TABLE `contract_documents` MODIFY `status` ENUM('PENDING', 'APPROVED', 'REJECTED') NOT NULL DEFAULT 'PENDING';
+
+-- AlterTable
+ALTER TABLE `contract_installments` MODIFY `status` ENUM('PENDING', 'PAID', 'OVERDUE', 'PARTIALLY_PAID', 'WAIVED') NOT NULL DEFAULT 'PENDING';
+
+-- AlterTable
+ALTER TABLE `contract_payments` MODIFY `status` ENUM('INITIATED', 'PENDING', 'COMPLETED', 'FAILED', 'REFUNDED') NOT NULL DEFAULT 'INITIATED';
+
+-- AlterTable
+ALTER TABLE `contract_phase_step_approvals` MODIFY `decision` ENUM('APPROVED', 'REJECTED', 'REQUEST_CHANGES') NOT NULL;
+
+-- AlterTable
+ALTER TABLE `contract_phase_steps` DROP COLUMN `requiredDocumentTypes`,
+    MODIFY `stepType` ENUM('UPLOAD', 'REVIEW', 'SIGNATURE', 'APPROVAL', 'EXTERNAL_CHECK', 'WAIT') NOT NULL,
+    MODIFY `status` ENUM('PENDING', 'IN_PROGRESS', 'COMPLETED', 'FAILED', 'SKIPPED') NOT NULL DEFAULT 'PENDING';
+
+-- AlterTable
+ALTER TABLE `contract_phases` ADD COLUMN `approvedDocumentsCount` INTEGER NOT NULL DEFAULT 0,
+    ADD COLUMN `completedStepsCount` INTEGER NOT NULL DEFAULT 0,
+    ADD COLUMN `completionCriterion` ENUM('DOCUMENT_APPROVALS', 'PAYMENT_AMOUNT', 'STEPS_COMPLETED') NULL,
+    ADD COLUMN `paymentPlanSnapshot` JSON NULL,
+    ADD COLUMN `requiredDocumentSnapshot` JSON NULL,
+    ADD COLUMN `requiredDocumentsCount` INTEGER NOT NULL DEFAULT 0,
+    ADD COLUMN `stepDefinitionsSnapshot` JSON NULL,
+    ADD COLUMN `totalStepsCount` INTEGER NOT NULL DEFAULT 0,
+    MODIFY `phaseCategory` ENUM('DOCUMENTATION', 'PAYMENT') NOT NULL,
+    MODIFY `phaseType` ENUM('KYC', 'VERIFICATION', 'DOWNPAYMENT', 'MORTGAGE', 'BALLOON', 'CUSTOM') NOT NULL,
+    MODIFY `status` ENUM('PENDING', 'IN_PROGRESS', 'AWAITING_APPROVAL', 'ACTIVE', 'COMPLETED', 'SKIPPED', 'FAILED') NOT NULL DEFAULT 'PENDING';
+
+-- AlterTable
+ALTER TABLE `contracts` MODIFY `status` ENUM('DRAFT', 'PENDING', 'ACTIVE', 'COMPLETED', 'CANCELLED', 'TERMINATED') NOT NULL DEFAULT 'DRAFT',
+    MODIFY `state` ENUM('DRAFT', 'PENDING', 'ACTIVE', 'COMPLETED', 'CANCELLED', 'TERMINATED') NOT NULL DEFAULT 'DRAFT';
+
+-- AlterTable
+ALTER TABLE `payment_plans` MODIFY `paymentFrequency` ENUM('MONTHLY', 'BIWEEKLY', 'WEEKLY', 'ONE_TIME', 'CUSTOM') NOT NULL;
+
+-- AlterTable
+ALTER TABLE `property_payment_method_phases` DROP COLUMN `requiredDocumentTypes`,
+    DROP COLUMN `stepDefinitions`,
+    ADD COLUMN `completionCriterion` ENUM('DOCUMENT_APPROVALS', 'PAYMENT_AMOUNT', 'STEPS_COMPLETED') NULL,
+    ADD COLUMN `requiredDocumentSnapshot` JSON NULL,
+    ADD COLUMN `stepDefinitionsSnapshot` JSON NULL,
+    MODIFY `phaseCategory` ENUM('DOCUMENTATION', 'PAYMENT') NOT NULL,
+    MODIFY `phaseType` ENUM('KYC', 'VERIFICATION', 'DOWNPAYMENT', 'MORTGAGE', 'BALLOON', 'CUSTOM') NOT NULL;
+
+-- CreateTable
+CREATE TABLE `payment_method_phase_steps` (
+    `id` VARCHAR(191) NOT NULL,
+    `phaseId` VARCHAR(191) NOT NULL,
+    `name` VARCHAR(191) NOT NULL,
+    `stepType` ENUM('UPLOAD', 'REVIEW', 'SIGNATURE', 'APPROVAL', 'EXTERNAL_CHECK', 'WAIT') NOT NULL,
+    `order` INTEGER NOT NULL,
+    `metadata` JSON NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `payment_method_phase_steps_phaseId_idx`(`phaseId`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `payment_method_phase_documents` (
+    `id` VARCHAR(191) NOT NULL,
+    `phaseId` VARCHAR(191) NOT NULL,
+    `documentType` VARCHAR(191) NOT NULL,
+    `isRequired` BOOLEAN NOT NULL DEFAULT true,
+    `description` TEXT NULL,
+    `allowedMimeTypes` VARCHAR(191) NULL,
+    `maxSizeBytes` INTEGER NULL,
+    `metadata` JSON NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+
+    INDEX `payment_method_phase_documents_phaseId_documentType_idx`(`phaseId`, `documentType`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `contract_phase_step_documents` (
+    `id` VARCHAR(191) NOT NULL,
+    `stepId` VARCHAR(191) NOT NULL,
+    `documentType` VARCHAR(191) NOT NULL,
+    `isRequired` BOOLEAN NOT NULL DEFAULT true,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+
+    INDEX `contract_phase_step_documents_stepId_documentType_idx`(`stepId`, `documentType`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- AddForeignKey
+ALTER TABLE `payment_method_phase_steps` ADD CONSTRAINT `payment_method_phase_steps_phaseId_fkey` FOREIGN KEY (`phaseId`) REFERENCES `property_payment_method_phases`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `payment_method_phase_documents` ADD CONSTRAINT `payment_method_phase_documents_phaseId_fkey` FOREIGN KEY (`phaseId`) REFERENCES `property_payment_method_phases`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `contract_phase_step_documents` ADD CONSTRAINT `contract_phase_step_documents_stepId_fkey` FOREIGN KEY (`stepId`) REFERENCES `contract_phase_steps`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;

package/prisma/migrations/20260101102022_add_contract_termination/migration.sql

@@ -0,0 +1,69 @@
+-- CreateTable
+CREATE TABLE `contract_terminations` (
+    `id` VARCHAR(191) NOT NULL,
+    `contractId` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `requestNumber` VARCHAR(191) NOT NULL,
+    `initiatedBy` ENUM('BUYER', 'SELLER', 'ADMIN', 'SYSTEM') NOT NULL,
+    `initiatorId` VARCHAR(191) NULL,
+    `type` ENUM('BUYER_WITHDRAWAL', 'SELLER_WITHDRAWAL', 'MUTUAL_AGREEMENT', 'PAYMENT_DEFAULT', 'DOCUMENT_FAILURE', 'FRAUD', 'FORCE_MAJEURE', 'PROPERTY_UNAVAILABLE', 'REGULATORY', 'OTHER') NOT NULL,
+    `reason` TEXT NULL,
+    `supportingDocs` JSON NULL,
+    `status` ENUM('REQUESTED', 'PENDING_REVIEW', 'PENDING_REFUND', 'REFUND_IN_PROGRESS', 'REFUND_COMPLETED', 'COMPLETED', 'REJECTED', 'CANCELLED') NOT NULL DEFAULT 'REQUESTED',
+    `requiresApproval` BOOLEAN NOT NULL DEFAULT true,
+    `autoApproveEligible` BOOLEAN NOT NULL DEFAULT false,
+    `reviewedBy` VARCHAR(191) NULL,
+    `reviewedAt` DATETIME(3) NULL,
+    `reviewNotes` TEXT NULL,
+    `rejectionReason` TEXT NULL,
+    `contractSnapshot` JSON NOT NULL,
+    `totalContractAmount` DOUBLE NOT NULL,
+    `totalPaidToDate` DOUBLE NOT NULL,
+    `outstandingBalance` DOUBLE NOT NULL,
+    `refundableAmount` DOUBLE NOT NULL DEFAULT 0,
+    `penaltyAmount` DOUBLE NOT NULL DEFAULT 0,
+    `forfeitedAmount` DOUBLE NOT NULL DEFAULT 0,
+    `adminFeeAmount` DOUBLE NOT NULL DEFAULT 0,
+    `netRefundAmount` DOUBLE NOT NULL DEFAULT 0,
+    `settlementNotes` TEXT NULL,
+    `refundStatus` ENUM('NOT_APPLICABLE', 'PENDING', 'INITIATED', 'PROCESSING', 'PARTIAL_COMPLETED', 'COMPLETED', 'FAILED') NOT NULL DEFAULT 'NOT_APPLICABLE',
+    `refundReference` VARCHAR(191) NULL,
+    `refundMethod` VARCHAR(191) NULL,
+    `refundAccountDetails` JSON NULL,
+    `refundInitiatedAt` DATETIME(3) NULL,
+    `refundCompletedAt` DATETIME(3) NULL,
+    `refundFailureReason` TEXT NULL,
+    `unitReleasedAt` DATETIME(3) NULL,
+    `unitReservedForId` VARCHAR(191) NULL,
+    `requestedAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `approvedAt` DATETIME(3) NULL,
+    `executedAt` DATETIME(3) NULL,
+    `completedAt` DATETIME(3) NULL,
+    `cancelledAt` DATETIME(3) NULL,
+    `idempotencyKey` VARCHAR(191) NULL,
+    `metadata` JSON NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    UNIQUE INDEX `contract_terminations_requestNumber_key`(`requestNumber`),
+    UNIQUE INDEX `contract_terminations_idempotencyKey_key`(`idempotencyKey`),
+    INDEX `contract_terminations_contractId_idx`(`contractId`),
+    INDEX `contract_terminations_tenantId_idx`(`tenantId`),
+    INDEX `contract_terminations_status_idx`(`status`),
+    INDEX `contract_terminations_type_idx`(`type`),
+    INDEX `contract_terminations_initiatorId_idx`(`initiatorId`),
+    INDEX `contract_terminations_requestedAt_idx`(`requestedAt`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- AddForeignKey
+ALTER TABLE `contract_terminations` ADD CONSTRAINT `contract_terminations_contractId_fkey` FOREIGN KEY (`contractId`) REFERENCES `contracts`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `contract_terminations` ADD CONSTRAINT `contract_terminations_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `contract_terminations` ADD CONSTRAINT `contract_terminations_initiatorId_fkey` FOREIGN KEY (`initiatorId`) REFERENCES `users`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `contract_terminations` ADD CONSTRAINT `contract_terminations_reviewedBy_fkey` FOREIGN KEY (`reviewedBy`) REFERENCES `users`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;

package/prisma/migrations/20260101110958_add_collect_funds/migration.sql

@@ -0,0 +1,8 @@
+-- AlterTable
+ALTER TABLE `contract_phases` ADD COLUMN `collectFunds` BOOLEAN NOT NULL DEFAULT true;
+
+-- AlterTable
+ALTER TABLE `payment_plans` ADD COLUMN `collectFunds` BOOLEAN NOT NULL DEFAULT true;
+
+-- AlterTable
+ALTER TABLE `property_payment_method_phases` ADD COLUMN `collectFunds` BOOLEAN NULL;

package/prisma/schema.prisma

@@ -99,6 +99,51 @@ enum ApprovalDecision {
   REQUEST_CHANGES
 }
 
+// =============================================================================
+// CONTRACT TERMINATION / CANCELLATION ENUMS
+// =============================================================================
+
+enum TerminationType {
+  BUYER_WITHDRAWAL // Buyer wants to cancel (voluntary)
+  SELLER_WITHDRAWAL // Seller/developer cancels
+  MUTUAL_AGREEMENT // Both parties agree to terminate
+  PAYMENT_DEFAULT // Buyer failed payment obligations
+  DOCUMENT_FAILURE // Buyer failed to provide required documents
+  FRAUD // Fraudulent activity detected
+  FORCE_MAJEURE // External circumstances (disaster, etc.)
+  PROPERTY_UNAVAILABLE // Property no longer available
+  REGULATORY // Regulatory/legal requirement
+  OTHER // Other reasons (with notes)
+}
+
+enum TerminationStatus {
+  REQUESTED // Initial request submitted
+  PENDING_REVIEW // Awaiting admin review
+  PENDING_REFUND // Approved, awaiting refund processing
+  REFUND_IN_PROGRESS // Refund being processed
+  REFUND_COMPLETED // Refund completed
+  COMPLETED // Termination fully executed (no refund or refund done)
+  REJECTED // Termination request rejected
+  CANCELLED // Termination request was cancelled
+}
+
+enum RefundStatus {
+  NOT_APPLICABLE // No refund needed (no payments made)
+  PENDING // Refund not yet initiated
+  INITIATED // Refund request sent to payment gateway
+  PROCESSING // Gateway processing refund
+  PARTIAL_COMPLETED // Some refund completed (penalties deducted)
+  COMPLETED // Full refund completed
+  FAILED // Refund failed (needs manual intervention)
+}
+
+enum TerminationInitiator {
+  BUYER
+  SELLER
+  ADMIN
+  SYSTEM
+}
+
 enum CompletionCriterion {
   DOCUMENT_APPROVALS
   PAYMENT_AMOUNT
@@ -160,6 +205,10 @@ model User {
   paymentMethodChangeRequests PaymentMethodChangeRequest[] @relation("ChangeRequestor")
   reviewedChangeRequests      PaymentMethodChangeRequest[] @relation("ChangeReviewer")
 
+  // Contract terminations
+  initiatedTerminations ContractTermination[] @relation("TerminationInitiator")
+  reviewedTerminations  ContractTermination[] @relation("TerminationReviewer")
+
   @@index([email])
   @@index([tenantId])
   @@map("users")
@@ -234,6 +283,9 @@ model Tenant {
   paymentMethodChangeRequests PaymentMethodChangeRequest[]
   documentRequirementRules    DocumentRequirementRule[]
 
+  // Contract terminations
+  contractTerminations ContractTermination[]
+
   @@index([subdomain])
   @@map("tenants")
 }
@@ -617,6 +669,11 @@ model PaymentPlan {
   calculateInterestDaily Boolean          @default(false)
   gracePeriodDays        Int              @default(0)
 
+  // Fund collection behavior
+  // true = we collect funds via wallet/gateway (e.g., downpayment)
+  // false = external payment, we only track/reconcile (e.g., bank mortgage)
+  collectFunds           Boolean          @default(true)
+
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 
@@ -713,6 +770,11 @@ model PropertyPaymentMethodPhase {
   interestRate   Float?
   percentOfPrice Float? // e.g., 10.0 for 10% downpayment
 
+  // Fund collection behavior (inherited from PaymentPlan if not set)
+  // true = we collect funds via wallet/gateway (e.g., downpayment)
+  // false = external payment, we only track/reconcile (e.g., bank mortgage)
+  collectFunds   Boolean? // null = inherit from PaymentPlan
+
   // Activation rules
   requiresPreviousPhaseCompletion Boolean              @default(true)
   minimumCompletionPercentage     Float?
@@ -827,11 +889,12 @@ model Contract {
   updatedAt          DateTime  @updatedAt
 
   // Relations
-  phases      ContractPhase[]
-  documents   ContractDocument[]
-  payments    ContractPayment[]
-  transitions ContractTransition[]
-  events      ContractEvent[]
+  phases       ContractPhase[]
+  documents    ContractDocument[]
+  payments     ContractPayment[]
+  transitions  ContractTransition[]
+  events       ContractEvent[]
+  terminations ContractTermination[]
 
   // Prequalification that led to this contract (optional)
   prequalification            Prequalification?
@@ -875,6 +938,11 @@ model ContractPhase {
   remainingAmount Float?
   interestRate    Float?
 
+  // Fund collection behavior (snapshotted from template at contract creation)
+  // true = we collect funds via wallet/gateway (e.g., downpayment)
+  // false = external payment, we only track/reconcile (e.g., bank mortgage)
+  collectFunds    Boolean @default(true)
+
   // Progress counters (for efficient activation checks)
   approvedDocumentsCount Int @default(0)
   requiredDocumentsCount Int @default(0)
@@ -1107,6 +1175,98 @@ model ContractEvent {
   @@map("contract_events")
 }
 
+// =============================================================================
+// CONTRACT TERMINATION - Full lifecycle for cancellation/termination
+// =============================================================================
+// Tracks termination requests from initiation through refund completion.
+// Industry-standard flow:
+// 1. Request created (by buyer/seller/admin/system)
+// 2. Admin reviews (if required by policy)
+// 3. Financial settlement calculated (refunds, penalties, forfeitures)
+// 4. Refund processed (if applicable)
+// 5. Contract marked terminated, unit released
+// =============================================================================
+
+model ContractTermination {
+  id         String   @id @default(cuid())
+  contractId String
+  contract   Contract @relation(fields: [contractId], references: [id], onDelete: Cascade)
+  tenantId   String
+  tenant     Tenant   @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  // Request identification
+  requestNumber String @unique // TRM-XXXXXX
+
+  // Who initiated and why
+  initiatedBy    TerminationInitiator
+  initiatorId    String? // userId if BUYER/SELLER/ADMIN
+  initiator      User?                @relation("TerminationInitiator", fields: [initiatorId], references: [id])
+  type           TerminationType
+  reason         String?              @db.Text
+  supportingDocs Json? // [{type, url, uploadedAt}]
+
+  // Workflow status
+  status              TerminationStatus @default(REQUESTED)
+  requiresApproval    Boolean           @default(true)
+  autoApproveEligible Boolean           @default(false) // Pre-signature, no payments
+
+  // Admin review
+  reviewedBy      String?
+  reviewer        User?     @relation("TerminationReviewer", fields: [reviewedBy], references: [id])
+  reviewedAt      DateTime?
+  reviewNotes     String?   @db.Text
+  rejectionReason String?   @db.Text
+
+  // Financial snapshot at time of request
+  contractSnapshot    Json // Full contract state snapshot
+  totalContractAmount Float
+  totalPaidToDate     Float
+  outstandingBalance  Float
+
+  // Settlement calculation
+  refundableAmount Float   @default(0) // Amount eligible for refund
+  penaltyAmount    Float   @default(0) // Penalties/fees to deduct
+  forfeitedAmount  Float   @default(0) // Amount forfeited (non-refundable deposits)
+  adminFeeAmount   Float   @default(0) // Processing fees
+  netRefundAmount  Float   @default(0) // refundableAmount - penaltyAmount - adminFeeAmount
+  settlementNotes  String? @db.Text
+
+  // Refund processing
+  refundStatus         RefundStatus @default(NOT_APPLICABLE)
+  refundReference      String? // Payment gateway reference
+  refundMethod         String? // ORIGINAL_METHOD, BANK_TRANSFER, CHECK, WALLET
+  refundAccountDetails Json? // Encrypted bank details if needed
+  refundInitiatedAt    DateTime?
+  refundCompletedAt    DateTime?
+  refundFailureReason  String?      @db.Text
+
+  // Property unit handling
+  unitReleasedAt    DateTime?
+  unitReservedForId String? // If unit being held for another buyer
+
+  // Timing
+  requestedAt DateTime  @default(now())
+  approvedAt  DateTime?
+  executedAt  DateTime?
+  completedAt DateTime?
+  cancelledAt DateTime?
+
+  // Idempotency and audit
+  idempotencyKey String? @unique
+  metadata       Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([contractId])
+  @@index([tenantId])
+  @@index([status])
+  @@index([type])
+  @@index([initiatorId])
+  @@index([requestedAt])
+  @@map("contract_terminations")
+}
+
 // =============================================================================
 // PREQUALIFICATION - Eligibility assessment before contract creation
 // =============================================================================