# 00 — Existing Gap Fixes

**Status**: Done
**Depends On**: —

---

## Goal

Close every hole identified in the currently-implemented modules (Region, Route, Vehicle, Store,
Warehouse, Order, User/Role/Permission) before any feature from [mainPlan.md](./mainPlan.md)
is built on top of them. This file is the running list of "Partially implemented" and foundational
"Not implemented" items pulled from that reference doc that block later steps, not just cosmetic
cleanup.

---

## Gaps to Fix

### 1. Route DTO — Missing RegionId

`RouteDTOs.cs` does not expose `RegionId` on create/update, so a Route cannot be linked to a
Region via the API even though `Route.FK_RegionId` exists on the model. Blocks §2/§3 of the
function reference (`assignAreaToRegion`, `getRegionHierarchy`) and any region-scoped authorization.

### 2. Store DTO — Missing RouteId

`StoreDTOs.cs` does not expose `RouteId` on create/update, so a Store cannot be linked to a Route
via the API even though `Store.FK_RouteId` exists on the model. Blocks `assignOutletsToRoute` (§3)
and route/region-scoped authorization for Stores and Orders.

> **Resolved** — `StoreDTOs.cs`'s `CreateStoreRequest`/`UpdateStoreRequest` now carry `RouteId`,
> and a dedicated bulk-assign endpoint (`POST /api/routes/{id}/stores`) was added in
> [11_route_sales_management.md](./11_route_sales_management.md).

### 3. Role Controller — Missing Authorization

`RoleController`'s GET endpoints carry only `[Authorize]`, with no `[Authorize(Policy = "...")]`
per action like every other controller. Any authenticated user — including a SalesRep — can read
every role and its full permission list today.

### 4. Secrets & Configuration Management

JWT signing key and DB connection string currently live in `appsettings.json`. Move both to
environment variables or user secrets before any non-local environment is stood up.

### 5. Input Validation

No DTO in any feature carries validation attributes (`[Required]`, `[MaxLength]`, range checks,
etc.). Bad data (empty names, negative levels, malformed emails) can enter the system silently
through any existing POST/PUT endpoint.

### 6. Item Model — Missing Properties

`Item : Template` has no properties (no SKU, name, unit of measure, category). `OrderItem`
references `Item`, but there's nothing there to reference. Fully scoped as its own step in
[01_item_catalog.md](./01_item_catalog.md) — tracked here only as the blocking dependency.

### 7. Order Has No Status / State Machine

`Order` has no status field, so `updateOrderStatus`, `approveOrder`/`rejectOrder`, and
`convertOrderToInvoice` (§1 of the function reference) have nowhere to write to. Every order-status
consumer downstream (delivery ride execution, sale ride execution, reconciliation, agent controls)
depends on this existing first.

### 8. No Credit Limit / Segment Fields on Store

`validateCreditLimit`, `updateStoreCreditLimit`, `getStoreOutstandingBalance`, and `classifyStore`
(§1, §4) all need fields that don't exist on `Store` today (credit limit, outstanding balance,
segment). Not scoped to a single feature file yet — flagged here so it isn't silently assumed by
a later step.

### 9. No Area Entity Between Region and Route

`assignAreaToRegion`, `createRoute(name, areaId)` (§2, §3) assume an `Area` level between Region
and Route that doesn't exist in the schema — only `Region → Route → Store` exists. Confirm with
the user whether `Area` is a real requirement or whether Region/Route is the intended two-level
hierarchy before building anything that assumes a third level.

### 10. No Driver Entity

`DeliveryRun.FK_DriverId`/`Driver` navigation is commented out in the model. `assignDriverToVehicle`,
`checkDriverCompliance` (§5) and any ride that needs a named driver depend on this existing.
Blocks [03_ride_lifecycle.md](./03_ride_lifecycle.md).

---

## Scope (What This Step Does NOT Include)

- No new feature modules (Procurement, Finance, Promotions, etc.) — those are separate steps,
  see [mainPlan.md](./mainPlan.md) for the full list and their own
  numbered files below.
- No UI/client changes.
- No changes to authentication (JWT) — only authorization policy coverage on `RoleController`.

---

## Business Rules

- A gap fix must not change the shape of an already-shipped response DTO in a breaking way without
  flagging it — additive fields only unless explicitly agreed.
- Soft-delete (`IsActive`) pattern must be preserved on every entity touched.

---

## Open Questions

- Is `Area` a real business concept (a level between Region and Route), or should
  `createRoute`/`assignAreaToRegion` in the function reference be reinterpreted as Region-only?
- Should `Store.CreditLimit` and `Store.OutstandingBalance` be added now as part of gap-fixing, or
  deferred to a dedicated Finance step (§13)?
- Does `Order.Status` need a fixed enum now (`pending/approved/picked/dispatched/delivered/invoiced`
  per §1), or a smaller interim set until the fuller order lifecycle is built?

---

## Implementation Notes

> Fill this section in during planning discussion before writing any code.