Add transaction status lifecycle enforcement

prisma/migrations/20260429000000_enforce_transaction_status_lifecycle/migration.sql

@@ -0,0 +1,15 @@
+UPDATE "transactions"
+SET "status" = 'CANCELLED'
+WHERE "status" = 'FAILED';
+
+ALTER TYPE "TransactionStatus" RENAME TO "TransactionStatus_old";
+
+CREATE TYPE "TransactionStatus" AS ENUM ('PENDING', 'COMPLETED', 'CANCELLED');
+
+ALTER TABLE "transactions"
+ALTER COLUMN "status" DROP DEFAULT,
+ALTER COLUMN "status" TYPE "TransactionStatus"
+USING ("status"::text::"TransactionStatus"),
+ALTER COLUMN "status" SET DEFAULT 'PENDING';
+
+DROP TYPE "TransactionStatus_old";

prisma/schema.prisma

@@ -45,7 +45,6 @@ enum TransactionStatus {
   PENDING
   COMPLETED
   CANCELLED
-  FAILED
 }
 
 // Document types

src/admin/admin.controller.ts

@@ -18,6 +18,7 @@ import {
   ModerationQueueQueryDto,
   ReviewFraudAlertDto,
   TransactionMonitoringQueryDto,
+  UpdateTransactionStatusDto,
 } from './dto/admin.dto';
 import { RestoreBackupDto, UpdateBackupScheduleDto } from '../backup/dto/backup.dto';
 
@@ -127,6 +128,14 @@ export class AdminController {
     return this.adminService.transactionMonitoringSummary();
   }
 
+  @Patch('transactions/:id/status')
+  updateTransactionStatus(
+    @Param('id') transactionId: string,
+    @Body() payload: UpdateTransactionStatusDto,
+  ) {
+    return this.adminService.updateTransactionStatus(transactionId, payload);
+  }
+
   @Get('fraud/alerts')
   listFraudAlerts(@Query() query: FraudAlertsQueryDto) {
     return this.adminService.listFraudAlerts(query);

src/admin/admin.module.ts

@@ -4,9 +4,10 @@ import { AdminService } from './admin.service';
 import { PrismaModule } from '../database/prisma.module';
 import { FraudModule } from '../fraud/fraud.module';
 import { BackupModule } from '../backup/backup.module';
+import { TransactionsModule } from '../transactions/transactions.module';
 
 @Module({
-  imports: [PrismaModule, FraudModule, BackupModule],
+  imports: [PrismaModule, FraudModule, BackupModule, TransactionsModule],
   controllers: [AdminController],
   providers: [AdminService],
   exports: [AdminService],

src/admin/admin.service.ts

@@ -13,16 +13,19 @@ import {
   ModerationQueueQueryDto,
   ReviewFraudAlertDto,
   TransactionMonitoringQueryDto,
+  UpdateTransactionStatusDto,
 } from './dto/admin.dto';
-import { PropertyStatus } from '../types/prisma.types';
+import { PropertyStatus, TransactionStatus, TransactionType } from '../types/prisma.types';
 import { FraudService } from '../fraud/fraud.service';
+import { TransactionsService } from '../transactions/transactions.service';
 
 @Injectable()
 export class AdminService {
   constructor(
     private readonly prisma: PrismaService,
     private readonly fraudService: FraudService,
     private readonly backupService: BackupService,
+    private readonly transactionsService: TransactionsService,
   ) {}
 
   async listBackups() {
@@ -63,22 +66,16 @@ export class AdminService {
         this.prisma.property.count({ where: { status: PropertyStatus.ACTIVE } }),
       ]);
 
-    const [
-      completedTransactions,
-      pendingTransactions,
-      failedTransactions,
-      salesAggregate,
-      rentAggregate,
-    ] = await Promise.all([
-      this.prisma.transaction.count({ where: { status: 'COMPLETED' } }),
-      this.prisma.transaction.count({ where: { status: 'PENDING' } }),
-      this.prisma.transaction.count({ where: { status: 'FAILED' } }),
+    const [completedTransactions, pendingTransactions, salesAggregate, rentAggregate] =
+      await Promise.all([
+      this.prisma.transaction.count({ where: { status: TransactionStatus.COMPLETED } }),
+      this.prisma.transaction.count({ where: { status: TransactionStatus.PENDING } }),
       this.prisma.transaction.aggregate({
-        where: { status: 'COMPLETED', type: 'SALE' },
+        where: { status: TransactionStatus.COMPLETED, type: TransactionType.SALE },
         _sum: { amount: true },
       }),
       this.prisma.transaction.aggregate({
-        where: { status: 'COMPLETED', type: 'TRANSFER' },
+        where: { status: TransactionStatus.COMPLETED, type: TransactionType.TRANSFER },
         _sum: { amount: true },
       }),
     ]);
@@ -101,7 +98,6 @@ export class AdminService {
       systemHealth: {
         completedTransactions,
         pendingTransactions,
-        failedTransactions,
       },
     };
   }
@@ -310,13 +306,12 @@ export class AdminService {
   }
 
   async transactionMonitoringSummary() {
-    const [pending, completed, cancelled, failed, aggregateValue] = await Promise.all([
-      this.prisma.transaction.count({ where: { status: 'PENDING' } }),
-      this.prisma.transaction.count({ where: { status: 'COMPLETED' } }),
-      this.prisma.transaction.count({ where: { status: 'CANCELLED' } }),
-      this.prisma.transaction.count({ where: { status: 'FAILED' } }),
+    const [pending, completed, cancelled, aggregateValue] = await Promise.all([
+      this.prisma.transaction.count({ where: { status: TransactionStatus.PENDING } }),
+      this.prisma.transaction.count({ where: { status: TransactionStatus.COMPLETED } }),
+      this.prisma.transaction.count({ where: { status: TransactionStatus.CANCELLED } }),
       this.prisma.transaction.aggregate({
-        where: { status: 'COMPLETED' },
+        where: { status: TransactionStatus.COMPLETED },
         _sum: { amount: true },
       }),
     ]);
@@ -325,11 +320,14 @@ export class AdminService {
       pending,
       completed,
       cancelled,
-      failed,
       totalCompletedValue: aggregateValue._sum.amount ?? 0,
     };
   }
 
+  async updateTransactionStatus(transactionId: string, payload: UpdateTransactionStatusDto) {
+    return this.transactionsService.updateTransactionStatus(transactionId, payload.status);
+  }
+
   async listFraudAlerts(query: FraudAlertsQueryDto) {
     return this.fraudService.listAlerts(query);
   }

src/admin/dto/admin.dto.ts

@@ -139,6 +139,11 @@ export class TransactionMonitoringQueryDto {
   limit: number = 20;
 }
 
+export class UpdateTransactionStatusDto {
+  @IsEnum(TransactionStatus)
+  status!: TransactionStatus;
+}
+
 export {
   AddFraudInvestigationNoteDto,
   BlockFraudUserDto,

src/transactions/transaction-status.constants.ts

@@ -0,0 +1,20 @@
+import { TransactionStatus } from '../types/prisma.types';
+
+export const DEFAULT_TRANSACTION_STATUS = TransactionStatus.PENDING;
+
+const ALLOWED_TRANSACTION_STATUS_TRANSITIONS: Record<TransactionStatus, readonly TransactionStatus[]> = {
+  [TransactionStatus.PENDING]: [TransactionStatus.COMPLETED, TransactionStatus.CANCELLED],
+  [TransactionStatus.COMPLETED]: [],
+  [TransactionStatus.CANCELLED]: [],
+};
+
+export function canTransitionTransactionStatus(
+  currentStatus: TransactionStatus,
+  nextStatus: TransactionStatus,
+): boolean {
+  if (currentStatus === nextStatus) {
+    return true;
+  }
+
+  return ALLOWED_TRANSACTION_STATUS_TRANSITIONS[currentStatus].includes(nextStatus);
+}

src/transactions/transactions.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { PrismaModule } from '../database/prisma.module';
+import { TransactionsService } from './transactions.service';
+
+@Module({
+  imports: [PrismaModule],
+  providers: [TransactionsService],
+  exports: [TransactionsService],
+})
+export class TransactionsModule {}

src/transactions/transactions.service.ts

@@ -0,0 +1,59 @@
+import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
+import { Decimal } from '@prisma/client/runtime/library';
+import { PrismaService } from '../database/prisma.service';
+import { TransactionStatus, TransactionType } from '../types/prisma.types';
+import {
+  canTransitionTransactionStatus,
+  DEFAULT_TRANSACTION_STATUS,
+} from './transaction-status.constants';
+
+export interface CreateTransactionInput {
+  propertyId: string;
+  buyerId: string;
+  sellerId: string;
+  amount: Decimal | number | string;
+  type: TransactionType;
+  status?: TransactionStatus;
+  blockchainHash?: string | null;
+  contractAddress?: string | null;
+  notes?: string | null;
+}
+
+@Injectable()
+export class TransactionsService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async createTransaction(input: CreateTransactionInput) {
+    return this.prisma.transaction.create({
+      data: {
+        ...input,
+        status: input.status ?? DEFAULT_TRANSACTION_STATUS,
+      },
+    });
+  }
+
+  async updateTransactionStatus(transactionId: string, status: TransactionStatus) {
+    const transaction = await this.prisma.transaction.findUnique({
+      where: { id: transactionId },
+    });
+
+    if (!transaction) {
+      throw new NotFoundException(`Transaction ${transactionId} not found`);
+    }
+
+    if (!canTransitionTransactionStatus(transaction.status as TransactionStatus, status)) {
+      throw new BadRequestException(
+        `Transaction status cannot transition from ${transaction.status} to ${status}`,
+      );
+    }
+
+    if (transaction.status === status) {
+      return transaction;
+    }
+
+    return this.prisma.transaction.update({
+      where: { id: transactionId },
+      data: { status },
+    });
+  }
+}

src/types/prisma.types.ts

@@ -78,7 +78,6 @@ export enum TransactionStatus {
   PENDING = 'PENDING',
   COMPLETED = 'COMPLETED',
   CANCELLED = 'CANCELLED',
-  FAILED = 'FAILED',
 }
 
 export enum FraudSeverity {

test/admin/transaction-status.dto.spec.ts

@@ -0,0 +1,23 @@
+import { BadRequestException, ValidationPipe } from '@nestjs/common';
+import { ArgumentMetadata } from '@nestjs/common/interfaces';
+import { UpdateTransactionStatusDto } from '../../src/admin/dto/admin.dto';
+
+describe('UpdateTransactionStatusDto', () => {
+  const pipe = new ValidationPipe({
+    whitelist: true,
+    forbidNonWhitelisted: true,
+    transform: true,
+  });
+
+  const metadata: ArgumentMetadata = {
+    type: 'body',
+    metatype: UpdateTransactionStatusDto,
+    data: '',
+  };
+
+  it('rejects invalid transaction status values', async () => {
+    await expect(pipe.transform({ status: 'FAILED' }, metadata)).rejects.toBeInstanceOf(
+      BadRequestException,
+    );
+  });
+});