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

2026-08-26 18:42:49 +00:00 · 2026-05-24 16:20:55 +03:00
parent 2f17f9c9ce
commit 87a423c859
37 changed files with 2284 additions and 486 deletions
--- a/README.md
+++ b/README.md
@@ -45,9 +45,18 @@ Enterprise-grade NestJS REST API for the Ethio-Djibouti Railway passenger bookin
  - **DJF** (Djiboutian Franc) - Display option
  - **USD** (US Dollar) - Display option
  - Real-time exchange rate conversion
- **Booking Management** - Complete booking lifecycle with modification, cancellation, refunds, and fare breakdown
+- **Booking Management** - Complete booking lifecycle:
+  - **Guest Booking**: Book without login, optional account creation
+  - **Saved Passengers**: Store passenger details for quick rebooking
+  - Modification, cancellation, refunds, and fare breakdown
+  - Multi-segment journey support
 - **Payment Integration** - Multi-provider support (Telebirr, CBE Birr, eBirr, Card, Wallet) with webhook handling
- **Seat Management** - Real-time seat inventory, holds, releases, and blocking with coach/class management
+- **Seat Management** - Real-time seat inventory:
+  - Seat holds with 15-minute expiry
+  - Seat releases and blocking with coach/class management
+  - Segment-based seat availability (partial journey bookings)
+  - Auto-assign seats with contiguous algorithm
+  - CSV import/export for seat configurations
 - **Ticketing** - QR code and barcode generation, PDF tickets, gate validation with audit logs
 - **Agent Operations** - Counter booking, shift management, commission tracking, and reconciliation
 - **Passenger Services** - Profile management, traveler profiles, saved routes, and preferences
@@ -173,7 +182,7 @@ pnpm --filter @edr/passenger-api run prisma:seed
 - 21 Stations (Complete Ethiopian-Djibouti Railway with country codes)
 - 1 Route with 21 stops and fare rules
 - 2 Train services with 4 trips
- 360 seats across 12 coaches (Economy, Bed, VIP classes)
+- 360 seats across 12 coaches (Economy Regular, Economy Bed, VIP Bed classes)
 - 3 User accounts (Admin, Passenger, Agent)
 - Fare rules for ADULT and CHILD passenger categories
 - Currency exchange rates (ETB, DJF, USD)
@@ -182,6 +191,7 @@ pnpm --filter @edr/passenger-api run prisma:seed
 - Promotions and FAQ content
 - Menu items and station crowd signals
 - Fraud detection rules
+- Saved passenger profiles for testing

 ### 5. Start Development Server
 ```bash
@@ -228,25 +238,28 @@ The API uses two authentication schemes:
 | Module | Base Path | Auth Type | Description |
 |--------|-----------|-----------|-------------|
 | **Auth** | `/auth` | Public/JWT | Register, login, OTP verification, password reset |
-| **Agents** | `/agents` | IAM | Agent booking, shifts, commissions, reconciliation |
-| **Fraud Detection** | `/fraud` | IAM | Fraud alerts, rules management, user blocking |
-| **Reports** | `/reports` | IAM | Revenue, occupancy, agent sales analytics |
-| **Stations** | `/stations` | JWT | Station directory and information |
-| **Fleet** | `/fleet` | JWT/IAM | Train services, coaches, seat configurations |
-| **Schedules** | `/schedules` | JWT/IAM | Trip schedules, fare rules, status updates |
-| **Search** | `/search` | JWT | Trip search, availability, fare quotes |
+| **Passengers** | `/passengers` | Public/JWT | Verifayda verification, international registration, profiles |
+| **Search** | `/search` | Public | Trip search, availability, fare quotes |
+| **Stations** | `/stations` | Public/JWT | Station directory and information |
 | **Seats** | `/seats` | JWT/IAM | Seat maps, holds, releases, blocking |
-| **Bookings** | `/bookings` | JWT | Create, modify, cancel bookings |
+| **Bookings** | `/bookings` | Public/JWT | Guest booking, create, modify, cancel bookings |
 | **Payments** | `/payments` | JWT/Public | Payment initiation, webhooks, refunds |
 | **Tickets** | `/tickets` | JWT/IAM | Ticket generation, QR/barcode, validation |
-| **Passengers** | `/passengers` | JWT | Profile management, traveler profiles |
 | **Notifications** | `/notifications` | JWT | In-app notifications, preferences |
 | **Loyalty** | `/loyalty` | JWT | Points, tiers, rewards redemption |
 | **Wallet** | `/wallet` | JWT | Balance, top-up, transaction history |
-| **Promotions** | `/promos` | JWT | Active promotions, promo code validation |
-| **Live Tracking** | `/live` | JWT | Real-time trip status, crowd signals |
-| **Support** | `/support` | JWT | FAQ, chat conversations |
+| **Promotions** | `/promos` | Public/JWT | Active promotions, promo code validation |
+| **Live Tracking** | `/live` | Public/JWT | Real-time trip status, crowd signals |
+| **Support** | `/support` | Public/JWT | FAQ, chat conversations |
 | **Dashboard** | `/dashboard` | JWT | Home screen aggregated data |
+| **Routes** | `/routes` | JWT/IAM | Reusable route templates with ordered stops |
+| **Schedules** | `/schedules` | JWT/IAM | Trip schedules, fare rules, status updates |
+| **Fleet** | `/fleet` | JWT/IAM | Train services, coaches, seat configurations |
+| **Seat Classes** | `/seat-classes` | Public/JWT/IAM | Seat class management and configuration |
+| **Segment Seats** | `/segments/seats` | Public/JWT | Segment-based seat availability and booking |
+| **Agents** | `/agents` | IAM | Agent booking, shifts, commissions, reconciliation |
+| **Fraud Detection** | `/fraud` | IAM | Fraud alerts, rules management, user blocking |
+| **Reports** | `/reports` | IAM | Revenue, occupancy, agent sales analytics |

 ### Example API Calls

@@ -280,30 +293,60 @@ Content-Type: application/json
 }
 ```

-#### 2b. Agent Booking (IAM Auth)
+#### 3. Verify Ethiopian National ID (Verifayda)
 ```bash
-POST /agents/bookings
-Authorization: Bearer <iam-token>
+POST /passengers/verify-fayda
 Content-Type: application/json

 {
-  "tripId": "uuid",
-  "seats": [...],
-  "paymentMethod": "CASH",
-  "cashReceived": 50000
+  "nationalId": "ET123456789"
+}
+
+# Response with verified passenger data
+{
+  "verified": true,
+  "passengerData": {
+    "fullName": "Abebe Kebede",
+    "dateOfBirth": "1985-03-15T00:00:00.000Z",
+    "gender": "Male",
+    "nationality": "Ethiopian"
+  }
 }
 ```

-#### 3. Search Trips
+#### 4. Register International Passenger
 ```bash
-GET /search/trips?originStationId={id}&destinationStationId={id}&date=2026-06-15&adultCount=2&childCount=1
-Authorization: Bearer {token}
+POST /passengers/register-international
+Content-Type: application/json
+
+{
+  "passengerName": "John Smith",
+  "dateOfBirth": "1990-07-20",
+  "passportNumber": "P1234567",
+  "passportCountry": "Kenya",
+  "nationality": "Kenyan",
+  "phone": "+254712345678",
+  "email": "john@example.com"
+}
 ```

-#### 4. Get Fare Quote
+#### 5. Search Trips
+```bash
+POST /search
+Content-Type: application/json
+
+{
+  "originStationId": "uuid",
+  "destinationStationId": "uuid",
+  "date": "2026-06-15",
+  "adultCount": 2,
+  "childCount": 1
+}
+```
+
+#### 6. Get Fare Quote
 ```bash
 POST /search/fare-quote
-Authorization: Bearer {token}
 Content-Type: application/json

 {
@@ -330,17 +373,16 @@ Content-Type: application/json
 }
 ```

-#### 5. Create Booking
+#### 7. Guest Booking (No Login Required)
 ```bash
-POST /bookings
-Authorization: Bearer {token}
+POST /bookings/guest
 Content-Type: application/json

 {
  "tripId": "uuid",
  "holdId": "uuid",
  "serviceClass": "ECONOMY_REGULAR",
-  "displayCurrency": "DJF",
+  "displayCurrency": "ETB",
  "passengers": [
    {
      "seatId": "uuid",
@@ -348,23 +390,25 @@ Content-Type: application/json
      "dateOfBirth": "1985-03-15",
      "idDocumentType": "NATIONAL_ID",
      "idDocumentNumber": "ET123456789"
-    },
-    {
-      "seatId": "uuid",
-      "passengerName": "Sara Abebe",
-      "dateOfBirth": "2023-01-10",
-      "idDocumentType": "NATIONAL_ID",
-      "idDocumentNumber": "ET987654321"
-    },
-    {
-      "seatId": "uuid",
-      "passengerName": "John Smith",
-      "dateOfBirth": "1990-07-20",
-      "idDocumentType": "PASSPORT",
-      "passportNumber": "P1234567",
-      "passportCountry": "Kenya"
    }
-  ]
+  ],
+  "createAccount": false,
+  "savePassengerDetails": true,
+  "deviceId": "device-uuid"
+}
+```
+
+#### 8. Agent Booking (IAM Auth)
+```bash
+POST /agents/bookings
+Authorization: Bearer <iam-token>
+Content-Type: application/json
+
+{
+  "tripId": "uuid",
+  "seats": [...],
+  "paymentMethod": "CASH",
+  "cashReceived": 50000
 }
 ```

@@ -453,6 +497,9 @@ apps/edr-passenger-api/
 - `SeatBlock`, `SeatHold`
 - `CurrencyExchangeRate` (Multi-currency)
 - `VerifaydaVerification` (National ID verification)
+- `SavedPassengerProfile` (Guest booking)
+- `SeatClass` (Seat class configuration)
+- `JourneySegment` (Multi-segment journeys)

 ## 🔧 Available Scripts