Merge pull request #175 from topcoder-platform/PM-4958-2

jmgasper · web-flow · commit efd64ee351fc · 2026-04-29T09:17:32.000+10:00
PM-4958: Release engagement BA consumption on cancellation
diff --git a/src/api/admin/admin.service.spec.ts b/src/api/admin/admin.service.spec.ts
@@ -74,6 +74,7 @@ describe('AdminService', () => {
     getBillingAccountById: jest.Mock;
     getBillingAccountsForUser: jest.Mock;
     lockConsumeAmount: jest.Mock;
+    syncEngagementConsumeAmounts: jest.Mock;
   };
   let accessControlService: {
     verifyAccess: jest.Mock;
@@ -120,6 +121,7 @@ describe('AdminService', () => {
         .mockResolvedValue({ id: 80001012, markup: 0.1 }),
       getBillingAccountsForUser: jest.fn().mockResolvedValue(['80001012']),
       lockConsumeAmount: jest.fn().mockResolvedValue(undefined),
+      syncEngagementConsumeAmounts: jest.fn().mockResolvedValue(undefined),
     };
     accessControlService = {
       verifyAccess: jest.fn().mockResolvedValue(undefined),
@@ -457,6 +459,62 @@ describe('AdminService', () => {
     });
   });
 
+  it('releases engagement billing-account rows when an engagement payment is cancelled', async () => {
+    prisma.payment.findMany
+      .mockResolvedValueOnce([
+        {
+          billing_account: '80001012',
+          currency: 'USD',
+          installment_number: 1,
+          payment_id: 'payment-1',
+          payment_status: PaymentStatus.OWED,
+          release_date: new Date('2026-04-28T00:00:00.000Z'),
+          version: 1,
+          winnings: {
+            category: 'ENGAGEMENT_PAYMENT',
+            external_id: 'assignment-1',
+            type: 'PAYMENT',
+          },
+        },
+      ])
+      .mockResolvedValueOnce([]);
+
+    const result = await service.updateWinnings(
+      {
+        paymentId: 'payment-1',
+        paymentStatus: PaymentStatus.CANCELLED,
+        winningsId: 'winning-1',
+      } as any,
+      'admin-1',
+      ['Payment Admin'],
+    );
+
+    expect(result.data).toBe('Successfully updated winnings');
+    expect(prisma.payment.findMany).toHaveBeenNthCalledWith(2, {
+      select: {
+        challenge_fee: true,
+        total_amount: true,
+      },
+      where: {
+        billing_account: '80001012',
+        currency: 'USD',
+        payment_status: { not: PaymentStatus.CANCELLED },
+        winnings: {
+          category: 'ENGAGEMENT_PAYMENT',
+          external_id: 'assignment-1',
+          type: 'PAYMENT',
+        },
+      },
+      orderBy: [{ created_at: 'asc' }, { payment_id: 'asc' }],
+    });
+    expect(baService.syncEngagementConsumeAmounts).toHaveBeenCalledWith({
+      amounts: [],
+      billingAccountId: 80001012,
+      externalId: 'assignment-1',
+    });
+    expect(baService.lockConsumeAmount).not.toHaveBeenCalled();
+  });
+
   it('returns task details for task payment with projectId and approver', async () => {
     prisma.winnings.findFirst.mockResolvedValue({
       winning_id: 'winning-task',
diff --git a/src/api/admin/admin.service.ts b/src/api/admin/admin.service.ts
@@ -36,12 +36,18 @@ import {
 import { WinningPaymentDetailsDto } from './dto/payment-details.dto';
 
 const PAYMENT_DECIMAL_PLACES = 2;
+const BUDGET_LEDGER_DECIMAL_PLACES = 4;
 
 interface ChallengeBudgetSyncTarget {
   billingAccountId: number;
   challengeId: string;
 }
 
+interface EngagementBudgetSyncTarget {
+  assignmentId: string;
+  billingAccountId: number;
+}
+
 /**
  * The admin winning service.
  */
@@ -394,6 +400,55 @@ export class AdminService {
     return [...targets.values()];
   }
 
+  /**
+   * Finds engagement billing-account rows that need to be reconciled after a
+   * wallet-admin payment status change.
+   *
+   * @param payments payment rows selected by the update request.
+   * @returns unique engagement assignment and billing-account pairs touched by
+   * USD engagement payments.
+   * @throws This helper does not throw.
+   */
+  private getEngagementBudgetSyncTargets(
+    payments: Awaited<ReturnType<AdminService['getPaymentsByWinningsId']>>,
+  ): EngagementBudgetSyncTarget[] {
+    const targets = new Map<string, EngagementBudgetSyncTarget>();
+
+    payments.forEach((payment) => {
+      const assignmentId =
+        typeof payment.winnings.external_id === 'string'
+          ? payment.winnings.external_id.trim()
+          : '';
+
+      if (
+        !assignmentId ||
+        payment.winnings.type !== winnings_type.PAYMENT ||
+        payment.winnings.category !== winnings_category.ENGAGEMENT_PAYMENT ||
+        (payment.currency ?? '') !== 'USD'
+      ) {
+        return;
+      }
+
+      const billingAccountId = this.normalizeBillingAccountId(
+        payment.billing_account,
+      );
+
+      if (!billingAccountId) {
+        this.logger.warn(
+          `Skipping engagement budget sync for payment ${payment.payment_id}; invalid billing account ${String(payment.billing_account)}`,
+        );
+        return;
+      }
+
+      targets.set(`${assignmentId}:${billingAccountId}`, {
+        assignmentId,
+        billingAccountId,
+      });
+    });
+
+    return [...targets.values()];
+  }
+
   /**
    * Resolves the billing account to synchronize for a challenge.
    *
@@ -465,6 +520,25 @@ export class AdminService {
     );
   }
 
+  /**
+   * Quantizes a billing-account ledger amount to the same four-decimal scale
+   * used by billing-accounts-api-v6.
+   *
+   * @param amount decimal amount to normalize.
+   * @returns JavaScript number rounded to four decimal places.
+   * @throws This helper does not throw.
+   */
+  private toBillingLedgerAmount(amount: Prisma.Decimal): number {
+    return Number(
+      amount
+        .toDecimalPlaces(
+          BUDGET_LEDGER_DECIMAL_PLACES,
+          Prisma.Decimal.ROUND_HALF_UP,
+        )
+        .toFixed(BUDGET_LEDGER_DECIMAL_PLACES),
+    );
+  }
+
   /**
    * Sums non-cancelled USD payment rows for a challenge and billing account.
    *
@@ -547,6 +621,74 @@ export class AdminService {
     );
   }
 
+  /**
+   * Reads active engagement payment ledger amounts for one assignment.
+   *
+   * @param assignmentId engagement assignment external id stored on winnings.
+   * @param billingAccountId billing account stored on payment rows.
+   * @returns ledger-scale consumed amounts for non-cancelled finance payments,
+   * in the same order used when engagement consumed rows were created.
+   * @throws Prisma errors when the payment query fails.
+   */
+  private async getActiveEngagementConsumeAmounts(
+    assignmentId: string,
+    billingAccountId: number,
+  ): Promise<number[]> {
+    const payments = await this.prisma.payment.findMany({
+      select: {
+        challenge_fee: true,
+        total_amount: true,
+      },
+      where: {
+        billing_account: String(billingAccountId),
+        currency: PrizeType.USD,
+        payment_status: { not: payment_status.CANCELLED },
+        winnings: {
+          category: winnings_category.ENGAGEMENT_PAYMENT,
+          external_id: assignmentId,
+          type: winnings_type.PAYMENT,
+        },
+      },
+      orderBy: [{ created_at: 'asc' }, { payment_id: 'asc' }],
+    });
+
+    return payments.map((paymentRow) =>
+      this.toBillingLedgerAmount(
+        new Prisma.Decimal(paymentRow.total_amount ?? 0).plus(
+          new Prisma.Decimal(paymentRow.challenge_fee ?? 0),
+        ),
+      ),
+    );
+  }
+
+  /**
+   * Reconciles engagement billing-account consumed rows after a wallet-admin
+   * cancellation changes the active payment set.
+   *
+   * @param targets unique engagement assignment and billing-account pairs to
+   * synchronize.
+   * @returns promise resolved after every target has been reconciled in BA.
+   * @throws Error when BA synchronization fails.
+   */
+  private async syncEngagementBudgetTargets(
+    targets: EngagementBudgetSyncTarget[],
+  ): Promise<void> {
+    await Promise.all(
+      targets.map(async (target) => {
+        const amounts = await this.getActiveEngagementConsumeAmounts(
+          target.assignmentId,
+          target.billingAccountId,
+        );
+
+        await this.baService.syncEngagementConsumeAmounts({
+          amounts,
+          billingAccountId: target.billingAccountId,
+          externalId: target.assignmentId,
+        });
+      }),
+    );
+  }
+
   /**
    * Verify that a BA admin user has access to the billing account(s)
    * associated with the given winningsId. Throws BadRequestException when
@@ -642,6 +784,10 @@ export class AdminService {
         body.paymentStatus === PaymentStatus.CANCELLED
           ? this.getChallengeBudgetSyncTargets(payments)
           : [];
+      const engagementBudgetSyncTargets =
+        body.paymentStatus === PaymentStatus.CANCELLED
+          ? this.getEngagementBudgetSyncTargets(payments)
+          : [];
 
       // iterate payments and build transaction list
       payments.forEach((payment) => {
@@ -928,6 +1074,10 @@ export class AdminService {
         await this.syncChallengeBudgetTargets(challengeBudgetSyncTargets);
       }
 
+      if (engagementBudgetSyncTargets.length > 0) {
+        await this.syncEngagementBudgetTargets(engagementBudgetSyncTargets);
+      }
+
       if (needsReconciliation) {
         const winning = await this.prisma.winnings.findFirst({
           select: {
diff --git a/src/shared/topcoder/billing-accounts.service.spec.ts b/src/shared/topcoder/billing-accounts.service.spec.ts
@@ -17,13 +17,34 @@ jest.mock('src/shared/global', () => ({
   },
 }));
 
+const mockBaTx = {
+  $executeRawUnsafe: jest.fn(),
+  $queryRawUnsafe: jest.fn(),
+};
+const mockBaClient = {
+  $transaction: jest.fn(),
+};
+
+jest.mock('src/shared/global/ba-prisma.client', () => ({
+  getBaClient: jest.fn(() => mockBaClient),
+}));
+
 import { ChallengeStatuses } from 'src/dto/challenge.dto';
 import { BillingAccountsService } from './billing-accounts.service';
 
 describe('BillingAccountsService', () => {
   let service: BillingAccountsService;
 
   beforeEach(() => {
+    jest.clearAllMocks();
+    mockBaTx.$executeRawUnsafe.mockResolvedValue(undefined);
+    mockBaTx.$queryRawUnsafe
+      .mockResolvedValueOnce([{ exists: true }])
+      .mockResolvedValueOnce([]);
+    mockBaClient.$transaction.mockImplementation(
+      (callback: (tx: typeof mockBaTx) => unknown) => callback(mockBaTx),
+    );
+
     service = new BillingAccountsService({} as any);
   });
 
@@ -95,4 +116,81 @@ describe('BillingAccountsService', () => {
     });
     expect(consumeAmountSpy).not.toHaveBeenCalled();
   });
+
+  it('deletes stale engagement consumed rows when no active amounts remain', async () => {
+    mockBaTx.$queryRawUnsafe
+      .mockReset()
+      .mockResolvedValueOnce([{ exists: true }])
+      .mockResolvedValueOnce([{ id: 'consumed-row-1' }]);
+
+    await service.syncEngagementConsumeAmounts({
+      amounts: [],
+      billingAccountId: 80001012,
+      externalId: 'assignment-1',
+    });
+
+    expect(mockBaTx.$queryRawUnsafe).toHaveBeenNthCalledWith(
+      2,
+      expect.stringContaining('"externalId" = $2'),
+      80001012,
+      'assignment-1',
+    );
+    expect(mockBaTx.$executeRawUnsafe).toHaveBeenCalledWith(
+      expect.stringContaining('DELETE FROM "ConsumedAmount"'),
+      'consumed-row-1',
+    );
+  });
+
+  it('syncs engagement consumed rows to the active ledger amounts', async () => {
+    mockBaTx.$queryRawUnsafe
+      .mockReset()
+      .mockResolvedValueOnce([{ exists: true }])
+      .mockResolvedValueOnce([{ id: 'consumed-row-1' }, { id: 'stale-row-1' }]);
+
+    await service.syncEngagementConsumeAmounts({
+      amounts: [24.2, 12],
+      billingAccountId: 80001012,
+      externalId: 'assignment-1',
+    });
+
+    expect(mockBaTx.$executeRawUnsafe).toHaveBeenCalledWith(
+      expect.stringContaining('UPDATE "ConsumedAmount"'),
+      24.2,
+      'consumed-row-1',
+    );
+    expect(mockBaTx.$executeRawUnsafe).toHaveBeenCalledWith(
+      expect.stringContaining('UPDATE "ConsumedAmount"'),
+      12,
+      'stale-row-1',
+    );
+    expect(mockBaTx.$executeRawUnsafe).not.toHaveBeenCalledWith(
+      expect.stringContaining('DELETE FROM "ConsumedAmount"'),
+      expect.any(String),
+    );
+  });
+
+  it('syncs legacy consumed rows with the aggregate active amount', async () => {
+    mockBaTx.$queryRawUnsafe
+      .mockReset()
+      .mockResolvedValueOnce([{ exists: false }])
+      .mockResolvedValueOnce([{ id: 'legacy-row-1' }]);
+
+    await service.syncEngagementConsumeAmounts({
+      amounts: [24.2, 12],
+      billingAccountId: 80001012,
+      externalId: 'assignment-1',
+    });
+
+    expect(mockBaTx.$queryRawUnsafe).toHaveBeenNthCalledWith(
+      2,
+      expect.stringContaining('"challengeId" = $2'),
+      80001012,
+      'assignment-1',
+    );
+    expect(mockBaTx.$executeRawUnsafe).toHaveBeenCalledWith(
+      expect.stringContaining('UPDATE "ConsumedAmount"'),
+      36.2,
+      'legacy-row-1',
+    );
+  });
 });
diff --git a/src/shared/topcoder/billing-accounts.service.ts b/src/shared/topcoder/billing-accounts.service.ts
