Document the implemented region management endpoints

Updates mainPlan.md's Region Management table, 10_region_management.md's status/open-questions/implementation-notes sections, and BACKEND_API_REFERENCE.md's Regions section to reflect the newly added target/budget/agency-map/tax-rule/hierarchy/dashboard endpoints, and flags that the EF Core migration for the new tables is still pending. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-30 22:51:46 +05:30
parent 9febae6d63
commit 8b84c8aeb3
3 changed files with 137 additions and 26 deletions
@@ -506,6 +506,88 @@ Array of:
 }
 ```

+**Beyond CRUD** — targets, budgets, agency mapping, tax rules, hierarchy, and dashboard. These are
+not gated by the `regions.*` permission codes above; access is checked by role level in
+`RegionService`: `RegionalManager` (level 50) can act only on a region they have scope over (via
+`UserRegionScope`), `RegionalAgency` (level 60) can act on any region.
+
+| Method | Path | Description |
+|---|---|---|
+| `PUT` | `/api/regions/{id}/targets/{period}` | Set the sales target for a region for a period (`period` = `yyyy-MM`) |
+| `PUT` | `/api/regions/{id}/budgets/{period}` | Set the budget for a region for a period |
+| `POST` | `/api/regions/{id}/agencies` | Map an existing user (holding the `RegionalAgency` role) to this region |
+| `PUT` | `/api/regions/{id}/tax-rule` | Set/replace the region's tax rule config |
+| `GET` | `/api/regions/{id}/hierarchy` | Region's routes and each route's store ids |
+| `GET` | `/api/regions/{id}/dashboard?period=yyyy-MM` | Real-time order count/sales/target/budget for the period |
+
+**Set target request / response:**
+```json
+// PUT /api/regions/{id}/targets/{period}
+{ "targetValue": 500000 }
+```
+```json
+{ "regionId": "guid", "period": "2026-08", "targetValue": 500000 }
+```
+
+**Set budget request / response:**
+```json
+// PUT /api/regions/{id}/budgets/{period}
+{ "budgetAmount": 200000 }
+```
+```json
+{ "regionId": "guid", "period": "2026-08", "budgetAmount": 200000 }
+```
+
+**Map agency request / response:**
+```json
+// POST /api/regions/{id}/agencies
+{ "agencyUserId": "guid" }   // must be a User with the RegionalAgency role
+```
+```json
+{ "regionId": "guid", "agencyUserId": "guid" }
+```
+
+**Set tax rule request / response:**
+```json
+// PUT /api/regions/{id}/tax-rule
+{ "ruleConfig": "{\"rate\": 0.15}" }   // arbitrary JSON stored as a string; not yet consumed by pricing
+```
+```json
+{ "regionId": "guid", "ruleConfig": "{\"rate\": 0.15}" }
+```
+
+**Hierarchy response:**
+```json
+{
+  "regionId": "guid",
+  "regionName": "string",
+  "routes": [
+    { "routeId": "guid", "routeName": "string", "storeIds": ["guid", "..."] }
+  ]
+}
+```
+
+**Dashboard response:**
+```json
+{
+  "regionId": "guid",
+  "period": "2026-08",
+  "targetValue": 500000,       // null if no target set for the period
+  "budgetAmount": 200000,      // null if no budget set for the period
+  "orderCount": 42,
+  "actualSales": 187500.00,
+  "lastOrderDate": "datetime | null"
+}
+```
+
+All four of these endpoints return `404` if the region doesn't exist, the caller lacks the
+required region scope, or (for agency mapping) the target user doesn't hold the `RegionalAgency`
+role — the response body carries no distinction between "not found" and "forbidden".
+
+No EF Core migration for `RegionalTarget`/`RegionalBudget`/`RegionAgencyMap`/`RegionalTaxRule` has
+been applied yet — these endpoints will 500 against a database that hasn't run the pending
+migration.
+
 ---

 ### 6.6 Routes