Add md file features in region, route, store, fleet, pricing, procurement, SFA, promotions, returns, finance, reporting, notifications, integration, and mobile capabilities

Distribution/docs/05_delivery_ride.md

@@ -7,13 +7,18 @@
 
 ## Goal
 
-
+Execute pre-confirmed orders against a loaded, active delivery ride. Covers the order-status half
+of [mainPlan.md §1](./mainPlan.md#1-order-management):
+`updateOrderStatus`, `convertOrderToInvoice`, `createBackorder`. Requires `Order.Status` to exist
+first — see gap #7 in [00_existing_gaps.md](./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](./04_loading_event.md)).
 
 ---
 
@@ -21,39 +26,51 @@
 
 ### 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](./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 `Delivered` without a customer confirmation.
+- `PartiallyDelivered` always creates a `createBackorder` entry and a credit note for the
+  undelivered quantity (see [18_returns_claims.md](./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](./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?
 
 ---