@valentine-efagene/qshelter-common 2.0.31 → 2.0.33

package/prisma/schema.prisma

@@ -104,37 +104,37 @@ enum ApprovalDecision {
 // =============================================================================
 
 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)
+  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
+  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)
+  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 {
@@ -206,8 +206,8 @@ model User {
   reviewedChangeRequests      PaymentMethodChangeRequest[] @relation("ChangeReviewer")
 
   // Contract terminations
-  initiatedTerminations       ContractTermination[]        @relation("TerminationInitiator")
-  reviewedTerminations        ContractTermination[]        @relation("TerminationReviewer")
+  initiatedTerminations ContractTermination[] @relation("TerminationInitiator")
+  reviewedTerminations  ContractTermination[] @relation("TerminationReviewer")
 
   @@index([email])
   @@index([tenantId])
@@ -284,7 +284,7 @@ model Tenant {
   documentRequirementRules    DocumentRequirementRule[]
 
   // Contract terminations
-  contractTerminations        ContractTermination[]
+  contractTerminations ContractTermination[]
 
   @@index([subdomain])
   @@map("tenants")
@@ -669,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
 
@@ -765,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?
@@ -879,11 +889,11 @@ 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)
@@ -928,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)
@@ -1183,62 +1198,62 @@ model ContractTermination {
   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}]
+  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
+  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
+  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
+  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
+  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
+  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
+  unitReservedForId String? // If unit being held for another buyer
 
   // Timing
-  requestedAt     DateTime  @default(now())
-  approvedAt      DateTime?
-  executedAt      DateTime?
-  completedAt     DateTime?
-  cancelledAt     DateTime?
+  requestedAt DateTime  @default(now())
+  approvedAt  DateTime?
+  executedAt  DateTime?
+  completedAt DateTime?
+  cancelledAt DateTime?
 
   // Idempotency and audit
-  idempotencyKey  String?   @unique
-  metadata        Json?
+  idempotencyKey String? @unique
+  metadata       Json?
 
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt