ERP_Distribution/Distribution/PLAN.md

Phase Plan — Route & Store Management

Scope

Build the full vertical-slice stack for: Region, Route, Vehicle, Store, Warehouse, Order, OrderItem.
Item model is sourced from ERP Core — excluded from this phase.
SaleRoute shape is TBD — excluded until clarified.

---

Project Structure (target)

Distribution/
├── Models/                          # All entity POCOs — unchanged
│   ├── Template.cs
│   ├── Region.cs
│   ├── Route.cs
│   ├── Vehicle.cs
│   ├── Store.cs
│   ├── Warehouse.cs
│   ├── SaleRoute.cs                 # TBD
│   ├── Order.cs
│   ├── OrderItem.cs
│   ├── DeliveryRun.cs
│   └── Item.cs                      # Sourced from ERP Core
├── Data/
│   └── AppDBContext.cs              # DbSets + Fluent API config
├── Infra/
│   ├── UoW/                         # Already implemented
│   │   ├── IUnitOfWork.cs
│   │   └── EFUnitOfWork.cs
│   └── Repositories/                # Shared generic base only
│       ├── IGenericRepo.cs
│       └── GenericRepo.cs
└── Features/
    ├── Region/
    │   ├── RegionDTOs.cs
    │   ├── IRegionRepository.cs
    │   ├── RegionRepository.cs
    │   ├── RegionService.cs
    │   └── RegionController.cs
    ├── Route/
    │   ├── RouteDTOs.cs
    │   ├── IRouteRepository.cs
    │   ├── RouteRepository.cs
    │   ├── RouteService.cs
    │   └── RouteController.cs
    ├── Vehicle/
    │   ├── VehicleDTOs.cs
    │   ├── IVehicleRepository.cs
    │   ├── VehicleRepository.cs
    │   ├── VehicleService.cs
    │   └── VehicleController.cs
    ├── Store/
    │   ├── StoreDTOs.cs
    │   ├── IStoreRepository.cs
    │   ├── StoreRepository.cs
    │   ├── StoreService.cs
    │   └── StoreController.cs
    ├── Warehouse/
    │   ├── WarehouseDTOs.cs
    │   ├── IWarehouseRepository.cs
    │   ├── WarehouseRepository.cs
    │   ├── WarehouseService.cs
    │   └── WarehouseController.cs
    └── Order/
        ├── OrderDTOs.cs
        ├── IOrderRepository.cs
        ├── OrderRepository.cs
        ├── OrderService.cs
        └── OrderController.cs

---

Hard Rules (from AGENTS.md)

• Only uow.CommitAsync() in services — never in repositories.
• Use DateTime.Now — never DateTime.UtcNow.
• Never build anything not explicitly requested.

---

Step 2 — Complete AppDBContext

File: Data/AppDBContext.cs

Add DbSets and Fluent API configuration:

public DbSet<Region> Regions { get; set; }
public DbSet<Route> Routes { get; set; }
public DbSet<Vehicle> Vehicles { get; set; }
public DbSet<Store> Stores { get; set; }
public DbSet<Warehouse> Warehouses { get; set; }
public DbSet<SaleRoute> SaleRoutes { get; set; }
public DbSet<Order> Orders { get; set; }
public DbSet<OrderItem> OrderItems { get; set; }
public DbSet<DeliveryRun> DeliveryRuns { get; set; }
public DbSet<Item> Items { get; set; }

// OnModelCreating
modelBuilder.Entity<OrderItem>()
    .HasKey(oi => new { oi.FK_OrderId, oi.FK_ItemId });

---

Step 3 — Initial Migration

dotnet ef migrations add InitialCreate --project Distribution
dotnet ef database update --project Distribution

Each developer applies this locally. No migration files are shared.

---

Step 4 — Generic Repository (Infra/Repositories)

IGenericRepo<T>

GetByIdAsync(Guid id)
GetAllAsync()
AddAsync(T entity)
Update(T entity)
Remove(T entity)

GenericRepo<T> — implements above using DbContext. No SaveChanges calls.

---

Step 5 — Feature Implementation Order

Build each feature in this dependency order:

1. Region      → no dependencies
2. Route       → no dependencies
3. Vehicle     → no dependencies
4. Store       → no dependencies
5. Warehouse   → depends on Vehicle (FK)
6. Order       → depends on Store (FK)
7. OrderItem   → depends on Order + Item (composite FK)

Per-feature deliverables

DTOs ({Feature}DTOs.cs)

• CreateRequest — fields accepted on POST
• UpdateRequest — fields accepted on PUT
• Response — shape returned to client (never expose the entity directly)

Repository interface (I{Feature}Repository.cs)

Extends IGenericRepo<T>. Add feature-specific queries (e.g., GetByStoreId).

Repository implementation ({Feature}Repository.cs)

Inherits GenericRepo<T>. Implements feature-specific queries. No CommitAsync calls.

Service ({Feature}Service.cs)

• Contains all business logic.
• Calls _uow.CommitAsync(ct) after write operations.
• For multi-step writes: BeginAsync → work → CommitAsync (catch → RollbackAsync).

Controller ({Feature}Controller.cs)

Thin — maps HTTP → service call → returns result. No logic, no UoW calls.

---

Step 6 — Endpoints

Region — /api/regions

Method	Route	Description
GET	/	Get all active regions
GET	/{id}	Get region by id
POST	/	Create region
PUT	/{id}	Update region
DELETE	/{id}	Soft delete (set IsActive = false)

Route — /api/routes

Method	Route	Description
GET	/	Get all active routes
GET	/{id}	Get route by id
POST	/	Create route
PUT	/{id}	Update route
DELETE	/{id}	Soft delete

Vehicle — /api/vehicles

Method	Route	Description
GET	/	Get all active vehicles
GET	/{id}	Get vehicle by id
POST	/	Create vehicle
PUT	/{id}	Update vehicle
DELETE	/{id}	Soft delete

Store — /api/stores

Method	Route	Description
GET	/	Get all active stores
GET	/{id}	Get store by id
POST	/	Create store
PUT	/{id}	Update store
DELETE	/{id}	Soft delete

Warehouse — /api/warehouses

Method	Route	Description
GET	/	Get all active warehouses
GET	/{id}	Get warehouse by id
POST	/	Create warehouse
PUT	/{id}	Update warehouse
DELETE	/{id}	Soft delete

Order — /api/orders

Method	Route	Description
GET	/	Get all active orders
GET	/{id}	Get order with items
GET	/store/{storeId}	Get orders by store
POST	/	Create order with items
PUT	/{id}	Update order
DELETE	/{id}	Soft delete

---

Step 7 — DI Registration (Program.cs)

Register all feature repositories and services:

// Generic base
builder.Services.AddScoped(typeof(IGenericRepo<>), typeof(GenericRepo<>));

// Feature repositories
builder.Services.AddScoped<IRegionRepository, RegionRepository>();
builder.Services.AddScoped<IRouteRepository, RouteRepository>();
builder.Services.AddScoped<IVehicleRepository, VehicleRepository>();
builder.Services.AddScoped<IStoreRepository, StoreRepository>();
builder.Services.AddScoped<IWarehouseRepository, WarehouseRepository>();
builder.Services.AddScoped<IOrderRepository, OrderRepository>();

// Feature services
builder.Services.AddScoped<RegionService>();
builder.Services.AddScoped<RouteService>();
builder.Services.AddScoped<VehicleService>();
builder.Services.AddScoped<StoreService>();
builder.Services.AddScoped<WarehouseService>();
builder.Services.AddScoped<OrderService>();

---

Deferred

Item	Reason
SaleRoute	Shape undefined — implement after clarification
Item model	Sourced from ERP Core — user handles integration
DeliveryRun	Not in scope for this phase
Driver FK on DeliveryRun	Commented out — depends on HR/Driver module
Tests	No test project yet — add after endpoints stabilize