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