@valentine-efagene/qshelter-common 2.0.142 → 2.0.144

package/prisma/schema.prisma

@@ -679,6 +679,12 @@ model Organization {
   tenant  Tenant               @relation(fields: [tenantId], references: [id], onDelete: Cascade)
   members OrganizationMember[]
 
+  // Applications where this organization is involved
+  applicationAssignments ApplicationOrganization[]
+
+  // Bank-specific document requirements (for BANK type organizations)
+  documentRequirements BankDocumentRequirement[]
+
   // Properties developed by this organization (for DEVELOPERs)
   // developedProperties Property[] @relation("PropertyDeveloper")
 
@@ -728,6 +734,83 @@ model OrganizationMember {
   @@map("organization_members")
 }
 
+// =============================================================================
+// BANK DOCUMENT REQUIREMENTS - Bank-specific document overlays
+// =============================================================================
+// Banks have different risk appetites and compliance requirements.
+// For a standardized product (e.g., NHF Mortgage), the payment structure is fixed
+// but document requirements vary by bank.
+//
+// This model defines OVERLAY rules:
+// - Base documents come from DocumentationPlan
+// - Bank adds/modifies requirements via BankDocumentRequirement
+//
+// When switching banks mid-application:
+// 1. Keep all existing approved documents
+// 2. Query new bank's requirements
+// 3. Calculate delta (what's missing)
+// 4. Customer uploads only the delta
+// =============================================================================
+
+/// How the bank's requirement modifies the base requirement
+enum BankDocumentModifier {
+  REQUIRED // Bank requires this document (add if not in base)
+  OPTIONAL // Bank makes this optional (override base if required)
+  NOT_REQUIRED // Bank doesn't need this (skip even if in base)
+  STRICTER // Bank has stricter version (e.g., 12 months instead of 6)
+}
+
+/// Bank Document Requirement - Bank-specific document rules
+model BankDocumentRequirement {
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  // Which bank this applies to
+  organizationId String
+  organization   Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+
+  // Which phase type this applies to (e.g., KYC, VERIFICATION)
+  phaseType String
+
+  // Optional: specific payment method (NULL = applies to all)
+  paymentMethodId String?
+  paymentMethod   PropertyPaymentMethod? @relation(fields: [paymentMethodId], references: [id])
+
+  // Document identification
+  documentType String // ID_CARD, BANK_STATEMENT, EMPLOYMENT_LETTER, etc.
+  documentName String // Human-readable override (e.g., "12 Months Bank Statement")
+
+  // How this modifies the base requirement
+  modifier BankDocumentModifier @default(REQUIRED)
+
+  // Bank-specific rules
+  description      String? @db.Text // Bank's specific instructions
+  expiryDays       Int? // Bank's validity period (may be stricter than base)
+  minFiles         Int? // Bank may require more files
+  maxFiles         Int?
+  allowedMimeTypes String? // Bank may restrict file types
+
+  // Bank-specific validation (JSON schema)
+  // Example: { "bankStatementMonths": 12, "minimumBalance": 500000 }
+  validationRules Json?
+
+  // Priority for conflict resolution (higher = takes precedence)
+  priority Int @default(100)
+
+  isActive  Boolean  @default(true)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([organizationId, phaseType, documentType, paymentMethodId])
+  @@index([tenantId])
+  @@index([organizationId])
+  @@index([phaseType])
+  @@index([documentType])
+  @@index([paymentMethodId])
+  @@map("bank_document_requirements")
+}
+
 model Tenant {
   id        String   @id @default(cuid())
   name      String
@@ -815,9 +898,18 @@ model Tenant {
   questionnairePhaseReviews   QuestionnairePhaseReview[]
   documentReviews             DocumentReview[]
 
+  // Bank-specific document requirements
+  bankDocumentRequirements BankDocumentRequirement[]
+
   // Organizations (Banks, Developers) operating on this tenant
   organizations Organization[]
 
+  // Application organization assignments
+  applicationOrganizations ApplicationOrganization[]
+
+  // State machine audit
+  stateTransitionLogs StateTransitionLog[]
+
   @@index([subdomain])
   @@map("tenants")
 }
@@ -1570,6 +1662,9 @@ model PropertyPaymentMethod {
   changeRulesFrom DocumentRequirementRule[] @relation("RuleFromMethod")
   changeRulesTo   DocumentRequirementRule[] @relation("RuleToMethod")
 
+  // Bank-specific document requirements for this payment method
+  bankDocumentRequirements BankDocumentRequirement[]
+
   @@unique([tenantId, name]) // Unique per tenant
   @@index([tenantId])
   @@map("property_payment_methods")
@@ -1914,6 +2009,17 @@ model Application {
   paymentMethodId String? // PropertyPaymentMethod used to create this contract
   paymentMethod   PropertyPaymentMethod? @relation(fields: [paymentMethodId], references: [id])
 
+  // =========================================================================
+  // PAYMENT METHOD VERSION SNAPSHOT
+  // =========================================================================
+  // Captures the payment method configuration at application creation time.
+  // This ensures existing applications continue with original terms even if
+  // the payment method template is later modified.
+  // =========================================================================
+  paymentMethodSnapshot     Json? // Full snapshot of PropertyPaymentMethod + phases at creation
+  paymentMethodSnapshotAt   DateTime? // When the snapshot was taken
+  paymentMethodSnapshotHash String? // Hash to detect if template changed since snapshot
+
   // Contract identification
   applicationNumber String  @unique
   title             String
@@ -1971,6 +2077,9 @@ model Application {
   // Refund requests
   refunds ApplicationRefund[]
 
+  // Organization assignments - which orgs are involved in this application
+  organizations ApplicationOrganization[]
+
   @@index([tenantId])
   @@index([propertyUnitId])
   @@index([buyerId])
@@ -1982,6 +2091,104 @@ model Application {
   @@map("applications")
 }
 
+// =============================================================================
+// APPLICATION ORGANIZATION - Binds organizations to specific applications
+// =============================================================================
+// Tracks which organizations (banks, developers, legal firms) are involved
+// in a specific application. This enables:
+// 1. Validation that only assigned developers can upload sales offers
+// 2. Only assigned banks can upload preapproval/mortgage offer letters
+// 3. Multi-bank application support (future: apply to multiple banks)
+// =============================================================================
+
+/// Role that an organization plays in an application
+enum ApplicationOrganizationRole {
+  DEVELOPER // Property developer - uploads sales offer letters
+  LENDER // Bank/financial institution - provides mortgage
+  LEGAL // Legal firm - handles conveyancing
+  INSURER // Insurance company
+  GOVERNMENT // Government agency (land registry, etc.)
+}
+
+/// Status of organization's involvement in the application
+enum ApplicationOrganizationStatus {
+  PENDING // Awaiting organization's response/engagement
+  ACTIVE // Organization is actively participating
+  COMPLETED // Organization's role is complete
+  DECLINED // Organization declined to participate
+  WITHDRAWN // Organization withdrew from the application
+}
+
+model ApplicationOrganization {
+  id            String      @id @default(cuid())
+  tenantId      String
+  tenant        Tenant      @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  applicationId String
+  application   Application @relation(fields: [applicationId], references: [id], onDelete: Cascade)
+
+  // Which organization is involved
+  organizationId String
+  organization   Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+
+  // What role does this organization play
+  role   ApplicationOrganizationRole
+  status ApplicationOrganizationStatus @default(PENDING)
+
+  // Who assigned this organization (admin or system)
+  assignedById String?
+  assignedAt   DateTime @default(now())
+
+  // For multi-bank applications: track if this is the selected lender
+  // Multiple banks can be PENDING, but only one should be ACTIVE for LENDER role
+  isPrimary Boolean @default(false)
+
+  // Organization-specific terms (e.g., bank's offered interest rate)
+  offeredTerms     Json? // { interestRate, termMonths, conditions, etc. }
+  termsOfferedAt   DateTime?
+  termsAcceptedAt  DateTime?
+  termsDeclinedAt  DateTime?
+  declineReason    String?   @db.Text
+
+  // Tracking
+  activatedAt  DateTime?
+  completedAt  DateTime?
+  withdrawnAt  DateTime?
+
+  // =========================================================================
+  // SLA TRACKING - Monitor bank responsiveness
+  // =========================================================================
+  // When documentation is complete, clock starts for bank to respond.
+  // If they're slow, admin can reassign to another bank.
+  // =========================================================================
+  slaHours           Int?      // Expected response time (e.g., 48 hours)
+  slaStartedAt       DateTime? // When clock started (e.g., when docs were complete)
+  slaBreachedAt      DateTime? // When SLA was breached (set by cron job)
+  slaBreachNotified  Boolean   @default(false) // Was admin notified of breach?
+  
+  // Reminder tracking
+  reminderCount      Int       @default(0)
+  lastReminderSentAt DateTime?
+  nextReminderAt     DateTime?
+  
+  // Escalation
+  escalatedAt       DateTime?
+  escalatedToUserId String?   // Admin handling the escalation
+  escalationNotes   String?   @db.Text
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([applicationId, organizationId, role]) // One org per role per application
+  @@index([tenantId])
+  @@index([applicationId])
+  @@index([organizationId])
+  @@index([role])
+  @@index([status])
+  @@index([isPrimary])
+  @@index([slaBreachedAt])
+  @@map("application_organizations")
+}
+
 // =============================================================================
 // CONTRACT REFUNDS - Track refund requests for overpayments or cancellations
 // =============================================================================
@@ -2182,8 +2389,8 @@ model QuestionnairePhaseReview {
   notes      String?        @db.Text
 
   // Snapshot of scores at time of review (for audit)
-  scoreAtReview   Int? // The totalScore when this review was made
-  passedAtReview  Boolean? // The passed flag when this review was made
+  scoreAtReview  Int? // The totalScore when this review was made
+  passedAtReview Boolean? // The passed flag when this review was made
 
   createdAt DateTime @default(now())
 
@@ -2478,6 +2685,29 @@ model ApplicationDocument {
   uploadedById String?
   uploadedBy   User?   @relation("DocumentUploader", fields: [uploadedById], references: [id])
 
+  // =========================================================================
+  // UPLOADER VALIDATION - Enforces who can upload this document
+  // =========================================================================
+  // expectedUploader is set from DocumentDefinition.uploadedBy at phase creation
+  // Allows validation that correct party is uploading (e.g., developer uploads sales offer)
+  expectedUploader UploadedBy? // CUSTOMER, LENDER, DEVELOPER, LEGAL, PLATFORM, etc.
+  // If expectedUploader is LENDER/DEVELOPER, track which org should upload
+  expectedOrganizationId String?
+
+  // =========================================================================
+  // DOCUMENT EXPIRY - Time-sensitive document tracking
+  // =========================================================================
+  // Documents like bank statements have a shelf life. If application takes too long,
+  // documents may need to be re-uploaded.
+  // =========================================================================
+  documentDate     DateTime? // When the document was issued/created (e.g., bank statement date)
+  expiresAt        DateTime? // When this document expires (computed from documentDate + expiryDays)
+  expiryDays       Int? // Number of days this document type is valid (copied from DocumentDefinition)
+  isExpired        Boolean   @default(false) // Denormalized flag, updated by cron job
+  expiredAt        DateTime? // When the document was marked expired
+  expiryWarningAt  DateTime? // When expiry warning was sent
+  revalidatedAt    DateTime? // If document was re-uploaded after expiry
+
   status DocumentStatus @default(PENDING)
 
   // NO versioning - document is replaced on re-upload (url is updated)
@@ -2504,6 +2734,8 @@ model ApplicationDocument {
   @@index([documentType])
   @@index([status])
   @@index([replacesDocumentId])
+  @@index([isExpired])
+  @@index([expiresAt])
   @@map("application_documents")
 }
 
@@ -3504,3 +3736,192 @@ model WorkflowBlocker {
   @@index([tenantId, isOverdue, blockerActor]) // For SLA violation queries
   @@map("workflow_blockers")
 }
+
+// =============================================================================
+// STATE MACHINE DEFINITION - Explicit state transitions
+// =============================================================================
+// Defines valid state transitions for applications and phases.
+// This makes the state machine configurable and auditable, rather than
+// being hard-coded in service logic.
+// =============================================================================
+
+/// Entity type that has state machine behavior
+enum StateMachineEntity {
+  APPLICATION
+  APPLICATION_PHASE
+  DOCUMENTATION_STAGE
+  DOCUMENT
+}
+
+/// State Machine Transition Definition - Configurable state transitions
+/// Allows admins to customize workflows without code changes
+model StateTransitionDefinition {
+  id       String @id @default(cuid())
+  tenantId String? // NULL = global template, set = tenant-specific override
+
+  // What entity this transition applies to
+  entityType StateMachineEntity
+
+  // The transition
+  fromState String // e.g., "DRAFT", "PENDING", "IN_PROGRESS"
+  toState   String // e.g., "ACTIVE", "COMPLETED"
+  trigger   String // e.g., "SUBMIT", "APPROVE", "COMPLETE"
+
+  // Transition constraints
+  isEnabled     Boolean @default(true)
+  requiresRole  String? // Role required to trigger this transition
+  requiresPhase String? // Phase type required (for APPLICATION transitions)
+
+  // Side effects configuration
+  sideEffects Json? // [{ type: "SEND_EMAIL", config: {...} }, { type: "LOCK_UNIT" }]
+
+  // Audit
+  description String?  @db.Text
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  @@unique([tenantId, entityType, fromState, trigger])
+  @@index([entityType])
+  @@index([fromState])
+  @@index([trigger])
+  @@map("state_transition_definitions")
+}
+
+/// State Transition Log - Audit trail for all state changes
+/// Records every state transition for compliance and debugging
+model StateTransitionLog {
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  // What entity changed state
+  entityType StateMachineEntity
+  entityId   String // Application ID, Phase ID, Document ID, etc.
+
+  // The transition that occurred
+  fromState String
+  toState   String
+  trigger   String
+
+  // Who triggered the transition
+  actorId   String?
+  actorType EventActorType?
+
+  // Context at time of transition
+  contextSnapshot Json? // Relevant data at time of transition (phase data, payment amounts, etc.)
+
+  // Timing
+  occurredAt DateTime @default(now())
+  durationMs Int? // How long the entity was in fromState
+
+  // Validation
+  wasValid     Boolean @default(true) // Was this a valid transition per state machine?
+  errorMessage String? @db.Text // If invalid, why?
+
+  @@index([tenantId])
+  @@index([entityType, entityId])
+  @@index([entityType, fromState])
+  @@index([entityType, toState])
+  @@index([occurredAt])
+  @@index([actorId])
+  @@map("state_transition_logs")
+}
+
+// =============================================================================
+// DOCUMENT EXPIRY JOB - Scheduled job tracking for document expiration checks
+// =============================================================================
+// Tracks scheduled jobs for checking document expiration across applications.
+// This supports a cron-based approach where a Lambda runs periodically to:
+// 1. Find documents nearing expiry (warning)
+// 2. Mark expired documents
+// 3. Notify customers to re-upload
+// 4. Optionally block phase progression if critical documents expired
+// =============================================================================
+
+/// Job status for scheduled background jobs
+enum ScheduledJobStatus {
+  PENDING
+  RUNNING
+  COMPLETED
+  FAILED
+  CANCELLED
+}
+
+/// Type of scheduled job
+enum ScheduledJobType {
+  DOCUMENT_EXPIRY_CHECK // Check for expired documents
+  SLA_BREACH_CHECK // Check for SLA breaches
+  PAYMENT_REMINDER // Send payment reminders
+  DOCUMENT_EXPIRY_WARNING // Warn about documents nearing expiry
+}
+
+/// Scheduled Job - Tracks execution of background jobs
+model ScheduledJob {
+  id       String @id @default(cuid())
+  tenantId String? // NULL = system-wide job, set = tenant-specific
+
+  jobType ScheduledJobType
+  status  ScheduledJobStatus @default(PENDING)
+
+  // Scheduling
+  scheduledAt DateTime // When the job should run
+  startedAt   DateTime? // When job started executing
+  completedAt DateTime? // When job finished
+  durationMs  Int? // Execution time
+
+  // Job parameters
+  parameters Json? // Job-specific configuration
+
+  // Results
+  itemsProcessed Int     @default(0)
+  itemsAffected  Int     @default(0) // Documents expired, SLAs breached, etc.
+  errorCount     Int     @default(0)
+  errors         Json? // Array of error details
+  summary        String? @db.Text // Human-readable summary
+
+  // Retry handling
+  attemptNumber Int       @default(1)
+  maxAttempts   Int       @default(3)
+  nextRetryAt   DateTime?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([tenantId])
+  @@index([jobType])
+  @@index([status])
+  @@index([scheduledAt])
+  @@index([jobType, status, scheduledAt])
+  @@map("scheduled_jobs")
+}
+
+/// Document Expiry Warning - Track warnings sent for expiring documents
+model DocumentExpiryWarning {
+  id         String @id @default(cuid())
+  tenantId   String
+  documentId String
+
+  // Warning details
+  expiresAt  DateTime // When document will expire
+  daysUntil  Int // Days until expiry at time of warning
+  warningSent DateTime @default(now())
+
+  // Customer notification tracking
+  notificationSent Boolean @default(false)
+  notificationId   String? // Reference to notification service
+
+  // Resolution tracking
+  resolved      Boolean   @default(false)
+  resolvedAt    DateTime?
+  resolvedBy    String? // User who resolved (re-uploaded document)
+  newDocumentId String? // ID of the replacement document
+
+  createdAt DateTime @default(now())
+
+  @@unique([documentId, daysUntil]) // One warning per document per threshold
+  @@index([tenantId])
+  @@index([documentId])
+  @@index([expiresAt])
+  @@index([resolved])
+  @@map("document_expiry_warnings")
+}