feat(web): add error boundaries, 404 page, loading states, and SEO metadata

- Add branded not-found.tsx with navigation links
- Add global error.tsx boundary with retry and error digest display
- Add root loading.tsx skeleton for route transitions
- Expand root layout metadata: OpenGraph, Twitter cards, robots, viewport
- Add sitemap.ts and robots.ts for SEO
- Add search page and listing detail metadata via route layouts

Co-Authored-By: Paperclip <noreply@paperclip.ing>

apps/api/src/modules/payments/presentation/controllers/payments.controller.ts

@@ -8,6 +8,14 @@ import {
   Query,
   UseGuards,
 } from '@nestjs/common';
+import {
+  ApiTags,
+  ApiOperation,
+  ApiResponse,
+  ApiBearerAuth,
+  ApiParam,
+} from '@nestjs/swagger';
+import { Throttle } from '@nestjs/throttler';
 import { CommandBus, QueryBus } from '@nestjs/cqrs';
 import { JwtAuthGuard } from '@modules/auth/presentation/guards/jwt-auth.guard';
 import { RolesGuard } from '@modules/auth/presentation/guards/roles.guard';
@@ -29,6 +37,7 @@ import { RefundPaymentDto } from '../dto/refund-payment.dto';
 import { ListTransactionsDto } from '../dto/list-transactions.dto';
 import { type PaymentProvider } from '@prisma/client';
 
+@ApiTags('payments')
 @Controller('payments')
 export class PaymentsController {
   constructor(
@@ -36,6 +45,11 @@ export class PaymentsController {
     private readonly queryBus: QueryBus,
   ) {}
 
+  @ApiBearerAuth()
+  @ApiOperation({ summary: 'Create a new payment' })
+  @ApiResponse({ status: 201, description: 'Payment created successfully' })
+  @ApiResponse({ status: 400, description: 'Bad request' })
+  @ApiResponse({ status: 401, description: 'Unauthorized' })
   @UseGuards(JwtAuthGuard)
   @Post()
   async createPayment(
@@ -58,6 +72,10 @@ export class PaymentsController {
     );
   }
 
+  @ApiOperation({ summary: 'Handle payment provider callback (webhook)' })
+  @ApiResponse({ status: 201, description: 'Callback processed successfully' })
+  @ApiParam({ name: 'provider', enum: ['vnpay', 'momo', 'zalopay'] })
+  @Throttle({ 'payment-callback': { ttl: 60_000, limit: 20 } })
   @Post('callback/:provider')
   async handleCallback(
     @Param('provider') provider: string,
@@ -72,6 +90,11 @@ export class PaymentsController {
     );
   }
 
+  @ApiBearerAuth()
+  @ApiOperation({ summary: 'Get payment status by ID' })
+  @ApiResponse({ status: 200, description: 'Payment status retrieved' })
+  @ApiResponse({ status: 401, description: 'Unauthorized' })
+  @ApiResponse({ status: 404, description: 'Payment not found' })
   @UseGuards(JwtAuthGuard)
   @Get(':id')
   async getPaymentStatus(
@@ -81,6 +104,10 @@ export class PaymentsController {
     return this.queryBus.execute(new GetPaymentStatusQuery(id, user.sub));
   }
 
+  @ApiBearerAuth()
+  @ApiOperation({ summary: 'List transactions for the authenticated user' })
+  @ApiResponse({ status: 200, description: 'Transactions retrieved' })
+  @ApiResponse({ status: 401, description: 'Unauthorized' })
   @UseGuards(JwtAuthGuard)
   @Get()
   async listTransactions(
@@ -92,6 +119,12 @@ export class PaymentsController {
     );
   }
 
+  @ApiBearerAuth()
+  @ApiOperation({ summary: 'Refund a payment (admin only)' })
+  @ApiResponse({ status: 201, description: 'Refund initiated successfully' })
+  @ApiResponse({ status: 401, description: 'Unauthorized' })
+  @ApiResponse({ status: 403, description: 'Forbidden — admin role required' })
+  @ApiResponse({ status: 404, description: 'Payment not found' })
   @UseGuards(JwtAuthGuard, RolesGuard)
   @Roles('ADMIN')
   @Post(':id/refund')