xpeditis2.0/docs/phases/READY_FOR_TESTING.md

✅ CSV Rate System - Ready for Testing

Implementation Status: COMPLETE ✓

All backend and frontend components have been implemented and are ready for testing.

What's Been Implemented

✅ Backend (100% Complete)

Domain Layer

• CsvRate entity with freight class pricing logic
• Volume, Surcharge, PortCode, ContainerType value objects
• CsvRateSearchService domain service with advanced filtering
• Search ports (input/output interfaces)
• Repository ports (CSV loader interface)

Infrastructure Layer

• CSV loader adapter with validation
• 5 CSV files with 126 total rate entries:
  • SSC Consolidation (25 rates)
  • ECU Worldwide (26 rates)
  • TCC Logistics (25 rates)
  • NVO Consolidation (25 rates)
  • Test Maritime Express (25 rates) ⭐ FICTIONAL - FOR TESTING
• TypeORM repository for CSV configurations
• Database migration with seed data

Application Layer

• RatesController with 3 public endpoints
• CsvRatesAdminController with 5 admin endpoints
• DTOs with validation
• Mappers (DTO ↔ Domain)
• RBAC guards (JWT + ADMIN role)

✅ Frontend (100% Complete)

Components

• VolumeWeightInput - CBM/weight/pallet inputs
• CompanyMultiSelect - Multi-select company filter
• RateFiltersPanel - 12 advanced filters
• RateResultsTable - Sortable results table
• CsvUpload - Admin CSV upload interface

Pages

• /rates/csv-search - Public rate search with comparator
• /admin/csv-rates - Admin CSV management

API Integration

• API client functions
• Custom React hooks
• TypeScript types

✅ Test Data

Test Maritime Express CSV

Created specifically to verify the comparator shows multiple companies with different prices:

Key Features:

• 25 rates across major trade lanes
• 10-20% cheaper than competitors
• Labels: "BEST DEAL", "PROMO", "LOWEST", "BEST VALUE"
• Same routes as existing carriers for easy comparison

Example Rate (NLRTM → USNYC):

• Test Maritime Express: $950 (all-in, no surcharges)
• SSC Consolidation: $1,100 (with surcharges)
• ECU Worldwide: $1,150 (with surcharges)
• TCC Logistics: $1,120 (with surcharges)
• NVO Consolidation: $1,130 (with surcharges)

API Endpoints Ready for Testing

Public Endpoints (Require JWT)

Method	Endpoint	Description
POST	/api/v1/rates/search-csv	Search rates with advanced filters
GET	/api/v1/rates/companies	Get available companies
GET	/api/v1/rates/filters/options	Get filter options

Admin Endpoints (Require ADMIN Role)

Method	Endpoint	Description
POST	/api/v1/admin/csv-rates/upload	Upload new CSV file
GET	/api/v1/admin/csv-rates/config	List all configurations
GET	/api/v1/admin/csv-rates/config/:companyName	Get specific config
POST	/api/v1/admin/csv-rates/validate/:companyName	Validate CSV file
DELETE	/api/v1/admin/csv-rates/config/:companyName	Delete configuration

How to Start Testing

Quick Start (3 Steps)

# 1. Start infrastructure
docker-compose up -d

# 2. Run migration (seeds 5 companies)
cd apps/backend
npm run migration:run

# 3. Start API server
npm run dev

Run Automated Tests

Option 1: Node.js Script (Recommended)

cd apps/backend
node test-csv-api.js

Option 2: Bash Script

cd apps/backend
chmod +x test-csv-api.sh
./test-csv-api.sh

Manual Testing

Follow the step-by-step guide in: 📄 MANUAL_TEST_INSTRUCTIONS.md

Test Files Available

File	Purpose
test-csv-api.js	Automated Node.js test script
test-csv-api.sh	Automated Bash test script
MANUAL_TEST_INSTRUCTIONS.md	Step-by-step manual testing guide
CSV_API_TEST_GUIDE.md	Complete API test documentation

Main Test Scenario: Comparator Verification

Goal: Verify that searching for rates shows multiple companies with different prices.

Test Route: NLRTM (Rotterdam) → USNYC (New York)

Search Parameters:

• Volume: 25.5 CBM
• Weight: 3500 kg
• Pallets: 10
• Container Type: LCL

Expected Results:

Rank	Company	Price (USD)	Transit	Notes
1️⃣	Test Maritime Express	$950	22 days	BEST DEAL ⭐
2️⃣	SSC Consolidation	$1,100	22 days	Standard
3️⃣	TCC Logistics	$1,120	22 days	Mid-range
4️⃣	NVO Consolidation	$1,130	22 days	Standard
5️⃣	ECU Worldwide	$1,150	23 days	Slightly slower

✅ Success Criteria

• All 5 companies appear in results
• Test Maritime Express shows lowest price (~10-20% cheaper)
• Each company has different pricing
• Prices are correctly calculated (freight class rule)
• Match scores are calculated (0-100%)
• Filters work correctly (company, price, transit, surcharges)
• Results can be sorted by price/transit/company/match score
• "All-in" badge appears for rates without surcharges

Features to Test

1. Rate Search

Endpoints:

• POST /api/v1/rates/search-csv

Test Cases:

• ✅ Basic search returns results from multiple companies
• ✅ Results sorted by relevance (match score)
• ✅ Total price includes freight + surcharges
• ✅ Freight class pricing: max(volume × rate, weight × rate)

2. Advanced Filters

12 Filter Types:

1. Companies (multi-select)
2. Min volume CBM
3. Max volume CBM
4. Min weight KG
5. Max weight KG
6. Min price
7. Max price
8. Currency (USD/EUR)
9. Max transit days
10. Without surcharges (all-in only)
11. Container type (LCL)
12. Date range (validity)

Test Cases:

• ✅ Company filter returns only selected companies
• ✅ Price range filter works for USD and EUR
• ✅ Transit days filter excludes slow routes
• ✅ Surcharge filter returns only all-in prices
• ✅ Multiple filters work together (AND logic)

3. Comparator

Goal: Show multiple offers from different companies for same route

Test Cases:

• ✅ Same route returns results from 3+ companies
• ✅ Test Maritime Express appears with competitive pricing
• ✅ Price differences are clear (10-20% variation)
• ✅ Each company has distinct pricing
• ✅ User can compare transit times, prices, surcharges

4. CSV Configuration (Admin)

Endpoints:

• POST /api/v1/admin/csv-rates/upload
• GET /api/v1/admin/csv-rates/config
• DELETE /api/v1/admin/csv-rates/config/:companyName

Test Cases:

• ✅ Admin can upload new CSV files
• ✅ CSV validation catches errors (missing columns, invalid data)
• ✅ File size and type validation works
• ✅ Admin can view all configurations
• ✅ Admin can delete configurations

Database Verification

After running migration, verify data in PostgreSQL:

-- Check CSV configurations
SELECT company_name, csv_file_path, is_active
FROM csv_rate_configs;

-- Expected: 5 rows
-- SSC Consolidation
-- ECU Worldwide
-- TCC Logistics
-- NVO Consolidation
-- Test Maritime Express

CSV Files Location

All CSV files are in:

apps/backend/src/infrastructure/storage/csv-storage/rates/
├── ssc-consolidation.csv (25 rates)
├── ecu-worldwide.csv (26 rates)
├── tcc-logistics.csv (25 rates)
├── nvo-consolidation.csv (25 rates)
└── test-maritime-express.csv (25 rates) ⭐ FICTIONAL

Price Calculation Logic

All prices follow the freight class rule:

freightPrice = max(volumeCBM × pricePerCBM, weightKG × pricePerKG)
totalPrice = freightPrice + surcharges

Example:

• Volume: 25 CBM × $35/CBM = $875
• Weight: 3500 kg × $2.10/kg = $7,350
• Freight: max($875, $7,350) = $7,350
• Surcharges: $0 (all-in price)
• Total: $7,350

Match Scoring

Results are scored 0-100% based on:

1. Exact port match (50%): Origin and destination match exactly
2. Volume match (20%): Shipment volume within min/max range
3. Weight match (20%): Shipment weight within min/max range
4. Pallet match (10%): Pallet count supported

Next Steps After Testing

1. ✅ Verify all tests pass
2. ✅ Test frontend interface (http://localhost:3000/rates/csv-search)
3. ✅ Test admin interface (http://localhost:3000/admin/csv-rates)
4. 📊 Run load tests (k6 scripts available)
5. 📝 Update API documentation (Swagger)
6. 🚀 Deploy to staging (Docker Compose)

Known Limitations

• CSV files are static (no real-time updates from carriers)
• Test Maritime Express is fictional (for testing only)
• No caching implemented yet (planned: Redis 15min TTL)
• No audit logging for CSV uploads (planned)

Support

If you encounter issues:

1. Check MANUAL_TEST_INSTRUCTIONS.md for troubleshooting
2. Verify infrastructure is running: docker ps
3. Check API logs: npm run dev output
4. Verify migration ran: npm run migration:run

Summary

🎯 Status: Ready for testing 📊 Coverage: 126 CSV rates across 5 companies 🧪 Test Scripts: 3 automated + 1 manual guide ⭐ Test Data: Fictional carrier with competitive pricing ✅ Endpoints: 8 API endpoints (3 public + 5 admin)

Everything is implemented and ready to test! 🚀

You can now:

1. Start the API server
2. Run the automated test scripts
3. Verify the comparator shows multiple companies
4. Confirm Test Maritime Express appears with cheaper rates