# 03 - DHL Charges Tracking

**Status: PARTIALLY IMPLEMENTED (UI Only)**

## Summary

Track and validate DHL shipping charges by cross-referencing invoice PDFs against expected shipping costs. Identifies incorrect or inflated charges that DHL may bill incorrectly.

## Current State

An experimental UI page exists at `/experimental/dhl-charges` with:
- Summary statistics (new flags count, total discrepancy, unmatched charges)
- Invoice list sidebar with filtering
- Flagged charges table showing tracking numbers, invoiced vs expected amounts, discrepancy percentages
- Status management (new/reviewed/disputed/resolved) with notes
- Shipment lookup modal querying `/api/admin/shipper/shipments` by tracking number
- Displays quoted rate from `currentShippingLabel.rate` for comparison

**Existing files:**
- `webapps/src/components/Experimental/DHLChargesPage.jsx` - Main UI (uses mock data)
- `webapps/src/components/Experimental/ExperimentalWrapper.jsx` - Nav link added
- `webapps/src/components/Experimental/ExperimentalHome.jsx` - Card added
- `webapps/arda/app/App.jsx` - Route at `/experimental/dhl-charges`

Shipping rates already stored on each BigShipment in `currentShippingLabel.rate` with `amount`, `provider`, `servicelevel_name`.

## Requirements

1. Parse DHL invoice PDFs to extract individual charges
2. Match each charge against shipments in our system by tracking number
3. Flag discrepancies where invoiced amount differs from quoted rate
4. Display prioritized list of problematic charges sorted by date
5. Pull new invoice data from DHL automatically (daily)

## Files to Create

| File | Purpose |
|------|---------|
| `api/src/fabricator/DHLInvoiceApi.ts` | API for DHL invoice management and parsing |
| `api/src/fabricator/DHLInvoiceSchemas.ts` | Schema definitions for invoice records and charge items |
| `webapps/src/components/BigLogistics/DHLChargesList.jsx` | Table component displaying charge discrepancies |

## Files to Modify

| File | Change |
|------|--------|
| `api/src/fabricator/FabricatorDatabase.ts` | Add methods for storing/querying DHL invoice records |
| `api/src/fabricator/FabricatorSchemas.ts` | Add `BigDHLInvoice` and `BigDHLCharge` schema types |
| `apps/admin_api/admin_api.ts` | Register new DHL invoice API routes |
| `webapps/src/components/BigLogistics/BigShipperWrapper.jsx` | Add navigation link to DHL Charges page |
| `apps/admin_api/db_setup.ts` | Add database tables |

## Database Changes

```sql
CREATE TABLE big_dhl_invoices (
    id TEXT PRIMARY KEY,
    invoiceNumber TEXT NOT NULL,
    invoiceDate BIGINT NOT NULL,
    totalAmount NUMERIC,
    currency TEXT,
    pdfUrl TEXT,
    charges JSONB,
    reconciliationStatus TEXT,  -- 'pending', 'reviewed', 'disputed'
    createdAt BIGINT,
    updatedAt BIGINT
);

CREATE TABLE big_dhl_charge_flags (
    id TEXT PRIMARY KEY,
    invoiceId TEXT REFERENCES big_dhl_invoices(id),
    bigShipmentId TEXT,
    trackingNumber TEXT,
    invoicedAmount NUMERIC,
    expectedAmount NUMERIC,
    discrepancyAmount NUMERIC,
    discrepancyPercent NUMERIC,
    flagReason TEXT,
    status TEXT,  -- 'new', 'reviewed', 'disputed', 'resolved'
    notes TEXT,
    createdAt BIGINT
);
```

## API Endpoints

| Method | Endpoint | Purpose |
|--------|----------|---------|
| POST | `/api/admin/dhl/invoices/upload` | Upload and parse DHL invoice PDF |
| GET | `/api/admin/dhl/invoices` | List all invoices with pagination |
| GET | `/api/admin/dhl/invoices/:id` | Get specific invoice details |
| GET | `/api/admin/dhl/charges/flagged` | Get all flagged charge discrepancies |
| PUT | `/api/admin/dhl/charges/:id` | Update charge status |
| POST | `/api/admin/dhl/reconcile` | Run reconciliation for an invoice |

## Remaining Work

- Backend API endpoints for invoice management
- Database tables for invoices and charge flags
- PDF parsing functionality
- Automatic reconciliation logic
- Move from experimental to production UI