@valentine-efagene/qshelter-common 2.0.56 → 2.0.58

package/package.json

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

package/prisma/migrations/20260105081842_unify_contract_events/migration.sql

@@ -0,0 +1,37 @@
+/*
+  Warnings:
+
+  - You are about to drop the column `createdAt` on the `contract_events` table. All the data in the column will be lost.
+  - You are about to drop the column `event` on the `contract_events` table. All the data in the column will be lost.
+  - You are about to alter the column `data` on the `contract_events` table. The data in that column could be lost. The data in that column will be cast from `Text` to `Json`.
+  - You are about to drop the `contract_transitions` table. If the table is not empty, all the data it contains will be lost.
+  - Added the required column `eventType` to the `contract_events` table without a default value. This is not possible if the table is not empty.
+
+*/
+-- DropForeignKey
+ALTER TABLE `contract_transitions` DROP FOREIGN KEY `contract_transitions_contractId_fkey`;
+
+-- AlterTable
+ALTER TABLE `contract_events` DROP COLUMN `createdAt`,
+    DROP COLUMN `event`,
+    ADD COLUMN `actorId` VARCHAR(191) NULL,
+    ADD COLUMN `actorType` VARCHAR(191) NULL,
+    ADD COLUMN `eventGroup` VARCHAR(191) NULL,
+    ADD COLUMN `eventType` VARCHAR(191) NOT NULL,
+    ADD COLUMN `fromState` VARCHAR(191) NULL,
+    ADD COLUMN `occurredAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    ADD COLUMN `toState` VARCHAR(191) NULL,
+    ADD COLUMN `trigger` VARCHAR(191) NULL,
+    MODIFY `data` JSON NULL;
+
+-- DropTable
+DROP TABLE `contract_transitions`;
+
+-- CreateIndex
+CREATE INDEX `contract_events_eventType_idx` ON `contract_events`(`eventType`);
+
+-- CreateIndex
+CREATE INDEX `contract_events_eventGroup_idx` ON `contract_events`(`eventGroup`);
+
+-- CreateIndex
+CREATE INDEX `contract_events_occurredAt_idx` ON `contract_events`(`occurredAt`);

package/prisma/migrations/20260105085337_simplify_los_remove_prequalification/migration.sql

@@ -0,0 +1 @@
+-- This is an empty migration.

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])