@valentine-efagene/qshelter-common 2.0.71 → 2.0.73

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

@@ -29,6 +29,7 @@ export type * from './models/PropertyPaymentMethod.js';
 export type * from './models/PropertyPaymentMethodLink.js';
 export type * from './models/PropertyPaymentMethodPhase.js';
 export type * from './models/PaymentMethodPhaseStep.js';
+export type * from './models/StepEventAttachment.js';
 export type * from './models/PaymentMethodPhaseDocument.js';
 export type * from './models/Contract.js';
 export type * from './models/ContractPhase.js';
@@ -50,4 +51,5 @@ export type * from './models/EventHandler.js';
 export type * from './models/WorkflowEvent.js';
 export type * from './models/EventHandlerExecution.js';
 export type * from './models/DomainEvent.js';
+export type * from './models/PropertyTransferRequest.js';
 export type * from './commonInputTypes.js';

package/dist/src/events/workflow-event.service.d.ts

@@ -123,10 +123,10 @@ export declare class WorkflowEventService {
             id: string;
             createdAt: Date;
             status: import("./workflow-types").ExecutionStatus;
+            handlerId: string;
             completedAt: Date | null;
             error: string | null;
             eventId: string;
-            handlerId: string;
             attempt: number;
             input: import("@prisma/client/runtime/client").JsonValue | null;
             output: import("@prisma/client/runtime/client").JsonValue | null;

package/package.json

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

package/prisma/migrations/20260106062140_add_step_event_attachments/migration.sql

@@ -0,0 +1,22 @@
+-- CreateTable
+CREATE TABLE `step_event_attachments` (
+    `id` VARCHAR(191) NOT NULL,
+    `stepId` VARCHAR(191) NOT NULL,
+    `trigger` ENUM('ON_COMPLETE', 'ON_REJECT', 'ON_SUBMIT', 'ON_RESUBMIT', 'ON_START') NOT NULL,
+    `handlerId` VARCHAR(191) NOT NULL,
+    `priority` INTEGER NOT NULL DEFAULT 100,
+    `enabled` BOOLEAN NOT NULL DEFAULT true,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `step_event_attachments_stepId_idx`(`stepId`),
+    INDEX `step_event_attachments_handlerId_idx`(`handlerId`),
+    UNIQUE INDEX `step_event_attachments_stepId_handlerId_trigger_key`(`stepId`, `handlerId`, `trigger`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- AddForeignKey
+ALTER TABLE `step_event_attachments` ADD CONSTRAINT `step_event_attachments_stepId_fkey` FOREIGN KEY (`stepId`) REFERENCES `payment_method_phase_steps`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `step_event_attachments` ADD CONSTRAINT `step_event_attachments_handlerId_fkey` FOREIGN KEY (`handlerId`) REFERENCES `event_handlers`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;

package/prisma/migrations/20260107121844_add_property_transfer_requests/migration.sql

@@ -0,0 +1,64 @@
+/*
+  Warnings:
+
+  - A unique constraint covering the columns `[transferredFromId]` on the table `contracts` will be added. If there are existing duplicate values, this will fail.
+
+*/
+-- AlterTable
+ALTER TABLE `contracts` ADD COLUMN `transferredFromId` VARCHAR(191) NULL,
+    MODIFY `status` ENUM('DRAFT', 'PENDING', 'ACTIVE', 'COMPLETED', 'CANCELLED', 'TERMINATED', 'TRANSFERRED') NOT NULL DEFAULT 'DRAFT',
+    MODIFY `state` ENUM('DRAFT', 'PENDING', 'ACTIVE', 'COMPLETED', 'CANCELLED', 'TERMINATED', 'TRANSFERRED') NOT NULL DEFAULT 'DRAFT';
+
+-- CreateTable
+CREATE TABLE `property_transfer_requests` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `sourceContractId` VARCHAR(191) NOT NULL,
+    `targetPropertyUnitId` VARCHAR(191) NOT NULL,
+    `requestedById` VARCHAR(191) NOT NULL,
+    `reviewedById` VARCHAR(191) NULL,
+    `status` ENUM('PENDING', 'APPROVED', 'REJECTED', 'IN_PROGRESS', 'COMPLETED', 'FAILED') NOT NULL DEFAULT 'PENDING',
+    `reason` TEXT NULL,
+    `reviewNotes` TEXT NULL,
+    `priceAdjustmentHandling` VARCHAR(191) NULL,
+    `sourceTotalAmount` DOUBLE NULL,
+    `targetTotalAmount` DOUBLE NULL,
+    `priceAdjustment` DOUBLE NULL,
+    `paymentsMigrated` INTEGER NULL,
+    `targetContractId` VARCHAR(191) NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `reviewedAt` DATETIME(3) NULL,
+    `completedAt` DATETIME(3) NULL,
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `property_transfer_requests_tenantId_idx`(`tenantId`),
+    INDEX `property_transfer_requests_sourceContractId_idx`(`sourceContractId`),
+    INDEX `property_transfer_requests_targetPropertyUnitId_idx`(`targetPropertyUnitId`),
+    INDEX `property_transfer_requests_requestedById_idx`(`requestedById`),
+    INDEX `property_transfer_requests_status_idx`(`status`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateIndex
+CREATE UNIQUE INDEX `contracts_transferredFromId_key` ON `contracts`(`transferredFromId`);
+
+-- AddForeignKey
+ALTER TABLE `contracts` ADD CONSTRAINT `contracts_transferredFromId_fkey` FOREIGN KEY (`transferredFromId`) REFERENCES `contracts`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `property_transfer_requests` ADD CONSTRAINT `property_transfer_requests_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `property_transfer_requests` ADD CONSTRAINT `property_transfer_requests_sourceContractId_fkey` FOREIGN KEY (`sourceContractId`) REFERENCES `contracts`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `property_transfer_requests` ADD CONSTRAINT `property_transfer_requests_targetPropertyUnitId_fkey` FOREIGN KEY (`targetPropertyUnitId`) REFERENCES `property_units`(`id`) ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `property_transfer_requests` ADD CONSTRAINT `property_transfer_requests_requestedById_fkey` FOREIGN KEY (`requestedById`) REFERENCES `users`(`id`) ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `property_transfer_requests` ADD CONSTRAINT `property_transfer_requests_reviewedById_fkey` FOREIGN KEY (`reviewedById`) REFERENCES `users`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `property_transfer_requests` ADD CONSTRAINT `property_transfer_requests_targetContractId_fkey` FOREIGN KEY (`targetContractId`) REFERENCES `contracts`(`id`) ON DELETE SET NULL ON UPDATE CASCADE;

package/prisma/schema.prisma

@@ -48,6 +48,16 @@ enum ContractStatus {
   COMPLETED
   CANCELLED
   TERMINATED
+  TRANSFERRED // Contract was transferred to a different property
+}
+
+enum TransferRequestStatus {
+  PENDING
+  APPROVED
+  REJECTED
+  IN_PROGRESS
+  COMPLETED
+  FAILED
 }
 
 enum PhaseStatus {
@@ -84,6 +94,15 @@ enum StepStatus {
   AWAITING_REVIEW // Submitted, waiting for admin/system review
 }
 
+/// When a step event attachment should trigger
+enum StepTrigger {
+  ON_COMPLETE // When step is approved/completed
+  ON_REJECT // When step is rejected
+  ON_SUBMIT // When step is submitted for review
+  ON_RESUBMIT // When step is resubmitted after rejection
+  ON_START // When step transitions to IN_PROGRESS
+}
+
 enum InstallmentStatus {
   PENDING
   PAID
@@ -283,6 +302,10 @@ model User {
   offerLettersGenerated OfferLetter[] @relation("OfferLetterGenerator")
   offerLettersSent      OfferLetter[] @relation("OfferLetterSender")
 
+  // Property transfer requests
+  transferRequestsSubmitted PropertyTransferRequest[] @relation("TransferRequestor")
+  transferRequestsReviewed  PropertyTransferRequest[] @relation("TransferReviewer")
+
   @@index([email])
   @@index([tenantId])
   @@map("users")
@@ -372,6 +395,9 @@ model Tenant {
   eventHandlers  EventHandler[]
   workflowEvents WorkflowEvent[]
 
+  // Property transfer requests
+  propertyTransferRequests PropertyTransferRequest[]
+
   @@index([subdomain])
   @@map("tenants")
 }
@@ -770,6 +796,9 @@ model PropertyUnit {
   // Relations
   contracts Contract[]
 
+  // Transfer requests targeting this unit
+  transferRequests PropertyTransferRequest[]
+
   @@unique([variantId, unitNumber])
   @@index([variantId])
   @@index([status])
@@ -947,10 +976,42 @@ model PaymentMethodPhaseStep {
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 
+  // Event attachments - handlers that fire on step transitions
+  eventAttachments StepEventAttachment[]
+
   @@index([phaseId])
   @@map("payment_method_phase_steps")
 }
 
+/// Step Event Attachment - Links event handlers to step template triggers
+/// When a step transitions (complete, reject, etc.), attached handlers fire
+model StepEventAttachment {
+  id     String @id @default(cuid())
+  stepId String
+  step   PaymentMethodPhaseStep @relation(fields: [stepId], references: [id], onDelete: Cascade)
+
+  /// When this handler should fire
+  trigger StepTrigger
+
+  /// The event handler to execute
+  handlerId String
+  handler   EventHandler @relation(fields: [handlerId], references: [id], onDelete: Cascade)
+
+  /// Order of execution (lower = first)
+  priority Int @default(100)
+
+  /// Whether this attachment is active
+  enabled Boolean @default(true)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([stepId, handlerId, trigger])
+  @@index([stepId])
+  @@index([handlerId])
+  @@map("step_event_attachments")
+}
+
 // Required document within a DOCUMENTATION phase
 model PaymentMethodPhaseDocument {
   id      String                     @id @default(cuid())
@@ -1042,6 +1103,16 @@ model Contract {
   // Payment method change requests for this contract
   paymentMethodChangeRequests PaymentMethodChangeRequest[]
 
+  // Transfer tracking - when a contract is transferred to a different property
+  transferredFromId String?   @unique // Source contract if this was created via transfer
+  transferredFrom   Contract? @relation("ContractTransfer", fields: [transferredFromId], references: [id])
+  transferredTo     Contract? @relation("ContractTransfer")
+
+  // Transfer requests where this contract is the source
+  outgoingTransferRequests PropertyTransferRequest[] @relation("SourceContract")
+  // Transfer requests where this contract is the target (created after approval)
+  incomingTransferRequests PropertyTransferRequest[] @relation("TargetContract")
+
   @@index([tenantId])
   @@index([propertyUnitId])
   @@index([buyerId])
@@ -1789,6 +1860,9 @@ model EventHandler {
   /// Handler execution logs
   executions EventHandlerExecution[]
 
+  /// Step attachments - steps that have attached this handler
+  stepAttachments StepEventAttachment[]
+
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 
@@ -1930,3 +2004,63 @@ model DomainEvent {
   @@index([occurredAt])
   @@map("domain_events")
 }
+
+// =============================================================================
+// Property Transfer Request
+// =============================================================================
+// Allows a buyer to request transferring their contract to a different property
+// while preserving payments, completed workflow steps, and progress.
+// =============================================================================
+
+model PropertyTransferRequest {
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  // Source contract being transferred
+  sourceContractId String
+  sourceContract   Contract @relation("SourceContract", fields: [sourceContractId], references: [id], onDelete: Cascade)
+
+  // Target property unit
+  targetPropertyUnitId String
+  targetPropertyUnit   PropertyUnit @relation(fields: [targetPropertyUnitId], references: [id])
+
+  // Requestor (buyer) and reviewer (admin)
+  requestedById String
+  requestedBy   User    @relation("TransferRequestor", fields: [requestedById], references: [id])
+  reviewedById  String?
+  reviewedBy    User?   @relation("TransferReviewer", fields: [reviewedById], references: [id])
+
+  // Status and workflow
+  status TransferRequestStatus @default(PENDING)
+
+  // Request details
+  reason String? @db.Text // Buyer's reason for transfer
+
+  // Review details
+  reviewNotes             String? @db.Text // Admin notes on decision
+  priceAdjustmentHandling String? // How to handle price difference: ADD_TO_MORTGAGE, REQUIRE_PAYMENT, CREDIT_BUYER
+
+  // Computed values
+  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
+
+  // Result - new contract created after approval
+  targetContractId String?
+  targetContract   Contract? @relation("TargetContract", fields: [targetContractId], references: [id])
+
+  // Timestamps
+  createdAt   DateTime  @default(now())
+  reviewedAt  DateTime?
+  completedAt DateTime?
+  updatedAt   DateTime  @updatedAt
+
+  @@index([tenantId])
+  @@index([sourceContractId])
+  @@index([targetPropertyUnitId])
+  @@index([requestedById])
+  @@index([status])
+  @@map("property_transfer_requests")
+}