2.5 KiB
05 — Delivery Ride Execution
Status: Not Started Depends On: 04 — Loading Event
Goal
Execute pre-confirmed orders against a loaded, active delivery ride. Covers the order-status half
of mainPlan.md §1:
updateOrderStatus, convertOrderToInvoice, createBackorder. Requires Order.Status to exist
first — see gap #7 in 00_existing_gaps.md.
Background / Context
Today Order has no status and no link to a ride. This step is where the order lifecycle
(pending → approved → picked → dispatched → delivered → invoiced) actually gets driven, once the
order has been picked/loaded (04_loading_event.md).
Data Model Changes
Delivery Task (per order on ride)
RideId, OrderId, Sequence (visit order), Status (Pending, Delivered, PartiallyDelivered,
Failed).
Delivery Outcome
Per delivery task: quantities actually delivered per line, vs. ordered — feeds createBackorder
for the shortfall.
Customer Confirmation
Signature or OTP captured against the delivery task before it can be marked complete.
API Endpoints
| Function reference | Endpoint intent |
|---|---|
updateOrderStatus(orderId, status) (§1) |
PUT /api/rides/{rideId}/tasks/{orderId}/status |
convertOrderToInvoice(orderId) (§1) |
Triggered automatically on Delivered/PartiallyDelivered — see 19_finance_accounting.md |
createBackorder(orderId, unfulfilledItems[]) (§1) |
Triggered automatically on PartiallyDelivered |
| — | POST /api/rides/{rideId}/tasks/{orderId}/confirm — captures customer signature/OTP |
Business Rules
- A delivery task cannot be marked
Deliveredwithout a customer confirmation. PartiallyDeliveredalways creates acreateBackorderentry and a credit note for the undelivered quantity (see 18_returns_claims.md for credit note shape).- Each confirmed delivery task creates a stock movement (
Sale/consumption) against the vehicle location per 02_stock_ledger.md.
Fraud / Control Considerations
- OTP/signature capture must be tamper-evident (timestamped, tied to the delivery task, not editable after submission).
Open Questions
- Signature capture (image) or OTP (SMS code) — one, or both, in v1?
Implementation Notes
Fill this section in during planning discussion before writing any code.