@valentine-efagene/qshelter-common 2.0.30 → 2.0.31

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.31",
   "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/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")
 }
@@ -832,6 +884,7 @@ model Contract {
   payments    ContractPayment[]
   transitions ContractTransition[]
   events      ContractEvent[]
+  terminations ContractTermination[]
 
   // Prequalification that led to this contract (optional)
   prequalification            Prequalification?
@@ -1107,6 +1160,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
 // =============================================================================