Sathira Sri Sathara
222483d194
- 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.
4.5 KiB
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.