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

2026-08-19 15:18:31 +05:30
parent 45f374133f
commit d2390e7b12
25 changed files with 1565 additions and 88 deletions
@@ -0,0 +1,70 @@
+# 17 — Promotions & Trade Scheme Management
+
+**Status**: Not Started
+**Depends On**: 01 — Item Catalog, 14 — Pricing & Supplier Master Data
+
+---
+
+## Goal
+
+Covers [mainPlan.md §11](./mainPlan.md#11-promotions--trade-scheme-management)
+in full — an entirely new subsystem. Once built, `applyPricingAndDiscounts` (§1) and
+`checkStoreSchemeEligibility` (§4) both read from it.
+
+---
+
+## Background / Context
+
+No scheme/promotion entity exists today. Every reference to "eligible discount" elsewhere in this
+doc set (order pricing, field invoices, agent discount limits) currently has no scheme data source
+— it only enforces the flat per-role discount ceiling from
+[08_sales_agent_controls.md](./08_sales_agent_controls.md).
+
+---
+
+## Data Model Changes
+
+### Scheme
+
+`Name`, `RuleType` (`BuyXGetY`, `SlabDiscount`, `FlatPercent`), `RuleConfig` (JSON), `Eligibility`
+(store segment / region scope), `DateRangeFrom`, `DateRangeTo`.
+
+### Scheme Redemption
+
+`SchemeId`, `OrderId` (or `FieldInvoiceId`), `DiscountAmount`, `RedeemedAt` — feeds
+`trackSchemeSpend` and `getSchemeROI` without re-scanning every order.
+
+---
+
+## API Endpoints
+
+| Function reference | Endpoint intent |
+|---|---|
+| `createScheme(schemeRules, eligibility, dateRange)` | `POST /api/schemes` |
+| `evaluateSchemeEligibility(storeId, orderId)` | `GET /api/schemes/eligible?storeId=...&orderId=...` |
+| `applySchemeDiscount(orderId, schemeId)` | `POST /api/orders/{id}/apply-scheme` |
+| `trackSchemeSpend(schemeId)` | `GET /api/schemes/{id}/spend` |
+| `getSchemeROI(schemeId)` | `GET /api/schemes/{id}/roi` |
+
+---
+
+## Business Rules
+
+- A scheme discount stacks with, but does not bypass, the per-role discount ceiling in
+  [08_sales_agent_controls.md](./08_sales_agent_controls.md) unless explicitly flagged as an
+  agent-limit-exempt scheme.
+- `getSchemeROI` requires a baseline (pre-scheme expected sales) to compare against — confirm data
+  source before implementing (see Open Questions).
+
+---
+
+## Open Questions
+
+- What counts as "incremental sales" for `getSchemeROI` — a manual baseline entered when the scheme
+  is created, or a trailing-period average computed automatically?
+
+---
+
+## Implementation Notes
+
+> Fill this section in during planning discussion before writing any code.