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 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).

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)
`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.

2.3 KiB Raw Blame History