Additional fields for wallet-admin to show expanded engagement details

Author: jmgasper

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

@@ -36,6 +36,10 @@ jest.mock('src/shared/access-control/access-control.service', () => ({
   AccessControlService: class {},
 }));
 
+jest.mock('src/shared/topcoder/members.service', () => ({
+  TopcoderMembersService: class {},
+}));
+
 import { AdminService } from './admin.service';
 
 describe('AdminService', () => {
@@ -54,6 +58,9 @@ describe('AdminService', () => {
     getAssignmentContextById: jest.Mock;
     getEngagementById: jest.Mock;
   };
+  let tcMembersService: {
+    getHandlesByUserIds: jest.Mock;
+  };
 
   beforeEach(() => {
     prisma = {
@@ -70,20 +77,27 @@ describe('AdminService', () => {
       getAssignmentContextById: jest.fn(),
       getEngagementById: jest.fn(),
     };
+    tcMembersService = {
+      getHandlesByUserIds: jest.fn().mockResolvedValue({
+        '654321': 'payment-manager',
+      }),
+    };
 
     service = new AdminService(
       prisma as any,
       paymentsService as any,
       baService as any,
       accessControlService as any,
       topcoderEngagementsService as any,
+      tcMembersService as any,
     );
   });
 
   it('returns work-log and engagement details for engagement payments', async () => {
     prisma.winnings.findFirst.mockResolvedValue({
       winning_id: 'winning-1',
       category: 'ENGAGEMENT_PAYMENT',
+      created_by: '654321',
       external_id: 'assignment-1',
       attributes: {
         hoursWorked: 12.5,
@@ -117,6 +131,9 @@ describe('AdminService', () => {
     expect(
       topcoderEngagementsService.getAssignmentContextById,
     ).toHaveBeenCalledWith('assignment-1');
+    expect(tcMembersService.getHandlesByUserIds).toHaveBeenCalledWith([
+      '654321',
+    ]);
     expect(result.data).toEqual({
       engagementDetails: {
         assignmentId: 'assignment-1',
@@ -130,6 +147,7 @@ describe('AdminService', () => {
         ratePerHour: '75.50',
         standardHoursPerWeek: 40,
       },
+      paymentCreatorHandle: 'payment-manager',
       workLog: {
         hoursWorked: 12.5,
         remarks: 'Completed sprint support and bug triage.',
@@ -141,6 +159,7 @@ describe('AdminService', () => {
     prisma.winnings.findFirst.mockResolvedValue({
       winning_id: 'winning-1',
       category: 'ENGAGEMENT_PAYMENT',
+      created_by: '654321',
       external_id: 'assignment-1',
       attributes: {
         hoursWorked: 8,
@@ -158,6 +177,7 @@ describe('AdminService', () => {
     );
 
     expect(result.data).toEqual({
+      paymentCreatorHandle: 'payment-manager',
       workLog: {
         hoursWorked: 8,
         remarks: 'Weekly support work.',
@@ -170,6 +190,7 @@ describe('AdminService', () => {
       winning_id: 'winning-1',
       winner_id: '123456',
       category: 'ENGAGEMENT_PAYMENT',
+      created_by: '654321',
       external_id: 'engagement-1',
       attributes: {
         hoursWorked: 10,
@@ -222,13 +243,44 @@ describe('AdminService', () => {
         ratePerHour: '82.50',
         standardHoursPerWeek: 35,
       },
+      paymentCreatorHandle: 'payment-manager',
       workLog: {
         hoursWorked: 10,
         remarks: 'Covered support hours.',
       },
     });
   });
 
+  it('falls back to the creator id when the handle lookup misses', async () => {
+    tcMembersService.getHandlesByUserIds.mockResolvedValue({});
+    prisma.winnings.findFirst.mockResolvedValue({
+      winning_id: 'winning-1',
+      category: 'ENGAGEMENT_PAYMENT',
+      created_by: '654321',
+      external_id: 'assignment-1',
+      attributes: {
+        hoursWorked: 8,
+      },
+    });
+    topcoderEngagementsService.getAssignmentContextById.mockRejectedValue(
+      new Error('upstream unavailable'),
+    );
+
+    const result = await service.getWinningPaymentDetails(
+      'winning-1',
+      '123456',
+      ['Payment Admin'],
+    );
+
+    expect(result.data).toEqual({
+      paymentCreatorHandle: '654321',
+      workLog: {
+        hoursWorked: 8,
+        remarks: undefined,
+      },
+    });
+  });
+
   it('prefers a numeric assignmentId stored in winning attributes', async () => {
     prisma.winnings.findFirst.mockResolvedValue({
       winning_id: 'winning-1',

src/api/admin/admin.service.ts

@@ -22,6 +22,7 @@ import {
   TopcoderEngagementDetails,
   TopcoderEngagementsService,
 } from 'src/shared/topcoder/engagements.service';
+import { TopcoderMembersService } from 'src/shared/topcoder/members.service';
 import { WinningPaymentDetailsDto } from './dto/payment-details.dto';
 
 /**
@@ -41,6 +42,7 @@ export class AdminService {
     private readonly baService: BillingAccountsService,
     private readonly accessControlService: AccessControlService,
     private readonly topcoderEngagementsService: TopcoderEngagementsService,
+    private readonly tcMembersService: TopcoderMembersService,
   ) {}
 
   async verifyUserAccessToWinning(
@@ -127,6 +129,42 @@ export class AdminService {
     return undefined;
   }
 
+  /**
+   * Resolves the wallet-admin payment creator into a handle for display.
+   *
+   * @param createdBy raw `created_by` value stored on the winnings row.
+   * @returns The resolved Topcoder handle, or the original identifier when the
+   * handle lookup fails.
+   * @throws This helper does not throw.
+   */
+  private async getPaymentCreatorHandle(
+    createdBy: unknown,
+  ): Promise<string | undefined> {
+    if (typeof createdBy !== 'string') {
+      return undefined;
+    }
+
+    const paymentCreatorId = createdBy.trim();
+    if (!paymentCreatorId) {
+      return undefined;
+    }
+
+    try {
+      const handles = await this.tcMembersService.getHandlesByUserIds([
+        paymentCreatorId,
+      ]);
+
+      return handles[paymentCreatorId] ?? paymentCreatorId;
+    } catch (error) {
+      this.logger.warn(
+        `Failed to resolve payment creator handle for winnings creator ${paymentCreatorId}`,
+        error instanceof Error ? error.message : error,
+      );
+
+      return paymentCreatorId;
+    }
+  }
+
   /**
    * Finds the engagement assignment that best matches the current winning.
    *
@@ -692,8 +730,12 @@ export class AdminService {
       hoursWorked: this.getNumericAttribute(winning.attributes, 'hoursWorked'),
       remarks: this.getStringAttribute(winning.attributes, 'remarks'),
     };
+    const paymentCreatorHandle = await this.getPaymentCreatorHandle(
+      winning.created_by,
+    );
 
     result.data = {
+      paymentCreatorHandle,
       workLog,
     };
 

src/api/admin/dto/payment-details.dto.ts

@@ -77,6 +77,13 @@ export class PaymentWorkLogDto {
 }
 
 export class WinningPaymentDetailsDto {
+  @ApiPropertyOptional({
+    description:
+      'The Topcoder handle of the user who created the payment record',
+    example: 'pm_admin',
+  })
+  paymentCreatorHandle?: string;
+
   @ApiPropertyOptional({
     description:
       'Engagement and assignment details when the winning is an engagement payment',

src/api/repository/winnings.repo.ts

@@ -286,6 +286,7 @@ export class WinningsRepository {
             id: item.winning_id,
             type: item.type,
             winnerId: item.winner_id,
+            createdBy: item.payment?.[0]?.created_by ?? item.created_by,
             origin: item.origin?.origin_name,
             category: (item.category ?? '') as WinningsCategory,
             title: item.title as string,
@@ -383,6 +384,7 @@ export class WinningsRepository {
           id: item.winning_id,
           type: item.type,
           winnerId: item.winner_id,
+          createdBy: item.payment?.[0]?.created_by ?? item.created_by,
           origin: item.origin?.origin_name,
           category: (item.category ?? '') as WinningsCategory,
           title: item.title as string,

src/dto/winning.dto.ts

@@ -113,6 +113,7 @@ export class WinningDto {
   id: string;
   type: string;
   winnerId: string;
+  createdBy?: string;
   origin?: string;
   category: WinningsCategory;
   title: string;