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

Distribution/docs/08_sales_agent_controls.md

@@ -7,13 +7,21 @@
 
 ## Goal
 
-
+Wire role levels to concrete business limits and approval chains. Covers the approval-routing half
+of [mainPlan.md §1](./mainPlan.md#1-order-management)
+(`submitOrderForApproval`, `approveOrder`, `rejectOrder`) and the performance-tracking functions
+from [§10 SFA/CRM](./mainPlan.md#10-sales-force-automation-sfa--crm)
+(`trackTargetVsAchievement`, `calculateIncentive`). Lead/interaction functions from §10
+(`logCustomerInteraction`, `createLead`, `convertLeadToStore`) are out of scope here — see
+[16_sfa_crm.md](./16_sfa_crm.md).
 
 ---
 
 ## Background / Context
 
-
+`Role.Level` already exists and drives the permission seed
+(`Data/Seed/RoleAndPermissionSeed.cs`), but nothing today turns a level into a discount limit,
+credit limit, or approval threshold — it only gates which API endpoints a role can call.
 
 ---
 
@@ -21,39 +29,56 @@
 
 ### Agent Limit Configuration (per role level)
 
-
+`RoleId`, `MaxDiscountPercent`, `MaxSingleTransactionValue` — read by both
+[06_sale_ride.md](./06_sale_ride.md) (line-item discount check) and order approval routing here.
 
 ### Override Log
 
-
+`OverrideById` (the supervisor), `TargetType`/`TargetId` (e.g. `Order`, `FieldInvoice`), `OldValue`,
+`NewValue`, `Reason`, `CreatedAt` — a one-time exception, logged against the supervisor's account.
 
 ### Customer Credit Profile
 
-
+Reuses `Store.CreditLimit`/`Store.OutstandingBalance` once added (gap #8 in
+[00_existing_gaps.md](./00_existing_gaps.md)) rather than a separate entity.
 
 ---
 
 ## API Endpoints
 
-
+| Function reference | Endpoint intent |
+|---|---|
+| `submitOrderForApproval(orderId)` (§1) | Triggered automatically when an order exceeds its agent's limit |
+| `approveOrder(orderId, approverId)` / `rejectOrder(orderId, reason)` (§1) | `POST /api/orders/{id}/approve`, `POST /api/orders/{id}/reject` |
+| `trackTargetVsAchievement(userId, period)` (§10) | `GET /api/agents/{userId}/performance?period=...` |
+| `calculateIncentive(userId, period)` (§10) | `GET /api/agents/{userId}/incentive?period=...` |
+| — | `POST /api/orders/{id}/override` — supervisor one-time exception, writes an Override Log entry |
 
 ---
 
 ## Business Rules
 
-
+- An order/invoice whose value or discount exceeds the agent's `Agent Limit Configuration` cannot
+  proceed without either supervisor approval or a logged override — no silent pass-through.
+- `calculateIncentive` reads only settled/closed rides (post-[07_ride_reconciliation.md](./07_ride_reconciliation.md)),
+  never in-flight ones.
 
 ---
 
 ## Fraud / Control Considerations
 
-
+- Every `Override Log` entry is permanent and immutable once written — feeds
+  [09_fraud_controls.md](./09_fraud_controls.md)'s anomaly detection (agents with unusually
+  frequent overrides).
 
 ---
 
 ## Open Questions
 
-
+- Are discount/transaction limits configured per `Role`, or can an individual `User` have a
+  tighter/looser override of their role's default?
+- What sales target source feeds `trackTargetVsAchievement` — is there a target-setting endpoint
+  needed here, or does it come from §2's `setRegionalTarget` rolled down to the individual?
 
 ---