Nationality, guest booking, waafi adapter, overall booking flow updates

apps/edr-passenger-api/src/main.ts

@@ -32,46 +32,65 @@ async function bootstrap() {
 ## Overview
 Enterprise-grade REST API for the Ethio-Djibouti Railway passenger booking and management platform. Built with NestJS, TypeScript, PostgreSQL, and Prisma ORM.
 
-## Authentication
-
-### Passenger Authentication (JWT-auth)
-Used for passenger-facing endpoints. Obtain token via \`POST /auth/login\`.
-
-**Usage:** Add header \`Authorization: Bearer <token>\`
-
-### Back-office Authentication (IAM-auth)
-Used for agent, fraud, and reporting endpoints. Requires corporate IAM token.
-
-**Usage:** Add header \`Authorization: Bearer <iam-token>\`
-
 ## Key Features
 
 ### 🎫 Booking Lifecycle
 - Search trips with real-time availability
-- Create bookings with seat selection
+- Age-based passenger categorization (Adult ≥5 years, Child <5 years)
+- Nationality-based verification (Ethiopian Fayda, International Passport)
+- Passenger information collection with verification
+- Coach and seat selection with real-time availability
+- Seat holding (15-minute expiry)
+- Create bookings with verified passenger data
 - Modify bookings (seat changes, passenger updates)
 - Cancel bookings with automatic refunds
 - Multi-segment journey support
 
+### 👤 Passenger Verification
+1. **Ethiopian Nationals:**
+- Automatic Fayda verification for adults (≥5 years)
+- Real-time national ID verification via government database
+- Retrieves verified passenger data (name, DOB, gender)
+- National IDs not stored (policy compliant)
+
+2. **International Passengers:**
+- Passport information collection
+- Manual verification for Djiboutian and other nationals
+- No government database verification required
+
+### 💰 Age-Based Pricing
+- **ADULT** (≥5 years): Pay 100% of base fare
+- **CHILD** (<5 years): First child travels FREE, subsequent children pay 100%
+- Automatic age calculation from date of birth
+- Example: 2 adults + 3 children = 4× base fare (first child free)
+
 ### 💳 Payment Integration
+1. **Ethiopian Payment Methods:**
 - **Telebirr** - Ethiopia's leading mobile money
 - **CBE Birr** - Commercial Bank of Ethiopia
 - **eBirr** - Electronic payment gateway
-- **Card** - International card payments
+
+2. **Djiboutian Payment Methods:**
+- **Waafi** - Djibouti's mobile money service
+
+3. **International Payment Methods:**
+- **Card** - International card payments (Visa, Mastercard)
 - **Wallet** - Internal wallet system
 
 ### 🪑 Seat Management
-- Real-time seat availability
-- Seat holds (15-minute expiry)
+- Real-time seat availability by coach and class
+- Seat holds with 15-minute expiry
 - Auto-assign seats with contiguous algorithm
 - Seat blocking for maintenance
 - Coach-level seat maps
+- Class-based seating (Economy Regular, Economy Bed, VIP Bed)
 
 ### 🎟️ Ticketing
 - QR code and barcode generation
 - PDF ticket generation
 - Gate validation with audit logs
 - Offline validation support
+- Multi-passenger tickets
 
 ### 🏆 Loyalty Program
 - 4 tiers: Bronze, Silver, Gold, Platinum
@@ -100,7 +119,7 @@ Used for agent, fraud, and reporting endpoints. Requires corporate IAM token.
 ### 🌍 Internationalization
 - Multi-language support (English, Amharic, French, Oromo)
 - Locale-based responses
-- Currency formatting
+- Currency formatting (ETB, DJF, USD)
 
 ### 👨‍💼 Agent Operations
 - Counter booking
@@ -108,6 +127,48 @@ Used for agent, fraud, and reporting endpoints. Requires corporate IAM token.
 - Commission tracking
 - Cash reconciliation
 
+## Authentication
+
+### Passenger Authentication (JWT-auth)
+Used for passenger-facing endpoints. Obtain token via \`POST /auth/login\`.
+
+**Usage:** Add header \`Authorization: Bearer <token>\`
+
+### Back-office Authentication (IAM-auth)
+Used for agent, fraud, and reporting endpoints. Requires corporate IAM token.
+
+**Usage:** Add header \`Authorization: Bearer <iam-token>\`
+
+## Passenger Booking Flow
+
+### Step 1: Search Trips
+\`POST /search\` with origin, destination, date, passenger counts, and nationality
+
+### Step 2: Get Fare Quote
+\`POST /search/fare-quote\` with passenger counts and display currency
+
+### Step 3: Passenger Information & Verification
+**For Ethiopian Passengers:**
+\`POST /passengers/verify-fayda\` - Automatic Fayda verification for adults (≥5 years)
+
+**For International Passengers:**
+\`POST /passengers/register-international\` - Passport information collection
+
+### Step 4: View Seat Map
+\`GET /seats/seatmap/{scheduleId}\` - Show available coaches and seats
+
+### Step 5: Login & Hold Seats
+\`POST /auth/login\` then \`POST /seats/hold\` to reserve seats for 15 minutes
+
+### Step 6: Create Booking
+\`POST /bookings/guest\` with verified passenger details and held seats
+
+### Step 7: Process Payment
+\`POST /payments/telebirr\` (Ethiopian) or \`POST /payments/waafi\` (Djiboutian)
+
+### Step 8: Get Tickets
+\`GET /payments/{paymentId}/status\` to confirm payment and retrieve tickets with QR codes
+
 ## Rate Limiting
 - Auth endpoints: 5 requests/minute
 - General endpoints: 100 requests/minute
@@ -132,10 +193,11 @@ List endpoints support pagination:
 
 ## Webhooks
 Payment providers send notifications to:
-- \`POST /payments/webhooks/telebirr\`
-- \`POST /payments/webhooks/cbe-birr\`
-- \`POST /payments/webhooks/ebirr\`
-- \`POST /payments/webhooks/card\`
+- \`POST /payments/webhooks/telebirr\` (Ethiopia)
+- \`POST /payments/webhooks/cbe-birr\` (Ethiopia)
+- \`POST /payments/webhooks/ebirr\` (Ethiopia)
+- \`POST /payments/webhooks/waafi\` (Djibouti)
+- \`POST /payments/webhooks/card\` (International)
 
 ## Support
 - **Email:** support@edr-platform.com