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

Distribution/docs/07_ride_reconciliation.md

@@ -7,13 +7,18 @@
 
 ## 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.
 
 ---
 
@@ -21,45 +26,61 @@
 
 ### 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?
 
 ---