PM-5043: Use gross challenge payments for BA sync

What was broken
Finance rebuilt challenge billing-account lock and consume totals from payment.total_amount. Some challenge payment rows can carry a fee-inclusive total, so the billing ledger could store member payments with the challenge fee already included and then apply markup again.

Root cause
The previous UI and billing API fixes corrected how existing ledger rows were displayed, but the finance synchronization path could still write or rebuild challenge billing rows from fee-inclusive payment totals instead of the member-payment subtotal.

What was changed
Added a shared finance helper that resolves the challenge member-payment amount from gross_amount with total_amount as a fallback. Updated new winning creation sync and wallet-admin resync paths to use that member subtotal when recalculating challenge billing-account rows.

Any added/updated tests
Updated WinningsService and AdminService coverage so fee-inclusive total_amount rows still sync billing accounts from gross_amount member payments.

Author: jmgasper

src/api/admin/admin.service.spec.ts

@@ -401,8 +401,8 @@ describe('AdminService', () => {
         },
       ])
       .mockResolvedValueOnce([
-        { total_amount: '12.00' },
-        { total_amount: '27.50' },
+        { gross_amount: '12.00', total_amount: '15.96' },
+        { gross_amount: '27.50', total_amount: '36.58' },
       ]);
     topcoderChallengesService.getChallengeById.mockResolvedValue({
       billing: {
@@ -439,7 +439,10 @@ describe('AdminService', () => {
       },
     });
     expect(prisma.payment.findMany).toHaveBeenNthCalledWith(2, {
-      select: { total_amount: true },
+      select: {
+        gross_amount: true,
+        total_amount: true,
+      },
       where: {
         billing_account: '80001012',
         currency: 'USD',
@@ -536,8 +539,8 @@ describe('AdminService', () => {
         },
       ])
       .mockResolvedValueOnce([
-        { total_amount: '150.00' },
-        { total_amount: '25.00' },
+        { gross_amount: '150.00', total_amount: '199.50' },
+        { gross_amount: '25.00', total_amount: '33.25' },
       ]);
     topcoderChallengesService.getChallengeById.mockResolvedValue({
       billing: {

src/api/admin/admin.service.ts

@@ -34,6 +34,7 @@ import {
   TopcoderChallengesService,
 } from 'src/shared/topcoder/challenges.service';
 import { WinningPaymentDetailsDto } from './dto/payment-details.dto';
+import { resolveChallengeMemberPaymentAmount } from 'src/shared/payments/challenge-payment-amount.util';
 
 const PAYMENT_DECIMAL_PLACES = 2;
 const BUDGET_LEDGER_DECIMAL_PLACES = 4;
@@ -573,20 +574,25 @@ export class AdminService {
   }
 
   /**
-   * Sums non-cancelled USD payment rows for a challenge and billing account.
+   * Sums non-cancelled USD member-payment rows for a challenge and billing
+   * account.
    *
    * @param challengeId challenge external id stored on winnings.
    * @param billingAccountId billing account stored on payment rows.
-   * @returns total member-payment amount that should remain locked or consumed
-   * for the challenge billing-account line item.
+   * @returns Total member-payment amount that should remain locked or consumed
+   * for the challenge billing-account line item. `gross_amount` is used before
+   * `total_amount` so fee-inclusive totals are not marked up again.
    * @throws Prisma errors when the aggregate query fails.
    */
   private async getActiveChallengePaymentTotal(
     challengeId: string,
     billingAccountId: number,
   ): Promise<number> {
     const payments = await this.prisma.payment.findMany({
-      select: { total_amount: true },
+      select: {
+        gross_amount: true,
+        total_amount: true,
+      },
       where: {
         billing_account: String(billingAccountId),
         currency: PrizeType.USD,
@@ -599,7 +605,12 @@ export class AdminService {
     });
     const totalAmount = payments.reduce(
       (sum, paymentRow) =>
-        sum.plus(new Prisma.Decimal(paymentRow.total_amount ?? 0)),
+        sum.plus(
+          resolveChallengeMemberPaymentAmount({
+            grossAmount: paymentRow.gross_amount,
+            totalAmount: paymentRow.total_amount,
+          }),
+        ),
       new Prisma.Decimal(0),
     );
 

src/api/winnings/winnings.service.spec.ts

@@ -450,8 +450,8 @@ describe('WinningsService', () => {
       status: 'COMPLETED',
     });
     tx.payment.findMany.mockResolvedValue([
-      { total_amount: '75.00' },
-      { total_amount: '25.00' },
+      { gross_amount: '75.00', total_amount: '99.75' },
+      { gross_amount: '25.00', total_amount: '33.25' },
     ]);
 
     await service.createWinningWithPayments(
@@ -477,7 +477,10 @@ describe('WinningsService', () => {
     );
 
     expect(tx.payment.findMany).toHaveBeenCalledWith({
-      select: { total_amount: true },
+      select: {
+        gross_amount: true,
+        total_amount: true,
+      },
       where: {
         billing_account: '80001012',
         currency: PrizeType.USD,
@@ -546,8 +549,8 @@ describe('WinningsService', () => {
       status: 'DRAFT',
     });
     tx.payment.findMany.mockResolvedValue([
-      { total_amount: '100.00' },
-      { total_amount: '50.25' },
+      { gross_amount: '100.00', total_amount: '120.00' },
+      { gross_amount: '50.25', total_amount: '60.30' },
     ]);
 
     await service.createWinningWithPayments(
@@ -576,7 +579,10 @@ describe('WinningsService', () => {
       'challenge-id',
     );
     expect(tx.payment.findMany).toHaveBeenCalledWith({
-      select: { total_amount: true },
+      select: {
+        gross_amount: true,
+        total_amount: true,
+      },
       where: {
         billing_account: '80001012',
         currency: PrizeType.USD,

src/api/winnings/winnings.service.ts

@@ -40,6 +40,7 @@ import {
   TopcoderChallengesService,
 } from 'src/shared/topcoder/challenges.service';
 import { TopcoderM2MHttpError } from 'src/shared/topcoder/topcoder-m2m.service';
+import { resolveChallengeMemberPaymentAmount } from 'src/shared/payments/challenge-payment-amount.util';
 
 const BUDGET_LEDGER_DECIMAL_PLACES = 4;
 const PAYMENT_DECIMAL_PLACES = 2;
@@ -539,22 +540,25 @@ export class WinningsService {
   }
 
   /**
-   * Sums non-cancelled persisted USD payment rows for a challenge and billing
-   * account.
+   * Sums non-cancelled persisted USD member-payment rows for a challenge and
+   * billing account.
    *
    * @param tx active Prisma transaction.
    * @param challengeId challenge external id stored on winnings.
    * @param billingAccountId billing account stored on payment rows.
-   * @returns Payment-scale total USD amount for active challenge payments on
-   * that billing account.
+   * @returns Payment-scale member-payment amount for active challenge payments
+   * on that billing account.
    */
   private async getPersistedChallengePaymentTotal(
     tx: Prisma.TransactionClient,
     challengeId: string,
     billingAccountId: number,
   ): Promise<number> {
     const payments = await tx.payment.findMany({
-      select: { total_amount: true },
+      select: {
+        gross_amount: true,
+        total_amount: true,
+      },
       where: {
         billing_account: String(billingAccountId),
         currency: PrizeType.USD,
@@ -567,7 +571,12 @@ export class WinningsService {
     });
     const totalAmount = payments.reduce(
       (sum, paymentRow) =>
-        sum.plus(new Prisma.Decimal(paymentRow.total_amount ?? 0)),
+        sum.plus(
+          resolveChallengeMemberPaymentAmount({
+            grossAmount: paymentRow.gross_amount,
+            totalAmount: paymentRow.total_amount,
+          }),
+        ),
       new Prisma.Decimal(0),
     );
 

src/shared/payments/challenge-payment-amount.util.ts

@@ -0,0 +1,50 @@
+import { Prisma } from '@prisma/client';
+
+type PaymentAmountValue = Prisma.Decimal | number | string | null | undefined;
+
+export interface ChallengePaymentBudgetAmount {
+  grossAmount?: PaymentAmountValue;
+  totalAmount?: PaymentAmountValue;
+}
+
+/**
+ * Converts a persisted payment amount to a Decimal when it is finite.
+ *
+ * @param value Raw amount from a finance payment column.
+ * @returns Decimal amount, or `undefined` when the value is missing or invalid.
+ * @throws This helper does not throw for missing or non-finite values.
+ */
+function toDecimalAmount(
+  value: PaymentAmountValue,
+): Prisma.Decimal | undefined {
+  if (value === null || value === undefined) {
+    return undefined;
+  }
+
+  const amount = Number(value);
+
+  return Number.isFinite(amount) ? new Prisma.Decimal(amount) : undefined;
+}
+
+/**
+ * Resolves the member-payment amount that should be used for challenge budget sync.
+ *
+ * Challenge payment `total_amount` values can include the billing challenge fee
+ * for older or external callers, while `gross_amount` is the member-payment
+ * amount before markup. Billing-account lock/consume rows must be based on
+ * that member amount so the markup is not applied a second time. Rows without a
+ * valid gross amount fall back to `total_amount` for backward compatibility.
+ *
+ * @param payment payment amount fields from a finance payment row.
+ * @returns Decimal member-payment amount for billing-account synchronization.
+ * @throws This helper does not throw for invalid payment amounts.
+ */
+export function resolveChallengeMemberPaymentAmount(
+  payment: ChallengePaymentBudgetAmount,
+): Prisma.Decimal {
+  return (
+    toDecimalAmount(payment.grossAmount) ??
+    toDecimalAmount(payment.totalAmount) ??
+    new Prisma.Decimal(0)
+  );
+}