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

import { Body, Controller, Get, Param, Post, UseGuards, Query, Request, UnauthorizedException, Patch, Delete, SetMetadata } from '@nestjs/common';
import { ApiTags, ApiOperation, ApiBearerAuth, ApiResponse, ApiQuery } from '@nestjs/swagger';
import { SkipThrottle, Throttle } from '@nestjs/throttler';
import { PassengersService } from './passengers.service';
import { CreateTravelerProfileDto, CreateSavedRouteDto, VerifyFaydaDto, SavePassengersDto, RegisterPassengerDto } from './passengers.dto';
import { JwtGuard } from '../../common/jwt.guard';
import { PassengerAdmin } from '../../common/passenger-guards';
import { VerifaydaService } from '../verifayda/verifayda.service';
import { OptionalJwtGuard } from '../verifayda/optional-jwt.guard';
import { PrismaService } from '../../common/prisma.service';

@ApiTags('Passengers')
@Controller('passengers')
@Throttle({ strict: { limit: 20, ttl: 60_000 } })
export class PassengersController {
  constructor(
    private service: PassengersService,
    private verifaydaService: VerifaydaService,
    private prisma: PrismaService,
  ) {}

  @Get()
  @SetMetadata('isPublic', true)
  @ApiOperation({ 
    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
        }
      }
    }
  })
  findAll(
    @Query('search') search?: string,
    @Query('gender') gender?: string,
    @Query('dateFrom') dateFrom?: string,
    @Query('dateTo') dateTo?: string,
    @Query('page') page?: string,
    @Query('pageSize') pageSize?: string,
  ) {
    return this.service.findAll({ 
      search, 
      gender,
      dateFrom,
      dateTo,
      page: page ? parseInt(page) : 1, 
      pageSize: pageSize ? parseInt(pageSize) : 20 
    });
  }

  @Get('me')
  @UseGuards(JwtGuard)
  @ApiBearerAuth('JWT-auth')
  @ApiOperation({ 
    summary: 'Get current passenger profile',
    description: 'Returns complete profile for authenticated passenger including passport details and verification status. Returns null if no passenger profile exists.'
  })
  @ApiResponse({ 
    status: 200, 
    description: 'Passenger profile retrieved successfully or null if not found'
  })
  @ApiResponse({ status: 401, description: 'Unauthorized - Invalid or missing token' })
  async getMe(@Request() req: any) {
    if (!req.user || !req.user.id) {
      throw new UnauthorizedException('User not authenticated');
    }

    try {
      const passenger = await this.prisma.passenger.findUnique({
        where: { iamUserId: req.user.id },
      });
      if (!passenger) return null;
      return this.service.getProfile(passenger.id);
    } catch (error) {
      return null;
    }
  }

  @Get(':id/profile')
  @UseGuards(JwtGuard)
  @ApiBearerAuth('JWT-auth')
  @ApiOperation({ summary: 'Get passenger profile' })
  getProfile(@Param('id') id: string) {
    return this.service.getProfile(id);
  }

  @Get(':id/stats')
  @UseGuards(JwtGuard)
  @ApiBearerAuth('JWT-auth')
  @ApiOperation({ summary: 'Get passenger stats' })
  getStats(@Param('id') id: string) {
    return this.service.getStats(id);
  }

  @Post('verify-fayda')
  @SetMetadata('isPublic', true)
  @ApiOperation({
    summary: 'Verify Ethiopian national ID via Verifayda 2.0',
    description: `**Standalone endpoint for pre-verification of Ethiopian national IDs**

---

### Purpose
Pre-verify national ID to auto-fill passenger registration form before submission.

---

### Flow

1. User enters national ID in form

2. Frontend calls \`POST /passengers/verify-fayda\`

3. API queries Verifayda 2.0 government database

4. Returns verified passenger data (name, DOB, gender)

5. Frontend auto-fills form with verified data

6. User submits form via \`POST /passengers/register\`

---

### Features
- Real-time verification via Verifayda 2.0 API
- Retrieves verified data: name, date of birth, gender, nationality
- **National IDs NOT stored** (policy compliant)
- Only for Ethiopian nationals with national ID
- Non-Ethiopians use passport (no verification)

---

### Important Notes
- This is a **read-only** verification endpoint
- Does NOT save passenger data to database
- Use \`POST /passengers/register\` to actually register
- Falls back to manual entry if Verifayda disabled or fails

---

### Authentication
- **Public endpoint** (no authentication required)
- Can be called before login/registration`,
  })
  @ApiResponse({ 
    status: 200, 
    description: 'Verification successful with passenger data',
    schema: {
      example: {
        verified: true,
        passengerData: {
          fullName: 'Abebe Kebede',
          dateOfBirth: '1985-03-15T00:00:00.000Z',
          gender: 'Male',
          nationality: 'Ethiopian'
        }
      }
    }
  })
  @ApiResponse({ status: 400, description: 'Verification failed or Verifayda disabled' })
  verifyFayda(@Body() dto: VerifyFaydaDto) {
    return this.verifaydaService.verifyNationalId(dto.nationalId);
  }

  @Post('register')
  @SetMetadata('isPublic', true)
  @UseGuards(OptionalJwtGuard)
  @ApiBearerAuth('JWT-auth')
  @ApiOperation({
    summary: 'Universal passenger registration endpoint',
    description: `**Single endpoint for all passenger registration scenarios**

---

### Automatic Detection
The API automatically detects:
- **Passenger Type**: Ethiopian (nationalId) vs International (passportNumber)
- **Authentication**: Logged-in (JWT token) vs Guest (deviceId)
- **Verification**: Auto-attempts Fayda for Ethiopian nationals

---

### Scenarios Handled

#### 1. Guest Ethiopian Passenger
- Provide: \`nationalId\`, \`deviceId\`
- Behavior: Attempts Fayda verification → Saves to SavedPassengerProfile
- Response: \`verified: true/false\`, \`linked: false\`

#### 2. Guest International Passenger
- Provide: \`passportNumber\`, \`passportCountry\`, \`deviceId\`
- Behavior: No verification → Saves to SavedPassengerProfile
- Response: \`verified: false\`, \`linked: false\`

#### 3. Logged-in Ethiopian Passenger
- Provide: JWT token + \`nationalId\`
- Behavior: Attempts Fayda verification → Updates user profile
- Response: \`verified: true/false\`, \`linked: true\`

#### 4. Logged-in International Passenger
- Provide: JWT token + \`passportNumber\`, \`passportCountry\`
- Behavior: No verification → Updates user profile
- Response: \`verified: false\`, \`linked: true\`

---

### Authentication
- **Optional JWT Bearer Token** (OptionalJwtGuard)
- Token present → Links to user account
- No token → Saves as guest (requires deviceId)

---

### Benefits
- Single endpoint for all scenarios
- Auto-detects passenger type and flow
- Graceful fallback if Fayda fails
- Consistent response structure

---

### Replaces
- Manual verification + save flows`,
  })
  @ApiResponse({ 
    status: 201, 
    description: 'Passenger registered successfully',
    schema: {
      example: {
        id: 'uuid-123',
        passengerName: 'Abebe Kebede',
        dateOfBirth: '1985-03-15T00:00:00.000Z',
        nationality: 'Ethiopian',
        verified: true,
        linked: false,
        message: 'Passenger details saved for guest booking'
      }
    }
  })
  @ApiResponse({ 
    status: 400, 
    description: 'Validation error or verification failed',
    schema: {
      example: {
        statusCode: 400,
        message: 'Validation failed',
        error: 'Bad Request'
      }
    }
  })
  @ApiResponse({ 
    status: 401, 
    description: 'Invalid JWT token (only if token provided but invalid)' 
  })
  registerPassenger(@Body() dto: RegisterPassengerDto, @Request() req: any) {
    const userId = req.user?.id;
    return this.service.registerPassenger({ ...dto, userId });
  }

  @Post('save-details')
  @SetMetadata('isPublic', true)
  @ApiOperation({
    summary: 'Bulk save passenger details from booking flow',
    description: `**Endpoint for saving multiple passengers in a single booking**

---

### 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.

---

### 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: 'All passenger details saved successfully',
    schema: {
      example: {
        count: 2,
        passengerIds: ['uuid-1', 'uuid-2'],
        passengers: [
          {
            id: 'uuid-1',
            passengerName: 'Abebe Kebede',
            dateOfBirth: '1985-03-15T00:00:00.000Z',
            nationality: 'Ethiopian',
            nationalId: 'ET123456789'
          },
          {
            id: 'uuid-2',
            passengerName: 'Sara Ketsela',
            dateOfBirth: '1990-08-22T00:00:00.000Z',
            nationality: 'Ethiopian',
            nationalId: 'ET987654321'
          }
        ],
        message: 'Passenger details saved successfully'
      }
    }
  })
  @ApiResponse({ status: 400, description: 'Validation error - passengers array required' })
  savePassengers(@Body() dto: SavePassengersDto) {
    return this.service.savePassengers(dto.passengers, dto.userId, dto.deviceId);
  }

  @Post('traveler-profiles')
  @UseGuards(JwtGuard)
  @ApiBearerAuth('JWT-auth')
  @ApiOperation({ summary: 'Add traveler profile (family member)' })
  createTravelerProfile(@Body() dto: CreateTravelerProfileDto) {
    return this.service.createTravelerProfile(dto);
  }

  @Get(':id/traveler-profiles')
  @UseGuards(JwtGuard)
  @ApiBearerAuth('JWT-auth')
  @ApiOperation({ summary: 'Get traveler profiles for passenger' })
  getTravelerProfiles(@Param('id') id: string) {
    return this.service.getTravelerProfiles(id);
  }

  @Post('saved-routes')
  @UseGuards(JwtGuard)
  @ApiBearerAuth('JWT-auth')
  @ApiOperation({ summary: 'Save a route' })
  createSavedRoute(@Body() dto: CreateSavedRouteDto) {
    return this.service.createSavedRoute(dto);
  }

  @Get(':id/saved-routes')
  @UseGuards(JwtGuard)
  @ApiBearerAuth('JWT-auth')
  @ApiOperation({ summary: 'Get saved routes' })
  getSavedRoutes(@Param('id') id: string) {
    return this.service.getSavedRoutes(id);
  }

  @Patch(':id')
  @SetMetadata('isPublic', true)
  @ApiOperation({ 
    summary: 'Update passenger details',
    description: 'Updates passenger information for admin/agent operations'
  })
  @ApiResponse({ status: 200, description: 'Passenger updated successfully' })
  @ApiResponse({ status: 404, description: 'Passenger not found' })
  updatePassenger(@Param('id') id: string, @Body() dto: any) {
    return this.service.updatePassenger(id, dto);
  }

  @Delete(':id')
  @PassengerAdmin()
  @ApiBearerAuth('IAM-auth')
  @ApiOperation({ 
    summary: 'Delete passenger (admin only)',
    description: 'Permanently deletes a passenger record and associated data'
  })
  @ApiQuery({ name: 'cascade', required: false, type: Boolean, description: 'Force delete with all related bookings and data' })
  @ApiResponse({ status: 200, description: 'Passenger deleted successfully' })
  @ApiResponse({ status: 404, description: 'Passenger not found' })
  deletePassenger(@Param('id') id: string, @Query('cascade') cascade?: string) {
    return this.service.deletePassenger(id, cascade === 'true');
  }

  @Get(':id/usage')
  @SetMetadata('isPublic', true)
  @ApiOperation({ 
    summary: 'Check if passenger is in use',
    description: 'Returns list of modules/data that reference this passenger'
  })
  @ApiResponse({ status: 200, description: 'Usage information retrieved' })
  @ApiResponse({ status: 404, description: 'Passenger not found' })
  checkUsage(@Param('id') id: string) {
    return this.service.checkPassengerUsage(id);
  }
}