# 06 — Sale Ride Execution

**Status**: Not Started
**Depends On**: 04 — Loading Event

---

## Goal

Support on-the-spot van sales with no pre-order: driver picks items/quantities, an invoice is
generated immediately, and payment is captured at point of sale. Covers `createInvoice`,
`recordPayment` from [mainPlan.md §13](./mainPlan.md#13-finance--accounting),
and reuses `applyPricingAndDiscounts` (§1) plus `evaluateSchemeEligibility`/`applySchemeDiscount`
(§11) if promotions are live by the time this ships.

---

## Background / Context

Distinct from [05_delivery_ride.md](./05_delivery_ride.md): there is no pre-existing `Order` row —
the field invoice *is* the order, created and settled in one step.

---

## Data Model Changes

### Field Invoice

`RideId`, `StoreId`, `CreatedByUserId`, `TotalAmount`, `PaymentStatus` (`Paid`, `PartiallyPaid`,
`OnCredit`).

### Field Invoice Line Item

`FieldInvoiceId`, `ItemId`, `Quantity`, `UnitPrice` (subject to the discount-limit rules in
[08_sales_agent_controls.md](./08_sales_agent_controls.md)).

### Payment Record

`FieldInvoiceId`, `Amount`, `Method` (`Cash`, `Credit`), `CollectedAt`.

---

## API Endpoints

| Function reference | Endpoint intent |
|---|---|
| `createInvoice(orderId)` (§13) | `POST /api/rides/{rideId}/field-invoices` — orderId is the field invoice itself here |
| `recordPayment(invoiceId, amount, method)` (§13) | `POST /api/field-invoices/{id}/payments` |
| `applyPricingAndDiscounts(orderId)` (§1) | Applied at line-item entry time, within agent discount limits |

---

## Business Rules

- Driver cannot sell more than what is loaded on the vehicle — every line item is checked against
  the vehicle's current stock balance ([02_stock_ledger.md](./02_stock_ledger.md)) before the
  invoice is finalized.
- Each confirmed sale line creates a `Sale` stock movement against the vehicle location,
  immediately (not batched at ride close).
- Discount applied per line must not exceed the agent's role-level limit (§8).

---

## Fraud / Control Considerations

- Cash collected must reconcile against invoiced totals at ride close — see
  [07_ride_reconciliation.md](./07_ride_reconciliation.md).

---

## Open Questions

- Are field invoices numbered/sequenced separately from warehouse-issued invoices, or share one
  sequence?

---

## Implementation Notes

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