@valentine-efagene/qshelter-common 2.0.29 → 2.0.31

package/prisma/schema.prisma

@@ -15,6 +15,147 @@ datasource db {
   provider = "mysql"
 }
 
+// =============================================================================
+// ENUMS - Database-enforced value constraints
+// =============================================================================
+
+enum PhaseCategory {
+  DOCUMENTATION
+  PAYMENT
+}
+
+enum PhaseType {
+  KYC
+  VERIFICATION
+  DOWNPAYMENT
+  MORTGAGE
+  BALLOON
+  CUSTOM
+}
+
+enum PaymentFrequency {
+  MONTHLY
+  BIWEEKLY
+  WEEKLY
+  ONE_TIME
+  CUSTOM
+}
+
+enum ContractStatus {
+  DRAFT
+  PENDING
+  ACTIVE
+  COMPLETED
+  CANCELLED
+  TERMINATED
+}
+
+enum PhaseStatus {
+  PENDING
+  IN_PROGRESS
+  AWAITING_APPROVAL
+  ACTIVE
+  COMPLETED
+  SKIPPED
+  FAILED
+}
+
+enum StepType {
+  UPLOAD
+  REVIEW
+  SIGNATURE
+  APPROVAL
+  EXTERNAL_CHECK
+  WAIT
+}
+
+enum StepStatus {
+  PENDING
+  IN_PROGRESS
+  COMPLETED
+  FAILED
+  SKIPPED
+}
+
+enum InstallmentStatus {
+  PENDING
+  PAID
+  OVERDUE
+  PARTIALLY_PAID
+  WAIVED
+}
+
+enum PaymentStatus {
+  INITIATED
+  PENDING
+  COMPLETED
+  FAILED
+  REFUNDED
+}
+
+enum ApprovalDecision {
+  APPROVED
+  REJECTED
+  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
+  STEPS_COMPLETED
+}
+
+enum DocumentStatus {
+  PENDING
+  APPROVED
+  REJECTED
+}
+
 // =============================================================================
 // USER & AUTH DOMAIN
 // =============================================================================
@@ -64,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")
@@ -138,6 +283,9 @@ model Tenant {
   paymentMethodChangeRequests PaymentMethodChangeRequest[]
   documentRequirementRules    DocumentRequirementRule[]
 
+  // Contract terminations
+  contractTerminations        ContractTermination[]
+
   @@index([subdomain])
   @@map("tenants")
 }
@@ -515,11 +663,11 @@ model PaymentPlan {
   isActive    Boolean @default(true)
 
   // Structure configuration
-  paymentFrequency       String // MONTHLY, BIWEEKLY, WEEKLY, ONE_TIME, CUSTOM
+  paymentFrequency       PaymentFrequency
   customFrequencyDays    Int?
   numberOfInstallments   Int // 1 for one-time, 360 for 30yr monthly, etc
-  calculateInterestDaily Boolean @default(false)
-  gracePeriodDays        Int     @default(0)
+  calculateInterestDaily Boolean          @default(false)
+  gracePeriodDays        Int              @default(0)
 
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
@@ -608,9 +756,9 @@ model PropertyPaymentMethodPhase {
   name        String
   description String? @db.Text
 
-  // Phase classification
-  phaseCategory String // DOCUMENTATION, PAYMENT
-  phaseType     String // Admin-defined: KYC, VERIFICATION, DOWNPAYMENT, MORTGAGE, BALLOON, CUSTOM, etc.
+  // Phase classification (DB-enforced enums)
+  phaseCategory PhaseCategory
+  phaseType     PhaseType
   order         Int
 
   // Financial configuration (for PAYMENT phases)
@@ -618,22 +766,64 @@ model PropertyPaymentMethodPhase {
   percentOfPrice Float? // e.g., 10.0 for 10% downpayment
 
   // Activation rules
-  requiresPreviousPhaseCompletion Boolean @default(true)
+  requiresPreviousPhaseCompletion Boolean              @default(true)
   minimumCompletionPercentage     Float?
+  completionCriterion             CompletionCriterion?
 
-  // For DOCUMENTATION phases: define required steps
-  requiredDocumentTypes String? // CSV: ID,BANK_STATEMENT,INCOME_PROOF
-  stepDefinitions       String? @db.Text // JSON: [{name, stepType, order}]
+  // Snapshots for audit (original config at creation time)
+  stepDefinitionsSnapshot  Json?
+  requiredDocumentSnapshot Json?
 
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 
+  // Normalized child tables (for DOCUMENTATION phases)
+  steps             PaymentMethodPhaseStep[]
+  requiredDocuments PaymentMethodPhaseDocument[]
+
   @@index([paymentMethodId])
   @@index([paymentPlanId])
   @@index([phaseCategory])
   @@map("property_payment_method_phases")
 }
 
+// Step template within a DOCUMENTATION phase
+model PaymentMethodPhaseStep {
+  id      String                     @id @default(cuid())
+  phaseId String
+  phase   PropertyPaymentMethodPhase @relation(fields: [phaseId], references: [id], onDelete: Cascade)
+
+  name     String
+  stepType StepType
+  order    Int
+
+  metadata  Json?
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([phaseId])
+  @@map("payment_method_phase_steps")
+}
+
+// Required document within a DOCUMENTATION phase
+model PaymentMethodPhaseDocument {
+  id      String                     @id @default(cuid())
+  phaseId String
+  phase   PropertyPaymentMethodPhase @relation(fields: [phaseId], references: [id], onDelete: Cascade)
+
+  documentType     String
+  isRequired       Boolean @default(true)
+  description      String? @db.Text
+  allowedMimeTypes String? // CSV: application/pdf,image/jpeg
+  maxSizeBytes     Int?
+
+  metadata  Json?
+  createdAt DateTime @default(now())
+
+  @@index([phaseId, documentType])
+  @@map("payment_method_phase_documents")
+}
+
 // =============================================================================
 // CONTRACT DOMAIN - Unified agreement model (replaces Mortgage, PurchasePlan, etc.)
 // =============================================================================
@@ -673,9 +863,9 @@ model Contract {
   totalPaidToDate   Float  @default(0)
   totalInterestPaid Float  @default(0)
 
-  // FSM state
-  status         String  @default("DRAFT") // DRAFT, PENDING, ACTIVE, COMPLETED, CANCELLED, TERMINATED
-  state          String  @default("DRAFT") // FSM state for workflow
+  // FSM state (DB-enforced enums)
+  status         ContractStatus @default(DRAFT)
+  state          ContractStatus @default(DRAFT) // FSM state for workflow
   currentPhaseId String?
 
   // Timing
@@ -694,6 +884,7 @@ model Contract {
   payments    ContractPayment[]
   transitions ContractTransition[]
   events      ContractEvent[]
+  terminations ContractTermination[]
 
   // Prequalification that led to this contract (optional)
   prequalification            Prequalification?
@@ -723,13 +914,13 @@ model ContractPhase {
   name        String
   description String? @db.Text
 
-  // Phase classification
-  phaseCategory String // DOCUMENTATION, PAYMENT
-  phaseType     String // Admin-defined: DOWNPAYMENT, MORTGAGE, KYC, VERIFICATION, BALLOON, CUSTOM, etc.
+  // Phase classification (DB-enforced enums)
+  phaseCategory PhaseCategory
+  phaseType     PhaseType
   order         Int
 
-  // FSM state for this phase
-  status String @default("PENDING") // PENDING, IN_PROGRESS, AWAITING_APPROVAL, ACTIVE, COMPLETED, SKIPPED, FAILED
+  // FSM state for this phase (DB-enforced enum)
+  status PhaseStatus @default(PENDING)
 
   // Financial details (for PAYMENT phases)
   totalAmount     Float?
@@ -737,6 +928,12 @@ model ContractPhase {
   remainingAmount Float?
   interestRate    Float?
 
+  // Progress counters (for efficient activation checks)
+  approvedDocumentsCount Int @default(0)
+  requiredDocumentsCount Int @default(0)
+  completedStepsCount    Int @default(0)
+  totalStepsCount        Int @default(0)
+
   // Timing
   dueDate     DateTime?
   startDate   DateTime?
@@ -745,8 +942,14 @@ model ContractPhase {
   completedAt DateTime?
 
   // Activation rules
-  requiresPreviousPhaseCompletion Boolean @default(true)
+  requiresPreviousPhaseCompletion Boolean              @default(true)
   minimumCompletionPercentage     Float?
+  completionCriterion             CompletionCriterion?
+
+  // Snapshots for audit (effective config at contract creation)
+  paymentPlanSnapshot      Json?
+  stepDefinitionsSnapshot  Json?
+  requiredDocumentSnapshot Json?
 
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
@@ -771,18 +974,18 @@ model ContractPhaseStep {
   phase   ContractPhase @relation(fields: [phaseId], references: [id], onDelete: Cascade)
 
   name        String
-  description String? @db.Text
-  stepType    String // UPLOAD, REVIEW, SIGNATURE, APPROVAL, EXTERNAL_CHECK, WAIT
+  description String?  @db.Text
+  stepType    StepType
   order       Int
 
-  status String @default("PENDING") // PENDING, IN_PROGRESS, COMPLETED, FAILED, SKIPPED
+  status StepStatus @default(PENDING)
 
   // Assignment
   assigneeId String?
   assignee   User?   @relation("PhaseStepAssignee", fields: [assigneeId], references: [id])
 
-  // Required document types for UPLOAD steps
-  requiredDocumentTypes String? // CSV: ID,BANK_STATEMENT,INCOME_PROOF
+  // Required document types for UPLOAD steps (normalized)
+  requiredDocuments ContractPhaseStepDocument[]
 
   // Timing
   dueDate     DateTime?
@@ -799,6 +1002,21 @@ model ContractPhaseStep {
   @@map("contract_phase_steps")
 }
 
+// Required documents for a step (normalized from CSV)
+model ContractPhaseStepDocument {
+  id     String            @id @default(cuid())
+  stepId String
+  step   ContractPhaseStep @relation(fields: [stepId], references: [id], onDelete: Cascade)
+
+  documentType String
+  isRequired   Boolean @default(true)
+
+  createdAt DateTime @default(now())
+
+  @@index([stepId, documentType])
+  @@map("contract_phase_step_documents")
+}
+
 // Approvals for documentation steps
 model ContractPhaseStepApproval {
   id         String            @id @default(cuid())
@@ -807,9 +1025,9 @@ model ContractPhaseStepApproval {
   approverId String?
   approver   User?             @relation("PhaseStepApprover", fields: [approverId], references: [id])
 
-  decision  String // APPROVED, REJECTED, REQUEST_CHANGES
-  comment   String?  @db.Text
-  decidedAt DateTime @default(now())
+  decision  ApprovalDecision
+  comment   String?          @db.Text
+  decidedAt DateTime         @default(now())
 
   createdAt DateTime @default(now())
 
@@ -830,7 +1048,7 @@ model ContractInstallment {
   interestAmount  Float @default(0)
 
   dueDate DateTime
-  status  String   @default("PENDING") // PENDING, PAID, OVERDUE, PARTIALLY_PAID, WAIVED
+  status  InstallmentStatus @default(PENDING)
 
   paidAmount Float     @default(0)
   paidDate   DateTime?
@@ -869,7 +1087,7 @@ model ContractPayment {
   lateFeeAmount   Float @default(0)
 
   paymentMethod String // BANK_TRANSFER, CREDIT_CARD, WALLET, CASH, CHECK
-  status        String @default("INITIATED") // INITIATED, PENDING, COMPLETED, FAILED, REFUNDED
+  status        PaymentStatus @default(INITIATED)
 
   reference       String? @unique
   gatewayResponse String? @db.Text // JSON
@@ -901,7 +1119,7 @@ model ContractDocument {
   uploadedById String?
   uploadedBy   User?   @relation("DocumentUploader", fields: [uploadedById], references: [id])
 
-  status String @default("PENDING") // PENDING, APPROVED, REJECTED
+  status DocumentStatus @default(PENDING)
 
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
@@ -942,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
 // =============================================================================