@valentine-efagene/qshelter-common 2.0.125 → 2.0.127

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

@@ -10,6 +10,7 @@ export * from './ApplicationTermination';
 export * from './ApprovalRequest';
 export * from './DeviceEndpoint';
 export * from './DocumentRequirementRule';
+export * from './DocumentReview';
 export * from './DocumentTemplate';
 export * from './DocumentationPhase';
 export * from './DocumentationPlan';
@@ -25,6 +26,8 @@ export * from './EventHandlerExecution';
 export * from './EventType';
 export * from './OAuthState';
 export * from './OfferLetter';
+export * from './Organization';
+export * from './OrganizationMember';
 export * from './PasswordReset';
 export * from './PaymentInstallment';
 export * from './PaymentMethodChangeRequest';

package/dist/generated/client/models/index.js

@@ -10,6 +10,7 @@ export * from './ApplicationTermination';
 export * from './ApprovalRequest';
 export * from './DeviceEndpoint';
 export * from './DocumentRequirementRule';
+export * from './DocumentReview';
 export * from './DocumentTemplate';
 export * from './DocumentationPhase';
 export * from './DocumentationPlan';
@@ -25,6 +26,8 @@ export * from './EventHandlerExecution';
 export * from './EventType';
 export * from './OAuthState';
 export * from './OfferLetter';
+export * from './Organization';
+export * from './OrganizationMember';
 export * from './PasswordReset';
 export * from './PaymentInstallment';
 export * from './PaymentMethodChangeRequest';

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

@@ -54,6 +54,7 @@ export type * from './models/DocumentationStepApproval.js';
 export type * from './models/PaymentInstallment.js';
 export type * from './models/ApplicationPayment.js';
 export type * from './models/ApplicationDocument.js';
+export type * from './models/DocumentReview.js';
 export type * from './models/DocumentTemplate.js';
 export type * from './models/OfferLetter.js';
 export type * from './models/ApplicationTermination.js';

package/package.json

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

package/prisma/migrations/20260116152051_add_multi_party_document_review/migration.sql

@@ -0,0 +1,59 @@
+-- AlterTable
+ALTER TABLE `application_documents` ADD COLUMN `replacesDocumentId` VARCHAR(191) NULL,
+    ADD COLUMN `version` INTEGER NOT NULL DEFAULT 1;
+
+-- AlterTable
+ALTER TABLE `documentation_plan_steps` ADD COLUMN `reviewOrder` VARCHAR(191) NULL,
+    ADD COLUMN `reviewRequirements` JSON NULL;
+
+-- AlterTable
+ALTER TABLE `documentation_steps` ADD COLUMN `reviewOrder` VARCHAR(191) NULL,
+    ADD COLUMN `reviewRequirements` JSON NULL;
+
+-- CreateTable
+CREATE TABLE `document_reviews` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `documentId` VARCHAR(191) NOT NULL,
+    `reviewParty` ENUM('INTERNAL', 'BANK', 'DEVELOPER', 'LEGAL', 'GOVERNMENT', 'INSURER', 'CUSTOMER') NOT NULL,
+    `organizationId` VARCHAR(191) NULL,
+    `reviewerId` VARCHAR(191) NULL,
+    `reviewerName` VARCHAR(191) NULL,
+    `decision` ENUM('PENDING', 'APPROVED', 'REJECTED', 'CHANGES_REQUESTED', 'WAIVED') NOT NULL DEFAULT 'PENDING',
+    `comments` TEXT NULL,
+    `concerns` JSON NULL,
+    `requestedAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `dueAt` DATETIME(3) NULL,
+    `reviewedAt` DATETIME(3) NULL,
+    `reviewOrder` INTEGER NOT NULL DEFAULT 0,
+    `parentReviewId` VARCHAR(191) NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `document_reviews_tenantId_idx`(`tenantId`),
+    INDEX `document_reviews_documentId_idx`(`documentId`),
+    INDEX `document_reviews_reviewParty_idx`(`reviewParty`),
+    INDEX `document_reviews_decision_idx`(`decision`),
+    INDEX `document_reviews_reviewerId_idx`(`reviewerId`),
+    INDEX `document_reviews_parentReviewId_idx`(`parentReviewId`),
+    UNIQUE INDEX `document_reviews_documentId_reviewParty_organizationId_key`(`documentId`, `reviewParty`, `organizationId`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateIndex
+CREATE INDEX `application_documents_replacesDocumentId_idx` ON `application_documents`(`replacesDocumentId`);
+
+-- AddForeignKey
+ALTER TABLE `application_documents` ADD CONSTRAINT `application_documents_replacesDocumentId_fkey` FOREIGN KEY (`replacesDocumentId`) REFERENCES `application_documents`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `document_reviews` ADD CONSTRAINT `document_reviews_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `document_reviews` ADD CONSTRAINT `document_reviews_documentId_fkey` FOREIGN KEY (`documentId`) REFERENCES `application_documents`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `document_reviews` ADD CONSTRAINT `document_reviews_reviewerId_fkey` FOREIGN KEY (`reviewerId`) REFERENCES `users`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `document_reviews` ADD CONSTRAINT `document_reviews_parentReviewId_fkey` FOREIGN KEY (`parentReviewId`) REFERENCES `document_reviews`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;

package/prisma/schema.prisma

@@ -201,8 +201,12 @@ enum ApprovalDecision {
 
 /// Type of organization on the platform
 enum OrganizationType {
+  PLATFORM // The platform operator (e.g., QShelter) - the tenant's own organization
   BANK // Financial institution providing mortgages (e.g., Access Bank, GTBank)
   DEVELOPER // Property developer building and selling properties
+  LEGAL // Legal firms handling conveyancing and documentation
+  INSURER // Insurance companies providing property or mortgage insurance
+  GOVERNMENT // Government agencies (e.g., land registry, tax authorities)
 }
 
 /// Status of an organization
@@ -262,6 +266,30 @@ enum CompletionCriterion {
   STEPS_COMPLETED
 }
 
+// =============================================================================
+// MULTI-PARTY DOCUMENT REVIEW ENUMS
+// =============================================================================
+// Enables different organizations to review the same document independently
+// =============================================================================
+
+enum ReviewParty {
+  INTERNAL // Your internal team (compliance, underwriting, etc.)
+  BANK // Partner bank/lender
+  DEVELOPER // Property developer
+  LEGAL // Legal team
+  GOVERNMENT // Government agencies (e.g., land registry)
+  INSURER // Insurance company
+  CUSTOMER // Customer acknowledgment/signature
+}
+
+enum ReviewDecision {
+  PENDING // Review not yet performed
+  APPROVED // Document approved by this party
+  REJECTED // Document rejected (permanent)
+  CHANGES_REQUESTED // Document needs modifications
+  WAIVED // Review not required by this party
+}
+
 enum DocumentStatus {
   DRAFT
   PENDING
@@ -460,6 +488,9 @@ model User {
   approvedRefunds  ApplicationRefund[] @relation("RefundApprover")
   processedRefunds ApplicationRefund[] @relation("RefundProcessor")
 
+  // Document reviews by this user
+  documentReviews DocumentReview[] @relation("DocumentReviewer")
+
   // Organization memberships (user can be employee of banks/developers)
   organizationMemberships OrganizationMember[]
 
@@ -578,9 +609,12 @@ model Organization {
   id       String             @id @default(cuid())
   tenantId String
   name     String // e.g., "Access Bank PLC", "Lekki Gardens Ltd"
-  type     OrganizationType // BANK or DEVELOPER
+  type     OrganizationType // PLATFORM, BANK, DEVELOPER, LEGAL, INSURER, GOVERNMENT
   status   OrganizationStatus @default(PENDING)
 
+  // Platform organization flag - marks the tenant's own organization
+  isPlatformOrg Boolean @default(false)
+
   // Common fields
   email       String? // Primary contact email
   phone       String? // Primary contact phone
@@ -747,6 +781,7 @@ model Tenant {
   domainEvents                DomainEvent[]
   workflowBlockers            WorkflowBlocker[]
   questionnairePlans          QuestionnairePlan[]
+  documentReviews             DocumentReview[]
 
   // Organizations (Banks, Developers) operating on this tenant
   organizations Organization[]
@@ -1271,6 +1306,17 @@ model DocumentationPlanStep {
   // { "all": [{ "questionKey": "has_spouse", "operator": "EQUALS", "value": "YES" }, { "questionKey": "spouse_employed", "operator": "EQUALS", "value": "YES" }] }
   condition Json?
 
+  // =========================================================================
+  // MULTI-PARTY REVIEW CONFIGURATION (for UPLOAD steps)
+  // =========================================================================
+  // Defines which parties must review documents uploaded in this step
+  // Format: [{ party: "INTERNAL", required: true }, { party: "BANK", required: true }]
+  // If null, defaults to single internal review (backward compatible)
+  reviewRequirements Json?
+
+  // Review order: 'SEQUENTIAL' = parties review in order, 'PARALLEL' = all review simultaneously
+  reviewOrder String? // 'SEQUENTIAL' | 'PARALLEL'
+
   // =========================================================================
   // GATE STEP CONFIGURATION (only applicable when stepType = GATE)
   // =========================================================================
@@ -2290,6 +2336,17 @@ model DocumentationStep {
   // Or: { "questionKey": "employment_status", "operator": "IN", "values": ["SELF_EMPLOYED", "BUSINESS_OWNER"] }
   condition Json?
 
+  // =========================================================================
+  // MULTI-PARTY REVIEW CONFIGURATION (for UPLOAD steps)
+  // =========================================================================
+  // Defines which parties must review documents uploaded in this step
+  // Format: [{ party: "INTERNAL", required: true }, { party: "BANK", required: true }]
+  // If null, defaults to single internal review (backward compatible)
+  reviewRequirements Json?
+
+  // Review order: 'SEQUENTIAL' = parties review in order, 'PARALLEL' = all review simultaneously
+  reviewOrder String? // 'SEQUENTIAL' | 'PARALLEL'
+
   // Assignment
   assigneeId String?
   assignee   User?   @relation("DocumentationStepAssignee", fields: [assigneeId], references: [id])
@@ -2465,18 +2522,83 @@ model ApplicationDocument {
 
   status DocumentStatus @default(PENDING)
 
+  // Document versioning (for re-uploads after changes requested)
+  version            Int                   @default(1)
+  replacesDocumentId String? // If this is a revision, points to original
+  replacesDocument   ApplicationDocument?  @relation("DocumentRevisions", fields: [replacesDocumentId], references: [id])
+  revisions          ApplicationDocument[] @relation("DocumentRevisions")
+
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 
+  // Multi-party reviews for this document
+  reviews DocumentReview[]
+
   @@index([tenantId])
   @@index([applicationId])
   @@index([phaseId])
   @@index([stepId])
   @@index([type])
   @@index([status])
+  @@index([replacesDocumentId])
   @@map("application_documents")
 }
 
+// =============================================================================
+// DOCUMENT REVIEW - Multi-party review tracking
+// =============================================================================
+// Tracks reviews by different organizations for the same document
+// Enables internal approval -> external approval workflows
+// =============================================================================
+
+model DocumentReview {
+  id         String              @id @default(cuid())
+  tenantId   String
+  tenant     Tenant              @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  documentId String
+  document   ApplicationDocument @relation(fields: [documentId], references: [id], onDelete: Cascade)
+
+  // Who is reviewing
+  reviewParty    ReviewParty // INTERNAL, BANK, DEVELOPER, LEGAL, etc.
+  organizationId String? // External organization ID if applicable
+  reviewerId     String? // User who performed the review
+  reviewer       User?       @relation("DocumentReviewer", fields: [reviewerId], references: [id])
+  reviewerName   String? // Denormalized for audit trail
+
+  // Review state
+  decision ReviewDecision @default(PENDING)
+  comments String?        @db.Text // General comments
+
+  // Structured concerns for change requests
+  // Format: [{ field: "income_period", issue: "Missing months April-June" }]
+  concerns Json?
+
+  // Review timing
+  requestedAt DateTime  @default(now())
+  dueAt       DateTime? // Optional deadline for this party
+  reviewedAt  DateTime? // When decision was made
+
+  // Review sequence (which order should parties review?)
+  reviewOrder Int @default(0) // 0 = parallel, 1/2/3 = sequential
+
+  // For review chains (re-reviews after changes)
+  parentReviewId String? // If this is a re-review after changes
+  parentReview   DocumentReview?  @relation("ReviewChain", fields: [parentReviewId], references: [id])
+  childReviews   DocumentReview[] @relation("ReviewChain")
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([documentId, reviewParty, organizationId]) // One review per party per org per doc
+  @@index([tenantId])
+  @@index([documentId])
+  @@index([reviewParty])
+  @@index([decision])
+  @@index([reviewerId])
+  @@index([parentReviewId])
+  @@map("document_reviews")
+}
+
 // =============================================================================
 // OFFER LETTERS - Provisional and Final offer documents
 // =============================================================================