feat: Implement Phase 8 Delivery and Rider Management

- 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.
2026-09-09 12:55:32 +05:30
parent cd2c1c6d08
commit 222483d194
24 changed files with 168 additions and 0 deletions
@@ -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.
@@ -420,3 +420,6 @@ Date: 2026-09-03. Module 06 is 91%, Module 08 is 84%, and Module 07 is revised t
 ## Phase 7 Completion Update

 Date: 2026-09-09. Module 09 is 86%, Module 10 is 76%, and Module 13 is revised to 82%. Orders are 90%, payments 78%, invoices 72%, refunds 68%, returns 82%, coupon redemption 80%, and verified-purchase reviews 90%. Eleven commerce models, a forward-only migration, transactional checkout conversion, owner/admin APIs, explicit state machines, verified/idempotent webhook processing, payment-time inventory consumption, invoice sequencing, itemized refund validation, RMA handling, and return-only restocking were added. Migration and real provider/MySQL/document-worker validation remain staging requirements. Module 16 AI Customer Support Chatbot is intentionally excluded from this backend and planned as a separate service.
+## Phase 8 Completion Update
+
+Date: 2026-09-09. Module 11 is 88%; shipments are 90%, riders 86%, assignment/dispatch 86%, tracking 88%, proof of delivery 82%, and return logistics 84%. Module 09 is revised to 90% through physical fulfillment integration. Six logistics models, a forward-only migration, explicit shipment states/actions, partial fulfillment, locked rider capacity/assignment, append-only events, proof media validation, safe tracking, and approved-return pickup were added. Automated checks pass 25 suites/123 tests with 305 JavaScript files syntax-checked. The migration was not executed. Staging must validate real InnoDB concurrency, multi-instance idempotency, proof storage, notification fan-out, permission seeding, and return handoff before production or Phase 9 rollout. Module 16 AI Customer Support Chatbot remains excluded from this backend and will be developed separately.
@@ -0,0 +1,87 @@
+# ZUMRI Phase 8 Delivery and Rider Management
+
+## Objective
+Add physical delivery and approved-return transportation after the paid Order boundary.
+
+## Existing Components Reused
+User/RIDER authentication, Order/OrderItem snapshots, ReturnRequest, ReferenceNumber, Upload, audit, notification foundations, and permissions.
+
+## Shipment Architecture
+Orders can have many CUSTOMER_DELIVERY shipments; returns have one RETURN_PICKUP. Shipment owns immutable destination and operational timestamps, never prices or payments.
+
+## Shipment Items
+ShipmentItem references OrderItem and supports partial allocation. Locked allocation checks prevent non-cancelled totals exceeding purchases.
+
+## Shipment State Machine
+Central legal transitions cover readiness, assignment, pickup, transit, delivery, failure, rescheduling, and cancellation. No generic status patch exists.
+
+## Order Fulfillment Integration
+Delivered shipment quantities derive UNFULFILLED, PARTIALLY_FULFILLED, or FULFILLED. Delivery never changes payment or initiates a refund.
+
+## Rider Profile
+Operational data attaches one-to-one to an existing RIDER User; authentication and identity remain on User.
+
+## Rider Availability
+ACTIVE/INACTIVE/SUSPENDED is separate from AVAILABLE/BUSY/OFFLINE. Assignment locks the rider and checks active capacity.
+
+## Assignment Architecture
+Append-preserved assignment rows record assignment, acceptance/rejection, unassignment, and completion. Shipment caches only the current rider.
+
+## Dispatch
+The dispatch view queries ready, active, failed, and rescheduled shipments without adding redundant persistence.
+
+## Rider Workflow
+Riders see and act only on their own current assignments through explicit legal action endpoints.
+
+## Delivery Events
+ShipmentEvent is append-only. Unique event IDs provide retry idempotency and chronological customer timelines.
+
+## Proof of Delivery
+Structured proof supports photo, signature, recipient confirmation, and return-pickup photo. Existing private Upload records are ownership/status/MIME checked.
+
+## Failed Deliveries
+Failure requires a reason code and increments attempts. It does not refund, cancel the Order, or restock.
+
+## Rescheduling
+Admin may schedule a failed delivery with bounded window/reason fields; no calendar optimizer is introduced.
+
+## Customer Tracking
+Authenticated ownership is mandatory. Safe projections exclude private rider/location and financial data.
+
+## Location Privacy
+Only latest optional coordinates are retained. They are operational data, absent from customer responses and broad audit metadata.
+
+## Return Logistics
+Physical transport remains separate from Phase 7 inspection, refund, and inventory decisions.
+
+## Return Pickup
+Only approved returns create an idempotent pickup. Delivery marks the request RECEIVED without premature refund/restock.
+
+## Notifications
+Existing Phase 2 infrastructure remains the integration boundary. Automated delivery notification fan-out needs durable outbox/worker hardening before production.
+
+## Permissions
+Shipment read/create/manage/assign, rider read/manage, dispatch read/manage, proof read, and return-logistics read/manage permissions were added.
+
+## Audit
+Creation, assignment, rider actions, cancellation, reschedule, and return pickup use stable Phase 2 activity types without precise location.
+
+## Idempotency
+Creation, assignment, and rider transitions use client keys mapped to unique ShipmentEvent IDs. Repeated delivery cannot duplicate proof/event/fulfillment changes.
+
+## Concurrency
+Transactions and row locks protect creation allocations, assignment, capacity, transitions, completion, and return-pickup uniqueness. Real multi-connection InnoDB tests remain required.
+
+## Database Changes
+Forward-only migration `20260909080000` creates six logistics tables with reference, event, lookup, and uniqueness indexes.
+
+## Tests
+Unit tests cover all primary legal/illegal transitions, owner-derived rider authorization, address injection rejection, failure reason validation, and location ranges.
+
+## Remaining Known Issues
+Real migrations/concurrency, durable notification fan-out, upload storage, pagination tuning, and assignment race testing require staging. No external courier or real-time GPS system exists.
+
+## Phase 9 Prerequisites
+Apply migrations on restored staging, seed permissions/rider profiles, validate real concurrent allocation/assignment/delivery requests, proof uploads, notification idempotency, and return receipt handoff.
+
+Module 16 AI Customer Support Chatbot remains intentionally outside this backend and will be developed separately.