@valentine-efagene/qshelter-common 2.0.102 → 2.0.104

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

@@ -12,6 +12,8 @@ export * from './DeviceEndpoint';
 export * from './DocumentRequirementRule';
 export * from './DocumentTemplate';
 export * from './DocumentationPhase';
+export * from './DocumentationPlan';
+export * from './DocumentationPlanStep';
 export * from './DocumentationStep';
 export * from './DocumentationStepApproval';
 export * from './DocumentationStepDocument';
@@ -47,6 +49,8 @@ export * from './PropertyVariantAmenity';
 export * from './PropertyVariantMedia';
 export * from './QuestionnaireField';
 export * from './QuestionnairePhase';
+export * from './QuestionnairePlan';
+export * from './QuestionnairePlanQuestion';
 export * from './RefreshToken';
 export * from './Role';
 export * from './RolePermission';

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

@@ -12,6 +12,8 @@ export * from './DeviceEndpoint';
 export * from './DocumentRequirementRule';
 export * from './DocumentTemplate';
 export * from './DocumentationPhase';
+export * from './DocumentationPlan';
+export * from './DocumentationPlanStep';
 export * from './DocumentationStep';
 export * from './DocumentationStepApproval';
 export * from './DocumentationStepDocument';
@@ -47,6 +49,8 @@ export * from './PropertyVariantAmenity';
 export * from './PropertyVariantMedia';
 export * from './QuestionnaireField';
 export * from './QuestionnairePhase';
+export * from './QuestionnairePlan';
+export * from './QuestionnairePlanQuestion';
 export * from './RefreshToken';
 export * from './Role';
 export * from './RolePermission';

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

@@ -25,6 +25,10 @@ export type * from './models/PropertyVariantAmenity.js';
 export type * from './models/PropertyVariantMedia.js';
 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/QuestionnairePlan.js';
+export type * from './models/QuestionnairePlanQuestion.js';
 export type * from './models/PaymentPlan.js';
 export type * from './models/PropertyPaymentMethod.js';
 export type * from './models/PropertyPaymentMethodLink.js';

package/dist/src/prisma/tenant.js

@@ -28,6 +28,10 @@ const GLOBAL_MODELS = [
  */
 const OPTIONAL_TENANT_MODELS = [
     "paymentPlan",
+    // DocumentationPlan can be global template (tenantId = null) or tenant-specific
+    "documentationPlan",
+    // QuestionnairePlan can be global template (tenantId = null) or tenant-specific
+    "questionnairePlan",
     // Role can be global template (tenantId = null) or tenant-specific
     "role",
     // Permission can be global template or tenant-specific

package/package.json

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

package/prisma/migrations/20260114034523_add_documentation_plan/migration.sql

@@ -0,0 +1,52 @@
+-- AlterTable
+ALTER TABLE `documentation_phases` ADD COLUMN `documentationPlanId` VARCHAR(191) NULL;
+
+-- AlterTable
+ALTER TABLE `property_payment_method_phases` ADD COLUMN `documentationPlanId` VARCHAR(191) NULL;
+
+-- CreateTable
+CREATE TABLE `documentation_plans` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NULL,
+    `name` VARCHAR(191) NOT NULL,
+    `description` TEXT NULL,
+    `isActive` BOOLEAN NOT NULL DEFAULT true,
+    `requiredDocumentTypes` JSON NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `documentation_plans_tenantId_idx`(`tenantId`),
+    UNIQUE INDEX `documentation_plans_tenantId_name_key`(`tenantId`, `name`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `documentation_plan_steps` (
+    `id` VARCHAR(191) NOT NULL,
+    `planId` VARCHAR(191) NOT NULL,
+    `name` VARCHAR(191) NOT NULL,
+    `stepType` ENUM('UPLOAD', 'REVIEW', 'SIGNATURE', 'APPROVAL', 'EXTERNAL_CHECK', 'WAIT', 'GENERATE_DOCUMENT', 'PRE_APPROVAL', 'UNDERWRITING') NOT NULL,
+    `order` INTEGER NOT NULL,
+    `documentType` VARCHAR(191) NULL,
+    `metadata` JSON NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `documentation_plan_steps_planId_idx`(`planId`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateIndex
+CREATE INDEX `property_payment_method_phases_documentationPlanId_idx` ON `property_payment_method_phases`(`documentationPlanId`);
+
+-- AddForeignKey
+ALTER TABLE `documentation_plans` ADD CONSTRAINT `documentation_plans_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `documentation_plan_steps` ADD CONSTRAINT `documentation_plan_steps_planId_fkey` FOREIGN KEY (`planId`) REFERENCES `documentation_plans`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `property_payment_method_phases` ADD CONSTRAINT `property_payment_method_phases_documentationPlanId_fkey` FOREIGN KEY (`documentationPlanId`) REFERENCES `documentation_plans`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `documentation_phases` ADD CONSTRAINT `documentation_phases_documentationPlanId_fkey` FOREIGN KEY (`documentationPlanId`) REFERENCES `documentation_plans`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;

package/prisma/schema.prisma

@@ -492,11 +492,12 @@ model Tenant {
   updatedAt DateTime @updatedAt
 
   // Back-relations for multitenancy
-  users          User[]
-  properties     Property[]
-  paymentPlans   PaymentPlan[]
-  paymentMethods PropertyPaymentMethod[]
-  applications   Application[]
+  users              User[]
+  properties         Property[]
+  paymentPlans       PaymentPlan[]
+  documentationPlans DocumentationPlan[]
+  paymentMethods     PropertyPaymentMethod[]
+  applications       Application[]
 
   // RBAC: Tenant-scoped roles and permissions
   roles       Role[]
@@ -566,6 +567,7 @@ model Tenant {
   settings                    Settings[]
   domainEvents                DomainEvent[]
   workflowBlockers            WorkflowBlocker[]
+  questionnairePlans          QuestionnairePlan[]
 
   @@index([subdomain])
   @@map("tenants")
@@ -1023,6 +1025,144 @@ model PropertyAmenity {
   @@map("property_amenities")
 }
 
+// =============================================================================
+// DOCUMENTATION PLAN DOMAIN - Reusable step workflow templates
+// =============================================================================
+
+// DocumentationPlan = reusable structure for documentation workflows
+// Examples: "Standard KYC", "Quick Verification", "Full Underwriting"
+model DocumentationPlan {
+  id          String  @id @default(cuid())
+  tenantId    String? // NULL = global template available to all tenants
+  tenant      Tenant? @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  name        String
+  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               DocumentationPlanStep[]
+  // Used by property payment method phases (templates)
+  methodPhases        PropertyPaymentMethodPhase[]
+  // Used by instantiated documentation phases
+  documentationPhases DocumentationPhase[]
+
+  @@unique([tenantId, name]) // Unique per tenant, or globally if tenantId is null
+  @@index([tenantId])
+  @@map("documentation_plans")
+}
+
+// Step template within a DocumentationPlan
+model DocumentationPlanStep {
+  id     String            @id @default(cuid())
+  planId String
+  plan   DocumentationPlan @relation(fields: [planId], references: [id], onDelete: Cascade)
+
+  name     String
+  stepType StepType
+  order    Int
+
+  // Optional: which document type this step handles (for UPLOAD steps)
+  documentType String?
+  metadata     Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([planId])
+  @@map("documentation_plan_steps")
+}
+
+// =============================================================================
+// QUESTIONNAIRE PLAN DOMAIN - Reusable form templates with scoring
+// =============================================================================
+// QuestionnairePlan = reusable structure for prequalification/screening forms
+// Examples: "Mortgage Prequalification", "Affordability Assessment", "Risk Screening"
+// =============================================================================
+
+model QuestionnairePlan {
+  id          String  @id @default(cuid())
+  tenantId    String? // NULL = global template available to all tenants
+  tenant      Tenant? @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  name        String
+  description String? @db.Text
+  version     Int     @default(1)
+  isActive    Boolean @default(true)
+
+  // Scoring configuration
+  passingScore        Int? // Minimum score to pass (null = no auto-scoring)
+  scoringStrategy     ScoringStrategy @default(SUM)
+  autoDecisionEnabled Boolean         @default(false) // Auto-pass/fail based on score
+
+  // Metadata
+  estimatedMinutes Int? // Estimated time to complete
+  category         QuestionnaireCategory @default(PREQUALIFICATION)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Questions that make up this plan
+  questions QuestionnairePlanQuestion[]
+
+  // Used by property payment method phases (templates)
+  methodPhases PropertyPaymentMethodPhase[]
+
+  // Used by instantiated questionnaire phases
+  questionnairePhases QuestionnairePhase[]
+
+  @@unique([tenantId, name, version])
+  @@index([tenantId])
+  @@index([category])
+  @@map("questionnaire_plans")
+}
+
+// Question template within a QuestionnairePlan
+model QuestionnairePlanQuestion {
+  id                  String            @id @default(cuid())
+  questionnairePlanId String
+  questionnairePlan   QuestionnairePlan @relation(fields: [questionnairePlanId], references: [id], onDelete: Cascade)
+
+  // Question identification
+  questionKey  String // Unique key for this question (e.g., "annual_income")
+  questionText String  @db.Text // The actual question text
+  helpText     String? @db.Text // Optional help/tooltip text
+
+  // Field configuration
+  questionType QuestionType
+  order        Int
+
+  // Validation
+  isRequired      Boolean @default(true)
+  validationRules Json? // { min: 0, max: 1000000, pattern: "^[0-9]+$" }
+
+  // Options for SELECT/MULTI_SELECT/RADIO
+  // [{ value: "employed", label: "Employed", score: 10 }, ...]
+  options Json?
+
+  // Scoring
+  scoreWeight  Int   @default(1) // Multiplier for this question's score
+  scoringRules Json? // { "employed": 10, "self_employed": 7, "unemployed": 0 } or ranges
+
+  // Conditional logic (branching)
+  // { "questionKey": "employment_status", "equals": "employed" }
+  showIf Json?
+
+  // Metadata for grouping
+  category String? // Group questions (e.g., "income", "employment", "property")
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([questionnairePlanId, questionKey])
+  @@index([questionnairePlanId])
+  @@map("questionnaire_plan_questions")
+}
+
 // =============================================================================
 // PAYMENT PLAN DOMAIN - Reusable installment structure templates
 // =============================================================================
@@ -1142,8 +1282,14 @@ model PropertyPaymentMethodPhase {
   tenant          Tenant                @relation(fields: [tenantId], references: [id], onDelete: Cascade)
   paymentMethodId String
   paymentMethod   PropertyPaymentMethod @relation(fields: [paymentMethodId], references: [id], onDelete: Cascade)
-  paymentPlanId   String? // Only for PAYMENT phases
-  paymentPlan     PaymentPlan?          @relation(fields: [paymentPlanId], references: [id])
+
+  // Plan references (only one should be set based on phaseCategory)
+  paymentPlanId       String? // Only for PAYMENT phases
+  paymentPlan         PaymentPlan?       @relation(fields: [paymentPlanId], references: [id])
+  documentationPlanId String? // Only for DOCUMENTATION phases
+  documentationPlan   DocumentationPlan? @relation(fields: [documentationPlanId], references: [id])
+  questionnairePlanId String? // Only for QUESTIONNAIRE phases
+  questionnairePlan   QuestionnairePlan? @relation(fields: [questionnairePlanId], references: [id])
 
   name        String
   description String? @db.Text
@@ -1168,13 +1314,14 @@ model PropertyPaymentMethodPhase {
   completionCriterion             CompletionCriterion?
 
   // Snapshots for audit (original config at creation time)
+  // These are still needed for inline definitions (backward compatibility)
   stepDefinitionsSnapshot  Json?
   requiredDocumentSnapshot Json?
 
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 
-  // Normalized child tables (for DOCUMENTATION phases)
+  // Normalized child tables (for DOCUMENTATION phases - inline definitions)
   steps               PaymentMethodPhaseStep[]
   requiredDocuments   PaymentMethodPhaseDocument[]
   // Normalized child tables (for QUESTIONNAIRE phases)
@@ -1185,6 +1332,8 @@ model PropertyPaymentMethodPhase {
   @@index([tenantId])
   @@index([paymentMethodId])
   @@index([paymentPlanId])
+  @@index([documentationPlanId])
+  @@index([questionnairePlanId])
   @@index([phaseCategory])
   @@map("property_payment_method_phases")
 }
@@ -1318,6 +1467,44 @@ enum FieldType {
   FILE // File upload (single)
 }
 
+// =============================================================================
+// QUESTIONNAIRE PLAN ENUMS - For scoring and categorization
+// =============================================================================
+
+enum QuestionType {
+  TEXT
+  NUMBER
+  CURRENCY
+  DATE
+  SELECT
+  MULTI_SELECT
+  RADIO
+  CHECKBOX
+  FILE_UPLOAD
+  PHONE
+  EMAIL
+  ADDRESS
+  PERCENTAGE
+  YEARS_MONTHS
+}
+
+enum ScoringStrategy {
+  SUM // Add up all scores
+  AVERAGE // Average of all scores
+  WEIGHTED_SUM // Sum with weights (score * weight)
+  MIN_ALL // Must meet minimum on all questions
+  CUSTOM // Use custom scoring function
+}
+
+enum QuestionnaireCategory {
+  PREQUALIFICATION // Initial eligibility screening
+  AFFORDABILITY // Income/expense assessment
+  PROPERTY_INTENT // What property are they looking for
+  RISK_ASSESSMENT // Credit/risk questions
+  COMPLIANCE // KYC/AML questions
+  CUSTOM
+}
+
 // Questionnaire field template within a QUESTIONNAIRE phase
 model PaymentMethodPhaseField {
   id       String                     @id @default(cuid())
@@ -1575,10 +1762,20 @@ model QuestionnairePhase {
   phaseId  String           @unique
   phase    ApplicationPhase @relation(fields: [phaseId], references: [id], onDelete: Cascade)
 
+  // Questionnaire plan reference (if created from a plan)
+  questionnairePlanId String?
+  questionnairePlan   QuestionnairePlan? @relation(fields: [questionnairePlanId], references: [id])
+
   // Progress tracking
   completedFieldsCount Int @default(0)
   totalFieldsCount     Int @default(0)
 
+  // Scoring results (from QuestionnairePlan scoring)
+  totalScore   Int?
+  passingScore Int? // Copied from plan at creation
+  passed       Boolean?
+  scoredAt     DateTime?
+
   // Computed results (for UNDERWRITING phases)
   underwritingScore    Float?
   debtToIncomeRatio    Float?
@@ -1596,6 +1793,7 @@ model QuestionnairePhase {
 
   @@index([tenantId])
   @@index([phaseId])
+  @@index([questionnairePlanId])
   @@map("questionnaire_phases")
 }
 
@@ -1612,6 +1810,10 @@ model DocumentationPhase {
   phaseId  String           @unique
   phase    ApplicationPhase @relation(fields: [phaseId], references: [id], onDelete: Cascade)
 
+  // Documentation plan reference (if created from a plan)
+  documentationPlanId String?
+  documentationPlan   DocumentationPlan? @relation(fields: [documentationPlanId], references: [id])
+
   // Current step pointer for UX and orchestration
   currentStepId String?
   currentStep   DocumentationStep? @relation("CurrentStep", fields: [currentStepId], references: [id])