Implemened verifayda and currency modules

2026-08-26 12:41:04 +00:00 · 2026-05-21 10:22:08 +03:00
parent 51bc906792
commit 3f60836e5d
22 changed files with 1032 additions and 220 deletions
--- a/README.md
+++ b/README.md
@@ -4,11 +4,47 @@ Enterprise-grade NestJS REST API for the Ethio-Djibouti Railway passenger bookin

 ## 🚀 Features

+### 🆕 NEW: Age-Based Pricing, Verifayda 2.0 & Multi-Currency
+
+#### 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)
+
+#### Verifayda 2.0 Integration
+- Real-time Ethiopian national ID verification
+- Retrieves passenger data from government database
+- National IDs NOT stored (policy compliant)
+- Non-Ethiopians use passport (no verification required)
+- Booking fails if verification unsuccessful
+
+#### Multi-Currency Support
+- **Transaction Currency**: ETB (Ethiopian Birr)
+- **Display Currencies**: ETB, DJF (Djiboutian Franc), USD (US Dollar)
+- Real-time exchange rate conversion
+- Prices shown in user's preferred currency
+- Exchange rates: ETB→DJF=3.25, ETB→USD=0.018
+
 ### Core Modules
 - **Authentication & Authorization** - Dual authentication system:
  - **Passenger Auth**: JWT-based auth with OTP verification, password reset, account lockout
  - **Corporate IAM**: Integration with @tria-plc corporate identity system for back-office operations (agents, supervisors, admins)
  - Role-based access control (RBAC) with granular permissions
+- **Age-Based Pricing** - Smart passenger categorization:
+  - **ADULT** (≥5 years): Full fare
+  - **CHILD** (<5 years): First child free, subsequent children full fare
+  - Automatic age calculation from date of birth
+- **Verifayda 2.0 Integration** - Ethiopian national ID verification:
+  - Real-time verification via government API
+  - Retrieves passenger data (name, DOB, nationality)
+  - National IDs NOT stored (policy compliant)
+  - Non-Ethiopians use passport (no verification)
+- **Multi-Currency Support** - Display prices in multiple currencies:
+  - **ETB** (Ethiopian Birr) - Transaction currency
+  - **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
 - **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
@@ -74,6 +110,16 @@ cp apps/edr-passenger-api/.env.example apps/edr-passenger-api/.env
 | `SENDGRID_API_KEY` | SendGrid API key (optional) | `SG.xxx` |
 | `SENDGRID_FROM_EMAIL` | Email sender address | `noreply@edr-platform.com` |

+#### Verifayda 2.0 Configuration (Ethiopian National ID Verification)
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `VERIFAYDA_ENABLED` | Enable Verifayda integration | `true` or `false` |
+| `VERIFAYDA_API_URL` | Verifayda API endpoint | `https://api.verifayda.gov.et/v2` |
+| `VERIFAYDA_API_KEY` | API key for Verifayda service | `your-verifayda-api-key` |
+
+**Note:** When `VERIFAYDA_ENABLED=false`, verification is skipped (development mode only).
+
 #### Corporate IAM Configuration (Back-office Authentication)

 | Variable | Description | Example |
@@ -124,15 +170,18 @@ pnpm --filter @edr/passenger-api run prisma:seed
 ```

 **Seed Data Includes:**
- 5 Stations (Addis Ababa, Adama, Awash, Dire Dawa, Djibouti)
- 1 Route with 5 stops and fare rules
- 2 Train services with 2 trips
- 360 seats across 6 coaches (Economy, Bed, VIP classes)
+- 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)
 - 3 User accounts (Admin, Passenger, Agent)
+- Fare rules for ADULT and CHILD passenger categories
+- Currency exchange rates (ETB, DJF, USD)
 - Baggage allowance rules
 - Notification templates
 - Promotions and FAQ content
 - Menu items and station crowd signals
+- Fraud detection rules

 ### 5. Start Development Server
 ```bash
@@ -247,11 +296,41 @@ Content-Type: application/json

 #### 3. Search Trips
 ```bash
-GET /search/trips?originStationId={id}&destinationStationId={id}&date=2026-06-15
+GET /search/trips?originStationId={id}&destinationStationId={id}&date=2026-06-15&adultCount=2&childCount=1
 Authorization: Bearer {token}
 ```

-#### 4. Create Booking
+#### 4. Get Fare Quote
+```bash
+POST /search/fare-quote
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "tripId": "uuid",
+  "serviceClass": "ECONOMY_REGULAR",
+  "adultCount": 2,
+  "childCount": 1,
+  "displayCurrency": "USD"
+}
+
+# Response includes age-based pricing breakdown
+{
+  "baseFareMinor": 35000,
+  "adultCount": 2,
+  "adultFareMinor": 70000,
+  "childCount": 1,
+  "freeChildrenCount": 1,
+  "paidChildrenCount": 0,
+  "childFareMinor": 0,
+  "totalMinor": 73500,
+  "currency": "ETB",
+  "displayCurrency": "USD",
+  "displayTotalMinor": 1323
+}
+```
+
+#### 5. Create Booking
 ```bash
 POST /bookings
 Authorization: Bearer {token}
@@ -259,12 +338,31 @@ Content-Type: application/json

 {
  "tripId": "uuid",
-  "seats": [
+  "holdId": "uuid",
+  "serviceClass": "ECONOMY_REGULAR",
+  "displayCurrency": "DJF",
+  "passengers": [
    {
      "seatId": "uuid",
-      "passengerName": "John Doe",
+      "passengerName": "Abebe Kebede",
+      "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",
-      "idDocumentNumber": "ET123456"
+      "passportNumber": "P1234567",
+      "passportCountry": "Kenya"
    }
  ]
 }
@@ -300,6 +398,7 @@ apps/edr-passenger-api/
 │   │   ├── auth/              # Authentication & authorization (JWT)
 │   │   ├── agents/            # Agent operations (IAM-protected)
 │   │   ├── bookings/          # Booking management (JWT)
+│   │   ├── currency/          # Currency conversion service
 │   │   ├── dashboard/         # Dashboard aggregations (JWT)
 │   │   ├── fleet/             # Train fleet management (JWT/IAM)
 │   │   ├── fraud/             # Fraud detection (IAM-protected)
@@ -317,6 +416,7 @@ apps/edr-passenger-api/
 │   │   ├── stations/          # Station management (JWT)
 │   │   ├── support/           # Customer support (JWT)
 │   │   ├── tickets/           # Ticketing (JWT/IAM)
+│   │   ├── verifayda/         # Verifayda 2.0 integration
 │   │   └── wallet/            # Wallet system (JWT)
 │   ├── app.module.ts          # Root application module
 │   └── main.ts                # Application entry point
@@ -351,6 +451,8 @@ apps/edr-passenger-api/
 - `Notification`, `NotificationTemplate`
 - `AuditLog`, `OperationalReport`
 - `SeatBlock`, `SeatHold`
+- `CurrencyExchangeRate` (Multi-currency)
+- `VerifaydaVerification` (National ID verification)

 ## 🔧 Available Scripts

@@ -467,6 +569,8 @@ pnpm --filter @edr/passenger-api run test:cov
 ### Pre-deployment Checklist
 - [ ] Update environment variables (JWT_SECRET, DATABASE_URL, etc.)
 - [ ] Configure IAM integration (IAM_ENABLED=true, IAM_API_URL, IAM_API_KEY)
+- [ ] Configure Verifayda integration (VERIFAYDA_ENABLED=true, VERIFAYDA_API_KEY)
+- [ ] Set up currency exchange rate sync (external API)
 - [ ] Set NODE_ENV=production
 - [ ] Configure CORS origins (FRONTEND_URL, PORTAL_URL)
 - [ ] Set up SSL/TLS certificates
@@ -475,6 +579,9 @@ pnpm --filter @edr/passenger-api run test:cov
 - [ ] Configure backup strategy
 - [ ] Test payment provider integrations
 - [ ] Verify IAM token validation endpoint
+- [ ] Test Verifayda verification with real national IDs
+- [ ] Verify currency conversion accuracy
+- [ ] Test age-based pricing calculations
 - [ ] Review security settings and audit logs
 - [ ] Test both JWT and IAM authentication flows