@valentine-efagene/qshelter-common 2.0.83 → 2.0.86

package/dist/src/events/index.d.ts

@@ -1,5 +1,7 @@
 export * from './notifications/notification-enums';
 export * from './notifications/notification-event';
 export * from './notifications/event-publisher';
+export * from './payments/payment-event';
+export * from './payments/payment-publisher';
 export * from './bus/event-bus.types';
 export * from './bus/event-bus.service';

package/dist/src/events/index.js

@@ -2,6 +2,9 @@
 export * from './notifications/notification-enums';
 export * from './notifications/notification-event';
 export * from './notifications/event-publisher';
+// Payment events and publisher (SNS-based)
+export * from './payments/payment-event';
+export * from './payments/payment-publisher';
 // Event bus (multi-transport delivery)
 export * from './bus/event-bus.types';
 export * from './bus/event-bus.service';

package/dist/src/events/payments/index.d.ts

@@ -0,0 +1,2 @@
+export * from './payment-event';
+export * from './payment-publisher';

package/dist/src/events/payments/index.js

@@ -0,0 +1,2 @@
+export * from './payment-event';
+export * from './payment-publisher';

package/dist/src/events/payments/payment-event.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Payment event types for the payment service queue
+ * These are internal service events, not user-facing notifications
+ */
+export declare enum PaymentEventType {
+    WALLET_CREDITED = "wallet.credited",
+    WALLET_DEBITED = "wallet.debited",
+    WALLET_CREATED = "wallet.created",
+    ALLOCATE_TO_INSTALLMENTS = "payment.allocate_to_installments",
+    PROCESS_INSTALLMENT_PAYMENT = "payment.process_installment",
+    REFUND_PAYMENT = "payment.refund",
+    VIRTUAL_ACCOUNT_FUNDED = "virtualaccount.funded"
+}
+/**
+ * Metadata for payment events
+ */
+export interface PaymentEventMeta {
+    /** Service that published the event */
+    source: string;
+    /** ISO timestamp of when event was created */
+    timestamp: string;
+    /** Correlation ID for distributed tracing */
+    correlationId?: string;
+    /** User ID */
+    userId?: string;
+    /** Tenant ID */
+    tenantId?: string;
+}
+/**
+ * Base payment event structure
+ */
+export interface PaymentEvent<T = Record<string, unknown>> {
+    type: PaymentEventType;
+    payload: T;
+    meta: PaymentEventMeta;
+}
+/**
+ * Payload when wallet is credited
+ */
+export interface WalletCreditedPayload {
+    walletId: string;
+    userId: string;
+    transactionId: string;
+    amount: number;
+    currency: string;
+    newBalance: number;
+    reference: string;
+    source: 'virtual_account' | 'manual' | 'refund';
+}
+/**
+ * Payload for allocating funds to installments
+ */
+export interface AllocateToInstallmentsPayload {
+    userId: string;
+    walletId: string;
+    /** Optional: limit to specific contract */
+    contractId?: string;
+    /** Optional: limit to specific amount */
+    maxAmount?: number;
+}
+/**
+ * Payload for processing an installment payment
+ */
+export interface ProcessInstallmentPaymentPayload {
+    installmentId: string;
+    amount: number;
+    walletId: string;
+    userId: string;
+    reference: string;
+}

package/dist/src/events/payments/payment-event.js

@@ -0,0 +1,18 @@
+/**
+ * Payment event types for the payment service queue
+ * These are internal service events, not user-facing notifications
+ */
+export var PaymentEventType;
+(function (PaymentEventType) {
+    // Wallet events (published by payment service)
+    PaymentEventType["WALLET_CREDITED"] = "wallet.credited";
+    PaymentEventType["WALLET_DEBITED"] = "wallet.debited";
+    PaymentEventType["WALLET_CREATED"] = "wallet.created";
+    // Allocation commands (published by mortgage service or after wallet credit)
+    PaymentEventType["ALLOCATE_TO_INSTALLMENTS"] = "payment.allocate_to_installments";
+    // Payment commands (published by mortgage service)
+    PaymentEventType["PROCESS_INSTALLMENT_PAYMENT"] = "payment.process_installment";
+    PaymentEventType["REFUND_PAYMENT"] = "payment.refund";
+    // Virtual account events
+    PaymentEventType["VIRTUAL_ACCOUNT_FUNDED"] = "virtualaccount.funded";
+})(PaymentEventType || (PaymentEventType = {}));

package/dist/src/events/payments/payment-publisher.d.ts

@@ -0,0 +1,46 @@
+import { PaymentEventType, PaymentEventMeta } from './payment-event';
+/**
+ * Configuration for the payment event publisher
+ */
+interface PaymentPublisherConfig {
+    region?: string;
+    endpoint?: string;
+    topicArn?: string;
+}
+/**
+ * Payment Event Publisher for sending payment events to SNS
+ * Used by payment-service and mortgage-service to communicate
+ */
+export declare class PaymentEventPublisher {
+    private readonly snsClient;
+    private readonly topicArn;
+    private readonly serviceName;
+    constructor(serviceName: string, config?: PaymentPublisherConfig);
+    /**
+     * Publish a payment event to SNS
+     */
+    publish<T>(type: PaymentEventType, payload: T, meta?: Partial<PaymentEventMeta>): Promise<string>;
+    /**
+     * Publish wallet credited event
+     */
+    publishWalletCredited(payload: {
+        walletId: string;
+        userId: string;
+        transactionId: string;
+        amount: number;
+        currency: string;
+        newBalance: number;
+        reference: string;
+        source: 'virtual_account' | 'manual' | 'refund';
+    }, meta?: Partial<PaymentEventMeta>): Promise<string>;
+    /**
+     * Publish allocate to installments command
+     */
+    publishAllocateToInstallments(payload: {
+        userId: string;
+        walletId: string;
+        contractId?: string;
+        maxAmount?: number;
+    }, meta?: Partial<PaymentEventMeta>): Promise<string>;
+}
+export {};

package/dist/src/events/payments/payment-publisher.js

@@ -0,0 +1,90 @@
+import { SNSClient, PublishCommand } from '@aws-sdk/client-sns';
+import { PaymentEventType, } from './payment-event';
+/**
+ * Get SNS client configured for LocalStack or AWS
+ */
+function createSNSClient(config) {
+    const endpoint = config.endpoint || process.env.LOCALSTACK_ENDPOINT;
+    const region = config.region || process.env.AWS_REGION || 'us-east-1';
+    const clientConfig = { region };
+    // For LocalStack, set custom endpoint
+    if (endpoint) {
+        clientConfig.endpoint = endpoint;
+    }
+    return new SNSClient(clientConfig);
+}
+/**
+ * Payment Event Publisher for sending payment events to SNS
+ * Used by payment-service and mortgage-service to communicate
+ */
+export class PaymentEventPublisher {
+    snsClient;
+    topicArn;
+    serviceName;
+    constructor(serviceName, config) {
+        this.serviceName = serviceName;
+        this.snsClient = createSNSClient(config || {});
+        // Topic ARN can be passed directly or constructed from env vars
+        const stage = process.env.STAGE || process.env.NODE_ENV || 'test';
+        const region = config?.region || process.env.AWS_REGION || 'us-east-1';
+        const accountId = process.env.AWS_ACCOUNT_ID || '000000000000';
+        this.topicArn = config?.topicArn ||
+            process.env.PAYMENTS_TOPIC_ARN ||
+            `arn:aws:sns:${region}:${accountId}:qshelter-${stage}-payments`;
+    }
+    /**
+     * Publish a payment event to SNS
+     */
+    async publish(type, payload, meta) {
+        const event = {
+            type,
+            payload,
+            meta: {
+                source: this.serviceName,
+                timestamp: new Date().toISOString(),
+                correlationId: meta?.correlationId || crypto.randomUUID(),
+                userId: meta?.userId,
+                tenantId: meta?.tenantId,
+            },
+        };
+        const command = new PublishCommand({
+            TopicArn: this.topicArn,
+            Message: JSON.stringify(event),
+            MessageAttributes: {
+                eventType: {
+                    DataType: 'String',
+                    StringValue: type,
+                },
+                source: {
+                    DataType: 'String',
+                    StringValue: this.serviceName,
+                },
+            },
+        });
+        const result = await this.snsClient.send(command);
+        console.log(`[PaymentEventPublisher] Published ${type} event to SNS`, {
+            topicArn: this.topicArn,
+            messageId: result.MessageId,
+            correlationId: event.meta.correlationId,
+        });
+        return result.MessageId || '';
+    }
+    /**
+     * Publish wallet credited event
+     */
+    async publishWalletCredited(payload, meta) {
+        return this.publish(PaymentEventType.WALLET_CREDITED, payload, {
+            ...meta,
+            userId: payload.userId,
+        });
+    }
+    /**
+     * Publish allocate to installments command
+     */
+    async publishAllocateToInstallments(payload, meta) {
+        return this.publish(PaymentEventType.ALLOCATE_TO_INSTALLMENTS, payload, {
+            ...meta,
+            userId: payload.userId,
+        });
+    }
+}

package/package.json

@@ -1,10 +1,20 @@
 {
   "name": "@valentine-efagene/qshelter-common",
-  "version": "2.0.83",
+  "version": "2.0.86",
   "description": "Shared database schemas and utilities for QShelter services",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
   "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "generate:prisma": "prisma generate && node scripts/generate-models-index.mjs",
+    "postgenerate": "node scripts/generate-models-index.mjs",
+    "migrate:dev": "prisma migrate dev",
+    "patch": "npm version patch && npm run build && npm publish --access public",
+    "prepublishOnly": "npm run build",
+    "publish:public": "npm publish --access public"
+  },
   "keywords": [
     "qshelter",
     "common",
@@ -47,14 +57,5 @@
     "@types/node": "^25.0.3",
     "typescript": "^5.7.3",
     "zod": "^4.0.0"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "generate:prisma": "prisma generate && node scripts/generate-models-index.mjs",
-    "postgenerate": "node scripts/generate-models-index.mjs",
-    "migrate:dev": "prisma migrate dev",
-    "patch": "npm version patch && npm run build && npm publish --access public",
-    "publish:public": "npm publish --access public"
   }
-}
+}

package/prisma/migrations/20260109132751_update_transfer_flow/migration.sql

@@ -0,0 +1,343 @@
+/*
+  Warnings:
+
+  - You are about to drop the column `phaseId` on the `contract_installments` table. All the data in the column will be lost.
+  - You are about to drop the column `approvedDocumentsCount` on the `contract_phases` table. All the data in the column will be lost.
+  - You are about to drop the column `collectFunds` on the `contract_phases` table. All the data in the column will be lost.
+  - You are about to drop the column `completedStepsCount` on the `contract_phases` table. All the data in the column will be lost.
+  - You are about to drop the column `completionCriterion` on the `contract_phases` table. All the data in the column will be lost.
+  - You are about to drop the column `currentStepId` on the `contract_phases` table. All the data in the column will be lost.
+  - You are about to drop the column `interestRate` on the `contract_phases` table. All the data in the column will be lost.
+  - You are about to drop the column `minimumCompletionPercentage` on the `contract_phases` table. All the data in the column will be lost.
+  - You are about to drop the column `paidAmount` on the `contract_phases` table. All the data in the column will be lost.
+  - You are about to drop the column `paymentPlanId` on the `contract_phases` table. All the data in the column will be lost.
+  - You are about to drop the column `paymentPlanSnapshot` on the `contract_phases` table. All the data in the column will be lost.
+  - You are about to drop the column `remainingAmount` on the `contract_phases` table. All the data in the column will be lost.
+  - You are about to drop the column `requiredDocumentSnapshot` on the `contract_phases` table. All the data in the column will be lost.
+  - You are about to drop the column `requiredDocumentsCount` on the `contract_phases` table. All the data in the column will be lost.
+  - You are about to drop the column `stepDefinitionsSnapshot` on the `contract_phases` table. All the data in the column will be lost.
+  - You are about to drop the column `totalAmount` on the `contract_phases` table. All the data in the column will be lost.
+  - You are about to drop the column `totalStepsCount` on the `contract_phases` table. All the data in the column will be lost.
+  - You are about to drop the column `debtToIncomeRatio` on the `contracts` table. All the data in the column will be lost.
+  - You are about to drop the column `downPayment` on the `contracts` table. All the data in the column will be lost.
+  - You are about to drop the column `downPaymentPaid` on the `contracts` table. All the data in the column will be lost.
+  - You are about to drop the column `interestRate` on the `contracts` table. All the data in the column will be lost.
+  - You are about to drop the column `monthlyExpenses` on the `contracts` table. All the data in the column will be lost.
+  - You are about to drop the column `monthlyIncome` on the `contracts` table. All the data in the column will be lost.
+  - You are about to drop the column `periodicPayment` on the `contracts` table. All the data in the column will be lost.
+  - You are about to drop the column `preApprovalAnswers` on the `contracts` table. All the data in the column will be lost.
+  - You are about to drop the column `principal` on the `contracts` table. All the data in the column will be lost.
+  - You are about to drop the column `state` on the `contracts` table. All the data in the column will be lost.
+  - You are about to drop the column `termMonths` on the `contracts` table. All the data in the column will be lost.
+  - You are about to drop the column `totalInterestPaid` on the `contracts` table. All the data in the column will be lost.
+  - You are about to drop the column `totalPaidToDate` on the `contracts` table. All the data in the column will be lost.
+  - You are about to drop the column `underwritingScore` on the `contracts` table. All the data in the column will be lost.
+  - You are about to drop the column `paymentsMigrated` on the `property_transfer_requests` table. All the data in the column will be lost.
+  - You are about to drop the `contract_phase_step_approvals` table. If the table is not empty, all the data it contains will be lost.
+  - You are about to drop the `contract_phase_step_documents` table. If the table is not empty, all the data it contains will be lost.
+  - You are about to drop the `contract_phase_steps` table. If the table is not empty, all the data it contains will be lost.
+  - Added the required column `paymentPhaseId` to the `contract_installments` table without a default value. This is not possible if the table is not empty.
+
+*/
+-- DropForeignKey
+ALTER TABLE `contract_installments` DROP FOREIGN KEY `contract_installments_phaseId_fkey`;
+
+-- DropForeignKey
+ALTER TABLE `contract_phase_step_approvals` DROP FOREIGN KEY `contract_phase_step_approvals_approverId_fkey`;
+
+-- DropForeignKey
+ALTER TABLE `contract_phase_step_approvals` DROP FOREIGN KEY `contract_phase_step_approvals_stepId_fkey`;
+
+-- DropForeignKey
+ALTER TABLE `contract_phase_step_documents` DROP FOREIGN KEY `contract_phase_step_documents_stepId_fkey`;
+
+-- DropForeignKey
+ALTER TABLE `contract_phase_steps` DROP FOREIGN KEY `contract_phase_steps_assigneeId_fkey`;
+
+-- DropForeignKey
+ALTER TABLE `contract_phase_steps` DROP FOREIGN KEY `contract_phase_steps_phaseId_fkey`;
+
+-- DropForeignKey
+ALTER TABLE `contract_phases` DROP FOREIGN KEY `contract_phases_currentStepId_fkey`;
+
+-- DropForeignKey
+ALTER TABLE `contract_phases` DROP FOREIGN KEY `contract_phases_paymentPlanId_fkey`;
+
+-- DropIndex
+DROP INDEX `contract_installments_phaseId_idx` ON `contract_installments`;
+
+-- DropIndex
+DROP INDEX `contract_phases_currentStepId_idx` ON `contract_phases`;
+
+-- DropIndex
+DROP INDEX `contract_phases_paymentPlanId_idx` ON `contract_phases`;
+
+-- DropIndex
+DROP INDEX `contracts_state_idx` ON `contracts`;
+
+-- AlterTable
+ALTER TABLE `contract_installments` DROP COLUMN `phaseId`,
+    ADD COLUMN `paymentPhaseId` VARCHAR(191) NOT NULL;
+
+-- AlterTable
+ALTER TABLE `contract_phases` DROP COLUMN `approvedDocumentsCount`,
+    DROP COLUMN `collectFunds`,
+    DROP COLUMN `completedStepsCount`,
+    DROP COLUMN `completionCriterion`,
+    DROP COLUMN `currentStepId`,
+    DROP COLUMN `interestRate`,
+    DROP COLUMN `minimumCompletionPercentage`,
+    DROP COLUMN `paidAmount`,
+    DROP COLUMN `paymentPlanId`,
+    DROP COLUMN `paymentPlanSnapshot`,
+    DROP COLUMN `remainingAmount`,
+    DROP COLUMN `requiredDocumentSnapshot`,
+    DROP COLUMN `requiredDocumentsCount`,
+    DROP COLUMN `stepDefinitionsSnapshot`,
+    DROP COLUMN `totalAmount`,
+    DROP COLUMN `totalStepsCount`,
+    MODIFY `phaseCategory` ENUM('QUESTIONNAIRE', 'DOCUMENTATION', 'PAYMENT') NOT NULL,
+    MODIFY `phaseType` ENUM('PRE_APPROVAL', 'UNDERWRITING', 'KYC', 'VERIFICATION', 'DOWNPAYMENT', 'MORTGAGE', 'BALLOON', 'CUSTOM') NOT NULL;
+
+-- AlterTable
+ALTER TABLE `contracts` DROP COLUMN `debtToIncomeRatio`,
+    DROP COLUMN `downPayment`,
+    DROP COLUMN `downPaymentPaid`,
+    DROP COLUMN `interestRate`,
+    DROP COLUMN `monthlyExpenses`,
+    DROP COLUMN `monthlyIncome`,
+    DROP COLUMN `periodicPayment`,
+    DROP COLUMN `preApprovalAnswers`,
+    DROP COLUMN `principal`,
+    DROP COLUMN `state`,
+    DROP COLUMN `termMonths`,
+    DROP COLUMN `totalInterestPaid`,
+    DROP COLUMN `totalPaidToDate`,
+    DROP COLUMN `underwritingScore`;
+
+-- AlterTable
+ALTER TABLE `property_payment_method_phases` MODIFY `phaseCategory` ENUM('QUESTIONNAIRE', 'DOCUMENTATION', 'PAYMENT') NOT NULL,
+    MODIFY `phaseType` ENUM('PRE_APPROVAL', 'UNDERWRITING', 'KYC', 'VERIFICATION', 'DOWNPAYMENT', 'MORTGAGE', 'BALLOON', 'CUSTOM') NOT NULL;
+
+-- AlterTable
+ALTER TABLE `property_transfer_requests` DROP COLUMN `paymentsMigrated`,
+    ADD COLUMN `refundTransactionId` VARCHAR(191) NULL,
+    ADD COLUMN `refundedAmount` DOUBLE NULL,
+    ADD COLUMN `refundedAt` DATETIME(3) NULL;
+
+-- DropTable
+DROP TABLE `contract_phase_step_approvals`;
+
+-- DropTable
+DROP TABLE `contract_phase_step_documents`;
+
+-- DropTable
+DROP TABLE `contract_phase_steps`;
+
+-- CreateTable
+CREATE TABLE `payment_method_phase_fields` (
+    `id` VARCHAR(191) NOT NULL,
+    `phaseId` VARCHAR(191) NOT NULL,
+    `name` VARCHAR(191) NOT NULL,
+    `label` VARCHAR(191) NOT NULL,
+    `description` TEXT NULL,
+    `placeholder` VARCHAR(191) NULL,
+    `fieldType` ENUM('TEXT', 'TEXTAREA', 'NUMBER', 'CURRENCY', 'EMAIL', 'PHONE', 'DATE', 'SELECT', 'MULTI_SELECT', 'CHECKBOX', 'RADIO', 'FILE') NOT NULL,
+    `isRequired` BOOLEAN NOT NULL DEFAULT true,
+    `order` INTEGER NOT NULL,
+    `validation` JSON NULL,
+    `displayCondition` JSON NULL,
+    `defaultValue` JSON NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `payment_method_phase_fields_phaseId_idx`(`phaseId`),
+    UNIQUE INDEX `payment_method_phase_fields_phaseId_name_key`(`phaseId`, `name`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `questionnaire_phases` (
+    `id` VARCHAR(191) NOT NULL,
+    `phaseId` VARCHAR(191) NOT NULL,
+    `completedFieldsCount` INTEGER NOT NULL DEFAULT 0,
+    `totalFieldsCount` INTEGER NOT NULL DEFAULT 0,
+    `underwritingScore` DOUBLE NULL,
+    `debtToIncomeRatio` DOUBLE NULL,
+    `underwritingDecision` VARCHAR(191) NULL,
+    `underwritingNotes` TEXT NULL,
+    `fieldsSnapshot` JSON NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    UNIQUE INDEX `questionnaire_phases_phaseId_key`(`phaseId`),
+    INDEX `questionnaire_phases_phaseId_idx`(`phaseId`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `documentation_phases` (
+    `id` VARCHAR(191) NOT NULL,
+    `phaseId` VARCHAR(191) NOT NULL,
+    `currentStepId` VARCHAR(191) NULL,
+    `approvedDocumentsCount` INTEGER NOT NULL DEFAULT 0,
+    `requiredDocumentsCount` INTEGER NOT NULL DEFAULT 0,
+    `completedStepsCount` INTEGER NOT NULL DEFAULT 0,
+    `totalStepsCount` INTEGER NOT NULL DEFAULT 0,
+    `minimumCompletionPercentage` DOUBLE NULL,
+    `completionCriterion` ENUM('DOCUMENT_APPROVALS', 'PAYMENT_AMOUNT', 'STEPS_COMPLETED') NULL,
+    `stepDefinitionsSnapshot` JSON NULL,
+    `requiredDocumentSnapshot` JSON NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    UNIQUE INDEX `documentation_phases_phaseId_key`(`phaseId`),
+    INDEX `documentation_phases_phaseId_idx`(`phaseId`),
+    INDEX `documentation_phases_currentStepId_idx`(`currentStepId`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `payment_phases` (
+    `id` VARCHAR(191) NOT NULL,
+    `phaseId` VARCHAR(191) NOT NULL,
+    `paymentPlanId` VARCHAR(191) NULL,
+    `totalAmount` DOUBLE NOT NULL,
+    `paidAmount` DOUBLE NOT NULL DEFAULT 0,
+    `interestRate` DOUBLE NOT NULL DEFAULT 0,
+    `collectFunds` BOOLEAN NOT NULL DEFAULT true,
+    `minimumCompletionPercentage` DOUBLE NULL,
+    `paymentPlanSnapshot` JSON NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    UNIQUE INDEX `payment_phases_phaseId_key`(`phaseId`),
+    INDEX `payment_phases_phaseId_idx`(`phaseId`),
+    INDEX `payment_phases_paymentPlanId_idx`(`paymentPlanId`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `questionnaire_fields` (
+    `id` VARCHAR(191) NOT NULL,
+    `questionnairePhaseId` VARCHAR(191) NOT NULL,
+    `name` VARCHAR(191) NOT NULL,
+    `label` VARCHAR(191) NOT NULL,
+    `description` TEXT NULL,
+    `placeholder` VARCHAR(191) NULL,
+    `fieldType` ENUM('TEXT', 'TEXTAREA', 'NUMBER', 'CURRENCY', 'EMAIL', 'PHONE', 'DATE', 'SELECT', 'MULTI_SELECT', 'CHECKBOX', 'RADIO', 'FILE') NOT NULL,
+    `isRequired` BOOLEAN NOT NULL DEFAULT true,
+    `order` INTEGER NOT NULL,
+    `validation` JSON NULL,
+    `displayCondition` JSON NULL,
+    `defaultValue` JSON NULL,
+    `answer` JSON NULL,
+    `isValid` BOOLEAN NOT NULL DEFAULT false,
+    `validationErrors` JSON NULL,
+    `submittedAt` DATETIME(3) NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `questionnaire_fields_questionnairePhaseId_idx`(`questionnairePhaseId`),
+    UNIQUE INDEX `questionnaire_fields_questionnairePhaseId_name_key`(`questionnairePhaseId`, `name`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `documentation_steps` (
+    `id` VARCHAR(191) NOT NULL,
+    `documentationPhaseId` VARCHAR(191) NOT NULL,
+    `name` VARCHAR(191) NOT NULL,
+    `description` TEXT NULL,
+    `stepType` ENUM('UPLOAD', 'REVIEW', 'SIGNATURE', 'APPROVAL', 'EXTERNAL_CHECK', 'WAIT', 'GENERATE_DOCUMENT', 'PRE_APPROVAL', 'UNDERWRITING') NOT NULL,
+    `order` INTEGER NOT NULL,
+    `status` ENUM('PENDING', 'IN_PROGRESS', 'COMPLETED', 'FAILED', 'SKIPPED', 'NEEDS_RESUBMISSION', 'ACTION_REQUIRED', 'AWAITING_REVIEW') NOT NULL DEFAULT 'PENDING',
+    `actionReason` TEXT NULL,
+    `submissionCount` INTEGER NOT NULL DEFAULT 0,
+    `lastSubmittedAt` DATETIME(3) NULL,
+    `metadata` JSON NULL,
+    `assigneeId` VARCHAR(191) NULL,
+    `dueDate` DATETIME(3) NULL,
+    `completedAt` DATETIME(3) NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `documentation_steps_documentationPhaseId_idx`(`documentationPhaseId`),
+    INDEX `documentation_steps_status_idx`(`status`),
+    INDEX `documentation_steps_order_idx`(`order`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `documentation_step_documents` (
+    `id` VARCHAR(191) NOT NULL,
+    `stepId` VARCHAR(191) NOT NULL,
+    `documentType` VARCHAR(191) NOT NULL,
+    `isRequired` BOOLEAN NOT NULL DEFAULT true,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+
+    INDEX `documentation_step_documents_stepId_documentType_idx`(`stepId`, `documentType`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `documentation_step_approvals` (
+    `id` VARCHAR(191) NOT NULL,
+    `stepId` VARCHAR(191) NOT NULL,
+    `approverId` VARCHAR(191) NULL,
+    `decision` ENUM('APPROVED', 'REJECTED', 'REQUEST_CHANGES') NOT NULL,
+    `comment` TEXT NULL,
+    `decidedAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+
+    INDEX `documentation_step_approvals_stepId_idx`(`stepId`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateIndex
+CREATE INDEX `contract_installments_paymentPhaseId_idx` ON `contract_installments`(`paymentPhaseId`);
+
+-- CreateIndex
+CREATE INDEX `contracts_currentPhaseId_idx` ON `contracts`(`currentPhaseId`);
+
+-- AddForeignKey
+ALTER TABLE `payment_method_phase_fields` ADD CONSTRAINT `payment_method_phase_fields_phaseId_fkey` FOREIGN KEY (`phaseId`) REFERENCES `property_payment_method_phases`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `contracts` ADD CONSTRAINT `contracts_currentPhaseId_fkey` FOREIGN KEY (`currentPhaseId`) REFERENCES `contract_phases`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `questionnaire_phases` ADD CONSTRAINT `questionnaire_phases_phaseId_fkey` FOREIGN KEY (`phaseId`) REFERENCES `contract_phases`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `documentation_phases` ADD CONSTRAINT `documentation_phases_phaseId_fkey` FOREIGN KEY (`phaseId`) REFERENCES `contract_phases`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `documentation_phases` ADD CONSTRAINT `documentation_phases_currentStepId_fkey` FOREIGN KEY (`currentStepId`) REFERENCES `documentation_steps`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `payment_phases` ADD CONSTRAINT `payment_phases_phaseId_fkey` FOREIGN KEY (`phaseId`) REFERENCES `contract_phases`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `payment_phases` ADD CONSTRAINT `payment_phases_paymentPlanId_fkey` FOREIGN KEY (`paymentPlanId`) REFERENCES `payment_plans`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `questionnaire_fields` ADD CONSTRAINT `questionnaire_fields_questionnairePhaseId_fkey` FOREIGN KEY (`questionnairePhaseId`) REFERENCES `questionnaire_phases`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `documentation_steps` ADD CONSTRAINT `documentation_steps_documentationPhaseId_fkey` FOREIGN KEY (`documentationPhaseId`) REFERENCES `documentation_phases`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `documentation_steps` ADD CONSTRAINT `documentation_steps_assigneeId_fkey` FOREIGN KEY (`assigneeId`) REFERENCES `users`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `documentation_step_documents` ADD CONSTRAINT `documentation_step_documents_stepId_fkey` FOREIGN KEY (`stepId`) REFERENCES `documentation_steps`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `documentation_step_approvals` ADD CONSTRAINT `documentation_step_approvals_stepId_fkey` FOREIGN KEY (`stepId`) REFERENCES `documentation_steps`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `documentation_step_approvals` ADD CONSTRAINT `documentation_step_approvals_approverId_fkey` FOREIGN KEY (`approverId`) REFERENCES `users`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `contract_installments` ADD CONSTRAINT `contract_installments_paymentPhaseId_fkey` FOREIGN KEY (`paymentPhaseId`) REFERENCES `payment_phases`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;

package/prisma/schema.prisma

@@ -20,16 +20,26 @@ datasource db {
 // =============================================================================
 
 enum PhaseCategory {
-  DOCUMENTATION
-  PAYMENT
+  QUESTIONNAIRE // Configurable form fields with validation
+  DOCUMENTATION // Document upload and approval workflow
+  PAYMENT // Installment-based payment collection
 }
 
 enum PhaseType {
+  // QUESTIONNAIRE phases
+  PRE_APPROVAL // Eligibility questionnaire (income, employment, etc.)
+  UNDERWRITING // System evaluation of eligibility
+
+  // DOCUMENTATION phases
   KYC
   VERIFICATION
+
+  // PAYMENT phases
   DOWNPAYMENT
   MORTGAGE
   BALLOON
+
+  // Generic
   CUSTOM
 }
 
@@ -898,9 +908,9 @@ model PaymentPlan {
   updatedAt DateTime @updatedAt
 
   // Used by property payment method phases (templates)
-  methodPhases   PropertyPaymentMethodPhase[]
-  // Used by instantiated contract phases
-  contractPhases ContractPhase[]
+  methodPhases  PropertyPaymentMethodPhase[]
+  // Used by instantiated payment phases
+  paymentPhases PaymentPhase[]
 
   @@unique([tenantId, name]) // Unique per tenant, or globally if tenantId is null
   @@index([tenantId])
@@ -1005,8 +1015,10 @@ model PropertyPaymentMethodPhase {
   updatedAt DateTime @updatedAt
 
   // Normalized child tables (for DOCUMENTATION phases)
-  steps             PaymentMethodPhaseStep[]
-  requiredDocuments PaymentMethodPhaseDocument[]
+  steps               PaymentMethodPhaseStep[]
+  requiredDocuments   PaymentMethodPhaseDocument[]
+  // Normalized child tables (for QUESTIONNAIRE phases)
+  questionnaireFields PaymentMethodPhaseField[]
 
   @@index([paymentMethodId])
   @@index([paymentPlanId])
@@ -1083,12 +1095,71 @@ model PaymentMethodPhaseDocument {
   @@map("payment_method_phase_documents")
 }
 
+// =============================================================================
+// QUESTIONNAIRE FIELD TYPES - For QUESTIONNAIRE phases
+// =============================================================================
+
+enum FieldType {
+  TEXT // Short text input
+  TEXTAREA // Long text input
+  NUMBER // Numeric input (with optional min/max)
+  CURRENCY // Currency input (validated as money)
+  EMAIL // Email validation
+  PHONE // Phone number validation
+  DATE // Date picker
+  SELECT // Dropdown/single select
+  MULTI_SELECT // Multiple selection
+  CHECKBOX // Boolean yes/no
+  RADIO // Radio button group
+  FILE // File upload (single)
+}
+
+// Questionnaire field template within a QUESTIONNAIRE phase
+model PaymentMethodPhaseField {
+  id      String                     @id @default(cuid())
+  phaseId String
+  phase   PropertyPaymentMethodPhase @relation(fields: [phaseId], references: [id], onDelete: Cascade)
+
+  // Field identification
+  name        String // Internal field name (e.g., "monthly_income")
+  label       String // Display label (e.g., "Monthly Income")
+  description String? @db.Text // Help text for the field
+  placeholder String? // Placeholder text
+
+  // Field configuration
+  fieldType  FieldType
+  isRequired Boolean   @default(true)
+  order      Int
+
+  // Validation rules (JSON schema-like)
+  // Examples:
+  // NUMBER: { "min": 0, "max": 1000000 }
+  // TEXT: { "minLength": 2, "maxLength": 100, "pattern": "^[A-Za-z]+$" }
+  // SELECT: { "options": [{"value": "employed", "label": "Employed"}, ...] }
+  // DATE: { "minDate": "now", "maxDate": "+30d" }
+  validation Json?
+
+  // For conditional display (e.g., show if another field has a certain value)
+  // { "field": "employment_status", "operator": "equals", "value": "employed" }
+  displayCondition Json?
+
+  // Default value (JSON to support any type)
+  defaultValue Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([phaseId, name])
+  @@index([phaseId])
+  @@map("payment_method_phase_fields")
+}
+
 // =============================================================================
 // CONTRACT DOMAIN - Unified agreement model (replaces Mortgage, PurchasePlan, etc.)
 // =============================================================================
 // Contract is the canonical agreement. "Mortgage" is just a product configuration
 // that creates a Contract with specific phases (documentation, downpayment, long-term payment).
-// Phases can be DOCUMENTATION (FSM for approvals) or PAYMENT (PaymentPlan-driven installments).
+// Phases can be QUESTIONNAIRE, DOCUMENTATION, or PAYMENT.
 // =============================================================================
 
 model Contract {
@@ -1111,28 +1182,13 @@ model Contract {
   description    String? @db.Text
   contractType   String // Admin-defined: MORTGAGE, INSTALLMENT, RENT_TO_OWN, CASH, LEASE, etc.
 
-  // Financial summary (computed from phases)
-  totalAmount       Float // Total contract value (from unit price or negotiated)
-  downPayment       Float  @default(0)
-  downPaymentPaid   Float  @default(0)
-  principal         Float? // Financed amount (if applicable)
-  interestRate      Float? // Overall interest rate (if applicable)
-  termMonths        Int? // Total term (if applicable)
-  periodicPayment   Float? // Computed periodic payment (if applicable)
-  totalPaidToDate   Float  @default(0)
-  totalInterestPaid Float  @default(0)
-
-  // Pre-approval and underwriting data (moved from prequalification)
-  monthlyIncome      Float? // Buyer's monthly income
-  monthlyExpenses    Float? // Buyer's monthly expenses
-  preApprovalAnswers Json? // Questionnaire answers from PRE_APPROVAL step
-  underwritingScore  Float? // Aggregate score from underwriting evaluation
-  debtToIncomeRatio  Float? // Calculated DTI ratio
-
-  // FSM state (DB-enforced enums)
+  // Contract value (negotiated from unit price)
+  totalAmount Float
+
+  // FSM state (DB-enforced enum)
   status         ContractStatus @default(DRAFT)
-  state          ContractStatus @default(DRAFT) // FSM state for workflow
   currentPhaseId String?
+  currentPhase   ContractPhase? @relation("CurrentPhase", fields: [currentPhaseId], references: [id])
 
   // Timing
   nextPaymentDueDate DateTime?
@@ -1176,7 +1232,7 @@ model Contract {
   @@index([sellerId])
   @@index([paymentMethodId])
   @@index([status])
-  @@index([state])
+  @@index([currentPhaseId])
   @@map("contracts")
 }
 
@@ -1237,12 +1293,21 @@ model ContractRefund {
 
 // Phase within a contract - can be DOCUMENTATION or PAYMENT type
 // Admin names phases freely (e.g., "KYC Documents", "Downpayment", "Monthly Mortgage")
+// =============================================================================
+// CONTRACT PHASE - Base model with polymorphic extensions
+// =============================================================================
+// ContractPhase is the base table with shared fields only.
+// Each phase has exactly ONE extension table based on phaseCategory:
+// - QUESTIONNAIRE → QuestionnairePhase
+// - DOCUMENTATION → DocumentationPhase
+// - PAYMENT → PaymentPhase
+// This eliminates nullable field pollution and makes the schema self-documenting.
+// =============================================================================
+
 model ContractPhase {
-  id            String       @id @default(cuid())
-  contractId    String
-  contract      Contract     @relation(fields: [contractId], references: [id], onDelete: Cascade)
-  paymentPlanId String? // Only for PAYMENT phases
-  paymentPlan   PaymentPlan? @relation(fields: [paymentPlanId], references: [id])
+  id         String   @id @default(cuid())
+  contractId String
+  contract   Contract @relation(fields: [contractId], references: [id], onDelete: Cascade)
 
   // Admin-defined naming
   name        String
@@ -1256,64 +1321,202 @@ 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])
+  // Timing (shared across all phase types)
+  dueDate     DateTime?
+  startDate   DateTime?
+  endDate     DateTime?
+  activatedAt DateTime?
+  completedAt DateTime?
 
-  // Financial details (for PAYMENT phases)
-  totalAmount     Float?
-  paidAmount      Float  @default(0)
-  remainingAmount Float?
-  interestRate    Float?
+  // Activation rules (shared)
+  requiresPreviousPhaseCompletion Boolean @default(true)
 
-  // Fund collection behavior (snapshotted from template at contract creation)
-  // true = we collect funds via wallet/gateway (e.g., downpayment)
-  // false = external payment, we only track/reconcile (e.g., bank mortgage)
-  collectFunds Boolean @default(true)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Polymorphic extensions (exactly one will be populated based on phaseCategory)
+  questionnairePhase QuestionnairePhase?
+  documentationPhase DocumentationPhase?
+  paymentPhase       PaymentPhase?
+
+  // Payments can be linked to any phase type (for tracking)
+  payments ContractPayment[]
+
+  // Back-relation for contracts where this is the current phase
+  currentForContracts Contract[] @relation("CurrentPhase")
+
+  @@index([contractId])
+  @@index([phaseCategory])
+  @@index([status])
+  @@index([order])
+  @@map("contract_phases")
+}
+
+// =============================================================================
+// QUESTIONNAIRE PHASE DATA - Extension for QUESTIONNAIRE phases
+// =============================================================================
+// Collects form data from users (eligibility, pre-approval, underwriting inputs)
+// =============================================================================
+
+model QuestionnairePhase {
+  id      String        @id @default(cuid())
+  phaseId String        @unique
+  phase   ContractPhase @relation(fields: [phaseId], references: [id], onDelete: Cascade)
+
+  // Progress tracking
+  completedFieldsCount Int @default(0)
+  totalFieldsCount     Int @default(0)
+
+  // Computed results (for UNDERWRITING phases)
+  underwritingScore    Float?
+  debtToIncomeRatio    Float?
+  underwritingDecision String? // APPROVED, CONDITIONAL, DECLINED
+  underwritingNotes    String? @db.Text
+
+  // Snapshot of field definitions at creation
+  fieldsSnapshot Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Child records
+  fields QuestionnaireField[]
+
+  @@index([phaseId])
+  @@map("questionnaire_phases")
+}
+
+// =============================================================================
+// DOCUMENTATION PHASE DATA - Extension for DOCUMENTATION phases
+// =============================================================================
+// Manages document upload/approval workflow with FSM steps
+// =============================================================================
+
+model DocumentationPhase {
+  id      String        @id @default(cuid())
+  phaseId String        @unique
+  phase   ContractPhase @relation(fields: [phaseId], references: [id], onDelete: Cascade)
 
-  // Progress counters (for efficient activation checks)
+  // Current step pointer for UX and orchestration
+  currentStepId String?
+  currentStep   DocumentationStep? @relation("CurrentStep", fields: [currentStepId], references: [id])
+
+  // Progress counters
   approvedDocumentsCount Int @default(0)
   requiredDocumentsCount Int @default(0)
   completedStepsCount    Int @default(0)
   totalStepsCount        Int @default(0)
 
-  // Timing
-  dueDate     DateTime?
-  startDate   DateTime?
-  endDate     DateTime?
-  activatedAt DateTime?
-  completedAt DateTime?
-
-  // Activation rules
-  requiresPreviousPhaseCompletion Boolean              @default(true)
-  minimumCompletionPercentage     Float?
-  completionCriterion             CompletionCriterion?
+  // Completion criteria
+  minimumCompletionPercentage Float?
+  completionCriterion         CompletionCriterion?
 
-  // Snapshots for audit (effective config at contract creation)
-  paymentPlanSnapshot      Json?
+  // Snapshots for audit
   stepDefinitionsSnapshot  Json?
   requiredDocumentSnapshot Json?
 
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 
-  // Relations
+  // Child records
+  steps DocumentationStep[]
+
+  @@index([phaseId])
+  @@index([currentStepId])
+  @@map("documentation_phases")
+}
+
+// =============================================================================
+// PAYMENT PHASE DATA - Extension for PAYMENT phases
+// =============================================================================
+// Manages installment-based payment collection
+// =============================================================================
+
+model PaymentPhase {
+  id      String        @id @default(cuid())
+  phaseId String        @unique
+  phase   ContractPhase @relation(fields: [phaseId], references: [id], onDelete: Cascade)
+
+  // Payment plan reference
+  paymentPlanId String?
+  paymentPlan   PaymentPlan? @relation(fields: [paymentPlanId], references: [id])
+
+  // Financial details
+  totalAmount  Float
+  paidAmount   Float @default(0)
+  interestRate Float @default(0)
+
+  // Fund collection behavior
+  // true = we collect funds via wallet/gateway (e.g., downpayment)
+  // false = external payment, we only track/reconcile (e.g., bank mortgage)
+  collectFunds Boolean @default(true)
+
+  // Completion criteria
+  minimumCompletionPercentage Float?
+
+  // Snapshot for audit
+  paymentPlanSnapshot Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Child records
   installments ContractInstallment[]
-  payments     ContractPayment[]
-  steps        DocumentationStep[] // For DOCUMENTATION phases (FSM steps)
 
-  @@index([contractId])
+  @@index([phaseId])
   @@index([paymentPlanId])
-  @@index([phaseCategory])
-  @@index([status])
-  @@index([order])
-  @@index([currentStepId])
-  @@map("contract_phases")
+  @@map("payment_phases")
+}
+
+// =============================================================================
+// QUESTIONNAIRE FIELDS - Instantiated fields within QUESTIONNAIRE phases
+// =============================================================================
+// When a contract is created from a payment method template, questionnaire field
+// templates are copied to QuestionnaireField records. Users submit answers here.
+// =============================================================================
+
+model QuestionnaireField {
+  id                   String             @id @default(cuid())
+  questionnairePhaseId String
+  questionnairePhase   QuestionnairePhase @relation(fields: [questionnairePhaseId], references: [id], onDelete: Cascade)
+
+  // Field identification (copied from template)
+  name        String // Internal field name (e.g., "monthly_income")
+  label       String // Display label (e.g., "Monthly Income")
+  description String? @db.Text
+  placeholder String?
+
+  // Field configuration (copied from template)
+  fieldType  FieldType
+  isRequired Boolean   @default(true)
+  order      Int
+
+  // Validation rules (copied from template)
+  validation       Json?
+  displayCondition Json?
+  defaultValue     Json?
+
+  // User's submitted answer (JSON to support any type)
+  // TEXT: "John Doe"
+  // NUMBER/CURRENCY: 500000
+  // SELECT: "employed"
+  // MULTI_SELECT: ["option1", "option2"]
+  // CHECKBOX: true
+  // DATE: "2024-01-15"
+  answer Json?
+
+  // Validation status
+  isValid          Boolean @default(false)
+  validationErrors Json? // Array of error messages if invalid
+
+  // Timestamps
+  submittedAt DateTime?
+  createdAt   DateTime  @default(now())
+  updatedAt   DateTime  @updatedAt
+
+  @@unique([questionnairePhaseId, name])
+  @@index([questionnairePhaseId])
+  @@map("questionnaire_fields")
 }
 
 // =============================================================================
@@ -1356,9 +1559,9 @@ model ContractEvent {
 
 // Steps within a DOCUMENTATION phase (FSM for document collection/approval)
 model DocumentationStep {
-  id      String        @id @default(cuid())
-  phaseId String
-  phase   ContractPhase @relation(fields: [phaseId], references: [id], onDelete: Cascade)
+  id                   String             @id @default(cuid())
+  documentationPhaseId String
+  documentationPhase   DocumentationPhase @relation(fields: [documentationPhaseId], references: [id], onDelete: Cascade)
 
   name        String
   description String?  @db.Text
@@ -1383,15 +1586,6 @@ model DocumentationStep {
   // Configuration metadata (for GENERATE_DOCUMENT steps, etc.)
   metadata Json?
 
-  // For PRE_APPROVAL steps: store questionnaire answers
-  preApprovalAnswers Json?
-
-  // For UNDERWRITING steps: store evaluation results
-  underwritingScore    Float?
-  debtToIncomeRatio    Float?
-  underwritingDecision String? // APPROVED, CONDITIONAL, DECLINED
-  underwritingNotes    String? @db.Text
-
   // Assignment
   assigneeId String?
   assignee   User?   @relation("DocumentationStepAssignee", fields: [assigneeId], references: [id])
@@ -1407,12 +1601,12 @@ model DocumentationStep {
   updatedAt DateTime @updatedAt
 
   approvals       DocumentationStepApproval[]
-  currentForPhase ContractPhase[]             @relation("CurrentStep")
+  currentForPhase DocumentationPhase[]        @relation("CurrentStep")
 
-  @@index([phaseId])
+  @@index([documentationPhaseId])
   @@index([status])
   @@index([order])
-  @@map("contract_phase_steps")
+  @@map("documentation_steps")
 }
 
 // Required documents for a step (normalized from CSV)
@@ -1427,7 +1621,7 @@ model DocumentationStepDocument {
   createdAt DateTime @default(now())
 
   @@index([stepId, documentType])
-  @@map("contract_phase_step_documents")
+  @@map("documentation_step_documents")
 }
 
 // Approvals for documentation steps
@@ -1445,14 +1639,14 @@ model DocumentationStepApproval {
   createdAt DateTime @default(now())
 
   @@index([stepId])
-  @@map("contract_phase_step_approvals")
+  @@map("documentation_step_approvals")
 }
 
 // Installments within a PAYMENT phase
 model ContractInstallment {
-  id      String        @id @default(cuid())
-  phaseId String
-  phase   ContractPhase @relation(fields: [phaseId], references: [id], onDelete: Cascade)
+  id             String       @id @default(cuid())
+  paymentPhaseId String
+  paymentPhase   PaymentPhase @relation(fields: [paymentPhaseId], references: [id], onDelete: Cascade)
 
   installmentNumber Int
 
@@ -1476,7 +1670,7 @@ model ContractInstallment {
 
   payments ContractPayment[]
 
-  @@index([phaseId])
+  @@index([paymentPhaseId])
   @@index([dueDate])
   @@index([status])
   @@map("contract_installments")
@@ -2126,8 +2320,16 @@ model DomainEvent {
 // =============================================================================
 // Property Transfer Request
 // =============================================================================
-// Allows a buyer to request transferring their contract to a different property
-// while preserving payments, completed workflow steps, and progress.
+// Allows a buyer to request transferring their contract to a different property.
+// 
+// TRANSFER PAYMENT FLOW:
+// 1. All payments from source contract are refunded to buyer's wallet (single credit transaction)
+// 2. Source contract marked TRANSFERRED, unit released
+// 3. New contract created for target unit with zero payments
+// 4. Buyer can optionally apply wallet balance as equity during new mortgage application
+//
+// This ensures clean accounting: each contract has isolated payment history,
+// wallet serves as intermediary, and buyer retains full credit.
 // =============================================================================
 
 model PropertyTransferRequest {
@@ -2163,7 +2365,11 @@ model PropertyTransferRequest {
   sourceTotalAmount Float? // Original contract total
   targetTotalAmount Float? // New contract total (based on target property)
   priceAdjustment   Float? // Difference (positive = buyer owes more)
-  paymentsMigrated  Int? // Number of payments migrated
+
+  // Wallet refund tracking (payments refunded to wallet, NOT carried over)
+  refundedAmount      Float? // Total amount refunded to wallet
+  refundTransactionId String? // Reference to wallet Transaction record
+  refundedAt          DateTime?
 
   // Result - new contract created after approval
   targetContractId String?