# 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](./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)).

---

## 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](./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?

---

## Implementation Notes

> Fill this section in during planning discussion before writing any code.