Merge branch 'alpha' into passenger/feat/iam-integration

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

@@ -218,21 +218,41 @@ The API automatically detects:
 
   @Post('save-details')
   @ApiOperation({
-    summary: '[LEGACY] Save all passenger details before seat selection',
-    description: `**Note:** This endpoint is legacy. Consider using \`POST /passengers/register\` instead.
+    summary: 'Bulk save passenger details from booking flow',
+    description: `**Endpoint for saving multiple passengers in a single booking**
 
-Saves all passenger details to database before proceeding to seat selection.
+---
 
-- Required step in booking flow
-- Saves details for all passengers in booking
-- Supports both logged-in users and guests
-- Prevents data loss if user navigates away
+### Purpose
+Save all passenger details for a multi-passenger booking before proceeding to seat selection. Optimized for batch operations where all passengers are collected upfront.
 
-**Migration:** Use \`POST /passengers/register\` for new implementations.`,
+---
+
+### Use Cases
+1. **Multi-passenger bookings** - Save all passengers in a single request
+2. **Batch registration** - Admin/Agent registering multiple passengers at once
+3. **Data preservation** - Save passenger data before proceeding to seat selection
+4. **Guest bookings** - Multiple guests booking together
+
+---
+
+### Differences from /register
+| Feature | /register | /save-details |
+|---------|-----------|---------------|
+| Purpose | Single passenger registration with optional verification | Bulk save multiple passengers |
+| Passengers | One at a time | Multiple in array |
+| Verification | Auto-attempts for Ethiopian nationals (if enabled) | No automatic verification |
+| Use case | Individual registration flow | Booking flow with all passengers |
+| Authentication | Optional JWT | Optional JWT |
+
+---
+
+### Response
+Returns saved passenger details with generated IDs and confirmation.`,
   })
   @ApiResponse({ 
     status: 201, 
-    description: 'Passenger details saved successfully',
+    description: 'All passenger details saved successfully',
     schema: {
       example: {
         count: 2,
@@ -240,15 +260,17 @@ Saves all passenger details to database before proceeding to seat selection.
         passengers: [
           {
             id: 'uuid-1',
-            passengerName: 'John Doe',
-            dateOfBirth: '1990-01-01T00:00:00.000Z',
-            nationality: 'Ethiopian'
+            passengerName: 'Abebe Kebede',
+            dateOfBirth: '1985-03-15T00:00:00.000Z',
+            nationality: 'Ethiopian',
+            nationalId: 'ET123456789'
           },
           {
             id: 'uuid-2',
-            passengerName: 'Jane Doe',
-            dateOfBirth: '1992-05-15T00:00:00.000Z',
-            nationality: 'Ethiopian'
+            passengerName: 'Sara Ketsela',
+            dateOfBirth: '1990-08-22T00:00:00.000Z',
+            nationality: 'Ethiopian',
+            nationalId: 'ET987654321'
           }
         ],
         message: 'Passenger details saved successfully'
@@ -256,9 +278,8 @@ Saves all passenger details to database before proceeding to seat selection.
     }
   })
   @ApiResponse({ status: 400, description: 'Validation error - passengers array required' })
-  savePassengers(@Body() body: any) {
-    const passengers = body.passengers || (Array.isArray(body) ? body : [body]);
-    return this.service.savePassengers(passengers, body.userId, body.deviceId);
+  savePassengers(@Body() dto: SavePassengersDto) {
+    return this.service.savePassengers(dto.passengers, dto.userId, dto.deviceId);
   }
 
   @Post('traveler-profiles')