ERP_Distribution/Distribution/docs/07_ride_reconciliation.md

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, 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) 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).

---

Fraud / Control Considerations

• Unresolved/high-frequency discrepancies are logged permanently against the agent's record — feeds the anomaly detection in 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.