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.
88 lines
4.5 KiB
Markdown
88 lines
4.5 KiB
Markdown
# 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.
|