# 07 — Ride Close & Reconciliation

**Status**: Not Started
**Depends On**: 05 — Delivery Ride Execution, 06 — Sale Ride Execution

---

## Goal

Physically count what's left on the vehicle at ride close and reconcile it against the stock
ledger and cash collected. Covers `runCycleCount` and `reconcileStock` from
[mainPlan.md §6](./mainPlan.md#6-warehouse-management), applied to a
vehicle location instead of a warehouse zone.

---

## Background / Context

This is the control point that catches loading discrepancies ([04_loading_event.md](./04_loading_event.md))
that went unresolved, and any shortfall between what was sold/delivered and what's physically on
the vehicle.

---

## Data Model Changes

### Ride Close Summary

`RideId`, `ClosedAt`, `ClosedByUserId`, computed totals for the reconciliation equation below.

### Variance Record

`RideId`, `ItemId` (or `Cash` for the monetary variance), `ExpectedQuantity`/`ExpectedAmount`,
`ActualQuantity`/`ActualAmount`, `Variance`, `ReasonCode`, `Status` (`Pending`, `Approved`,
`Rejected`).

### Supervisor Approval

Every non-zero variance requires a supervisor-level approval (`Role.Level >= 20`) before the ride
can transition to `Closed`.

---

## The Reconciliation Equation

```
Opening Stock − Sales − Damages + Returns = Closing Stock (physical count)   [runCycleCount / reconcileStock]
Cash Collected + Credit Extended = Total Sales − Returns
```

---

## API Endpoints

| Function reference | Endpoint intent |
|---|---|
| `runCycleCount(warehouseId, zoneId)` (§6) | `POST /api/rides/{id}/cycle-count` — `zoneId` maps to the ride's vehicle location |
| `reconcileStock(warehouseId, countResults)` (§6) | `POST /api/rides/{id}/reconcile` |
| — | `POST /api/rides/{id}/variances/{id}/approve` — supervisor sign-off |
| — | `POST /api/rides/{id}/close` — only succeeds once every variance is `Approved` |

---

## Business Rules

- A ride cannot close with an unexplained variance — every `Variance` row must be `Approved` or
  `Rejected` (with the discrepancy converted to a stock `Adjustment` movement) before close.
- `reconcileStock` writes an `Adjustment` movement per variance line, never edits the running
  balance directly (see [02_stock_ledger.md](./02_stock_ledger.md)).

---

## Fraud / Control Considerations

- Unresolved/high-frequency discrepancies are logged permanently against the agent's record — feeds
  the anomaly detection in [09_fraud_controls.md](./09_fraud_controls.md).

---

## Open Questions

- Is there a variance threshold below which supervisor approval is auto-granted (e.g. rounding-
  level cash differences), or does every non-zero variance require explicit sign-off?

---

## Implementation Notes

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