Niolla/Zumri-Backend
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Implement Phase 8 Delivery and Rider Management
CI / test (push) Successful in 10m26s
Details

Browse Source 
- 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.
This commit is contained in:
Sathira Sri Sathara
2026-09-09 12:55:32 +05:30
parent cd2c1c6d08
commit 222483d194
24 changed files with 168 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Documentation/API_DELIVERY_RIDER.md
+41
View File
@@ -0,0 +1,41 @@
# 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.