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

Distribution/docs/09_fraud_controls.md

@@ -7,13 +7,18 @@
 
 ## Goal
 
-
+A dedicated, immutable audit log plus automated anomaly detection over everything built in steps
+01–08. Covers [mainPlan.md §18](./mainPlan.md#18-compliance--audit)
+(`logAuditEvent`, `checkLicenseCompliance`, `generateComplianceReport`) and the fraud-relevant piece
+of §15 (`sendRouteDeviationAlert`) and §12 (return-without-prior-sale detection).
 
 ---
 
 ## Background / Context
 
-
+Every prior step in this plan references "logged" or "flagged" behavior (override logs, loading
+discrepancies, reconciliation variances) — this step is where that logging actually becomes a
+queryable, immutable audit trail instead of scattered per-feature notes.
 
 ---
 
@@ -21,45 +26,69 @@
 
 ### Audit Log Entry
 
-
+`UserId`, `Action`, `EntityType`, `EntityId`, `OldValue`/`NewValue` (JSON snapshot), `CreatedAt`,
+`SourceIp`/`RequestId` if available. Append-only — no update or delete path exposed anywhere.
 
 ### Anomaly Flag
 
-
+`Type` (`ReturnWithoutSale`, `RouteDeviation`, `HighVarianceRate`, `CashShortfall`), `EntityType`/
+`EntityId`, `RaisedAt`, `Status` (`Open`, `Reviewed`, `Dismissed`).
 
 ### Return Approval Record
 
-
+Reuses the `approveReturn` flow from [18_returns_claims.md](./18_returns_claims.md) — this step
+adds the automated pre-check (`ReturnWithoutSale`) that runs before a human approver sees it.
 
 ---
 
 ## API Endpoints
 
-
+| Function reference | Endpoint intent |
+|---|---|
+| `logAuditEvent(userId, action, entityType, entityId)` (§18) | Internal — called by every mutating service, not directly exposed |
+| `checkLicenseCompliance(entityId, licenseType)` (§18) | `GET /api/compliance/{entityType}/{entityId}/license-check` |
+| `generateComplianceReport(period)` (§18) | `GET /api/compliance/report?period=...` |
+| `sendRouteDeviationAlert(routeId, salesRepId)` (§15) | Triggered from route check-in/out data (§3 of the function reference; not yet in any numbered step — see [11_route_sales_management.md](./11_route_sales_management.md)) |
+| — | `GET /api/audit-log?entityType=...&entityId=...` |
+| — | `GET /api/anomaly-flags?status=Open` |
 
 ---
 
 ## Automated Checks & Flags
 
-
+- Returns without a matching prior sale (`ReturnWithoutSale`).
+- Sales/deliveries outside the geofenced route (`RouteDeviation`) — depends on GPS check-in/out
+  data from [11_route_sales_management.md](./11_route_sales_management.md).
+- Agents with consistently high variance rates across closed rides (`HighVarianceRate`) — reads
+  `Variance Record` history from [07_ride_reconciliation.md](./07_ride_reconciliation.md).
+- Cash collected below invoiced amount (`CashShortfall`) — reads `Payment Record` from
+  [06_sale_ride.md](./06_sale_ride.md).
 
 ---
 
 ## Business Rules
 
-
+- Every state-changing action across every feature must call `logAuditEvent` — this is the one
+  cross-cutting requirement every other numbered step inherits once this lands.
+- Return approval requires supervisor sign-off before stock is credited back
+  ([18_returns_claims.md](./18_returns_claims.md)), regardless of whether an anomaly flag fired.
 
 ---
 
 ## Fraud / Control Considerations
 
-
+- Anomaly reports are surfaced to area managers on a scheduled basis — batch job or on-demand
+  endpoint, not real-time push, in v1.
 
 ---
 
 ## Open Questions
 
-
+- Should `logAuditEvent` be wired in as a cross-cutting concern (e.g. an EF `SaveChanges`
+  interceptor) rather than an explicit call in every service, to guarantee nothing is missed?
+- What licenses does `checkLicenseCompliance` actually need to validate for this business — is
+  regulated goods handling in scope at all, or is this function speculative until a real
+  requirement shows up?
 
 ---