ERP_Distribution/Distribution/docs/00_existing_gaps.md

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

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

---

Scope (What This Step Does NOT Include)

• No new feature modules (Procurement, Finance, Promotions, etc.) — those are separate steps, see 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.