Round trip journeys, feedback items, backoffice documentation

2026-09-09 07:08:18 +00:00 · 2026-06-16 13:33:03 +03:00
parent 28e183b086
commit 75c8423f50
46 changed files with 7222 additions and 570 deletions
--- a/apps/edr-passenger-api/src/main.ts
+++ b/apps/edr-passenger-api/src/main.ts
@@ -34,6 +34,14 @@ 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.

+## 🆕 Latest Updates
+- **Sequence Ordering:** Stations and coaches now sorted by sequence field for consistent UI display
+- **User Profile Data:** Gender, DOB, passport, and national ID fields for comprehensive passenger profiles
+- **Seat Class Fees:** Premium charges and insurance fees per seat class for transparent pricing
+- **Booking Types:** Support for ONE_WAY and ROUND_TRIP booking categories
+- **Multi-Currency Display:** Bookings track display currency and converted amounts
+- **Ticket Lifecycle:** Tickets now include validatedAt and boardedAt timestamps for complete audit trail
+
 ## Key Features

 ### 🎫 Booking Lifecycle
@@ -47,6 +55,11 @@ Enterprise-grade REST API for the Ethio-Djibouti Railway passenger booking and m
 - Modify bookings (seat changes, passenger updates)
 - Cancel bookings with automatic refunds
 - Multi-segment journey support
+- Cross-border journeys via Dire Dawa transit (Ethiopia → Djibouti)
+- Round-trip booking with return journey scheduling
+- Coach type selection with seat class and pricing options
+- **NEW:** Booking type tracking (ONE_WAY vs ROUND_TRIP)
+- **NEW:** Display currency and converted pricing per booking

 ### 👤 Passenger Verification
 1. **Ethiopian Nationals:**
@@ -65,12 +78,13 @@ Enterprise-grade REST API for the Ethio-Djibouti Railway passenger booking and m
 - **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)
+- **NEW:** Premium charges and insurance fees per seat class
+- **NEW:** Transparent fee breakdown in pricing calculations

 ### 💳 Payment Integration
 1. **Ethiopian Payment Methods:**
 - **Telebirr** - Ethiopia's leading mobile money
 - **CBE Birr** - Commercial Bank of Ethiopia
- **eBirr** - Electronic payment gateway

 2. **Djiboutian Payment Methods:**
 - **Waafi** - Djibouti's mobile money service
@@ -84,8 +98,9 @@ Enterprise-grade REST API for the Ethio-Djibouti Railway passenger booking and m
 - Seat holds with 15-minute expiry
 - Auto-assign seats with contiguous algorithm
 - Seat blocking for maintenance
- Coach-level seat maps
+- Coach-level seat maps (ordered by sequence)
 - Class-based seating (Economy Regular, Economy Bed, VIP Bed)
+- **NEW:** Sequence-based coach ordering for consistent display

 ### 🎟️ Ticketing
 - QR code and barcode generation
@@ -93,6 +108,8 @@ Enterprise-grade REST API for the Ethio-Djibouti Railway passenger booking and m
 - Gate validation with audit logs
 - Offline validation support
 - Multi-passenger tickets
+- **NEW:** Ticket lifecycle tracking (validatedAt, boardedAt timestamps)
+- **NEW:** Complete audit trail for compliance and reporting

 ### 🏆 Loyalty Program
 - 4 tiers: Bronze, Silver, Gold, Platinum
@@ -118,16 +135,50 @@ Enterprise-grade REST API for the Ethio-Djibouti Railway passenger booking and m
 - Failed payment pattern detection
 - Automatic user blocking

+### 👤 Passenger Profiles
+- Comprehensive profile data: gender, date of birth, nationality
+- National ID for Ethiopian citizens (Fayda verified)
+- Passport information for international passengers
+- **NEW:** Complete demographic data for personalized services
+- **NEW:** Improved user targeting and communications
+
 ### 🌍 Internationalization
 - Multi-language support (English, Amharic, French, Oromo)
 - Locale-based responses
 - Currency formatting (ETB, DJF, USD)
+- **NEW:** Multi-currency display per booking (ETB, DJF, USD)

-### 👨‍💼 Agent Operations
- Counter booking
- Shift management
- Commission tracking
- Cash reconciliation
+### 🚌 Transit Stop Management
+- Automatic detection of cross-border journeys (Ethiopia → Djibouti)
+- Dire Dawa as mandatory transit hub for international journeys
+- Dual-leg fare calculation (domestic + international)
+- Age-based pricing applied independently per leg
+- Seamless multi-segment booking workflow
+- Transit stop optimization and route planning
+
+### 🔄 Round-Trip Booking
+- One-way and round-trip journey options
+- Flexible return date selection
+- Combined pricing for outbound + return legs
+- Separate seat management per leg
+- Independent modification/cancellation per leg
+- Return journey tracking and notifications
+- **NEW:** Booking type stored for analytics and reporting
+
+### 🚐 Coach Type & Class Selection
+- Browse available coach types per route (standard coaches, premium coaches)
+- View seat classes per coach (Economy Regular, Economy Bed, VIP Bed)
+- Compare base prices by coach type and class
+- Real-time availability per coach configuration
+- Deferred pricing at seat selection stage
+- Coach amenities and features display
+- **NEW:** Sequence-based coach ordering for consistent UI
+- **NEW:** Premium and insurance fee transparency per class
+
+### 📊 Data Organization
+- **Stations:** Ordered by sequence (1-15) for consistent route display
+- **Coaches:** Ordered by sequence (1+) per type for predictable configuration
+- **Booking History:** Sorted chronologically with filtering options

 ## Authentication

@@ -197,7 +248,6 @@ List endpoints support pagination:
 Payment providers send notifications to:
 - \`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)

@@ -212,33 +262,38 @@ Payment providers send notifications to:
      { type: "http", scheme: "bearer", bearerFormat: "JWT", in: "header" },
      "JWT-auth",
    )
-    .addTag("Agents", "Counter booking, shift management, and commission tracking")
-    .addTag("Auth", "User registration, login, and profile management")
-    .addTag("Booking", "Complete booking lifecycle: create, modify, cancel")
-    .addTag("Dashboard", "Aggregated dashboard data for home screen")
-    .addTag("Fare Engine", "Distance-based fare calculator with multi-currency support")
-    .addTag("Fayda Verification", "Ethiopian national ID verification via government API")
-    .addTag("Fleet", "Train services, coaches, and seat configurations")
-    .addTag("Fraud Detection", "Fraud monitoring, alerts, and user blocking")
-    .addTag("Live Tracking", "Real-time trip status, delays, and station crowds")
-    .addTag("Loyalty", "Points accumulation, tiers, and reward redemption")
-    .addTag("Notifications", "Multi-channel notifications: email, SMS, push")
-    .addTag("Passengers", "Passenger registration, verification, and profiles")
-    .addTag("Payment", "Payment processing, intents, and refunds")
-    .addTag("Payment Webhooks", "Payment provider webhook handlers")
-    .addTag("Promotions", "Promo codes, campaigns, and discount management")
-    .addTag("Reports", "Sales reports, occupancy analytics, and metrics")
-    .addTag("Routes", "Route templates with stops and fare rules")
-    .addTag("Schedule", "Trip schedules, availability, and status updates")
-    .addTag("Search", "Trip search, availability checks, and fare quotes")
-    .addTag("Seat Classes", "Seat class management: Economy, VIP configurations")
-    .addTag("Seats", "Seat maps, holds, releases, and blocking")
-    .addTag("Segment-based Seats", "Segment-level seat allocation and availability")
-    .addTag("Stations", "Station directory and information")
-    .addTag("Support", "FAQ management and live chat support")
-    .addTag("Tickets", "QR ticket generation, PDFs, and gate validation")
-    .addTag("Wallet", "Wallet balance, top-ups, and transaction ledger")
-    .addTag("Config", "System configuration and settings")
+    .addTag("Agents", "Counter booking, shift management, commission tracking, and reconciliation")
+    .addTag("Audit", "User activity logging, system changes, compliance tracking, and audit trails")
+    .addTag("Auth", "Passenger registration, login, OTP, password reset, and profile management")
+    .addTag("Booking", "Complete booking lifecycle: create, modify, cancel, guest checkout")
+    .addTag("Config", "System settings, feature flags, and configuration management")
+    .addTag("Currencies", "Multi-currency support, exchange rates, and currency conversion")
+    .addTag("Dashboard", "Home screen aggregations: trips, loyalty, wallet, notifications")
+    .addTag("Fare Engine", "Distance-based fare calculation with age-based pricing and multi-currency")
+    .addTag("Fayda Verification", "Ethiopian national ID verification via Verifayda 2.0 government API")
+    .addTag("Fleet", "Train services, coaches, coach types, seat classes, amenities, and configurations")
+    .addTag("Fraud Detection", "Velocity checks, monitoring alerts, pattern detection, and user blocking")
+    .addTag("Internal Payments", "Internal payment tracking, wallet transactions, and balance management")
+    .addTag("Live Tracking", "Real-time trip status, location updates, delays, and crowd signals")
+    .addTag("Loyalty", "Points ledger, tier management (Bronze/Silver/Gold/Platinum), rewards")
+    .addTag("Notifications", "Multi-channel delivery (email, SMS, push) and preference management")
+    .addTag("Passengers", "Registration, Fayda verification, international passports, saved profiles")
+    .addTag("Payment", "Telebirr, CBE Birr, Waafi, Card, Wallet payment processing and refunds")
+    .addTag("Payment Webhooks", "Payment provider webhook handlers and transaction confirmation")
+    .addTag("Promotions", "Promo codes, campaigns, discounts, and redemption tracking")
+    .addTag("Reports", "Revenue analytics, occupancy reports, agent sales, and KPI dashboards")
+    .addTag("Round Trip", "Round-trip bookings, return scheduling, combined pricing, and management (NEW)")
+    .addTag("Routes", "Route templates with ordered stops, fare rules, and baggage allowance")
+    .addTag("Schedule", "Trip schedules, availability windows, status tracking, and timing")
+    .addTag("Search", "Trip search, fare quotes, coach types, and real-time availability")
+    .addTag("Seat Classes", "Economy Regular, Economy Bed, VIP Bed class configuration and pricing")
+    .addTag("Seats", "Seat maps, holds (15-min expiry), releases, blocking, and inventory")
+    .addTag("Segment-based Seats", "Multi-leg journey seats, segment allocation, and per-leg availability")
+    .addTag("Stations", "Station directory, location data, baggage facilities, and amenities")
+    .addTag("Support", "FAQ management, search, live chat conversations, and ticket resolution")
+    .addTag("Tickets", "QR/barcode generation, PDF tickets, gate validation, and audit trails")
+    .addTag("Transit Stops", "Cross-border journey management, Dire Dawa hub, multi-leg routing (NEW)")
+    .addTag("Wallet", "Balance management, top-ups, withdrawals, and transaction ledger")
    //.addServer('http://localhost:4000', 'Development')
    // .addServer("https://api.edr-platform.com", "Production")
    .build();