@valentine-efagene/qshelter-common 2.0.117 → 2.0.118

package/package.json

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

package/prisma/migrations/20260115084033_add_gate_step_type/migration.sql

@@ -0,0 +1,29 @@
+-- AlterTable
+ALTER TABLE `documentation_plan_steps` ADD COLUMN `allowReject` BOOLEAN NOT NULL DEFAULT true,
+    ADD COLUMN `gateAction` ENUM('APPROVE', 'ACKNOWLEDGE', 'CONFIRM', 'CONSENT') NULL,
+    ADD COLUMN `gateActor` ENUM('ADMIN', 'CUSTOMER', 'SPECIFIC_ROLE') NULL,
+    ADD COLUMN `gateInstructions` TEXT NULL,
+    ADD COLUMN `gateRoleId` VARCHAR(191) NULL,
+    ADD COLUMN `rejectBehavior` ENUM('BLOCK', 'RESTART_STEP', 'RESTART_PHASE', 'TERMINATE') NULL,
+    ADD COLUMN `requiresComment` BOOLEAN NOT NULL DEFAULT false,
+    MODIFY `stepType` ENUM('UPLOAD', 'REVIEW', 'SIGNATURE', 'APPROVAL', 'EXTERNAL_CHECK', 'WAIT', 'GENERATE_DOCUMENT', 'PRE_APPROVAL', 'UNDERWRITING', 'GATE') NOT NULL;
+
+-- AlterTable
+ALTER TABLE `documentation_steps` ADD COLUMN `allowReject` BOOLEAN NOT NULL DEFAULT true,
+    ADD COLUMN `gateActedAt` DATETIME(3) NULL,
+    ADD COLUMN `gateActedById` VARCHAR(191) NULL,
+    ADD COLUMN `gateAction` ENUM('APPROVE', 'ACKNOWLEDGE', 'CONFIRM', 'CONSENT') NULL,
+    ADD COLUMN `gateActor` ENUM('ADMIN', 'CUSTOMER', 'SPECIFIC_ROLE') NULL,
+    ADD COLUMN `gateComment` TEXT NULL,
+    ADD COLUMN `gateDecision` VARCHAR(191) NULL,
+    ADD COLUMN `gateInstructions` TEXT NULL,
+    ADD COLUMN `gateRoleId` VARCHAR(191) NULL,
+    ADD COLUMN `rejectBehavior` ENUM('BLOCK', 'RESTART_STEP', 'RESTART_PHASE', 'TERMINATE') NULL,
+    ADD COLUMN `requiresComment` BOOLEAN NOT NULL DEFAULT false,
+    MODIFY `stepType` ENUM('UPLOAD', 'REVIEW', 'SIGNATURE', 'APPROVAL', 'EXTERNAL_CHECK', 'WAIT', 'GENERATE_DOCUMENT', 'PRE_APPROVAL', 'UNDERWRITING', 'GATE') NOT NULL;
+
+-- AlterTable
+ALTER TABLE `payment_method_phase_steps` MODIFY `stepType` ENUM('UPLOAD', 'REVIEW', 'SIGNATURE', 'APPROVAL', 'EXTERNAL_CHECK', 'WAIT', 'GENERATE_DOCUMENT', 'PRE_APPROVAL', 'UNDERWRITING', 'GATE') NOT NULL;
+
+-- AddForeignKey
+ALTER TABLE `documentation_steps` ADD CONSTRAINT `documentation_steps_gateActedById_fkey` FOREIGN KEY (`gateActedById`) REFERENCES `users`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;

package/prisma/schema.prisma

@@ -92,6 +92,30 @@ enum StepType {
   GENERATE_DOCUMENT // Triggers document generation (offer letters, contracts, etc.)
   PRE_APPROVAL // Customer answers eligibility questionnaire
   UNDERWRITING // System evaluates DTI, score, eligibility
+  GATE // Explicit human gate requiring action (approve, acknowledge, consent)
+}
+
+/// Who must perform a GATE step action
+enum GateActor {
+  ADMIN // Any tenant admin
+  CUSTOMER // The application buyer
+  SPECIFIC_ROLE // Requires gateRoleId to be set
+}
+
+/// What action is required for a GATE step
+enum GateAction {
+  APPROVE // Approve/Reject decision (default)
+  ACKNOWLEDGE // Just acknowledge, no reject option
+  CONFIRM // Confirm details are correct
+  CONSENT // Legal consent (e.g., terms & conditions)
+}
+
+/// What happens when a GATE step is rejected
+enum GateRejectBehavior {
+  BLOCK // Block progression, admin must resolve
+  RESTART_STEP // Reset this step to pending
+  RESTART_PHASE // Reset entire phase
+  TERMINATE // Terminate the application
 }
 
 enum StepStatus {
@@ -353,9 +377,10 @@ model User {
   applicationPayments ApplicationPayment[] @relation("ApplicationPayer")
 
   // Documentation step assignments and approvals
-  assignedSteps DocumentationStep[]         @relation("DocumentationStepAssignee")
-  stepApprovals DocumentationStepApproval[] @relation("DocumentationStepApprover")
-  uploadedDocs  ApplicationDocument[]       @relation("DocumentUploader")
+  assignedSteps  DocumentationStep[]         @relation("DocumentationStepAssignee")
+  gateActedSteps DocumentationStep[]         @relation("GateActedBy")
+  stepApprovals  DocumentationStepApproval[] @relation("DocumentationStepApprover")
+  uploadedDocs   ApplicationDocument[]       @relation("DocumentUploader")
 
   // Payment method changes
   paymentMethodChangeRequests PaymentMethodChangeRequest[] @relation("ChangeRequestor")
@@ -1091,6 +1116,17 @@ model DocumentationPlanStep {
   // { "all": [{ "questionKey": "has_spouse", "operator": "EQUALS", "value": "YES" }, { "questionKey": "spouse_employed", "operator": "EQUALS", "value": "YES" }] }
   condition Json?
 
+  // =========================================================================
+  // GATE STEP CONFIGURATION (only applicable when stepType = GATE)
+  // =========================================================================
+  gateActor          GateActor? // Who must perform the action
+  gateAction         GateAction? // What action is required
+  gateRoleId         String? // If gateActor = SPECIFIC_ROLE, which role
+  gateInstructions   String?    @db.Text // Instructions shown to actor
+  allowReject        Boolean    @default(true) // Can the actor reject?
+  rejectBehavior     GateRejectBehavior? // What happens on reject
+  requiresComment    Boolean    @default(false) // Must actor provide a comment?
+
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 
@@ -2067,6 +2103,24 @@ model DocumentationStep {
   // Required document types for UPLOAD steps (normalized)
   requiredDocuments DocumentationStepDocument[]
 
+  // =========================================================================
+  // GATE STEP CONFIGURATION (only applicable when stepType = GATE)
+  // =========================================================================
+  gateActor          GateActor? // Who must perform the action
+  gateAction         GateAction? // What action is required
+  gateRoleId         String? // If gateActor = SPECIFIC_ROLE, which role
+  gateInstructions   String?    @db.Text // Instructions shown to actor
+  allowReject        Boolean    @default(true) // Can the actor reject?
+  rejectBehavior     GateRejectBehavior? // What happens on reject
+  requiresComment    Boolean    @default(false) // Must actor provide a comment?
+
+  // Gate action tracking
+  gateActedAt        DateTime? // When the gate action was performed
+  gateActedById      String? // Who performed the gate action
+  gateActedBy        User?      @relation("GateActedBy", fields: [gateActedById], references: [id])
+  gateDecision       String? // APPROVED, REJECTED, ACKNOWLEDGED, etc.
+  gateComment        String?    @db.Text // Comment from actor
+
   // Timing
   dueDate     DateTime?
   completedAt DateTime?