xpeditis2.0/CSV_API_TEST_GUIDE.md

# CSV Rate API Testing Guide

## Prerequisites

1. Start the backend API:
```bash
cd /Users/david/Documents/xpeditis/dev/xpeditis2.0/apps/backend
npm run dev
```

2. Ensure PostgreSQL and Redis are running:
```bash
docker-compose up -d
```

3. Run database migrations (if not done):
```bash
npm run migration:run
```

## Test Scenarios

### 1. Get Available Companies

Test that all 4 configured companies are returned:

```bash
curl -X GET http://localhost:4000/api/v1/rates/companies \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Expected Response:**
```json
{
  "companies": ["SSC Consolidation", "ECU Worldwide", "TCC Logistics", "NVO Consolidation"],
  "total": 4
}
```

### 2. Get Filter Options

Test that all filter options are available:

```bash
curl -X GET http://localhost:4000/api/v1/rates/filters/options \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Expected Response:**
```json
{
  "companies": ["SSC Consolidation", "ECU Worldwide", "TCC Logistics", "NVO Consolidation"],
  "containerTypes": ["LCL"],
  "currencies": ["USD", "EUR"]
}
```

### 3. Search CSV Rates - Single Company

Test search for NLRTM → USNYC with 25 CBM, 3500 kg:

```bash
curl -X POST http://localhost:4000/api/v1/rates/search-csv \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "origin": "NLRTM",
    "destination": "USNYC",
    "volumeCBM": 25,
    "weightKG": 3500,
    "palletCount": 10,
    "containerType": "LCL"
  }'
```

**Expected:** Multiple results from SSC Consolidation, ECU Worldwide, TCC Logistics, NVO Consolidation

### 4. Search with Company Filter

Test filtering by specific company:

```bash
curl -X POST http://localhost:4000/api/v1/rates/search-csv \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "origin": "NLRTM",
    "destination": "USNYC",
    "volumeCBM": 25,
    "weightKG": 3500,
    "palletCount": 10,
    "containerType": "LCL",
    "filters": {
      "companies": ["SSC Consolidation"]
    }
  }'
```

**Expected:** Only SSC Consolidation results

### 5. Search with Price Range Filter

Test filtering by price range (USD 1000-1500):

```bash
curl -X POST http://localhost:4000/api/v1/rates/search-csv \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "origin": "NLRTM",
    "destination": "USNYC",
    "volumeCBM": 25,
    "weightKG": 3500,
    "palletCount": 10,
    "containerType": "LCL",
    "filters": {
      "minPrice": 1000,
      "maxPrice": 1500,
      "currency": "USD"
    }
  }'
```

**Expected:** Only rates between $1000-$1500

### 6. Search with Transit Days Filter

Test filtering by maximum transit days (25 days):

```bash
curl -X POST http://localhost:4000/api/v1/rates/search-csv \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "origin": "NLRTM",
    "destination": "USNYC",
    "volumeCBM": 25,
    "weightKG": 3500,
    "containerType": "LCL",
    "filters": {
      "maxTransitDays": 25
    }
  }'
```

**Expected:** Only rates with transit ≤ 25 days

### 7. Search with Surcharge Filters

Test excluding rates with surcharges:

```bash
curl -X POST http://localhost:4000/api/v1/rates/search-csv \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "origin": "NLRTM",
    "destination": "USNYC",
    "volumeCBM": 25,
    "weightKG": 3500,
    "containerType": "LCL",
    "filters": {
      "withoutSurcharges": true
    }
  }'
```

**Expected:** Only "all-in" rates without separate surcharges

---

## Admin Endpoints (ADMIN Role Required)

### 8. Upload Test Maritime Express CSV

Upload the fictional carrier CSV:

```bash
curl -X POST http://localhost:4000/api/v1/admin/csv-rates/upload \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
  -F "file=@/Users/david/Documents/xpeditis/dev/xpeditis2.0/apps/backend/src/infrastructure/storage/csv-storage/rates/test-maritime-express.csv" \
  -F "companyName=Test Maritime Express" \
  -F "fileDescription=Fictional carrier for testing comparator"
```

**Expected Response:**
```json
{
  "message": "CSV file uploaded and validated successfully",
  "companyName": "Test Maritime Express",
  "ratesLoaded": 25,
  "validation": {
    "valid": true,
    "errors": []
  }
}
```

### 9. Get All CSV Configurations

List all configured CSV carriers:

```bash
curl -X GET http://localhost:4000/api/v1/admin/csv-rates/config \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN"
```

**Expected:** 5 configurations (SSC, ECU, TCC, NVO, Test Maritime Express)

### 10. Get Specific Company Configuration

Get Test Maritime Express config:

```bash
curl -X GET http://localhost:4000/api/v1/admin/csv-rates/config/Test%20Maritime%20Express \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN"
```

**Expected Response:**
```json
{
  "id": "...",
  "companyName": "Test Maritime Express",
  "filePath": "rates/test-maritime-express.csv",
  "isActive": true,
  "lastUpdated": "2025-10-24T...",
  "fileDescription": "Fictional carrier for testing comparator"
}
```

### 11. Validate CSV File

Validate a CSV file before uploading:

```bash
curl -X POST http://localhost:4000/api/v1/admin/csv-rates/validate/Test%20Maritime%20Express \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN"
```

**Expected Response:**
```json
{
  "valid": true,
  "companyName": "Test Maritime Express",
  "totalRates": 25,
  "errors": [],
  "warnings": []
}
```

### 12. Delete CSV Configuration

Delete Test Maritime Express configuration:

```bash
curl -X DELETE http://localhost:4000/api/v1/admin/csv-rates/config/Test%20Maritime%20Express \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN"
```

**Expected Response:**
```json
{
  "message": "CSV configuration deleted successfully",
  "companyName": "Test Maritime Express"
}
```

---

## Comparator Test Scenario

**MAIN TEST: Verify multiple company offers appear**

1. **Upload Test Maritime Express CSV** (see test #8 above)

2. **Search for rates on competitive route** (NLRTM → USNYC):

```bash
curl -X POST http://localhost:4000/api/v1/rates/search-csv \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "origin": "NLRTM",
    "destination": "USNYC",
    "volumeCBM": 25.5,
    "weightKG": 3500,
    "palletCount": 10,
    "containerType": "LCL"
  }'
```

3. **Expected Results (multiple companies with different prices):**

| Company | Price (USD) | Transit Days | Notes |
|---------|-------------|--------------|-------|
| **Test Maritime Express** | **~$950** | 22 | **"BEST DEAL"** - Cheapest |
| SSC Consolidation | ~$1,100 | 22 | Standard pricing |
| ECU Worldwide | ~$1,150 | 23 | Slightly higher |
| TCC Logistics | ~$1,120 | 22 | Mid-range |
| NVO Consolidation | ~$1,130 | 22 | Standard |

4. **Verification Points:**
   - ✅ All 5 companies appear in results
   - ✅ Test Maritime Express shows lowest price (~10-20% cheaper)
   - ✅ Each company shows different pricing
   - ✅ Match scores are calculated (0-100%)
   - ✅ Results can be sorted by price, transit, company, match score
   - ✅ "All-in price" badge appears for Test Maritime Express rates (withoutSurcharges=true)

5. **Test filtering by company:**

```bash
curl -X POST http://localhost:4000/api/v1/rates/search-csv \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "origin": "NLRTM",
    "destination": "USNYC",
    "volumeCBM": 25.5,
    "weightKG": 3500,
    "palletCount": 10,
    "containerType": "LCL",
    "filters": {
      "companies": ["Test Maritime Express", "SSC Consolidation"]
    }
  }'
```

**Expected:** Only Test Maritime Express and SSC Consolidation results

---

## Test Checklist

- [ ] All 4 original companies return in /companies endpoint
- [ ] Filter options return correct values
- [ ] Basic rate search returns multiple results
- [ ] Company filter works correctly
- [ ] Price range filter works correctly
- [ ] Transit days filter works correctly
- [ ] Surcharge filter works correctly
- [ ] Admin can upload Test Maritime Express CSV
- [ ] Test Maritime Express appears in configurations
- [ ] Search returns results from all 5 companies
- [ ] Test Maritime Express shows competitive pricing
- [ ] Results can be sorted by different criteria
- [ ] Match scores are calculated correctly
- [ ] "All-in price" badge appears for rates without surcharges

---

## Authentication

To get a JWT token for testing:

```bash
# Login as regular user
curl -X POST http://localhost:4000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test4@xpeditis.com",
    "password": "SecurePassword123"
  }'

# Login as admin (if you have an admin account)
curl -X POST http://localhost:4000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@xpeditis.com",
    "password": "AdminPassword123"
  }'
```

Copy the `accessToken` from the response and use it as `YOUR_JWT_TOKEN` or `YOUR_ADMIN_JWT_TOKEN` in the test commands above.

---

## Notes

- All prices are calculated using freight class rule: `max(volumeCBM * pricePerCBM, weightKG * pricePerKG) + surcharges`
- Test Maritime Express rates are designed to be 10-20% cheaper than competitors
- Surcharges are automatically added to total price (BAF, CAF, etc.)
- Match scores indicate how well each rate matches the search criteria (100% = perfect match)
- Results are cached in Redis for 15 minutes (planned feature)