@valentine-efagene/qshelter-common 2.0.57 → 2.0.60

package/package.json

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

package/prisma/migrations/20260105094604_workflow_tracking_current_step/migration.sql

@@ -0,0 +1,14 @@
+-- AlterTable
+ALTER TABLE `contract_phase_steps` ADD COLUMN `actionReason` TEXT NULL,
+    ADD COLUMN `lastSubmittedAt` DATETIME(3) NULL,
+    ADD COLUMN `submissionCount` INTEGER NOT NULL DEFAULT 0,
+    MODIFY `status` ENUM('PENDING', 'IN_PROGRESS', 'COMPLETED', 'FAILED', 'SKIPPED', 'NEEDS_RESUBMISSION', 'ACTION_REQUIRED', 'AWAITING_REVIEW') NOT NULL DEFAULT 'PENDING';
+
+-- AlterTable
+ALTER TABLE `contract_phases` ADD COLUMN `currentStepId` VARCHAR(191) NULL;
+
+-- CreateIndex
+CREATE INDEX `contract_phases_currentStepId_idx` ON `contract_phases`(`currentStepId`);
+
+-- AddForeignKey
+ALTER TABLE `contract_phases` ADD CONSTRAINT `contract_phases_currentStepId_fkey` FOREIGN KEY (`currentStepId`) REFERENCES `contract_phase_steps`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;

package/prisma/schema.prisma

@@ -79,6 +79,9 @@ enum StepStatus {
   COMPLETED
   FAILED
   SKIPPED
+  NEEDS_RESUBMISSION // User must re-upload or correct something (after rejection)
+  ACTION_REQUIRED // User action needed (generic - check actionReason)
+  AWAITING_REVIEW // Submitted, waiting for admin/system review
 }
 
 enum InstallmentStatus {
@@ -965,6 +968,15 @@ model ContractPhase {
   // FSM state for this phase (DB-enforced enum)
   status PhaseStatus @default(PENDING)
 
+  // =========================================================================
+  // WORKFLOW TRACKING - Current step pointer for UX and orchestration
+  // =========================================================================
+  // Canonical pointer to the step currently requiring attention.
+  // Updated by service when: phase activates (→ first step), step completes (→ next),
+  // step rejected (→ same step with NEEDS_RESUBMISSION), or phase completes (→ null).
+  currentStepId String?
+  currentStep   DocumentationStep? @relation("CurrentStep", fields: [currentStepId], references: [id])
+
   // Financial details (for PAYMENT phases)
   totalAmount     Float?
   paidAmount      Float  @default(0)
@@ -1012,6 +1024,7 @@ model ContractPhase {
   @@index([phaseCategory])
   @@index([status])
   @@index([order])
+  @@index([currentStepId])
   @@map("contract_phases")
 }
 
@@ -1028,6 +1041,19 @@ model DocumentationStep {
 
   status StepStatus @default(PENDING)
 
+  // =========================================================================
+  // USER ACTION TRACKING - For rejection/resubmission flows
+  // =========================================================================
+  // When status is NEEDS_RESUBMISSION or ACTION_REQUIRED, this explains why.
+  // Populated from DocumentationStepApproval.comment on rejection.
+  actionReason String? @db.Text
+
+  // Number of times this step has been submitted (for tracking resubmissions)
+  submissionCount Int @default(0)
+
+  // Last submission timestamp (for tracking resubmission timing)
+  lastSubmittedAt DateTime?
+
   // Configuration metadata (for GENERATE_DOCUMENT steps, etc.)
   metadata Json?
 
@@ -1054,7 +1080,8 @@ model DocumentationStep {
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 
-  approvals DocumentationStepApproval[]
+  approvals       DocumentationStepApproval[]
+  currentForPhase ContractPhase[]             @relation("CurrentStep")
 
   @@index([phaseId])
   @@index([status])