@valentine-efagene/qshelter-common 2.0.137 → 2.0.139

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

@@ -8,7 +8,11 @@ export * from './ApplicationPhase';
 export * from './ApplicationRefund';
 export * from './ApplicationTermination';
 export * from './ApprovalRequest';
+export * from './ApprovalStage';
+export * from './ApprovalStageProgress';
 export * from './DeviceEndpoint';
+export * from './DocumentApproval';
+export * from './DocumentDefinition';
 export * from './DocumentRequirementRule';
 export * from './DocumentReview';
 export * from './DocumentTemplate';

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

@@ -8,7 +8,11 @@ export * from './ApplicationPhase';
 export * from './ApplicationRefund';
 export * from './ApplicationTermination';
 export * from './ApprovalRequest';
+export * from './ApprovalStage';
+export * from './ApprovalStageProgress';
 export * from './DeviceEndpoint';
+export * from './DocumentApproval';
+export * from './DocumentDefinition';
 export * from './DocumentRequirementRule';
 export * from './DocumentReview';
 export * from './DocumentTemplate';

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

@@ -29,6 +29,8 @@ export type * from './models/PropertyUnit.js';
 export type * from './models/PropertyAmenity.js';
 export type * from './models/DocumentationPlan.js';
 export type * from './models/DocumentationPlanStep.js';
+export type * from './models/DocumentDefinition.js';
+export type * from './models/ApprovalStage.js';
 export type * from './models/QuestionnairePlan.js';
 export type * from './models/QuestionnairePlanQuestion.js';
 export type * from './models/PaymentPlan.js';
@@ -55,6 +57,8 @@ 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/ApprovalStageProgress.js';
+export type * from './models/DocumentApproval.js';
 export type * from './models/DocumentTemplate.js';
 export type * from './models/OfferLetter.js';
 export type * from './models/ApplicationTermination.js';

package/dist/src/utils/documentation-enums.d.ts

@@ -1,9 +1,13 @@
 /**
  * Documentation-related enums for documentation plan steps.
  * Used in DocumentationPlanStep metadata to indicate upload responsibility.
+ *
+ * NOTE: The UploadedBy Prisma enum is now the source of truth.
+ * This constant object is kept for backward compatibility.
  */
 /**
  * Indicates who is responsible for uploading a document in a documentation step.
+ * @deprecated Use the UploadedBy Prisma enum instead
  */
 export declare const UPLOADED_BY: {
     /** Document is uploaded by the customer/applicant */
@@ -16,10 +20,15 @@ export declare const UPLOADED_BY: {
     readonly DEVELOPER: "DEVELOPER";
     /** Document is uploaded by the system (auto-generated) */
     readonly SYSTEM: "SYSTEM";
+    /** Document is uploaded by the platform staff */
+    readonly PLATFORM: "PLATFORM";
     /** Document is uploaded by a legal officer */
     readonly LEGAL: "LEGAL";
+    /** Document is uploaded by an insurer */
+    readonly INSURER: "INSURER";
 };
 /**
  * Type representing a valid uploadedBy value.
+ * @deprecated Use the UploadedBy Prisma enum instead
  */
-export type UploadedBy = (typeof UPLOADED_BY)[keyof typeof UPLOADED_BY];
+export type UploadedByType = (typeof UPLOADED_BY)[keyof typeof UPLOADED_BY];

package/dist/src/utils/documentation-enums.js

@@ -1,9 +1,13 @@
 /**
  * Documentation-related enums for documentation plan steps.
  * Used in DocumentationPlanStep metadata to indicate upload responsibility.
+ *
+ * NOTE: The UploadedBy Prisma enum is now the source of truth.
+ * This constant object is kept for backward compatibility.
  */
 /**
  * Indicates who is responsible for uploading a document in a documentation step.
+ * @deprecated Use the UploadedBy Prisma enum instead
  */
 export const UPLOADED_BY = {
     /** Document is uploaded by the customer/applicant */
@@ -16,6 +20,10 @@ export const UPLOADED_BY = {
     DEVELOPER: 'DEVELOPER',
     /** Document is uploaded by the system (auto-generated) */
     SYSTEM: 'SYSTEM',
+    /** Document is uploaded by the platform staff */
+    PLATFORM: 'PLATFORM',
     /** Document is uploaded by a legal officer */
     LEGAL: 'LEGAL',
+    /** Document is uploaded by an insurer */
+    INSURER: 'INSURER',
 };

package/package.json

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

package/prisma/migrations/20260119180401_add_document_name_remove_required_doc_types/migration.sql

@@ -0,0 +1,14 @@
+/*
+  Warnings:
+
+  - You are about to drop the column `requiredDocumentTypes` on the `documentation_plans` table. All the data in the column will be lost.
+
+*/
+-- AlterTable
+ALTER TABLE `documentation_plan_steps` ADD COLUMN `documentName` VARCHAR(191) NULL;
+
+-- AlterTable
+ALTER TABLE `documentation_plans` DROP COLUMN `requiredDocumentTypes`;
+
+-- AlterTable
+ALTER TABLE `documentation_steps` ADD COLUMN `documentName` VARCHAR(191) NULL;

package/prisma/migrations/20260119190336_add_document_approval_workflow/migration.sql

@@ -0,0 +1,134 @@
+-- AlterTable
+ALTER TABLE `application_documents` ADD COLUMN `documentName` VARCHAR(191) NULL,
+    ADD COLUMN `documentType` VARCHAR(191) NULL,
+    MODIFY `status` ENUM('DRAFT', 'PENDING', 'PENDING_SIGNATURE', 'SENT', 'VIEWED', 'SIGNED', 'APPROVED', 'REJECTED', 'EXPIRED', 'CANCELLED', 'NEEDS_REUPLOAD') NOT NULL DEFAULT 'PENDING';
+
+-- CreateTable
+CREATE TABLE `document_definitions` (
+    `id` VARCHAR(191) NOT NULL,
+    `planId` VARCHAR(191) NOT NULL,
+    `documentType` VARCHAR(191) NOT NULL,
+    `documentName` VARCHAR(191) NOT NULL,
+    `uploadedBy` ENUM('CUSTOMER', 'LENDER', 'DEVELOPER', 'LEGAL', 'INSURER', 'PLATFORM') NOT NULL DEFAULT 'CUSTOMER',
+    `order` INTEGER NOT NULL,
+    `isRequired` BOOLEAN NOT NULL DEFAULT true,
+    `description` TEXT NULL,
+    `maxSizeBytes` INTEGER NULL,
+    `allowedMimeTypes` VARCHAR(191) NULL,
+    `expiryDays` INTEGER NULL,
+    `minFiles` INTEGER NOT NULL DEFAULT 1,
+    `maxFiles` INTEGER NOT NULL DEFAULT 1,
+    `condition` JSON NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `document_definitions_planId_idx`(`planId`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `approval_stages` (
+    `id` VARCHAR(191) NOT NULL,
+    `planId` VARCHAR(191) NOT NULL,
+    `name` VARCHAR(191) NOT NULL,
+    `order` INTEGER NOT NULL,
+    `reviewParty` ENUM('INTERNAL', 'BANK', 'DEVELOPER', 'LEGAL', 'GOVERNMENT', 'INSURER', 'CUSTOMER') NOT NULL,
+    `autoTransition` BOOLEAN NOT NULL DEFAULT false,
+    `waitForAllDocuments` BOOLEAN NOT NULL DEFAULT true,
+    `allowEarlyVisibility` BOOLEAN NOT NULL DEFAULT false,
+    `onRejection` ENUM('CASCADE_BACK', 'RESTART_CURRENT', 'RESTART_FROM_STAGE') NOT NULL DEFAULT 'CASCADE_BACK',
+    `restartFromStageOrder` INTEGER NULL,
+    `organizationId` VARCHAR(191) NULL,
+    `slaHours` INTEGER NULL,
+    `description` TEXT NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `approval_stages_planId_idx`(`planId`),
+    UNIQUE INDEX `approval_stages_planId_order_key`(`planId`, `order`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `approval_stage_progress` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `documentationPhaseId` VARCHAR(191) NOT NULL,
+    `approvalStageId` VARCHAR(191) NOT NULL,
+    `name` VARCHAR(191) NOT NULL,
+    `order` INTEGER NOT NULL,
+    `reviewParty` ENUM('INTERNAL', 'BANK', 'DEVELOPER', 'LEGAL', 'GOVERNMENT', 'INSURER', 'CUSTOMER') NOT NULL,
+    `autoTransition` BOOLEAN NOT NULL DEFAULT false,
+    `waitForAllDocuments` BOOLEAN NOT NULL DEFAULT true,
+    `allowEarlyVisibility` BOOLEAN NOT NULL DEFAULT false,
+    `onRejection` ENUM('CASCADE_BACK', 'RESTART_CURRENT', 'RESTART_FROM_STAGE') NOT NULL DEFAULT 'CASCADE_BACK',
+    `restartFromStageOrder` INTEGER NULL,
+    `status` ENUM('PENDING', 'IN_PROGRESS', 'AWAITING_TRANSITION', 'COMPLETED') NOT NULL DEFAULT 'PENDING',
+    `activatedAt` DATETIME(3) NULL,
+    `completedAt` DATETIME(3) NULL,
+    `completedById` VARCHAR(191) NULL,
+    `transitionComment` TEXT NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `approval_stage_progress_tenantId_idx`(`tenantId`),
+    INDEX `approval_stage_progress_documentationPhaseId_idx`(`documentationPhaseId`),
+    INDEX `approval_stage_progress_approvalStageId_idx`(`approvalStageId`),
+    INDEX `approval_stage_progress_status_idx`(`status`),
+    UNIQUE INDEX `approval_stage_progress_documentationPhaseId_order_key`(`documentationPhaseId`, `order`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `document_approvals` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `documentId` VARCHAR(191) NOT NULL,
+    `stageProgressId` VARCHAR(191) NOT NULL,
+    `reviewerId` VARCHAR(191) NOT NULL,
+    `reviewParty` ENUM('INTERNAL', 'BANK', 'DEVELOPER', 'LEGAL', 'GOVERNMENT', 'INSURER', 'CUSTOMER') NOT NULL,
+    `decision` ENUM('PENDING', 'APPROVED', 'REJECTED', 'CHANGES_REQUESTED', 'WAIVED') NOT NULL,
+    `comment` TEXT NULL,
+    `reviewedAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+
+    INDEX `document_approvals_tenantId_idx`(`tenantId`),
+    INDEX `document_approvals_documentId_idx`(`documentId`),
+    INDEX `document_approvals_stageProgressId_idx`(`stageProgressId`),
+    INDEX `document_approvals_reviewerId_idx`(`reviewerId`),
+    INDEX `document_approvals_decision_idx`(`decision`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateIndex
+CREATE INDEX `application_documents_documentType_idx` ON `application_documents`(`documentType`);
+
+-- AddForeignKey
+ALTER TABLE `document_definitions` ADD CONSTRAINT `document_definitions_planId_fkey` FOREIGN KEY (`planId`) REFERENCES `documentation_plans`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `approval_stages` ADD CONSTRAINT `approval_stages_planId_fkey` FOREIGN KEY (`planId`) REFERENCES `documentation_plans`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `approval_stage_progress` ADD CONSTRAINT `approval_stage_progress_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `approval_stage_progress` ADD CONSTRAINT `approval_stage_progress_documentationPhaseId_fkey` FOREIGN KEY (`documentationPhaseId`) REFERENCES `documentation_phases`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `approval_stage_progress` ADD CONSTRAINT `approval_stage_progress_approvalStageId_fkey` FOREIGN KEY (`approvalStageId`) REFERENCES `approval_stages`(`id`) ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `approval_stage_progress` ADD CONSTRAINT `approval_stage_progress_completedById_fkey` FOREIGN KEY (`completedById`) REFERENCES `users`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `document_approvals` ADD CONSTRAINT `document_approvals_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `document_approvals` ADD CONSTRAINT `document_approvals_documentId_fkey` FOREIGN KEY (`documentId`) REFERENCES `application_documents`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `document_approvals` ADD CONSTRAINT `document_approvals_stageProgressId_fkey` FOREIGN KEY (`stageProgressId`) REFERENCES `approval_stage_progress`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `document_approvals` ADD CONSTRAINT `document_approvals_reviewerId_fkey` FOREIGN KEY (`reviewerId`) REFERENCES `users`(`id`) ON DELETE RESTRICT ON UPDATE CASCADE;

package/prisma/schema.prisma

@@ -301,6 +301,36 @@ enum DocumentStatus {
   REJECTED
   EXPIRED
   CANCELLED
+  NEEDS_REUPLOAD // Document rejected, customer must re-upload
+}
+
+// =============================================================================
+// APPROVAL STAGE ENUMS (Multi-stage document workflow)
+// =============================================================================
+
+/// Status of an approval stage in a documentation phase
+enum StageStatus {
+  PENDING // Not yet activated
+  IN_PROGRESS // Activated, documents being reviewed
+  AWAITING_TRANSITION // All docs approved, waiting for explicit stage completion
+  COMPLETED // Stage completed, next stage can activate
+}
+
+/// Who uploads a document
+enum UploadedBy {
+  CUSTOMER
+  LENDER
+  DEVELOPER
+  LEGAL
+  INSURER
+  PLATFORM // QShelter staff
+}
+
+/// What happens when a later stage rejects a document
+enum RejectionBehavior {
+  CASCADE_BACK // Restart from Stage 1 (default - full re-vetting)
+  RESTART_CURRENT // Only current stage re-reviews after re-upload
+  RESTART_FROM_STAGE // Restart from specific stage (uses restartFromStageOrder)
 }
 
 enum OfferLetterType {
@@ -491,6 +521,12 @@ model User {
   // Document reviews by this user
   documentReviews DocumentReview[] @relation("DocumentReviewer")
 
+  // NEW: Document approval trail entries by this user
+  documentApprovals DocumentApproval[] @relation("DocumentApprovalReviewer")
+
+  // NEW: Approval stages completed by this user
+  completedStages ApprovalStageProgress[] @relation("StageCompletedBy")
+
   // Organization memberships (user can be employee of banks/developers)
   organizationMemberships OrganizationMember[]
 
@@ -783,6 +819,10 @@ model Tenant {
   questionnairePlans          QuestionnairePlan[]
   documentReviews             DocumentReview[]
 
+  // NEW: Approval stage progress and document approvals
+  approvalStageProgress ApprovalStageProgress[]
+  documentApprovals     DocumentApproval[]
+
   // Organizations (Banks, Developers) operating on this tenant
   organizations Organization[]
 
@@ -1256,14 +1296,18 @@ model DocumentationPlan {
   description String? @db.Text
   isActive    Boolean @default(true)
 
-  // Document requirements for this plan
-  requiredDocumentTypes Json? // Array of document type strings, e.g., ["ID_CARD", "BANK_STATEMENT"]
-
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 
-  // Steps that make up this plan
+  // Steps that make up this plan (DEPRECATED - use documentDefinitions + approvalStages)
   steps               DocumentationPlanStep[]
+  
+  // NEW: Document definitions (what documents to collect)
+  documentDefinitions DocumentDefinition[]
+  
+  // NEW: Approval stages (sequential workflow for reviewing documents)
+  approvalStages      ApprovalStage[]
+  
   // Used by property payment method phases (templates)
   methodPhases        PropertyPaymentMethodPhase[]
   // Used by instantiated documentation phases
@@ -1286,6 +1330,9 @@ model DocumentationPlanStep {
 
   // Optional: which document type this step handles (for UPLOAD steps)
   documentType String?
+  // Human-readable document name (e.g., "Valid ID Card" for ID_CARD)
+  // If not provided, step name can be auto-generated: "Upload ${documentName}"
+  documentName String?
   metadata     Json?
 
   // Document validation rules (for UPLOAD steps)
@@ -1335,6 +1382,93 @@ model DocumentationPlanStep {
   @@map("documentation_plan_steps")
 }
 
+// =============================================================================
+// DOCUMENT DEFINITION - What documents to collect (template)
+// =============================================================================
+// Defines a document requirement within a documentation plan.
+// This is separate from approval workflow - just defines WHAT to collect.
+// =============================================================================
+
+model DocumentDefinition {
+  id     String            @id @default(cuid())
+  planId String
+  plan   DocumentationPlan @relation(fields: [planId], references: [id], onDelete: Cascade)
+
+  // Document identification
+  documentType String // ID_CARD, BANK_STATEMENT, EMPLOYMENT_LETTER, etc.
+  documentName String // Human-readable: "Valid ID Card", "6 Months Bank Statement"
+
+  // Who uploads this document
+  uploadedBy UploadedBy @default(CUSTOMER)
+
+  // Display order
+  order Int
+
+  // Validation rules
+  isRequired       Boolean @default(true)
+  description      String? @db.Text // Instructions for the uploader
+  maxSizeBytes     Int? // Max file size allowed (e.g., 5242880 for 5MB)
+  allowedMimeTypes String? // CSV: application/pdf,image/jpeg,image/png
+  expiryDays       Int? // Document must not be older than X days
+  minFiles         Int     @default(1)
+  maxFiles         Int     @default(1)
+
+  // Conditional logic (based on questionnaire answers)
+  // NULL = always required
+  // Example: { "questionKey": "mortgage_type", "operator": "EQUALS", "value": "JOINT" }
+  condition Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([planId])
+  @@map("document_definitions")
+}
+
+// =============================================================================
+// APPROVAL STAGE - Sequential workflow stages for document review (template)
+// =============================================================================
+// Defines a stage in the approval workflow. Documents flow through stages
+// sequentially. Each stage can have different reviewers (INTERNAL, BANK, etc.)
+// =============================================================================
+
+model ApprovalStage {
+  id     String            @id @default(cuid())
+  planId String
+  plan   DocumentationPlan @relation(fields: [planId], references: [id], onDelete: Cascade)
+
+  name        String // "QShelter Staff Review", "Bank Review"
+  order       Int // 1, 2, 3 - sequential order
+  reviewParty ReviewParty // INTERNAL, BANK, DEVELOPER, LEGAL, etc.
+
+  // Stage behavior flags
+  autoTransition       Boolean @default(false) // Auto-complete when all docs approved? Default: require explicit approval
+  waitForAllDocuments  Boolean @default(true) // Wait for all docs approved before allowing transition
+  allowEarlyVisibility Boolean @default(false) // Allow read-only view before stage activates
+
+  // Rejection behavior - what happens when this stage rejects a document
+  onRejection           RejectionBehavior @default(CASCADE_BACK)
+  restartFromStageOrder Int? // If onRejection = RESTART_FROM_STAGE, which stage order to restart from
+
+  // Optional: specific organization (e.g., which bank)
+  organizationId String?
+
+  // SLA (optional)
+  slaHours Int? // Escalate if not completed within X hours
+
+  description String? @db.Text // Instructions for reviewers at this stage
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Runtime instances
+  stageProgress ApprovalStageProgress[]
+
+  @@unique([planId, order])
+  @@index([planId])
+  @@map("approval_stages")
+}
+
 // =============================================================================
 // QUESTIONNAIRE PLAN DOMAIN - Reusable form templates with scoring
 // =============================================================================
@@ -2144,6 +2278,9 @@ model DocumentationPhase {
   // Child records
   steps DocumentationStep[]
 
+  // NEW: Approval stage progress (tracks which stages are completed)
+  stageProgress ApprovalStageProgress[]
+
   @@index([tenantId])
   @@index([phaseId])
   @@index([currentStepId])
@@ -2304,10 +2441,12 @@ model DocumentationStep {
   documentationPhaseId String
   documentationPhase   DocumentationPhase @relation(fields: [documentationPhaseId], references: [id], onDelete: Cascade)
 
-  name        String
-  description String?  @db.Text
-  stepType    StepType
-  order       Int
+  name         String
+  // Human-readable document name (e.g., "Valid ID Card" for ID_CARD)
+  documentName String?
+  description  String?  @db.Text
+  stepType     StepType
+  order        Int
 
   status StepStatus @default(PENDING)
 
@@ -2514,15 +2653,19 @@ model ApplicationDocument {
   phaseId       String? // Optional link to specific phase
   stepId        String? // Optional link to specific step
 
-  name         String
+  // Document info
+  documentType String? // ID_CARD, BANK_STATEMENT, etc. (matches DocumentDefinition.documentType)
+  documentName String? // Human-readable name (copied from DocumentDefinition.documentName)
+  name         String // File name
   url          String
-  type         String // ID, BANK_STATEMENT, INCOME_PROOF, TITLE_DEED, SIGNATURE, etc.
+  type         String // ID, BANK_STATEMENT, INCOME_PROOF, TITLE_DEED, SIGNATURE, etc. (legacy, use documentType)
   uploadedById String?
   uploadedBy   User?   @relation("DocumentUploader", fields: [uploadedById], references: [id])
 
   status DocumentStatus @default(PENDING)
 
-  // Document versioning (for re-uploads after changes requested)
+  // NO versioning - document is replaced on re-upload (url is updated)
+  // Keep these fields for backward compatibility but don't use for new code
   version            Int                   @default(1)
   replacesDocumentId String? // If this is a revision, points to original
   replacesDocument   ApplicationDocument?  @relation("DocumentRevisions", fields: [replacesDocumentId], references: [id])
@@ -2531,14 +2674,18 @@ model ApplicationDocument {
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 
-  // Multi-party reviews for this document
+  // OLD: Multi-party reviews (deprecated, use approvalTrail)
   reviews DocumentReview[]
 
+  // NEW: Full approval trail across all stages
+  approvalTrail DocumentApproval[]
+
   @@index([tenantId])
   @@index([applicationId])
   @@index([phaseId])
   @@index([stepId])
   @@index([type])
+  @@index([documentType])
   @@index([status])
   @@index([replacesDocumentId])
   @@map("application_documents")
@@ -2599,6 +2746,100 @@ model DocumentReview {
   @@map("document_reviews")
 }
 
+// =============================================================================
+// APPROVAL STAGE PROGRESS - Runtime tracking of stage completion per phase
+// =============================================================================
+// Tracks the progress of each approval stage within a documentation phase.
+// Created when a documentation phase is instantiated from a plan.
+// =============================================================================
+
+model ApprovalStageProgress {
+  id                   String             @id @default(cuid())
+  tenantId             String
+  tenant               Tenant             @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  documentationPhaseId String
+  documentationPhase   DocumentationPhase @relation(fields: [documentationPhaseId], references: [id], onDelete: Cascade)
+
+  // Link to template
+  approvalStageId String
+  approvalStage   ApprovalStage @relation(fields: [approvalStageId], references: [id])
+
+  // Stage info (denormalized for convenience)
+  name        String
+  order       Int
+  reviewParty ReviewParty
+
+  // Behavior flags (copied from template)
+  autoTransition       Boolean @default(false)
+  waitForAllDocuments  Boolean @default(true)
+  allowEarlyVisibility Boolean @default(false)
+
+  // Rejection behavior (copied from template)
+  onRejection           RejectionBehavior @default(CASCADE_BACK)
+  restartFromStageOrder Int?
+
+  // Status tracking
+  status      StageStatus @default(PENDING)
+  activatedAt DateTime?
+  completedAt DateTime?
+
+  // Who completed this stage (when autoTransition = false)
+  completedById     String?
+  completedBy       User?   @relation("StageCompletedBy", fields: [completedById], references: [id])
+  transitionComment String? @db.Text // Optional comment when completing stage
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Document approvals made during this stage
+  documentApprovals DocumentApproval[]
+
+  @@unique([documentationPhaseId, order])
+  @@index([tenantId])
+  @@index([documentationPhaseId])
+  @@index([approvalStageId])
+  @@index([status])
+  @@map("approval_stage_progress")
+}
+
+// =============================================================================
+// DOCUMENT APPROVAL - Audit trail for document reviews per stage
+// =============================================================================
+// Records every review action taken on a document within a specific stage.
+// Provides full audit trail: who reviewed, what decision, when, with comments.
+// =============================================================================
+
+model DocumentApproval {
+  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)
+
+  // Which stage this approval belongs to
+  stageProgressId String
+  stageProgress   ApprovalStageProgress @relation(fields: [stageProgressId], references: [id], onDelete: Cascade)
+
+  // Reviewer info
+  reviewerId  String
+  reviewer    User        @relation("DocumentApprovalReviewer", fields: [reviewerId], references: [id])
+  reviewParty ReviewParty // INTERNAL, BANK, etc.
+
+  // Decision
+  decision ReviewDecision // APPROVED, REJECTED, CHANGES_REQUESTED
+  comment  String?        @db.Text // Required on rejection
+
+  reviewedAt DateTime @default(now())
+  createdAt  DateTime @default(now())
+
+  @@index([tenantId])
+  @@index([documentId])
+  @@index([stageProgressId])
+  @@index([reviewerId])
+  @@index([decision])
+  @@map("document_approvals")
+}
+
 // =============================================================================
 // OFFER LETTERS - Provisional and Final offer documents
 // =============================================================================