# Cancelled trip lists + admin multi-currency rates

Summary of recent backend/admin changes. **No brand-new public API paths were added.** Existing endpoints changed behavior as documented below.

---

## 1. Cancelled trip list membership (Option A)

### Product rule (unchanged cancel semantics)

On cancel:

| Object | Status |
|--------|--------|
| Trip | `CANCELLED` |
| Shipment | `CANCELLED` |

No auto re-open on the market. Shipper republishes via **clone-draft → edit → publish**.

### Shared trip status buckets

| Bucket | Statuses |
|--------|----------|
| **Active** (in progress) | `EN_ROUTE`, `ARRIVED_PICKUP`, `LOADED`, `IN_TRANSIT`, `ARRIVED_DELIVERY` |
| **Assign** | `ASSIGNED` only |
| **Completed / history** | `DELIVERED`, `COMPLETED`, `CLOSED`, **`CANCELLED`** |

---

### Behavior changes by endpoint

#### Shipper

| Method | Endpoint | Change |
|--------|----------|--------|
| `GET` | `/api/shipper/trips/` | **Excludes** `CANCELLED` (Active Trips) |
| `GET` | `/api/shipper/shipments/` | **Includes** `PUBLISHED` **and** `CANCELLED` (My Loads) |
| `GET` | `/api/shipper/shipments/history/` | **Includes** `CANCELLED` (with DELIVERED/COMPLETED/CLOSED) |
| `POST` | `/api/shipper/shipments/{id}/clone-draft/` | Allowed for **`CANCELLED`** (even if a trip exists) and for **`PUBLISHED`** without a trip |
| `POST` | `/api/shipper/trips/{id}/cancel/` | Unchanged Option A (trip + shipment → `CANCELLED`) |

#### Transporter — fleet (My Trips tabs)

| Method | Endpoint | App tab | Change |
|--------|----------|---------|--------|
| `GET` | `/api/transporter/trips/my/` | Available | **Excludes** `CANCELLED` (primary bug fix) |
| `GET` | `/api/transporter/trips/assigned/` | Assign | Still excludes cancelled |
| `GET` | `/api/transporter/trips/active/` | Active | Uses Active set (no `DELIVERED` / no cancelled) |
| `GET` | `/api/transporter/trips/completed/` | Completed | **Includes** `CANCELLED` (+ DELIVERED/COMPLETED/CLOSED) |
| `POST` | `/api/transporter/trips/{id}/cancel/` | — | Unchanged Option A |

#### Transporter — individual driver

| Method | Endpoint | Change |
|--------|----------|--------|
| `GET` | `/api/transporter/my-trips/assigned/` | Excludes cancelled |
| `GET` | `/api/transporter/my-trips/active/` | Active set only |
| `GET` | `/api/transporter/my-trips/completed/` | **Includes** cancelled |

#### Transporter — fleet driver

| Method | Endpoint | Change |
|--------|----------|--------|
| `GET` | `/api/transporter/driver/trips/assigned/` | Excludes cancelled |
| `GET` | `/api/transporter/driver/trips/active/` | Active set only |
| `GET` | `/api/transporter/driver/trips/completed/` | **Includes** cancelled |

#### Open-market discovery (unchanged; already correct)

| Method | Endpoint | Behavior |
|--------|----------|----------|
| `GET` | `/api/transporter/available-shipments/` | Only `PUBLISHED` with **no** trip |
| `GET` | `/api/transporter/load-discovery/` | Same |

Cancelled loads do not appear until the shipper publishes a **new** draft.

---

### Cancel API (existing)

**Auth:** Bearer token  
**Eligible trip statuses:** `ASSIGNED`, `EN_ROUTE`, `ARRIVED_PICKUP`

#### Shipper cancel

```http
POST /api/shipper/trips/{trip_id}/cancel/
Content-Type: application/json
Authorization: Bearer <token>
```

#### Transporter / driver cancel

```http
POST /api/transporter/trips/{trip_id}/cancel/
Content-Type: application/json
Authorization: Bearer <token>
```

**Payload**

```json
{
  "reason_code": "WRONG_DETAILS",
  "reason_text": "Optional free text; required when reason_code is OTHER"
}
```

**`reason_code` values**

| Code | Meaning |
|------|---------|
| `SCHEDULE_CHANGE` | Schedule / timing change |
| `WRONG_DETAILS` | Wrong load or address details |
| `NO_LONGER_NEEDED` | Load / trip no longer needed |
| `DRIVER_UNAVAILABLE` | Driver unavailable |
| `PRICE_DISPUTE` | Price / commercial disagreement |
| `OTHER` | Other (`reason_text` required) |

**Expected success response** (`200`)

Envelope: `{ "success": true, "message": "...", "data": { ... } }`

`data` is the trip detail serializer for the caller (shipper or transporter), with an added `cancellation` object:

```json
{
  "success": true,
  "message": "Trip cancelled successfully.",
  "data": {
    "id": 123,
    "status": "CANCELLED",
    "unique_id": "TR-00012",
    "shipment": {
      "id": 456,
      "status": "CANCELLED",
      "unique_id": "SH-00075"
    },
    "cancellation": {
      "reason_code": "WRONG_DETAILS",
      "reason_text": "Bad address",
      "cancelled_by_id": 10,
      "cancelled_by_role": "SHIPPER",
      "previous_status": "ASSIGNED",
      "cancelled_at": "2026-11-16T14:00:00+00:00"
    }
  }
}
```

(`shipment` fields follow the existing trip-detail serializer; status after cancel is `CANCELLED`.)

**Idempotent:** already-cancelled trip returns `200` with `"Trip already cancelled."` and the same `cancellation` payload.

**List reasons**

```http
GET /api/shipper/trip-cancel-reasons/
GET /api/transporter/trip-cancel-reasons/
```

```json
{
  "success": true,
  "message": "...",
  "data": {
    "reasons": [
      { "code": "SCHEDULE_CHANGE", "label": "Schedule / timing change" }
    ]
  }
}
```

---

### Clone-draft from cancelled (behavior change)

```http
POST /api/shipper/shipments/{shipment_id}/clone-draft/
Authorization: Bearer <shipper token>
```

**Payload:** none (empty body)

**Allowed sources**

| Source status | Has trip? | Allowed? |
|---------------|-----------|----------|
| `PUBLISHED` | No | Yes |
| `PUBLISHED` | Yes | No (`400`) |
| `CANCELLED` | Yes or no | **Yes** (new) |
| Other | — | No (`400`) |

**Expected success response** (`201`)

```json
{
  "success": true,
  "message": "Draft shipment created from cancelled load.",
  "data": {
    "id": 789,
    "status": "DRAFT",
    "unique_id": "SH-00099",
    "cargo_type": "...",
    "pickup_address": "...",
    "delivery_address": "..."
  }
}
```

Then shipper edits and publishes:

```http
PATCH /api/shipper/shipments/{draft_id}/
Content-Type: application/json

{
  "status": "PUBLISHED"
}
```

(plus any updated load fields). Old cancelled shipment/trip remain history.

---

### After cancel — expected list membership

| List | Cancelled trip/shipment? |
|------|---------------------------|
| Shipper Active Trips `GET /shipper/trips/` | Absent |
| Shipper My Loads `GET /shipper/shipments/` | Present as `CANCELLED` |
| Shipper history `GET /shipper/shipments/history/` | Present as `CANCELLED` |
| Fleet Available `GET /transporter/trips/my/` | Absent |
| Fleet Assign / Active | Absent |
| Fleet Completed | Present |
| Individual / fleet-driver completed | Present |
| `available-shipments` / `load-discovery` | Absent |

---

## 2. Admin: multi-currency vehicle rates + scrollable modals

Admin UI only (Django panel). Not mobile REST APIs.

### Data model

| Model | Unique constraint |
|-------|-------------------|
| `ZoneVehicleRate` | `(zone, vehicle_type, currency)` |
| `FreightRouteVehicleRate` | `(route, vehicle_type, currency)` |

Same vehicle type may have multiple GCC rates (`SAR`, `QAR`, `KWD`, `BHD`, `OMR`); duplicate `(type, currency)` is rejected.

Migration: `core/migrations/0044_vehicle_rate_type_currency_unique.py`

### Pricing

When multiple currencies exist for one vehicle type, lookup **prefers the country-matched currency** (zone country / freight origin), then falls back to another row for that type.

### Admin form payload (multipart, existing admin URLs)

Zone create/edit still posts parallel lists (one row per currency under a vehicle type):

| Field | Meaning |
|-------|---------|
| `vehicle_type` | Repeated; same value for each currency of that type |
| `vehicle_type_rate` | Rate per km (zones) |
| `vehicle_type_currency` | GCC currency code |
| `vehicle_min_freight` | Min freight (freight routes; instead of rate) |

Example (zone — Flat Bed with SAR + QAR):

```
vehicle_type=Flat Bed 12m
vehicle_type_rate=3.00
vehicle_type_currency=SAR
vehicle_type=Flat Bed 12m
vehicle_type_rate=4.50
vehicle_type_currency=QAR
```

**UI:** create/edit zone and freight-route modals use sticky header/footer and a scrollable body; vehicle types are grouped cards with nested currency rows.

---

## 3. Files touched (high level)

| Area | Files |
|------|--------|
| Trip list filters / clone | `api/views.py`, `api/billing_api.py` |
| Cancel list tests | `api/tests/test_cancelled_trip_list_buckets.py`, `api/tests/test_trip_cancel_and_load_republish.py`, `api/tests/test_individual_driver_trip_lists_api.py` |
| Rates model / pricing | `core/models.py`, `core/migrations/0044_…`, `core/pricing/service.py`, `core/views.py` |
| Admin modals | `core/templates/core/zones.html`, `core/templates/core/freight_routes.html` |
| Rate tests | `core/tests/test_zone_pricing.py` |
