# 04 - Lost Shipments

**Status: NOT STARTED**

## Summary

Streamline handling of lost-in-transit shipments with CS ticket integration, document storage for carrier claims, and a case management workflow.

## Current State

The system tracks shipment status including `DeliveryFailed` but has no:
- Customer service ticket integration
- Document upload capability
- Claim filing workflow
- Lost shipment case management

See `lost-shipments.md` in this folder for additional planning notes.

## Requirements

1. Link CS tickets to shipment records in Arda
2. Track claim status through the carrier dispute process
3. Store submitted documents (proof of shipment, value declarations, etc.)
4. Automate parts of claim filing where possible
5. Provide visibility into all open lost shipment cases
6. Button on individual shipment page to report as lost

## Files to Create

| File | Purpose |
|------|---------|
| `api/src/fabricator/LostShipmentApi.ts` | API for lost shipment case management |
| `api/src/fabricator/LostShipmentSchemas.ts` | Schema for cases and documents |
| `webapps/src/components/BigLogistics/LostShipmentsPage.jsx` | Main page listing all cases |
| `webapps/src/components/BigLogistics/LostShipmentCase.jsx` | Individual case detail view |
| `webapps/src/components/BigLogistics/LostShipmentDocuments.jsx` | Document upload and management |

## Files to Modify

| File | Change |
|------|--------|
| `api/src/fabricator/FabricatorDatabase.ts` | Add methods for lost shipment case CRUD |
| `api/src/fabricator/FabricatorSchemas.ts` | Add `BigLostShipmentCase` schema type |
| `api/src/fabricator/ShippingAdminApi.ts` | Add action to mark shipment as lost and create case |
| `apps/admin_api/admin_api.ts` | Register lost shipment API routes |
| `apps/admin_api/db_setup.ts` | Add database table |
| `webapps/src/components/BigLogistics/BigShipperWrapper.jsx` | Add navigation link |
| `webapps/src/components/BigLogistics/BigShipment.jsx` | Add "Report as Lost" button |

## Database Changes

```sql
CREATE TABLE big_lost_shipment_cases (
    id TEXT PRIMARY KEY,
    bigShipmentId TEXT NOT NULL,
    trackingNumber TEXT,
    carrier TEXT,
    customerEmail TEXT,
    csTicketId TEXT,
    csTicketUrl TEXT,
    claimStatus TEXT,  -- 'reported', 'claim_filed', 'pending_carrier', 'approved', 'denied', 'resolved'
    claimAmount NUMERIC,
    claimCurrency TEXT,
    carrierClaimId TEXT,
    documents JSONB,
    notes TEXT,
    reportedAt BIGINT,
    claimFiledAt BIGINT,
    resolvedAt BIGINT,
    createdAt BIGINT,
    updatedAt BIGINT
);
```

## Implementation Notes

- Consider integration with Zendesk, Freshdesk, or other CS platforms via API
- Documents should be uploaded to S3 with signed URLs for secure access
- Carrier claim filing may need carrier-specific API integrations (DHL, UPS claim APIs)