From b27f5931da40d2795fa913e3f237c1ab0c59788e Mon Sep 17 00:00:00 2001
From: kilodesodiq-arch <kilodesodiq-arch@users.noreply.github.com>
Date: Tue, 30 Jun 2026 03:11:31 +0000
Subject: [PATCH] fix(#772): tag Admin controller and add role-restricted
 Swagger badges

- Add @ApiTags('Fraud') at method-level on all 8 fraud endpoints in admin.controller.ts so they appear under the Fraud tag section in Swagger (operations keep their Admin tag too)
- Register tag descriptions 'Admin' and 'Fraud' in setupSwagger with explicit role-restricted ('admin role only') hints, providing the role-restricted badge called out in the issue
- Note: src/fraud/fraud.controller.ts does not currently exist; fraud routes are nested under /admin/fraud/* in admin.controller.ts. Extracting into a dedicated FraudController is left for a follow-up issue since it would break URL paths
---
 src/admin/admin.controller.ts | 8 ++++++++
 src/config/swagger.config.ts  | 6 ++++++
 2 files changed, 14 insertions(+)

diff --git a/src/admin/admin.controller.ts b/src/admin/admin.controller.ts
index 4b4947a6..c18b4455 100644
--- a/src/admin/admin.controller.ts
+++ b/src/admin/admin.controller.ts
@@ -163,21 +163,25 @@ export class AdminController {
     return this.adminService.updateTransactionStatus(transactionId, payload, user.sub);
   }
 
+  @ApiTags('Fraud')
   @Get('fraud/alerts')
   listFraudAlerts(@Query() query: FraudAlertsQueryDto) {
     return this.adminService.listFraudAlerts(query);
   }
 
+  @ApiTags('Fraud')
   @Get('fraud/alerts/summary')
   getFraudAlertsSummary() {
     return this.adminService.getFraudAlertsSummary();
   }
 
+  @ApiTags('Fraud')
   @Get('fraud/alerts/:id')
   getFraudAlertDetails(@Param('id') alertId: string) {
     return this.adminService.getFraudAlertDetails(alertId);
   }
 
+  @ApiTags('Fraud')
   @Patch('fraud/alerts/:id')
   reviewFraudAlert(
     @Param('id') alertId: string,
@@ -187,6 +191,7 @@ export class AdminController {
     return this.adminService.reviewFraudAlert(alertId, payload, user.sub);
   }
 
+  @ApiTags('Fraud')
   @Post('fraud/alerts/:id/notes')
   addFraudAlertNote(
     @Param('id') alertId: string,
@@ -196,6 +201,7 @@ export class AdminController {
     return this.adminService.addFraudAlertNote(alertId, payload, user.sub);
   }
 
+  @ApiTags('Fraud')
   @Post('fraud/alerts/:id/block-user')
   blockFraudUser(
     @Param('id') alertId: string,
@@ -205,11 +211,13 @@ export class AdminController {
     return this.adminService.blockFraudUser(alertId, user.sub, payload);
   }
 
+  @ApiTags('Fraud')
   @Post('fraud/users/:id/scan')
   scanUserForFraud(@Param('id') userId: string, @CurrentUser() user: AuthUserPayload) {
     return this.adminService.scanUserForFraud(userId, user.sub);
   }
 
+  @ApiTags('Fraud')
   @Post('fraud/properties/:id/scan')
   scanPropertyForFraud(@Param('id') propertyId: string, @CurrentUser() user: AuthUserPayload) {
     return this.adminService.scanPropertyForFraud(propertyId, user.sub);
diff --git a/src/config/swagger.config.ts b/src/config/swagger.config.ts
index e245d270..37fb4bc0 100644
--- a/src/config/swagger.config.ts
+++ b/src/config/swagger.config.ts
@@ -50,6 +50,12 @@ export function setupSwagger(app: INestApplication): void {
     .addTag('Trust Score', 'Trust score calculation and management')
     .addTag('Email', 'Email verification endpoints')
     .addTag('Versioning', 'API versioning information')
+    .addTag('Admin', 'Administrative endpoints — admin role only (role-restricted)')
+    .addTag(
+      'Fraud',
+      'Fraud detection and investigation endpoints — admin role only (role-restricted). ' +
+        'Currently routed through the Admin module; a future change may extract these into a dedicated controller.',
+    )
     .build();
 
   const document = SwaggerModule.createDocument(app, config);