# Delivery and Rider API

All endpoints use `/api/v1`. There is no public tracking endpoint.

## Admin fulfillment

- `GET /admin/shipments`, `GET /admin/shipments/:id`
- `POST /admin/shipments` creates a delivery from immutable Order address/shipping snapshots and item quantities.
- `POST /admin/shipments/return-pickup` creates one pickup for an approved return.
- `POST /admin/shipments/:id/assign`, `/unassign`, `/reschedule`, `/cancel`
- `GET /admin/dispatch` projects unassigned, active, and attention-needed shipments.

Administration requires explicit shipment, dispatch, rider, or return-logistics permission. Shipment creation supports partial quantities, locks the order, checks existing non-cancelled allocations, and uses `Idempotency-Key` event identity.

## Rider administration

- `GET /admin/riders`, `GET /admin/riders/:id`
- `POST /admin/riders` attaches an operational profile to an existing RIDER User; it does not create another identity/password system.
- `PATCH /admin/riders/:id`
- `GET /admin/riders/:id/assignments`

Profile status is independent of User account status. Availability is AVAILABLE, BUSY, or OFFLINE and capacity is configurable.

## Rider workflow

- `GET /rider/shipments`, `GET /rider/shipments/:id`
- Explicit actions: accept, reject, pickup, in-transit, out-for-delivery, deliver, and fail-delivery.
- `PUT /rider/location` stores optional latest coordinates; location is not included in customer tracking.

Every operation derives the rider from authentication and constrains the current assignment. State changes use row locks and unique event IDs. Delivery requires structured proof; linked photo/signature uploads must be AVAILABLE images uploaded by that rider.

## Customer tracking

- `GET /orders/:orderId/tracking`
- `GET /returns/:id/tracking`

Responses contain shipment status and ordered event projections, not rider phone, location, capacity, assignment history, payment, or provider data.

## Behavior boundaries

Delivered item quantities recalculate Order fulfillment without changing payment status. Failed delivery never refunds or restocks. Return-pickup delivery marks the RMA received for Phase 7 inspection; it does not refund or restock. External couriers, maps, route optimization, delivery OTP, live sockets, and AI dispatch are not implemented.