Sathira Sri Sathara
222483d194
CI / test (push) Successful in 10m26s
- Introduced new Delivery and Rider API documentation. - Added new models for RiderProfile, Shipment, ShipmentItem, ShipmentAssignment, ShipmentEvent, and ShipmentProof. - Developed controllers for admin and rider logistics, including shipment management and rider actions. - Created services for handling shipment creation, assignment, and state transitions. - Implemented validation schemas for shipment and rider operations. - Added new routes for admin and rider logistics, including tracking endpoints. - Established a state machine for shipment status transitions. - Created migration scripts for new database tables and relationships. - Added unit tests for shipment state transitions and validation security.
42 lines
2.3 KiB
Markdown
42 lines
2.3 KiB
Markdown
# 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.
|