Boarding, payment methods, journey direction on seat hold, and more updates

apps/edr-passenger-api/src/modules/passengers/passengers.controller.ts

@@ -21,22 +21,152 @@ export class PassengersController {
   @Get()
   @SetMetadata('isPublic', true)
   @ApiOperation({ 
-    summary: 'List all passengers with filters (Admin/Agent)',
-    description: 'Returns paginated list of passengers with search filters'
+    summary: 'List all travelers with filters (Admin/Agent)',
+    description: `**Returns paginated list of all travelers in the system**
+
+---
+
+### Data Source
+- Fetches from **TravelerProfile** table (created during booking)
+- Shows ALL passengers from ALL bookings (including guest bookings)
+- Each row represents a unique traveler, not a user account
+
+---
+
+### Features
+- Search by name, email, phone
+- Filter by gender
+- Date range filtering (createdAt)
+- Pagination support (page, pageSize)
+- Includes loyalty and wallet info if linked to user account
+- Shows booking count per traveler
+
+---
+
+### Response Fields
+- **id**: TravelerProfile ID
+- **fullName**: Passenger name
+- **email/phone**: Contact info (from linked user or booking)
+- **gender**: Male/Female/Other (from Verifayda or manual entry)
+- **dateOfBirth**: Birth date in YYYY-MM-DD format
+- **nationality**: Passenger nationality
+- **faydaVerified**: Whether verified via Verifayda
+- **loyaltyTier/loyaltyPoints**: If linked to user account
+- **totalBookings**: Number of bookings
+- **createdAt**: When traveler was first added to system`
+  })
+  @ApiQuery({ name: 'search', required: false, description: 'Search by name, email, or phone' })
+  @ApiQuery({ name: 'gender', required: false, description: 'Filter by gender (Male, Female, Other)' })
+  @ApiQuery({ name: 'dateFrom', required: false, description: 'Filter by creation date from (YYYY-MM-DD)' })
+  @ApiQuery({ name: 'dateTo', required: false, description: 'Filter by creation date to (YYYY-MM-DD)' })
+  @ApiQuery({ name: 'page', required: false, description: 'Page number (default: 1)' })
+  @ApiQuery({ name: 'pageSize', required: false, description: 'Items per page (default: 20)' })
+  @ApiResponse({
+    status: 200,
+    description: 'Travelers retrieved successfully',
+    schema: {
+      example: {
+        items: [
+          {
+            id: 'uuid-123',
+            fullName: 'Abebe Kebede',
+            email: 'abebe@example.com',
+            phone: '+251911234567',
+            gender: 'Male',
+            dateOfBirth: '1985-03-15',
+            nationality: 'Ethiopian',
+            faydaVerified: true,
+            loyaltyTier: 'SILVER',
+            loyaltyPoints: 1500,
+            totalBookings: 5,
+            createdAt: '2024-01-10T12:00:00.000Z'
+          }
+        ],
+        meta: {
+          page: 1,
+          pageSize: 20,
+          total: 150,
+          totalPages: 8
+        }
+      }
+    }
+  })
+  @ApiResponse({
+    status: 200,
+    description: 'Travelers retrieved successfully',
+    schema: {
+      example: {
+        items: [
+          {
+            id: 'uuid-123',
+            fullName: 'Abebe Kebede',
+            email: 'abebe@example.com',
+            phone: '+251911234567',
+            gender: 'Male',
+            dateOfBirth: '1985-03-15',
+            nationality: 'Ethiopian',
+            nationalityCode: 'ET',
+            faydaVerified: true,
+            faydaVerifiedAt: '2024-01-15T10:30:00.000Z',
+            passportNumber: null,
+            passportCountry: null,
+            passportExpiryDate: null,
+            idDocumentType: 'NATIONAL_ID',
+            verified: true,
+            lastLoginAt: '2024-01-20T08:15:00.000Z',
+            role: 'PASSENGER',
+            loyalty: {
+              tier: 'SILVER',
+              pointsBalance: 1500,
+              lifetimePoints: 3000
+            },
+            wallet: {
+              balanceMinor: 50000,
+              currency: 'ETB'
+            },
+            loyaltyTier: 'SILVER',
+            loyaltyPoints: 1500,
+            totalBookings: 5,
+            createdAt: '2024-01-10T12:00:00.000Z'
+          },
+          {
+            id: 'uuid-456',
+            fullName: 'Sara Ketsela',
+            email: null,
+            phone: null,
+            gender: 'Female',
+            dateOfBirth: '1990-08-22',
+            nationality: 'Ethiopian',
+            nationalityCode: null,
+            faydaVerified: false,
+            faydaVerifiedAt: null,
+            passportNumber: null,
+            passportCountry: null,
+            passportExpiryDate: null,
+            idDocumentType: null,
+            verified: false,
+            lastLoginAt: null,
+            role: null,
+            loyalty: null,
+            wallet: null,
+            loyaltyTier: 'BRONZE',
+            loyaltyPoints: 0,
+            totalBookings: 1,
+            createdAt: '2024-01-18T14:30:00.000Z'
+          }
+        ],
+        meta: {
+          page: 1,
+          pageSize: 20,
+          total: 150,
+          totalPages: 8
+        }
+      }
+    }
   })
-  @ApiQuery({ name: 'search', required: false })
-  @ApiQuery({ name: 'verified', required: false })
-  @ApiQuery({ name: 'gender', required: false })
-  @ApiQuery({ name: 'nationality', required: false })
-  @ApiQuery({ name: 'dateFrom', required: false })
-  @ApiQuery({ name: 'dateTo', required: false })
-  @ApiQuery({ name: 'page', required: false })
-  @ApiQuery({ name: 'pageSize', required: false })
   findAll(
     @Query('search') search?: string,
-    @Query('verified') verified?: string,
     @Query('gender') gender?: string,
-    @Query('nationality') nationality?: string,
     @Query('dateFrom') dateFrom?: string,
     @Query('dateTo') dateTo?: string,
     @Query('page') page?: string,
@@ -44,9 +174,7 @@ export class PassengersController {
   ) {
     return this.service.findAll({ 
       search, 
-      verified: verified ? verified === 'true' : undefined,
       gender,
-      nationality,
       dateFrom,
       dateTo,
       page: page ? parseInt(page) : 1,