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,71 @@
+# 10 — Region Management (Beyond CRUD)
+
+**Status**: Not Started
+**Depends On**: 00 — Existing Gap Fixes
+
+---
+
+## Goal
+
+Region CRUD already exists (`Features/Region`). This step covers everything in
+[mainPlan.md §2](./mainPlan.md#2-region-management) that isn't plain
+CRUD: targets, budgets, agency mapping, tax rules, hierarchy, and dashboarding.
+
+---
+
+## Background / Context
+
+`Region` today has only a `Name`. Nothing points to it except `Route.FK_RegionId`. There is no
+`Area` level (see Open Question in [00_existing_gaps.md](./00_existing_gaps.md#9-no-area-entity-between-region-and-route)).
+
+---
+
+## Data Model Changes
+
+### Regional Target / Budget
+
+`RegionId`, `Period` (e.g. `2026-08`), `TargetValue`, `BudgetAmount`.
+
+### Agency-Region Map
+
+`RegionId`, `AgencyId` — depends on whether "Regional Agency" becomes a distinct entity or stays a
+`Role` (see Open Questions).
+
+### Regional Tax Rule
+
+`RegionId`, `RuleConfig` (JSON) — deferred to whenever tax/pricing rule overrides are prioritized.
+
+---
+
+## API Endpoints
+
+| Function reference | Endpoint intent |
+|---|---|
+| `assignAreaToRegion(areaId, regionId)` | Blocked — no `Area` entity exists (see [00_existing_gaps.md](./00_existing_gaps.md#9-no-area-entity-between-region-and-route)) |
+| `setRegionalTarget(regionId, period, targetValue)` | `PUT /api/regions/{id}/targets/{period}` |
+| `setRegionalBudget(regionId, period, budgetAmount)` | `PUT /api/regions/{id}/budgets/{period}` |
+| `mapAgencyToRegion(agencyId, regionId)` | `POST /api/regions/{id}/agencies` |
+| `setRegionalTaxRule(regionId, ruleConfig)` | `PUT /api/regions/{id}/tax-rule` |
+| `getRegionHierarchy(regionId)` | `GET /api/regions/{id}/hierarchy` |
+| `getRegionDashboard(regionId, period)` | `GET /api/regions/{id}/dashboard?period=...` |
+
+---
+
+## Business Rules
+
+- Only `RegionalManager` and above (per role level in `Data/Seed/RoleAndPermissionSeed.cs`) can
+  set targets/budgets for their own region; only `RegionalAgency` can set them across regions.
+
+---
+
+## Open Questions
+
+- Is "Regional Agency" a business entity distinct from the `RegionalAgency` role (e.g. a contracted
+  third party with its own record), or is the role sufficient?
+- Does `getRegionDashboard` need real-time aggregation, or a scheduled/cached rollup?
+
+---
+
+## Implementation Notes
+
+> Fill this section in during planning discussion before writing any code.