# ERP Distribution — Master Plan

## What Already Exists

| Area | Status | Notes |
|---|---|---|
| JWT Authentication | Done | Token generation, claims, 120-min expiry |
| Permission-based Authorization | Done | Dynamic policy provider, role → permission mapping |
| User Management | Done | CRUD, role assignment, scope assignment (region/route/store) |
| Role Management | Done (read-only) | 6 roles seeded, no create/update via API |
| Region / Route / Vehicle CRUD | Done | Full API surface with permission checks |
| Store / Warehouse CRUD | Done | Full API surface with permission checks |
| Order CRUD | Done | Scope-aware (user only sees their assigned stores) |
| Unit of Work + Repositories | Done | Transaction support throughout |
| Soft Deletes | Done | IsActive pattern on all entities |

## Known Gaps in Existing System (Pre-Work)

These are not new features — they are fixable holes in what's already built.
They must be resolved before new feature steps begin because later steps depend on correct foundations.

| Gap | Impact |
|---|---|
| Route DTOs missing RegionId | Can't link routes to regions via API |
| Store DTOs missing RouteId | Can't link stores to routes via API |
| Role endpoints have no [Authorize] | Anyone can read roles without authentication |
| JWT key & DB credentials in appsettings.json | Security risk in any shared/production environment |
| No input validation on any DTO | Bad data can enter the system silently |
| Item model is empty (no properties) | OrderItems reference items that have no data |

---

## Feature Steps

| # | Feature | Status | Depends On | Detail File |
|---|---|---|---|---|
| 00 | Existing Gap Fixes | Done | — | [00_existing_gaps.md](./00_existing_gaps.md) |
| 01 | Item Catalog | Done | 00 | [01_item_catalog.md](./01_item_catalog.md) |
| 02 | Stock Ledger | Not Started | 01 | [02_stock_ledger.md](./02_stock_ledger.md) |
| 03 | Ride Lifecycle | Not Started | 02 | [03_ride_lifecycle.md](./03_ride_lifecycle.md) |
| 04 | Loading Event | Not Started | 03 | [04_loading_event.md](./04_loading_event.md) |
| 05 | Delivery Ride Execution | Not Started | 04 | [05_delivery_ride.md](./05_delivery_ride.md) |
| 06 | Sale Ride Execution | Not Started | 04 | [06_sale_ride.md](./06_sale_ride.md) |
| 07 | Ride Close & Reconciliation | Not Started | 05, 06 | [07_ride_reconciliation.md](./07_ride_reconciliation.md) |
| 08 | Sales Agent Controls | Not Started | 07 | [08_sales_agent_controls.md](./08_sales_agent_controls.md) |
| 09 | Fraud Controls & Audit Trail | Not Started | 08 | [09_fraud_controls.md](./09_fraud_controls.md) |

---

## Feature Summaries

### 00 — Existing Gap Fixes
Fix all known holes in the current codebase before new features are layered on top.
Includes DTO field gaps, missing authorization on role endpoints, secrets management,
and adding input validation across all existing endpoints.
**Gate**: All existing API endpoints behave correctly and securely before step 01 begins.

### 01 — Item Catalog
Define the Item entity with real properties (name, SKU, unit of measure, category, price tiers).
Items are the unit of stock — nothing in the stock ledger makes sense without them.
This step also covers the Item CRUD API and how items relate to orders.
**Gate**: An item can be created, updated, and referenced in an order with quantity and price.

### 02 — Stock Ledger
Introduce the concept of stock per location. Every warehouse (fixed or vehicle) holds a quantity
of each item. Stock is never edited directly — all changes happen through movement transactions
(load, sale, return, damage, adjustment). The current balance is always the running sum.
This is the single most important architectural decision for the whole system.
**Gate**: Stock balance for any item at any location can be queried. Every change is a traceable transaction.

### 03 — Ride Lifecycle
A ride is a session that turns a vehicle into a temporary warehouse. It has a state machine:
Draft → Open → Active → Closed. A vehicle can only be on one active ride at a time.
Two ride types exist: Delivery (pre-orders) and Sale (van sales). The ride tracks who is driving,
which route, which vehicle, and when it started and ended.
**Gate**: A ride can be created, opened, and closed. A vehicle's stock ledger is created when a ride opens.

### 04 — Loading Event
When a ride opens, stock must be physically loaded from a source warehouse onto the vehicle.
This is a two-party event: warehouse manager confirms what was dispatched, driver confirms what was received.
Discrepancies between the two are flagged immediately and require resolution before the ride goes active.
The loading event creates stock movement transactions that debit the warehouse and credit the vehicle.
**Gate**: Stock moves from warehouse to vehicle via a confirmed loading event. Any discrepancy is logged.

### 05 — Delivery Ride Execution
On a delivery ride, the driver fulfills pre-confirmed orders. Each order becomes a delivery task.
The driver marks each as delivered, partially delivered, or failed. Partially delivered orders
generate a credit note for the undelivered quantity. Customer confirmation (signature or OTP)
is required to mark a delivery complete. Stock movements are created per delivery event.
**Gate**: A delivery ride can execute all orders on its route and produce a delivery report.

### 06 — Sale Ride Execution
On a sale ride, the driver visits customers and creates invoices on the spot. No pre-orders exist.
The driver selects items, quantities, and prices (within approved discount limits), and the invoice
is generated immediately. Payment is collected (cash or credit) at the point of sale.
The vehicle's stock ledger decreases with each sale. The driver cannot sell more than what is loaded.
**Gate**: A sale ride can generate invoices in the field. Stock on vehicle decreases with each sale.

### 07 — Ride Close & Reconciliation
When a ride ends, the system performs a full reconciliation. The equation must balance:
  Opening Stock − Sales − Damages + Returns = Closing Stock (physical count)
  Cash Collected + Credit Extended = Total Sales − Returns
Any variance must be approved by a supervisor with a reason code before the ride can close.
Unresolved variances are logged as discrepancies against the agent's record.
**Gate**: A ride cannot close with an unexplained variance. All discrepancies are permanently recorded.

### 08 — Sales Agent Controls
Agents operate within boundaries set by their role level. This step wires role levels to business rules:
discount limits per agent level, credit limits per customer, maximum single-transaction value,
and approval chains for exceptions. Supervisors can grant one-time overrides logged against their account.
**Gate**: An agent cannot exceed their limits without a logged, authorized override.

### 09 — Fraud Controls & Audit Trail
A dedicated audit log records every sensitive event (who, what, when, from where).
Automated checks flag: returns without a matching prior sale, sales outside the geofenced route,
agents with consistently high variance rates, and cash collected below invoiced amounts.
Return approval requires supervisor sign-off before stock is credited. Anomaly reports are
surfaced to area managers on a scheduled basis.
**Gate**: Every sensitive event is logged immutably. Automated flags surface to the right level of management.

---

## Rules

1. A feature file must be filled in and reviewed before implementation begins on that step.
2. Status must be updated in this file whenever a step transitions.
3. If implementation reveals a design change, the feature file is updated and this plan is revised.
4. Steps must be done in dependency order — no skipping.