@valentine-efagene/qshelter-common 2.0.25 → 2.0.26

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

@@ -36,5 +36,8 @@ 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/Prequalification.js';
+export type * from './models/PaymentMethodChangeRequest.js';
+export type * from './models/DocumentRequirementRule.js';
 export type * from './models/DomainEvent.js';
 export type * from './commonInputTypes.js';

package/package.json

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

package/prisma/migrations/20251230231217_add_prequalification_and_payment_method_change/migration.sql

@@ -0,0 +1,137 @@
+-- CreateTable
+CREATE TABLE `prequalifications` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `userId` VARCHAR(191) NOT NULL,
+    `propertyId` VARCHAR(191) NOT NULL,
+    `paymentMethodId` VARCHAR(191) NOT NULL,
+    `answers` JSON NOT NULL,
+    `score` DOUBLE NULL,
+    `requestedAmount` DOUBLE NULL,
+    `monthlyIncome` DOUBLE NULL,
+    `monthlyExpenses` DOUBLE NULL,
+    `debtToIncomeRatio` DOUBLE NULL,
+    `suggestedTermMonths` INTEGER NULL,
+    `status` ENUM('DRAFT', 'SUBMITTED', 'UNDER_REVIEW', 'APPROVED', 'REJECTED', 'EXPIRED') NOT NULL DEFAULT 'DRAFT',
+    `notes` TEXT NULL,
+    `reviewedBy` VARCHAR(191) NULL,
+    `reviewedAt` DATETIME(3) NULL,
+    `expiresAt` DATETIME(3) NULL,
+    `contractId` VARCHAR(191) NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    UNIQUE INDEX `prequalifications_contractId_key`(`contractId`),
+    INDEX `prequalifications_tenantId_idx`(`tenantId`),
+    INDEX `prequalifications_userId_idx`(`userId`),
+    INDEX `prequalifications_propertyId_idx`(`propertyId`),
+    INDEX `prequalifications_status_idx`(`status`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `payment_method_change_requests` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `contractId` VARCHAR(191) NOT NULL,
+    `fromPaymentMethodId` VARCHAR(191) NOT NULL,
+    `toPaymentMethodId` VARCHAR(191) NOT NULL,
+    `requestorId` VARCHAR(191) NOT NULL,
+    `reason` TEXT NULL,
+    `requiredDocumentTypes` VARCHAR(191) NULL,
+    `submittedDocuments` JSON NULL,
+    `currentOutstanding` DOUBLE NULL,
+    `newTermMonths` INTEGER NULL,
+    `newInterestRate` DOUBLE NULL,
+    `newMonthlyPayment` DOUBLE NULL,
+    `penaltyAmount` DOUBLE NULL,
+    `financialImpactNotes` TEXT NULL,
+    `status` ENUM('PENDING_DOCUMENTS', 'DOCUMENTS_SUBMITTED', 'UNDER_REVIEW', 'APPROVED', 'REJECTED', 'EXECUTED', 'CANCELLED') NOT NULL DEFAULT 'PENDING_DOCUMENTS',
+    `reviewerId` VARCHAR(191) NULL,
+    `reviewNotes` TEXT NULL,
+    `reviewedAt` DATETIME(3) NULL,
+    `executedAt` DATETIME(3) NULL,
+    `previousPhaseData` JSON NULL,
+    `newPhaseData` JSON NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `payment_method_change_requests_tenantId_idx`(`tenantId`),
+    INDEX `payment_method_change_requests_contractId_idx`(`contractId`),
+    INDEX `payment_method_change_requests_status_idx`(`status`),
+    INDEX `payment_method_change_requests_requestorId_idx`(`requestorId`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `document_requirement_rules` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `context` ENUM('PREQUALIFICATION', 'CONTRACT_PHASE', 'PAYMENT_METHOD_CHANGE') NOT NULL,
+    `paymentMethodId` VARCHAR(191) NULL,
+    `phaseType` VARCHAR(191) NULL,
+    `fromPaymentMethodId` VARCHAR(191) NULL,
+    `toPaymentMethodId` VARCHAR(191) NULL,
+    `documentType` VARCHAR(191) NOT NULL,
+    `isRequired` BOOLEAN NOT NULL DEFAULT true,
+    `description` VARCHAR(191) NULL,
+    `maxSizeBytes` INTEGER NULL,
+    `allowedMimeTypes` VARCHAR(191) NULL,
+    `expiryDays` INTEGER NULL,
+    `requiresManualReview` BOOLEAN NOT NULL DEFAULT false,
+    `isActive` BOOLEAN NOT NULL DEFAULT true,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `document_requirement_rules_tenantId_idx`(`tenantId`),
+    INDEX `document_requirement_rules_context_idx`(`context`),
+    INDEX `document_requirement_rules_paymentMethodId_idx`(`paymentMethodId`),
+    INDEX `document_requirement_rules_phaseType_idx`(`phaseType`),
+    INDEX `document_requirement_rules_fromPaymentMethodId_toPaymentMeth_idx`(`fromPaymentMethodId`, `toPaymentMethodId`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- AddForeignKey
+ALTER TABLE `prequalifications` ADD CONSTRAINT `prequalifications_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `prequalifications` ADD CONSTRAINT `prequalifications_userId_fkey` FOREIGN KEY (`userId`) REFERENCES `users`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `prequalifications` ADD CONSTRAINT `prequalifications_propertyId_fkey` FOREIGN KEY (`propertyId`) REFERENCES `properties`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `prequalifications` ADD CONSTRAINT `prequalifications_paymentMethodId_fkey` FOREIGN KEY (`paymentMethodId`) REFERENCES `property_payment_methods`(`id`) ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `prequalifications` ADD CONSTRAINT `prequalifications_contractId_fkey` FOREIGN KEY (`contractId`) REFERENCES `contracts`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `payment_method_change_requests` ADD CONSTRAINT `payment_method_change_requests_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `payment_method_change_requests` ADD CONSTRAINT `payment_method_change_requests_contractId_fkey` FOREIGN KEY (`contractId`) REFERENCES `contracts`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `payment_method_change_requests` ADD CONSTRAINT `payment_method_change_requests_fromPaymentMethodId_fkey` FOREIGN KEY (`fromPaymentMethodId`) REFERENCES `property_payment_methods`(`id`) ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `payment_method_change_requests` ADD CONSTRAINT `payment_method_change_requests_toPaymentMethodId_fkey` FOREIGN KEY (`toPaymentMethodId`) REFERENCES `property_payment_methods`(`id`) ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `payment_method_change_requests` ADD CONSTRAINT `payment_method_change_requests_requestorId_fkey` FOREIGN KEY (`requestorId`) REFERENCES `users`(`id`) ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `payment_method_change_requests` ADD CONSTRAINT `payment_method_change_requests_reviewerId_fkey` FOREIGN KEY (`reviewerId`) REFERENCES `users`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `document_requirement_rules` ADD CONSTRAINT `document_requirement_rules_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `document_requirement_rules` ADD CONSTRAINT `document_requirement_rules_paymentMethodId_fkey` FOREIGN KEY (`paymentMethodId`) REFERENCES `property_payment_methods`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `document_requirement_rules` ADD CONSTRAINT `document_requirement_rules_fromPaymentMethodId_fkey` FOREIGN KEY (`fromPaymentMethodId`) REFERENCES `property_payment_methods`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `document_requirement_rules` ADD CONSTRAINT `document_requirement_rules_toPaymentMethodId_fkey` FOREIGN KEY (`toPaymentMethodId`) REFERENCES `property_payment_methods`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;

package/prisma/schema.prisma

@@ -59,6 +59,11 @@ model User {
   stepApprovals ContractPhaseStepApproval[] @relation("PhaseStepApprover")
   uploadedDocs  ContractDocument[]          @relation("DocumentUploader")
 
+  // Prequalification and payment method changes
+  prequalifications           Prequalification[]
+  paymentMethodChangeRequests PaymentMethodChangeRequest[] @relation("ChangeRequestor")
+  reviewedChangeRequests      PaymentMethodChangeRequest[] @relation("ChangeReviewer")
+
   @@index([email])
   @@index([tenantId])
   @@map("users")
@@ -128,6 +133,11 @@ model Tenant {
   paymentMethods PropertyPaymentMethod[]
   contracts      Contract[]
 
+  // Prequalification and payment method changes
+  prequalifications           Prequalification[]
+  paymentMethodChangeRequests PaymentMethodChangeRequest[]
+  documentRequirementRules    DocumentRequirementRule[]
+
   @@index([subdomain])
   @@map("tenants")
 }
@@ -303,11 +313,12 @@ model Property {
   updatedAt      DateTime       @updatedAt
 
   // Relations
-  documents      PropertyDocument[]
-  media          PropertyMedia[]             @relation("PropertyMedia")
-  amenities      PropertyAmenity[] // Shared amenities (gym, pool, security)
-  paymentMethods PropertyPaymentMethodLink[]
-  variants       PropertyVariant[]
+  documents         PropertyDocument[]
+  media             PropertyMedia[]             @relation("PropertyMedia")
+  amenities         PropertyAmenity[] // Shared amenities (gym, pool, security)
+  paymentMethods    PropertyPaymentMethodLink[]
+  variants          PropertyVariant[]
+  prequalifications Prequalification[]
 
   @@index([tenantId])
   @@index([userId])
@@ -552,6 +563,18 @@ model PropertyPaymentMethod {
   // Contracts using this method
   contracts  Contract[]
 
+  // Prequalifications for this payment method
+  prequalifications Prequalification[]
+
+  // Payment method change tracking
+  changeRequestsFrom PaymentMethodChangeRequest[] @relation("ChangeFromMethod")
+  changeRequestsTo   PaymentMethodChangeRequest[] @relation("ChangeToMethod")
+
+  // Document requirement rules
+  documentRules   DocumentRequirementRule[] @relation("RulePaymentMethod")
+  changeRulesFrom DocumentRequirementRule[] @relation("RuleFromMethod")
+  changeRulesTo   DocumentRequirementRule[] @relation("RuleToMethod")
+
   @@unique([tenantId, name]) // Unique per tenant
   @@index([tenantId])
   @@map("property_payment_methods")
@@ -672,6 +695,11 @@ model Contract {
   transitions ContractTransition[]
   events      ContractEvent[]
 
+  // Prequalification that led to this contract (optional)
+  prequalification            Prequalification?
+  // Payment method change requests for this contract
+  paymentMethodChangeRequests PaymentMethodChangeRequest[]
+
   @@index([tenantId])
   @@index([propertyUnitId])
   @@index([buyerId])
@@ -914,6 +942,198 @@ model ContractEvent {
   @@map("contract_events")
 }
 
+// =============================================================================
+// PREQUALIFICATION - Eligibility assessment before contract creation
+// =============================================================================
+// Prequalification is a separate aggregate that evaluates a user's eligibility
+// for a specific product (property + payment method). It captures their answers
+// to eligibility questions and calculates a score. Once approved, it can be
+// linked to a Contract to provide context about how the buyer qualified.
+// =============================================================================
+
+enum PrequalificationStatus {
+  DRAFT
+  SUBMITTED
+  UNDER_REVIEW
+  APPROVED
+  REJECTED
+  EXPIRED
+}
+
+model Prequalification {
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  userId   String
+  user     User   @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  // What they're applying for
+  propertyId      String
+  property        Property              @relation(fields: [propertyId], references: [id], onDelete: Cascade)
+  paymentMethodId String
+  paymentMethod   PropertyPaymentMethod @relation(fields: [paymentMethodId], references: [id])
+
+  // Questionnaire responses and scoring
+  answers Json // Array of {questionId, answer, weight, score}
+  score   Float? // Computed eligibility score (0-100)
+
+  // Financial assessment
+  requestedAmount     Float? // How much they want to finance
+  monthlyIncome       Float? // Self-reported monthly income
+  monthlyExpenses     Float? // Self-reported monthly expenses
+  debtToIncomeRatio   Float? // Computed DTI
+  suggestedTermMonths Int? // System-suggested term based on affordability
+
+  // Status tracking
+  status     PrequalificationStatus @default(DRAFT)
+  notes      String?                @db.Text // Admin notes
+  reviewedBy String? // Admin who reviewed
+  reviewedAt DateTime?
+  expiresAt  DateTime? // Prequalification validity period
+
+  // If approved, may be linked to eventual contract
+  contractId String?   @unique
+  contract   Contract? @relation(fields: [contractId], references: [id])
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([tenantId])
+  @@index([userId])
+  @@index([propertyId])
+  @@index([status])
+  @@map("prequalifications")
+}
+
+// =============================================================================
+// PAYMENT METHOD CHANGE REQUEST - Mid-contract payment method changes
+// =============================================================================
+// When a user wants to change their payment method after contract creation,
+// this aggregate tracks the request, required documentation, approvals, and
+// final execution. Different from-to combinations may require different docs.
+// =============================================================================
+
+enum PaymentMethodChangeStatus {
+  PENDING_DOCUMENTS
+  DOCUMENTS_SUBMITTED
+  UNDER_REVIEW
+  APPROVED
+  REJECTED
+  EXECUTED
+  CANCELLED
+}
+
+model PaymentMethodChangeRequest {
+  id         String   @id @default(cuid())
+  tenantId   String
+  tenant     Tenant   @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  contractId String
+  contract   Contract @relation(fields: [contractId], references: [id], onDelete: Cascade)
+
+  // The change being requested
+  fromPaymentMethodId String
+  fromPaymentMethod   PropertyPaymentMethod @relation("ChangeFromMethod", fields: [fromPaymentMethodId], references: [id])
+  toPaymentMethodId   String
+  toPaymentMethod     PropertyPaymentMethod @relation("ChangeToMethod", fields: [toPaymentMethodId], references: [id])
+
+  // Who requested and why
+  requestorId String
+  requestor   User    @relation("ChangeRequestor", fields: [requestorId], references: [id])
+  reason      String? @db.Text
+
+  // Documentation requirements (determined by DocumentRequirementRule)
+  requiredDocumentTypes String? // CSV: BANK_STATEMENT,INCOME_PROOF,NEW_EMPLOYER_LETTER
+  submittedDocuments    Json? // [{type, s3Key, uploadedAt, status}]
+
+  // Financial impact assessment
+  currentOutstanding   Float? // Outstanding balance at time of request
+  newTermMonths        Int? // New term if applicable
+  newInterestRate      Float? // New rate if applicable
+  newMonthlyPayment    Float? // Projected new payment
+  penaltyAmount        Float? // Early change penalty if applicable
+  financialImpactNotes String? @db.Text
+
+  // Status and workflow
+  status      PaymentMethodChangeStatus @default(PENDING_DOCUMENTS)
+  reviewerId  String?
+  reviewer    User?                     @relation("ChangeReviewer", fields: [reviewerId], references: [id])
+  reviewNotes String?                   @db.Text
+  reviewedAt  DateTime?
+
+  // Execution details
+  executedAt        DateTime?
+  previousPhaseData Json? // Snapshot of phases before change
+  newPhaseData      Json? // New phases created after change
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([tenantId])
+  @@index([contractId])
+  @@index([status])
+  @@index([requestorId])
+  @@map("payment_method_change_requests")
+}
+
+// =============================================================================
+// DOCUMENT REQUIREMENT RULES - Configurable document requirements
+// =============================================================================
+// Admins can configure which documents are required for specific scenarios:
+// - Prequalification for a payment method type
+// - Contract phases
+// - Payment method changes (from-to combinations)
+// This allows tenants to customize documentation workflows per product.
+// =============================================================================
+
+enum DocumentRequirementContext {
+  PREQUALIFICATION // During prequalification
+  CONTRACT_PHASE // During a contract phase
+  PAYMENT_METHOD_CHANGE // When changing payment method mid-contract
+}
+
+model DocumentRequirementRule {
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  // Rule context
+  context DocumentRequirementContext
+
+  // Scoping (which situations this rule applies to)
+  // For PREQUALIFICATION: paymentMethodId
+  // For CONTRACT_PHASE: phaseType
+  // For PAYMENT_METHOD_CHANGE: fromMethodId + toMethodId
+  paymentMethodId     String?
+  paymentMethod       PropertyPaymentMethod? @relation("RulePaymentMethod", fields: [paymentMethodId], references: [id])
+  phaseType           String? // KYC, VERIFICATION, DOWNPAYMENT, etc.
+  fromPaymentMethodId String?
+  fromPaymentMethod   PropertyPaymentMethod? @relation("RuleFromMethod", fields: [fromPaymentMethodId], references: [id])
+  toPaymentMethodId   String?
+  toPaymentMethod     PropertyPaymentMethod? @relation("RuleToMethod", fields: [toPaymentMethodId], references: [id])
+
+  // Document requirements
+  documentType     String // ID_CARD, PASSPORT, BANK_STATEMENT, INCOME_PROOF, etc.
+  isRequired       Boolean @default(true)
+  description      String? // Instructions for the user
+  maxSizeBytes     Int? // Max file size allowed
+  allowedMimeTypes String? // CSV: application/pdf,image/jpeg,image/png
+
+  // Validation rules
+  expiryDays           Int? // Document must not be older than X days
+  requiresManualReview Boolean @default(false)
+
+  isActive  Boolean  @default(true)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([tenantId])
+  @@index([context])
+  @@index([paymentMethodId])
+  @@index([phaseType])
+  @@index([fromPaymentMethodId, toPaymentMethodId])
+  @@map("document_requirement_rules")
+}
+
 // =============================================================================
 // EVENT OUTBOX - For guaranteed event delivery to SQS queues
 // =============================================================================