Distribution/docs/refactor_docs/dispatch_pipeline.md

@@ -133,7 +133,7 @@ See [loading_event.md](./loading_event.md) for the full state machine.
 
 ## Stage 6 — Invoice Finalized
 
-**Trigger**: `POST /api/invoices/{id}/complete`
+**Trigger**: `POST /api/invoices/{id}/finalize`
 
 After the ride or day-end, the agent returns the printed invoice to the office. The office worker
 enters any edits the agent made into the system and submits.
@@ -146,44 +146,6 @@ enters any edits the agent made into the system and submits.
 
 ---
 
-## Stage 3 — Loading Sheet Population
-
-A dispatcher manually triggers population via `POST /api/loading-sheets/populate` with one or more
-filters. The system finds all matching Confirmed POs and aggregates them into **one loading sheet**.
-
-**Filters (at least one required):**
-- `routeId` — all Confirmed POs for shops on this route
-- `agentId` — all Confirmed POs created by this agent
-- `shopId` — all Confirmed POs for this specific shop
-
-**What happens:**
-1. System finds all `Order` records matching the filter where `Invoice.Status = Draft`
-2. One `LoadingSheet` created at `Planned` status
-3. `LoadingSheetItem` rows populated from the active `OrderItem` lines of those POs
-4. Each source PO recorded in `LoadingSheetOrder` linking table
-5. Each item carries `FK_OrderItemId` pointing back to its source `OrderItem`
-
-**After population — editing:**
-- Dispatcher can edit item quantities while the sheet is `Planned` or `Assigned`
-- Every edit soft-deletes all current `LoadingSheetItem` rows (`IsActive = false`) and writes a
-  fresh set — same versioning mechanism as Shop PO items
-- Active rows (`IsActive = true`) = latest version; soft-deleted = history
-
-**Confirmation and stock movement:**
-- Dispatcher assigns a ride + source warehouse (`Planned → Assigned`)
-- Dispatcher confirms the sheet (`Assigned → Confirmed`) — items frozen
-- Stock movement timing is an open question — see [loading_event.md](./loading_event.md) Open Question 1
-
-See [loading_event.md](./loading_event.md) for the full loading sheet state machine and dispatch/receipt flow.
-
----
-
-## Stage 4+ — Delivery and Invoice Finalization
-
-**Status**: TBD — to be designed in a subsequent pass.
-
----
-
 ## Open Questions
 
 1. **Who can confirm a Shop PO?** — the creating sales agent, a supervisor, or either?

Distribution/docs/refactor_docs/invoice_collection.md

@@ -0,0 +1,224 @@
+# [Refactor] Invoice Collection — Cash/Cheque/Credit Collection After Finalize
+
+**Status**: Proposed (design only — no code changes yet)
+**Depends On**: [order_invoice_lifecycle.md](./order_invoice_lifecycle.md) — this document only applies
+once an `Invoice` reaches `Finalized`; it does not touch Pending/Draft.
+**Refactors**: `Models/Payment.cs`, `Models/Enums.cs` (`PaymentMethod`, `PaymentStatus`),
+`Sale.PaymentStatus`, and the payment recording flow in
+[06_sale_ride.md](../06_sale_ride.md) (`POST /api/sales/{saleId}/payments`). Also resolves
+[19_finance_accounting.md](../19_finance_accounting.md)'s open question of whether field and
+warehouse invoices share one `Payment` shape, and [order_invoice_lifecycle.md](./order_invoice_lifecycle.md)'s
+Impact item 2 / Open Question 4 ("how does `Payment` attach once `Invoice` exists?").
+
+---
+
+## Goal
+
+Once an `Invoice` is `Finalized` (locked amount — see `order_invoice_lifecycle.md`), someone still has
+to physically collect that money from the shop and get it recorded. Today `Payment` attaches to
+`Sale` and only distinguishes `Cash`/`Credit` (`Models/Payment.cs`, `Models/Enums.cs:28`). This
+document re-points `Payment` at `Invoice` (the real billing document, not the Sale), adds `Cheque` as
+a method, and — the core problem this document solves — accounts for the fact that the money doesn't
+always arrive in one clean, connected transaction:
+
+- **Real-time**: whoever is at the shop (the same rep, a dedicated collector, or anyone authorized —
+  no role restriction) enters the collection on the spot as it happens, one method per entry.
+- **Day-end / offline**: when there's no real-time connectivity or no live tracking at the point of
+  collection, office staff enter the same details after the fact, at day-end, from whatever
+  paper/verbal record the field brought back.
+
+Both paths produce the exact same `Payment` row shape — `EntryMode` only records *how* it was
+captured, it does not change what's captured or how it's totaled.
+
+---
+
+## Background / Context
+
+- `order_invoice_lifecycle.md` deliberately left `Invoice.TotalAmount` as "the amount the shop
+  actually received and paid" once `Finalized`, but designed no collection/payment mechanism against
+  it — it only flagged the gap (Impact item 2, Open Question 4).
+- `19_finance_accounting.md` independently sketched a `Payment` (`InvoiceId`, `Amount`, `Method`,
+  `CollectedAt`) and asked whether it should unify with the existing `Sale`-attached `Payment` from
+  `06_sale_ride.md`. This document answers that: yes, one `Payment` table, moved to key off
+  `Invoice`, not `Sale`.
+- Any *reduction* in the amount owed (returns, damage, short-delivery, discounts) is **not** a new
+  concept introduced here — it is the same deduction mechanism already described at Finalize time in
+  `order_invoice_lifecycle.md`, reusing the `CreditNote` shape from
+  [18_returns_claims.md](../18_returns_claims.md). By the time a `Payment` is recorded, `Invoice.TotalAmount`
+  already reflects every reduction — collection only ever records money actually received against
+  that already-net amount. This document does not add a second reduction path.
+- A single `Payment` uses exactly one `Method` — a shop paying part cash and part cheque on the same
+  visit is recorded as two `Payment` rows, not one row with a split. Multiple `Payment` rows against
+  the same `Invoice` over time are expected and normal (e.g. partial cash today, the remainder by
+  cheque next week, or the balance written off to credit) — collection is not a single lump action.
+
+---
+
+## Data Model Changes
+
+### `Payment` — re-pointed from `Sale` to `Invoice`
+
+```
+Payment
+├── Id (Guid)                  — PK, from Template
+├── FK_InvoiceId (Guid)        — required. WAS FK_SaleId — see Migration Notes for the cutover.
+│                                 Invoice replaces Sale as the thing being paid down, per
+│                                 order_invoice_lifecycle.md.
+├── FK_StoreId (Guid)          — unchanged, still denormalized for reporting/scope filtering
+├── Amount (decimal)           — unchanged
+├── Method (PaymentMethod)     — Cash, Cheque, Credit (Cheque is new — see below)
+├── EntryMode (EntryMode)      — NEW: RealTime, DayEndManual (see below)
+├── CollectedAt (DateTime)     — unchanged: when the money actually changed hands at the shop, not
+│                                 when the row was saved (see EntryMode below for why these differ)
+├── CollectedBy (Guid)         — unchanged: UserId of whoever collected it. No role constraint — can
+│                                 be the rep, a dedicated collector, or office staff entering on
+│                                 someone else's behalf at day-end.
+├── RecordedBy (Guid?)         — NEW, nullable. Only set when EntryMode = DayEndManual and the person
+│                                 keying it in is not the same person who physically collected it
+│                                 (CollectedBy). Null under RealTime, where the collector is the one
+│                                 entering it.
+├── ChequeNumber (string?)     — NEW, only meaningful when Method = Cheque
+├── ChequeDate (DateTime?)     — NEW, only meaningful when Method = Cheque (the date on the cheque,
+│                                 not CollectedAt)
+├── IsActive, CreatedAt        — from Template
+```
+
+### `PaymentMethod` — add `Cheque`
+
+```csharp
+public enum PaymentMethod { Cash, Cheque, Credit }
+```
+
+`Credit` records that the shop was not charged now — the amount is carried as store debt (see
+`Store.OutstandingBalance`, `19_finance_accounting.md`) rather than settled; no money moves.
+
+### New Enum — `EntryMode`
+
+```csharp
+public enum EntryMode { RealTime, DayEndManual }
+```
+
+Purely a provenance flag on how the row was captured — it does not affect totaling, `PaymentStatus`
+computation, or any business rule below. It exists so a day-end reconciliation view can distinguish
+"confirmed live at the shop" from "keyed in later from a paper/verbal record," which matters for
+audit and for spotting collectors who never enter anything in real time.
+
+### `Invoice.PaymentStatus` (new field on `Invoice`, from `order_invoice_lifecycle.md`)
+
+```
+Invoice
+├── ... (existing fields from order_invoice_lifecycle.md: Status, ConfirmedAt, FinalizedAt, ...)
+├── PaymentStatus (PaymentStatus)  — NEW: Pending, PartiallyPaid, Paid — mirrors the existing
+│                                     Sale.PaymentStatus pattern from 06_sale_ride.md, recomputed on
+│                                     every Payment insert (see Business Rules)
+```
+
+This is a deliberate second axis alongside `Invoice.Status` (`Pending/Draft/Finalized`, the document
+lifecycle) — `PaymentStatus` only starts being meaningful once `Status = Finalized`, and answers
+`order_invoice_lifecycle.md`'s Open Question 3 (whether the two axes should merge): they stay
+separate. `PaymentStatus` is the same axis `19_finance_accounting.md` proposed baking into
+`Invoice.Status` (`Issued/PartiallyPaid/Paid`) — this document keeps it as its own field instead of
+folding it into `Invoice.Status`, so `Invoice.Status` stays purely about the PO→Invoice document
+pipeline.
+
+`Sale.PaymentStatus` (`06_sale_ride.md`) is superseded by `Invoice.PaymentStatus` for any Sale that
+has a linked Order/Invoice — see Impact section.
+
+---
+
+## Business Rules
+
+1. A `Payment` can only be recorded against an `Invoice` whose `Status = Finalized` — matches
+   `order_invoice_lifecycle.md`'s framing that Finalize is "the record used for day-end calculations."
+   Attempting to record a `Payment` against a Pending/Draft invoice is rejected (409).
+2. Multiple `Payment` rows are allowed per `Invoice` — collection is not required to happen in a
+   single action. Each row has exactly one `Method`; a mixed cash+cheque collection on one visit is
+   two rows with the same `CollectedAt`/visit context, not one split row.
+3. On every `Payment` insert, sum all `Payment.Amount` for the `Invoice` and recompute
+   `Invoice.PaymentStatus` in the same transaction — identical logic to the existing
+   `Sale.PaymentStatus` computation in `06_sale_ride.md`:
+   - `sum == 0` → `Pending`
+   - `sum < Invoice.TotalAmount` → `PartiallyPaid`
+   - `sum >= Invoice.TotalAmount` → `Paid`
+4. Overpayment is allowed (`sum > Invoice.TotalAmount`), same as the existing Sale-level rule —
+   `PaymentStatus` stays `Paid`. No refund/credit-back mechanism is designed here.
+5. `Method = Credit` still inserts a `Payment` row (so it's part of the same total and audit trail)
+   but represents no money movement — it exists so the collector/office can record "this portion
+   isn't being collected now, it's going on the shop's account" in the same flow as an actual cash or
+   cheque collection, rather than needing a separate mechanism.
+6. `ChequeNumber`/`ChequeDate` are required when `Method = Cheque`, ignored (nullable, left unset) for
+   `Cash`/`Credit`.
+7. `EntryMode` does not gate or delay anything — a `RealTime` and a `DayEndManual` `Payment` are
+   processed identically once submitted; the only difference is which field is populated
+   (`RecordedBy` vs. not) and what the UI shows for provenance.
+8. `RecordedBy` is only set when `EntryMode = DayEndManual` and the person entering the row is not
+   `CollectedBy` (e.g. office staff transcribing a rep's paper collection sheet at day-end). If the
+   same person both collected and enters it, `RecordedBy` is left null even under `DayEndManual`.
+9. No reduction/deduction is recorded on `Payment` itself — any amount not being collected in full is
+   either already netted into `Invoice.TotalAmount` via the Finalize-time deduction (returns/damage/
+   discount, per `order_invoice_lifecycle.md`) or is recorded as `Method = Credit` (rule 5) for the
+   uncollected remainder. There is no third path.
+
+---
+
+## Impact on Dependent Features
+
+1. **`06_sale_ride.md`'s `POST /api/sales/{saleId}/payments`** — this endpoint and
+   `Sale.PaymentStatus` become the field-sale-specific legacy path. Once a Sale has a linked
+   Order/Invoice (per `order_invoice_lifecycle.md`), payments should go through
+   `POST /api/invoices/{id}/payments` instead and `Sale.PaymentStatus` stops being authoritative.
+   Whether `Sale.PaymentStatus` is removed outright or kept in sync (mirrored from
+   `Invoice.PaymentStatus`) for backward compatibility is not decided here — see Open Questions.
+2. **`Store.OutstandingBalance`** (`12_store_management.md`, referenced in `19_finance_accounting.md`)
+   — needs to account for `Method = Credit` payments (rule 5) increasing the balance, same as it
+   already should for any unpaid `Invoice.TotalAmount` minus `PaymentStatus`-tracked collections. Not
+   redesigned here, just flagged as touched.
+3. **`19_finance_accounting.md`'s GL posting** (`postToGeneralLedger`) should trigger off `Payment`
+   insert events the same way it already anticipates triggering off invoice/payment/credit-note
+   events — no new trigger type, just confirms `Payment` (now Invoice-keyed) is the event source.
+4. **Existing `Payment` rows** (keyed by `FK_SaleId` today) need a migration path once `Order`/
+   `Invoice` exist for the sales they belong to — see Migration Notes.
+
+---
+
+## Open Questions
+
+1. **Does `Sale.PaymentStatus` get removed, or mirrored?** — see Impact item 1. Not decided here;
+   removing it outright is cleaner but touches whatever UI/reporting still reads it directly.
+2. **Multi-visit collection reminders/scheduling** — this document only covers *recording* a
+   collection, not scheduling or reminding a collector to go back for the remainder of a
+   `PartiallyPaid` invoice. Out of scope here.
+3. **Cheque bounce / dishonor handling** — a `Cheque` `Payment` is recorded as collected the moment
+   it's received; there's no designed path for reversing a `Payment` (and its effect on
+   `Invoice.PaymentStatus`) if the cheque later bounces. Flagged as a gap, not solved.
+4. **Does `EntryMode = DayEndManual` need a batch/reconciliation view** (e.g. "these 12 collections
+   were keyed in for yesterday's rides") rather than being entered one `Payment` at a time through the
+   same endpoint as real-time? Not designed here — this document only specifies the data shape and
+   business rules, not the day-end UI workflow.
+5. **Should a `Payment` be linkable to a specific `Ride`/visit** (beyond `CollectedAt`/`CollectedBy`),
+   so a day-end reconciliation can group collections by the ride that generated them? Not modeled
+   here — `Payment` only links to `Invoice` and `Store`.
+
+---
+
+## Migration Notes (for when this is implemented)
+
+Not part of this docs-only pass, but captured for the eventual implementation step:
+
+- Add `Cheque` to `PaymentMethod` (`Models/Enums.cs:28`); add `EntryMode` enum (`RealTime`,
+  `DayEndManual`).
+- Add `FK_InvoiceId`, `EntryMode`, `RecordedBy`, `ChequeNumber`, `ChequeDate` to `Models/Payment.cs`.
+- `FK_SaleId` on `Payment` is superseded by `FK_InvoiceId` — do not drop it immediately; keep it
+  nullable through a transition period so existing field-sale payments (which predate any
+  Order/Invoice) aren't orphaned, and backfill `FK_InvoiceId` where a Sale's Order has a linked
+  Invoice. Full removal of `FK_SaleId` is a follow-up once backfill is verified complete.
+- Add `PaymentStatus` to `Models/Invoice.cs` (from `order_invoice_lifecycle.md`'s new `Invoice`
+  entity), defaulting to `Pending`.
+- New `POST /api/invoices/{id}/payments` endpoint (`Features/Payment/`, extending the existing
+  feature rather than duplicating it) — validates `Invoice.Status == Finalized`, inserts `Payment`,
+  recomputes `Invoice.PaymentStatus` in the same transaction as the existing
+  `POST /api/sales/{saleId}/payments` logic in `06_sale_ride.md`.
+- `GET /api/invoices/{id}/payments` — list collections against an invoice (needed for both the
+  real-time collector view and the day-end reconciliation view).
+- Resolve Open Question 1 (Sale.PaymentStatus fate) before removing or repointing the existing
+  `POST /api/sales/{saleId}/payments` endpoint.

Distribution/docs/refactor_docs/loading_event.md

@@ -1,41 +1,36 @@
-# [Refactor] Loading Event — PO-Generated, Route-Free, No Ride Activation
+# [Refactor] Loading Event — Dispatcher-Populated, Multi-PO, Multi-Warehouse
 
 **Status**: Proposed (design only — no code changes yet)
 **Refactors**: [../04_loading_event.md](../04_loading_event.md) (kept as-is, this is the target design)
-**Depends On**: [ride_lifecycle.md](./ride_lifecycle.md), [order_invoice_lifecycle.md](./order_invoice_lifecycle.md)
+**Depends On**: [ride_lifecycle.md](./ride_lifecycle.md), [order_invoice_lifecycle.md](./order_invoice_lifecycle.md), [dispatch_pipeline.md](./dispatch_pipeline.md)
 
 ---
 
 ## Goal
 
-Bring `04_loading_event.md` in line with the other two refactors:
+Replace the previous loading event design with a dispatcher-driven, multi-PO model:
 
-1. **No more `Open -> Active`.** [ride_lifecycle.md](./ride_lifecycle.md) collapses `Ride.Status` to
-   `Open`/`Cancelled`/`Closed` — there is no `Active` stage left to auto-trigger. Confirming a
-   loading event no longer changes `Ride.Status` at all; the ride simply stays `Open` through
-   loading, delivery, and everything else, until it's explicitly `Closed` or `Cancelled`.
-   `LoadingSheet.Status` tracks loading progress entirely on its own.
-2. **No more Route or `RideType`-based item population.** `04_loading_event.md`'s "Delivery rides
-   auto-populate from the ride's route" no longer applies — `Ride` no longer carries a route
-   ([ride_lifecycle.md](./ride_lifecycle.md)) and no longer distinguishes Delivery/Sale. Instead, per
-   [order_invoice_lifecycle.md](./order_invoice_lifecycle.md), a `LoadingSheet` is generated
-   automatically from a single PO's items the moment that PO is confirmed (`Invoice` Pending →
-   Draft) — before any ride exists.
-3. **A `LoadingSheet` now starts ride-less.** It's created PO-scoped
-   (`FK_OrderId`), not ride-scoped, and gets attached to an actual `Ride` + source warehouse later,
-   via a new explicit action, once a vehicle/trip is planned for it. The rest of the
-   dispatch/receipt/discrepancy workflow is unchanged in shape — it just now runs per PO-generated
-   sheet instead of per ride-created sheet.
+1. **No more auto-creation.** Loading sheets are no longer generated automatically when a PO is
+   confirmed. A dispatcher manually triggers population.
+2. **No more `Open → Active`.** `Ride.Status` collapses to `Open`/`Cancelled`/`Closed` — no
+   `Active` stage. Loading sheet confirmation no longer changes `Ride.Status` at all.
+3. **One sheet aggregates multiple POs.** A single loading sheet is created from all Confirmed POs
+   matching a dispatcher's filter (route/agent/shop). No longer one sheet per PO.
+4. **Ride set at populate time.** The ride is provided when the dispatcher triggers population —
+   no separate assign-ride step.
+5. **Warehouse is per item, not per sheet.** Different items on the same loading sheet can be
+   loaded from different warehouses. Stock movements are generated per item's warehouse.
+6. **Item versioning.** Loading sheet items are versioned the same way as Shop PO items — every
+   edit soft-deletes current rows (`IsActive = false`) and writes a fresh set.
 
 ---
 
 ## Background / Context
 
 Same physical mechanics as `04_loading_event.md`: a vehicle is a location with
-`LocationType.Vehicle` in the stock ledger, and confirming receipt (or resolving a discrepancy)
-creates the same two stock movements per item — debit source warehouse, credit vehicle. None of that
-changes here. What changes is *when a `LoadingSheet` comes into existence* and *what it takes to
-start the dispatch/receipt workflow on it*.
+`LocationType.Vehicle` in the stock ledger. Confirming receipt (or resolving a discrepancy)
+creates stock movements — debit source warehouse(s), credit vehicle. What changes is *when and how
+a `LoadingSheet` comes into existence*, *which POs it covers*, and *how warehouse selection works*.
 
 ---
 
@@ -46,80 +41,122 @@ start the dispatch/receipt workflow on it*.
 | Column | Type | Notes |
 |---|---|---|
 | Id | Guid | PK |
-| **`FK_OrderId`** | Guid | **New, required.** FK → `Order` (PO). Set at creation; never changes. |
-| **`FK_RideId`** | Guid? | **Now nullable.** Null while `Planned`; set by the new assign-ride action. |
-| **`FK_SourceWarehouseId`** | Guid? | **Now nullable**, for the same reason — set together with `FK_RideId` at assign time, not at creation. |
-| Status | LoadingSheetStatus | State machine below — gains a `Planned`/`Assigned` prefix. |
-| **`AssignedAt`** | DateTime? | **New.** Set when a Ride + source warehouse are assigned. |
-| **`AssignedBy`** | Guid? | **New.** UserId of whoever assigned the ride. |
-| DispatchConfirmedAt | DateTime? | Unchanged — set when warehouse confirms dispatch. |
-| DispatchConfirmedBy | Guid? | Unchanged. |
-| ReceiptConfirmedAt | DateTime? | Unchanged — set when driver confirms receipt. |
-| ReceiptConfirmedBy | Guid? | Unchanged. |
-| CreatedAt | DateTime | Unchanged. |
+| ~~`FK_OrderId`~~ | — | **Removed.** One sheet now aggregates multiple POs — replaced by `LoadingSheetOrder` linking table. |
+| **`FK_RideId`** | Guid | **Required. Set at population time** — dispatcher provides the ride when triggering populate. |
+| ~~`FK_SourceWarehouseId`~~ | — | **Removed.** Warehouse is tracked per item, not per sheet — a single sheet can be fulfilled from multiple warehouses. |
+| Status | LoadingSheetStatus | See state machine below. |
+| **`PopulatedBy`** | Guid | **New.** UserId of dispatcher who triggered population. |
+| **`PopulatedAt`** | DateTime | **New.** When population was triggered. |
+| ~~`AssignedAt`~~ | — | **Removed.** No separate assign step. |
+| ~~`AssignedBy`~~ | — | **Removed.** Same reason. |
+| ConfirmedAt | DateTime? | Set when loading sheet is confirmed (items locked). |
+| ConfirmedBy | Guid? | UserId of whoever confirmed the sheet. |
+| DispatchConfirmedAt | DateTime? | Path B only — see Open Questions. |
+| DispatchConfirmedBy | Guid? | Path B only. |
+| ReceiptConfirmedAt | DateTime? | Path B only. |
+| ReceiptConfirmedBy | Guid? | Path B only. |
+| CreatedAt | DateTime | From Template. |
 
-`LoadingSheetItem` is **unchanged** (`FK_ItemId`, `QuantityDispatched`, `QuantityReceived`,
-`QuantityResolved`) — still populated the same way, just from a different source (see
-[Item Population](#item-population) below).
+### New Entity — `LoadingSheetOrder` (linking table)
+
+One loading sheet aggregates multiple Confirmed POs. This table records which POs were included.
+
+| Column | Type | Notes |
+|---|---|---|
+| FK_LoadingSheetId | Guid | FK → LoadingSheet |
+| FK_OrderId | Guid | FK → Order (must be a Confirmed PO at population time) |
+
+### Updated Entity — `LoadingSheetItem`
+
+| Column | Type | Notes |
+|---|---|---|
+| Id | Guid | PK |
+| FK_LoadingSheetId | Guid | FK → LoadingSheet |
+| **`FK_WarehouseId`** | Guid | **New. Required.** The warehouse this specific item is loaded from. Different items on the same sheet can come from different warehouses. Set by dispatcher when editing items. |
+| **`FK_OrderItemId`** | Guid? | **New.** Traces back to the source `OrderItem` from the Confirmed PO. Null for manually added lines. |
+| FK_ItemId | Guid | FK → Item (product) |
+| QuantityDispatched | decimal | Quantity to load from `FK_WarehouseId` |
+| QuantityReceived | decimal? | Driver's received qty (Path B only) |
+| QuantityResolved | decimal? | Supervisor's resolved qty after discrepancy (Path B only) |
+| **`IsActive`** | bool | **Versioning.** Every edit soft-deletes current items (`IsActive = false`) and writes a fresh set. Active items = latest version; soft-deleted = history. |
+| CreatedAt | DateTime | From Template |
 
 ### Updated Enum — `LoadingSheetStatus`
 
 ```csharp
 public enum LoadingSheetStatus
 {
-    Planned,             // new: created from a confirmed PO, no ride yet
-    Assigned,            // new: ride + source warehouse attached, ready to dispatch
-    DispatchConfirmed,
-    ReceiptConfirmed,
-    DiscrepancyFlagged,
-    Resolved
+    Planned,             // populated by dispatcher (ride set, items editable/versioned)
+    Confirmed,           // items locked — stock movement path TBD (see Open Questions)
+    DispatchConfirmed,   // Path B only: warehouse confirms dispatch
+    ReceiptConfirmed,    // Path B only: driver confirms receipt, stock moves
+    DiscrepancyFlagged,  // Path B only: received qty mismatch
+    Resolved             // Path B only: supervisor resolves discrepancy, stock moves
 }
 ```
 
-`Pending` from `04_loading_event.md` is replaced by two states (`Planned`, `Assigned`) to make the
-new ride-less creation step explicit. `DispatchConfirmed`, `ReceiptConfirmed`,
-`DiscrepancyFlagged`, and `Resolved` keep their existing meaning and stock-movement behavior
-unchanged.
+`Pending` from `04_loading_event.md` is replaced by `Planned` and `Confirmed`. `Assigned` is
+removed — ride is set at populate time, no separate assign step.
 
 ---
 
 ## State Machine
 
 ```text
-Planned -> Assigned -> DispatchConfirmed -> ReceiptConfirmed
-                                       \-> DiscrepancyFlagged -> Resolved
+Planned -> Confirmed -> [Path A: stock moves here]
+                    \-> [Path B: DispatchConfirmed -> ReceiptConfirmed]
+                                                 \-> DiscrepancyFlagged -> Resolved
 ```
 
 | Transition | Trigger | What it does |
 |---|---|---|
-| (implicit) -> Planned | PO confirmed (`POST /api/orders/{id}/confirm`, per [order_invoice_lifecycle.md](./order_invoice_lifecycle.md)) | `LoadingSheet` is created automatically with `FK_OrderId` set, items populated from the PO's `OrderItem` lines. No ride, no warehouse yet. |
-| Planned -> Assigned | `POST /{id}/assign-ride` | Dispatcher attaches `FK_RideId` (must be an `Open` ride) and `FK_SourceWarehouseId`. Sets `AssignedAt`/`AssignedBy`. This is the new step that replaces `04_loading_event.md`'s ride-scoped sheet creation. |
-| Assigned -> DispatchConfirmed | `POST /{id}/confirm-dispatch` | Unchanged from `04_loading_event.md` — warehouse manager locks in `QuantityDispatched` per line. **Ride status is untouched** (no more `Open` requirement check beyond what assign-ride already validated). |
-| DispatchConfirmed -> ReceiptConfirmed | `POST /{id}/confirm-receipt` | Unchanged — driver's received quantities all match dispatched. Creates stock movements. **No longer triggers any ride transition** (there is no `Active` to trigger). |
-| DispatchConfirmed -> DiscrepancyFlagged | `POST /{id}/confirm-receipt` | Unchanged — any line mismatch. No stock movements created. |
-| DiscrepancyFlagged -> Resolved | `POST /{id}/resolve` | Unchanged mechanics — supervisor enters `QuantityResolved` per line, creates stock movements using resolved quantities. **No longer triggers any ride transition.** |
+| (create) → Planned | `POST /api/loading-sheets/populate` | Dispatcher provides `rideId` + filters. System finds all matching Confirmed POs, creates one `LoadingSheet` with `FK_RideId` set, populates `LoadingSheetItem` rows from active `OrderItem` lines, records PO links in `LoadingSheetOrder`. `PopulatedBy`/`PopulatedAt` set. Items editable (versioned via `IsActive`). Dispatcher sets `FK_WarehouseId` per item. |
+| Planned → Confirmed | `POST /{id}/confirm` | Locks the sheet — `LoadingSheetItem` rows frozen. Sets `ConfirmedAt`/`ConfirmedBy`. Stock movement path TBD (see Open Questions). |
+| Confirmed → DispatchConfirmed | `POST /{id}/confirm-dispatch` | **Path B only.** Warehouse manager confirms dispatch quantities. |
+| DispatchConfirmed → ReceiptConfirmed | `POST /{id}/confirm-receipt` | **Path B only.** Driver's received quantities all match. Stock movements created — one debit per `LoadingSheetItem.FK_WarehouseId`, one credit to the ride's vehicle. No ride status transition. |
+| DispatchConfirmed → DiscrepancyFlagged | `POST /{id}/confirm-receipt` | **Path B only.** Any line mismatch. No stock movements yet. |
+| DiscrepancyFlagged → Resolved | `POST /{id}/resolve` | **Path B only.** Supervisor enters `QuantityResolved` per line. Stock movements created using resolved quantities. |
 
 ---
 
 ## Item Population
 
-Replaces `04_loading_event.md`'s "Item Population by Ride Type" section — there is no more
-Delivery/Sale split:
+A dispatcher manually triggers population via `POST /api/loading-sheets/populate` providing:
 
-Every `LoadingSheet` is auto-populated on creation (at `Planned`) from the aggregate of its own
-PO's (`Order`) `OrderItem` lines — the same mechanism for every ride scenario, since
-[order_invoice_lifecycle.md](./order_invoice_lifecycle.md) generates one `LoadingSheet` per
-confirmed PO regardless of how that PO originated. `PUT /{id}/items` remains available to override
-quantities before dispatch is confirmed (through `Planned` and `Assigned`).
+| Input | Notes |
+|---|---|
+| `rideId` | **Required.** The ride this loading sheet is for. Must be an `Open` ride. |
+| `routeId` | Filter — all Confirmed POs for shops on this route |
+| `agentId` | Filter — all Confirmed POs created by this agent |
+| `shopId` | Filter — all Confirmed POs for this specific shop |
+
+At least one filter must be provided alongside `rideId`. The system finds all matching `Order`
+records where items are locked (Confirmed PO), aggregates their active `OrderItem` lines into one
+`LoadingSheet`, and records each PO in `LoadingSheetOrder`.
+
+`LoadingSheetItem.FK_OrderItemId` traces each line back to its source `OrderItem` for audit.
+
+After population, the dispatcher sets `FK_WarehouseId` on each item — specifying which warehouse
+that item is loaded from. Different items can come from different warehouses. Items are editable
+while `Planned` — every edit soft-deletes all current `LoadingSheetItem` rows (`IsActive = false`)
+and writes a fresh set. Latest version = `IsActive = true` rows.
 
 ---
 
 ## Stock Movements
 
-**Unchanged** from `04_loading_event.md`. Still created exactly once, at `ReceiptConfirmed` or
-`Resolved`, still one pair per line item (debit `FK_SourceWarehouseId`, credit the assigned ride's
-vehicle), still using `QuantityFinal` = `QuantityReceived` or `QuantityResolved`, still
-`Type = Load`.
+One stock movement pair per `LoadingSheetItem` (active rows only). Created exactly once.
+
+- **Debit**: `LoadingSheetItem.FK_WarehouseId` (the warehouse that item loads from)
+- **Credit**: the vehicle on the assigned ride (`LoadingSheet.FK_RideId → DeliveryRun.FK_VehicleId`)
+- **Type**: `Load`
+
+Since different items can have different `FK_WarehouseId` values, one loading sheet can produce
+stock movements from multiple warehouses into one vehicle.
+
+**When** movements are created depends on the path chosen (see Open Questions):
+- **Path A** — stock moves at `Confirmed`
+- **Path B** — stock moves at `ReceiptConfirmed` or `Resolved`
 
 ---
 
@@ -129,63 +166,37 @@ Base route: `/api/loading-sheets`
 
 | Method | Route | Who | Description |
 |---|---|---|---|
-| ~~POST `/`~~ | — | — | **Removed.** Sheets are no longer manually created — they're generated automatically when a PO is confirmed. |
-| GET | `/` | Any | List sheets. Filter by `orderId`, `rideId`, `status`. Paginated. |
-| GET | `/{id}` | Any | Get sheet detail with all line items. |
-| PUT | `/{id}/items` | Warehouse mgr | Set or override item quantities — allowed through `Planned` and `Assigned`. |
-| **POST `/{id}/assign-ride`** | **Dispatcher** | **New.** `{ rideId, sourceWarehouseId }`. Requires the ride to be `Open`. `Planned -> Assigned`. |
-| POST | `/{id}/confirm-dispatch` | Warehouse mgr | `Assigned -> DispatchConfirmed`. |
-| PUT | `/{id}/receipt-items` | Driver | Set `QuantityReceived` per line. Unchanged. |
-| POST | `/{id}/confirm-receipt` | Driver | `-> ReceiptConfirmed` or `DiscrepancyFlagged`. No ride-status side effect. |
-| POST | `/{id}/resolve` | Supervisor | Enter `QuantityResolved` per line `-> Resolved`. No ride-status side effect. |
+| POST | `/populate` | Dispatcher | Trigger population: `{ rideId, routeId?, agentId?, shopId? }` — `rideId` required, at least one filter required. Creates one `LoadingSheet` at `Planned` with `FK_RideId` set. |
+| GET | `/` | Any | List sheets. Filter by `routeId`, `agentId`, `shopId`, `rideId`, `status`. Paginated. `routeId` resolves via `Store.FK_RouteId → Order.FK_StoreId → LoadingSheetOrder.FK_OrderId` server-side. |
+| GET | `/{id}` | Any | Get sheet detail. Active items only by default; `?history=true` includes soft-deleted versions. |
+| PUT | `/{id}/items` | Dispatcher | Rewrite items while `Planned`. Each item must include `FK_WarehouseId`. Soft-deletes current rows (`IsActive = false`) and writes a fresh set. |
+| POST | `/{id}/confirm` | Dispatcher | Lock the sheet. `Planned → Confirmed`. Items frozen. |
+| POST | `/{id}/confirm-dispatch` | Warehouse mgr | **Path B only.** `Confirmed → DispatchConfirmed`. |
+| PUT | `/{id}/receipt-items` | Driver | **Path B only.** Set `QuantityReceived` per line. |
+| POST | `/{id}/confirm-receipt` | Driver | **Path B only.** `→ ReceiptConfirmed` or `DiscrepancyFlagged`. |
+| POST | `/{id}/resolve` | Supervisor | **Path B only.** Enter `QuantityResolved` per line `→ Resolved`. |
 
 ---
 
 ## Business Rules
 
-1. A `LoadingSheet` is created automatically, exactly once per PO, when that PO is confirmed — there
-   is no manual "create sheet" action and no `Open`-ride precondition at creation time (replaces
-   `04_loading_event.md` rule 1).
-2. **A ride may now have more than one `LoadingSheet` assigned to it** — one per PO whose sheet was
-   assigned there. `04_loading_event.md`'s "a ride can only have one active loading sheet at a time"
-   no longer holds, since a single ride/trip can carry stock for several stores' POs at once. Each
-   assigned sheet still progresses through dispatch/receipt/discrepancy independently.
-3. `assign-ride` requires the target ride to be `Open`; a `Cancelled` or `Closed` ride cannot receive
-   a new assignment.
-4. `QuantityDispatched != QuantityReceived` on any line -> `DiscrepancyFlagged`. No partial receipt
-   confirmation (unchanged from `04_loading_event.md`, minus the "activation" language since there's
-   no `Active` status anymore).
-5. Stock movements are created only once — at `ReceiptConfirmed` or `Resolved`. Never on dispatch or
-   on assignment. Unchanged.
-6. Discrepancies must be resolved per line item with an explicit `QuantityResolved` value. Unchanged.
-7. All list endpoints return paginated responses. Unchanged.
-8. Vehicle capacity check is still not enforced in this step. Unchanged.
-9. Loading confirmation and receipt no longer trigger any `Ride.Status` change — replaces
-   `04_loading_event.md` rules that referenced `Open -> Active`.
-
-`04_loading_event.md`'s rule 8 ("Immediate handover from a Sale ride still creates an order") is
-dropped along with `RideType` — every PO already creates its own `Invoice`/`LoadingSheet` uniformly,
-regardless of how quickly it moves through Pending → Draft → Finalized.
-
----
-
-## Impact on Dependent Features
-
-1. **`ride_lifecycle.md`'s Impact item 2** (loading sheet auto-population without a route) and
-   **`order_invoice_lifecycle.md`'s Impact item 6** are addressed by this document: population now
-   comes from the PO directly, and the ride-attachment gap (`order_invoice_lifecycle.md`'s
-   [Open Question 7](../refactor_docs/order_invoice_lifecycle.md#open-questions)) is resolved by the
-   new `Planned -> Assigned` step and `POST /{id}/assign-ride` endpoint.
-2. **Dispatcher role/permission is new** — `04_loading_event.md`'s permission table has no
-   "dispatcher" concept; `assign-ride` needs a new permission (see below), and who is authorized to
-   perform it (a route/trip planner role?) is not fully specified here.
-3. **Multiple sheets per ride** changes how a driver/warehouse experiences dispatch — instead of one
-   confirm-dispatch per ride, there may now be several, one per assigned PO. UI/UX and any
-   "ride loading summary" view built against the old one-sheet-per-ride assumption needs rework —
-   not designed here.
-4. **`order_invoice_lifecycle.md`'s Open Question 8** (does editing PO items post-confirm re-sync the
-   `LoadingSheet`?) is still open here too — this document doesn't resolve what happens to an
-   `Assigned` or later-stage sheet if its source PO's items change afterward.
+1. A `LoadingSheet` is created manually by a dispatcher — not automatically. `rideId` and at least
+   one PO filter (routeId, agentId, or shopId) are required.
+2. The ride (`FK_RideId`) is set at populate time — there is no separate assign-ride step.
+3. Only Confirmed POs (locked items) are included in population — Shop POs are excluded.
+4. One `LoadingSheet` aggregates all matching Confirmed POs — not one sheet per PO.
+5. A ride may have more than one `LoadingSheet` — each progresses independently.
+6. The target ride must be `Open` at populate time.
+7. Each `LoadingSheetItem` carries its own `FK_WarehouseId` — items on the same sheet can come
+   from different warehouses. There is no sheet-level source warehouse.
+8. Items are editable (versioned via `IsActive`) while `Planned` — frozen at `Confirmed`.
+9. Every item edit soft-deletes all current `LoadingSheetItem` rows (`IsActive = false`) and writes
+   a fresh set. Active rows = latest version; soft-deleted = history.
+10. Stock movements are created exactly once — one debit per item warehouse, one credit to the
+    vehicle. Timing depends on path chosen (see Open Questions).
+11. No `Ride.Status` transition is triggered at any point in this flow.
+12. All list endpoints return paginated responses.
+13. Vehicle capacity check is not enforced in this step.
 
 ---
 
@@ -194,57 +205,50 @@ regardless of how quickly it moves through Pending → Draft → Finalized.
 | Code | Who |
 |---|---|
 | `loading.view` | All roles |
-| **`loading.assign`** | **New.** Dispatcher and above |
-| `loading.dispatch` | Warehouse manager and above |
-| `loading.receive` | Driver |
-| `loading.resolve` | Supervisor and above |
+| **`loading.populate`** | **New.** Dispatcher — trigger population, edit items, confirm sheet |
+| `loading.dispatch` | Warehouse manager — Path B dispatch confirmation |
+| `loading.receive` | Driver — Path B receipt confirmation |
+| `loading.resolve` | Supervisor — Path B discrepancy resolution |
 
 ---
 
 ## Fraud / Control Considerations
 
-Unchanged from `04_loading_event.md`:
 - Discrepancies are immediately visible and block further progress.
 - `QuantityResolved` is permanently stored per line for audit purposes.
-
-Additionally: `AssignedAt`/`AssignedBy` gives an audit trail for who committed a planned PO load to
-a specific ride/vehicle, which didn't exist as a separate step before.
+- `PopulatedBy`/`PopulatedAt` gives an audit trail for who triggered population and when.
+- `FK_OrderItemId` on each item traces the exact source PO line for full audit.
 
 ---
 
 ## Open Questions
 
-1. **Who is authorized to assign a ride to a Planned sheet?** — a new "dispatcher" role/permission is
-   introduced (`loading.assign`) but not otherwise defined in this pass.
-2. **What happens to a `Planned` sheet if its PO is never assigned to a ride?** — no timeout, retry,
-   or cancellation path is designed here.
-3. **Does editing a PO's items after its sheet is `Planned`/`Assigned` re-sync the sheet?** — carried
-   over from `order_invoice_lifecycle.md`'s Open Question 8, still unresolved here.
-4. **Should multiple `Planned` sheets ever merge into one `Assigned` sheet** (e.g. one dispatch
-   covering several stores' POs on the same ride), rather than staying as separate per-PO sheets that
-   each go through their own dispatch/receipt cycle? Not designed here — this document keeps them as
-   independent per-PO sheets (see Business Rule 2).
-5. Vehicle capacity check — still deferred, unchanged from `04_loading_event.md`.
+1. **Path A vs Path B — when do stock movements happen?** Stock can move at `Confirmed` (Path A)
+   or at `ReceiptConfirmed`/`Resolved` (Path B). Both paths retained until decided.
+2. **Who confirms the loading sheet?** — the dispatcher who populated it, the warehouse manager,
+   or either?
+3. **What happens to a `Planned` sheet if it is never confirmed?** — no cancellation or timeout
+   path is designed here.
+4. Vehicle capacity check — still deferred.
 
 ---
 
 ## Migration Notes (for when this is implemented)
 
-Not part of this docs-only pass, but captured for the eventual implementation step:
-
-- Add `FK_OrderId` (required), `AssignedAt`, `AssignedBy` to `Models/LoadingSheet.cs`; make
-  `FK_RideId` and `FK_SourceWarehouseId` nullable.
-- Replace `LoadingSheetStatus.Pending` with `Planned` and `Assigned`; update all status checks in
-  `LoadingSheetService`/`LoadingSheetRepository` accordingly.
-- Remove `POST /api/loading-sheets` (manual create); wire automatic `LoadingSheet` creation into the
-  PO-confirm action from [order_invoice_lifecycle.md](./order_invoice_lifecycle.md)'s migration
-  notes.
-- Add `POST /{id}/assign-ride` endpoint/service method, validating the target ride's `Status == Open`
-  (per [ride_lifecycle.md](./ride_lifecycle.md)'s narrowed `RideStatus`).
-- Remove the `confirm-receipt`/`resolve` code paths' calls into ride-activation logic — there is no
-  `Ride.Status` transition to trigger anymore.
-- Remove the ride-route-based item population path entirely (`Order.Store.FK_RouteId` aggregation);
-  replace with direct `FK_OrderId`-based population at sheet-creation time.
-- Seed the new `loading.assign` permission.
-- Resolve Open Questions 1 and 4 before finalizing the `assign-ride` endpoint's authorization rules
-  and the one-sheet-per-PO assumption, respectively.
+- Remove `FK_OrderId` and `FK_SourceWarehouseId` from `Models/LoadingSheet.cs`. Make `FK_RideId`
+  required (non-nullable). Remove `AssignedAt`/`AssignedBy`. Add `PopulatedBy`, `PopulatedAt`,
+  `ConfirmedAt`, `ConfirmedBy`.
+- Add `Models/LoadingSheetOrder.cs` (`FK_LoadingSheetId`, `FK_OrderId`) with composite PK.
+- Add `FK_WarehouseId` (required), `FK_OrderItemId` (nullable), `IsActive` to
+  `Models/LoadingSheetItem.cs`.
+- Replace `LoadingSheetStatus.Pending` and `Assigned` with `Planned` and `Confirmed`; update all
+  status checks in `LoadingSheetService`/`LoadingSheetRepository`.
+- Remove `POST /api/loading-sheets` (old manual create) and `POST /{id}/assign-ride`; add
+  `POST /api/loading-sheets/populate` and `POST /{id}/confirm`.
+- Remove ride-route-based item population (`GetAggregatedOrderItemsByRouteIdAsync`); replace with
+  filter-based multi-PO aggregation in `LoadingSheetService`.
+- Remove all calls to ride-activation logic from `confirm-receipt`/`resolve` — no `Ride.Status`
+  transition exists anymore.
+- Seed the new `loading.populate` permission.
+- Resolve Open Question 1 (stock movement timing) before implementing `POST /{id}/confirm` and
+  `POST /{id}/confirm-receipt` stock movement logic.

Distribution/docs/refactor_docs/order_invoice_lifecycle.md

@@ -3,37 +3,34 @@
 **Status**: Proposed (design only — no code changes yet)
 **Refactors**: [../05_delivery_ride.md](../05_delivery_ride.md) and
 [../06_sale_ride.md](../06_sale_ride.md) (both kept as-is, this is the target design)
-**Related but independent**: [ride_lifecycle.md](./ride_lifecycle.md) — that refactor removes
-`RideType`/`Route`/`Status` from `Ride`; this document does not attempt to resolve most of its open
-questions, and this document's design does not depend on it landing first. One exception: this
-document's automatic `LoadingSheet` creation on PO confirm (see below) partially addresses
-`ride_lifecycle.md`'s "loading sheet auto-population" gap — the `LoadingSheet` is now generated from
-the PO/Invoice directly, not from a Route. How that `LoadingSheet` later attaches to an actual Ride
-(vehicle) is resolved in [loading_event.md](./loading_event.md).
+**Related but independent**: [ride_lifecycle.md](./ride_lifecycle.md), [dispatch_pipeline.md](./dispatch_pipeline.md)
 
 ---
 
 ## Goal
 
-Replace the Delivery-vs-Sale ride-type split as the organizing concept for how a store's order gets
-turned into money. Today `05_delivery_ride.md` (rep takes an order now, delivers days later) and
-`06_sale_ride.md` (rep+driver visit together and sell on the spot) are two separate flows. Underneath,
-both are the same shape: a rep collects a **PO** from the shop — whether fulfilled immediately or
-days later — and once the PO exists, an **Invoice** is generated from it. That invoice always moves
-through the same three statuses regardless of which scenario produced it:
+Replace the Delivery-vs-Sale ride-type split with a single unified pipeline. The PO and Invoice are
+two separate but linked concerns — the PO tracks what the shop ordered; the Invoice is the billing
+document that goes with the delivery.
 
-1. **Pending** — invoice just created from the PO; the PO's line items are freely editable.
-2. **Draft** — a PO-confirm action moves it out of Pending (no customer signature/OTP — see
-   [State Machine](#state-machine)). Confirming also automatically generates a `LoadingSheet` from
-   the PO's current line items. The PO's line items **remain editable** in this state too — Draft is
-   a working document, not a lock.
-3. **Finalize** — the reconciliation step: item add/delete and amount deductions (returns, damage,
-   short-delivery, discounts) get applied here, producing the final, locked invoice amount — this is
-   what the shop actually received and paid, and is the record used for day-end calculations. This
-   is the only state where free-form editing stops.
+### PO lifecycle (on `Order`)
 
-The two ride scenarios differ only in *timing* through this one pipeline, not in structure — no
-ride-type-specific branching is needed in the PO/Invoice model itself.
+1. **Shop PO** — PO created by sales agent, line items freely editable (versioned via `IsActive`).
+2. **Confirmed PO** — office user confirms the PO, locking its items. Invoice creation depends on
+   the system's active mode (see [Invoice Creation Modes](#invoice-creation-modes) below).
+
+### Invoice lifecycle (on `Invoice`)
+
+An Invoice is **not** auto-created when a PO is created. It is created by an office user action —
+either combined with PO confirmation (Mode A) or as a separate step after confirmation (Mode B).
+Once created, the Invoice always moves through these states:
+
+1. **Draft** — Invoice created, ready to be printed.
+2. **Printed** — Invoice physically printed and handed to the agent for the field. The agent makes
+   handwritten edits on the paper copy during the ride.
+3. **Finalized** — after the ride or day-end, the agent returns the printed invoice. The office
+   worker enters any edits the agent made into the system and submits — locking the invoice as the
+   final billing record.
 
 ---
 
@@ -54,198 +51,171 @@ name as `Order` in code.
 Order ("PO")
 ├── Id (Guid)                  — PK, from Template
 ├── FK_StoreId (Guid)          — required, unchanged
-├── FK_SaleId (Guid?)          — now OPTIONAL (was required). See Impact section — a PO can now
-│                                 exist before any Sale/payment event completes.
-├── TotalAmount (decimal)      — unchanged, though only authoritative once the linked Invoice is
-│                                 Finalized (see below)
+├── FK_SaleId (Guid?)          — now OPTIONAL (was required). A PO can exist before any Sale.
+├── InvoiceId (Guid?)          — NOT a FK constraint. Set when the Invoice is created for this PO
+│                                 (Mode A or B). Null until then. No referential enforcement at DB
+│                                 level — configured explicitly in Fluent API.
+├── TotalAmount (decimal)      — only authoritative once the linked Invoice is Finalized
 ├── Status (OrderStatus)       — unchanged: Pending, PartiallyFulfilled, Fulfilled, Cancelled.
-│                                 This tracks fulfillment progress, a separate axis from the new
-│                                 InvoiceStatus below — not merged in this pass.
+│                                 Tracks fulfillment progress — separate axis from InvoiceStatus.
 ├── FulfilledAt (DateTime?)    — unchanged
 ├── IsActive, CreatedAt        — from Template
 ```
 
-`OrderItem` (the PO's line items) is unchanged in shape (`FK_ItemId`, `Quantity`,
-`QuantityFulfilled`, `UnitPrice`) — editability is now gated by the linked `Invoice`'s status (see
-below), not by `Order.Status` directly.
+`OrderItem` (`FK_ItemId`, `Quantity`, `QuantityFulfilled`, `UnitPrice`, `IsActive`, `CreatedAt`) —
+editability gated by whether the PO is confirmed. Every edit soft-deletes current rows
+(`IsActive = false`) and writes a fresh set. Active rows = latest version; soft-deleted = history.
 
 ### New Entity — `Invoice`
 
 ```
 Invoice
 ├── Id (Guid)                  — PK, from Template
-├── FK_OrderId (Guid)          — required. One PO → one Invoice for v1 (see Open Questions).
-├── Status (InvoiceStatus)     — Pending, Draft, Finalized
-├── ConfirmedAt (DateTime?)    — set on Pending → Draft, when the PO is confirmed
-├── FinalizedAt (DateTime?)    — set on Draft → Finalized
-├── FinalizedBy (Guid?)        — UserId of whoever finalized it
-├── TotalAmount (decimal)      — mirrors the PO total while Pending/Draft; becomes the
-│                                 authoritative, locked amount once Finalized
+├── FK_OrderId (Guid)          — required. One PO → one Invoice (1:1).
+├── Status (InvoiceStatus)     — Draft, Printed, Finalized
+├── CreatedBy (Guid)           — UserId of office user who created the invoice
+├── PrintedAt (DateTime?)      — set on Draft → Printed
+├── PrintedBy (Guid?)          — UserId of whoever triggered the print
+├── FinalizedAt (DateTime?)    — set on Printed → Finalized
+├── FinalizedBy (Guid?)        — UserId of office worker who entered agent edits and submitted
+├── TotalAmount (decimal)      — reflects current line items through Draft/Printed; locked at Finalized
 ├── IsActive, CreatedAt        — from Template
 ```
 
-There is no signature/OTP field on `Invoice` — confirming a PO is a plain action, not a captured
-customer signature (see [State Machine](#state-machine); this also resolves
-[Open Question 1](#open-questions) from the prior pass of this document).
-
-### `LoadingSheet` — now generated from the PO, not the Route
-
-`LoadingSheet` already exists in the codebase (`Features/LoadingEvent/`), previously populated by
-aggregating orders on a ride's route (`LoadingSheetRepository.GetAggregatedOrderItemsByRouteIdAsync`
-— see `ride_lifecycle.md`'s Impact item 2). Under this design, a `LoadingSheet` is instead created
-automatically the moment an `Order`/`Invoice` moves Pending → Draft (PO confirmed), populated from
-that PO's `OrderItem` lines directly:
-
-```
-LoadingSheet
-├── FK_OrderId (Guid)          — required. Links the sheet to the PO/Invoice it was generated from.
-```
-
-It is **not** linked to a Ride or vehicle at creation time — it exists purely as "what needs to be
-loaded for this PO." How/when it later gets attached to an actual Ride for physical stock loading is
-left open — see [Open Questions](#open-questions).
-
 ### New Enum — `InvoiceStatus`
 
 ```csharp
-public enum InvoiceStatus { Pending, Draft, Finalized }
+public enum InvoiceStatus { Draft, Printed, Finalized }
 ```
 
-An `Invoice` is created automatically the moment a PO (`Order`) is created, starting at `Pending` —
-there is no separate "create invoice" action.
+### Invoice Creation Modes
+
+In a given system instance, **exactly one** of the following modes is active. Controlled by a
+system-level configuration flag (`InvoiceCreationMode: "A" | "B"`). Both modes cannot be active
+at the same time.
+
+**Mode A — Confirm PO + Create Invoice (combined action)**
+- Office user presses "Confirm PO & Create Invoice"
+- Single endpoint: `POST /api/orders/{id}/confirm-and-create-invoice`
+- Confirms the PO (locks `OrderItem` lines) and creates the Invoice at `Draft` in one atomic action.
+- `Order.InvoiceId` set to the new Invoice's Id in the same transaction.
+
+**Mode B — Create Invoice from Confirmed POs (separate action)**
+- PO confirmation is a separate step: `POST /api/orders/{id}/confirm` — locks items only.
+- `Order.InvoiceId` remains null until invoice is created.
+- Office user browses Confirmed POs filtered by `agentId`, `routeId`, or `shopId`, then creates
+  the invoice: `POST /api/invoices { orderId }`.
+- `Order.InvoiceId` set to the new Invoice's Id at creation.
+
+### `LoadingSheet` — populated from Confirmed POs, separate flow
+
+Loading sheets are populated from Confirmed POs as a separate dispatcher-triggered flow — not
+auto-triggered at PO confirm or invoice creation time. One loading sheet aggregates multiple
+Confirmed POs based on route/agent/shop filters. See [loading_event.md](./loading_event.md) and
+[dispatch_pipeline.md](./dispatch_pipeline.md) for the full loading sheet lifecycle.
 
 ---
 
 ## State Machine
 
-```
-Pending → Draft → Finalized
-```
+### PO (`Order`) transitions
 
-No branch/cancel path is designed in this pass (unlike the Ride state machine) — cancellation of a
-PO/Invoice is not addressed here; flagged as an open question below.
+```
+(create) → Shop PO → Confirmed PO
+```
 
 | Transition | Trigger | What it does |
 |---|---|---|
-| (implicit) → Pending | PO (`Order`) created | Invoice is created automatically, `Status = Pending`. `OrderItem` lines fully editable. |
-| Pending → Draft | `POST /api/orders/{id}/confirm` | Confirms the PO — a plain action, not a customer signature/OTP. Lives on the `Order` (PO) resource, not the `Invoice`; does **not** add or change any `Order.Status` value — PO confirmation and fulfillment tracking stay separate axes. Sets `Invoice.ConfirmedAt`, `Invoice.Status = Draft`, and automatically creates a `LoadingSheet` from the PO's current `OrderItem` lines. **`OrderItem` lines remain editable** after confirm — Draft is not a lock; whether/how a later edit re-syncs the already-generated `LoadingSheet` is an open question (see below). |
-| Draft → Finalized | `POST /api/invoices/{id}/finalize` | Accepts an item-adjustment/deduction payload (add/delete lines, amount deductions for returns/damage/short-delivery/discounts), recomputes and locks `TotalAmount`. This is a distinct, audited action — not the same add/edit/remove path used in Pending/Draft. Once Finalized, the Invoice and its PO's items are fully locked. |
+| (create) → Shop PO | `POST /api/orders` | PO created. `OrderItem` lines editable — every edit soft-deletes current rows (`IsActive = false`) and writes a fresh set. Active rows = latest version. No Invoice yet. |
+| Shop PO → Confirmed PO | **Mode A:** `POST /api/orders/{id}/confirm-and-create-invoice` | Confirms PO and creates Invoice at `Draft` atomically. `OrderItem` lines locked. `Order.InvoiceId` set. |
+| Shop PO → Confirmed PO | **Mode B:** `POST /api/orders/{id}/confirm` | Confirms PO only. `OrderItem` lines locked. `Order.InvoiceId` remains null until invoice created separately. |
+
+### Invoice transitions
+
+```
+Draft → Printed → Finalized
+```
+
+| Transition | Trigger | What it does |
+|---|---|---|
+| (create) → Draft | **Mode A:** combined with PO confirm above | Invoice created at `Draft`. `Order.InvoiceId` set. |
+| (create) → Draft | **Mode B:** `POST /api/invoices` `{ orderId }` | Office user selects a Confirmed PO (filtered by `agentId` / `routeId` / `shopId`) and creates the Invoice at `Draft`. `Order.InvoiceId` set. |
+| Draft → Printed | `POST /api/invoices/{id}/print` | Invoice is physically printed. `PrintedAt`/`PrintedBy` set. Agent takes the printed copy to the field and makes handwritten edits during the ride. |
+| Printed → Finalized | `POST /api/invoices/{id}/finalize` | After ride/day-end, agent returns printed invoice. Office worker enters any edits the agent made (quantity adjustments, returns, damage, discounts) and submits. `TotalAmount` locked. `FinalizedAt`/`FinalizedBy` set. |
 
 ---
 
 ## Business Rules
 
-1. `OrderItem` add/edit/remove is allowed while the linked `Invoice.Status` is `Pending` **or**
-   `Draft` — both are working-document states.
-2. An `Invoice` cannot be `Finalized` without first passing through `Draft` — `Pending → Finalized`
-   directly is not a valid transition.
-3. `Order.TotalAmount`/`Invoice.TotalAmount` is only authoritative once `Finalized`; while
-   Pending/Draft it reflects the current (still-changeable) line items.
-4. `Order.Status` (fulfillment tracking: Pending/PartiallyFulfilled/Fulfilled/Cancelled) is
-   untouched and operates on a separate axis from `Invoice.Status` (billing/document lifecycle) —
-   whether these two should eventually merge is an open question, not resolved here.
-5. `Order.FK_SaleId` is now optional — a PO/Invoice can exist and progress through Pending/Draft
-   before any `Sale` is recorded, covering the take-order-now/deliver-later scenario. See Impact
-   section for what this touches.
-6. Both ride scenarios (take-order-now-deliver-later vs. on-the-spot sale) create a PO the same way
-   and pass through the same three Invoice statuses — the only difference is how quickly they move
-   through Pending → Draft → Finalized. No `RideType`-specific branching applies to the PO/Invoice
-   model.
-7. Confirming a PO (Pending → Draft) requires no customer signature or OTP — it is a plain action
-   available to whoever is authorized to confirm a PO (e.g. the rep/dispatcher), not a
-   customer-facing sign-off step.
-8. A `LoadingSheet` is generated exactly once per PO, automatically, at PO-confirm time — there is no
-   separate manual "create loading sheet" action.
+1. `OrderItem` editing is allowed **only** while the PO is a Shop PO (before confirmation). Every
+   edit soft-deletes all current `OrderItem` rows (`IsActive = false`) and creates a fresh set —
+   active rows are the latest version, soft-deleted rows are history. Once confirmed, items are
+   locked permanently.
+2. Invoice is **not** auto-created at PO creation — it is always a deliberate office user action.
+3. Exactly one Invoice Creation Mode (A or B) is active per system instance — controlled by
+   `InvoiceCreationMode` config flag. Both modes cannot be active simultaneously.
+4. Mode A only: confirming a PO and creating its Invoice are atomic — one cannot happen without
+   the other.
+5. Mode B only: a PO can be confirmed without an Invoice existing; the Invoice is created later as
+   a separate action.
+6. `Order.InvoiceId` is set (non-null) once the Invoice is created — in the same transaction as
+   Invoice creation for both modes. It is stored as a plain column with no DB-level FK constraint.
+7. An Invoice cannot skip `Printed` — `Draft → Finalized` directly is not a valid transition.
+8. `Invoice.TotalAmount` is only authoritative once `Finalized`; through `Draft`/`Printed` it
+   reflects the current line items.
+9. `Order.Status` (fulfillment tracking: Pending/PartiallyFulfilled/Fulfilled/Cancelled) is a
+   separate axis from `Invoice.Status` — not merged in this pass.
+10. `Order.FK_SaleId` is optional — a PO can exist and be confirmed before any `Sale` is recorded.
+11. Loading sheet population is a separate dispatcher-triggered flow — not triggered by PO
+    confirmation or invoice creation. See [dispatch_pipeline.md](./dispatch_pipeline.md).
 
 ---
 
 ## Impact on Dependent Features
 
-Reshaping `Order` and introducing `Invoice` touches several existing behaviors. Each is flagged here
-as **known-affected, deferred follow-up work**, not solved in this pass:
-
-1. **`SaleService.CreateAsync`** — currently the only path that creates an `Order`, and it always
-   sets a non-null `FK_SaleId`. With `FK_SaleId` now optional, a new PO-creation path (not
-   necessarily originating from a `Sale`) needs to exist for the take-order-now/deliver-later
-   scenario. Any other code that assumes `Order.Sale` is always non-null also needs auditing —
-   not enumerated exhaustively here.
-2. **`Payment` attachment** — per `06_sale_ride.md`, `Payment` currently attaches to `Sale`. Once
-   `Invoice` exists as the real billing document, `Payment` more naturally attaches to the `Invoice`
-   instead. Flagged as a design question for [19_finance_accounting.md](../19_finance_accounting.md)
-   to reconcile — not decided here.
-3. **`19_finance_accounting.md`'s proposed Invoice status** (`Issued, PartiallyPaid, Paid`) needs
-   reconciling with this document's `Pending/Draft/Finalized`. These are likely two different axes
-   on the same `Invoice` — document lifecycle status (this doc) vs. payment-collection status (the
-   finance doc) — but that reconciliation is not attempted here.
-4. **`DeliveryTask.CustomerConfirmed`** (boolean, from `05_delivery_ride.md`) overlaps conceptually
-   with the new Pending → Draft transition (both represent "the customer confirmed this"). Whether
-   they merge into one confirmation event, or stay deliberately separate (delivery confirmation vs.
-   invoice sign-off, which could happen at different times), is not decided here.
-5. **`05_delivery_ride.md` and `06_sale_ride.md`** both go stale the moment this design ships and
-   need their own rewrite/retirement — tracked as follow-up, not attempted in this pass.
-6. **`LoadingSheet` generation moves from route-scoped to PO-scoped.** `LoadingSheetRepository`'s
-   existing `GetAggregatedOrderItemsByRouteIdAsync` (aggregating by `Order.Store.FK_RouteId`) is
-   superseded by generating one `LoadingSheet` per PO at confirm time. This directly answers part of
-   `ride_lifecycle.md`'s Impact item 2 (loading sheet auto-population without a route) — but raises a
-   new gap: nothing in this design says how/when a PO-scoped `LoadingSheet` gets matched to an actual
-   Ride/vehicle for physical loading, since `ride_lifecycle.md` also removed `FK_SourceWarehouseId`
-   and any route/store linkage from `Ride`. Flagged as [Open Question 7](#open-questions), not solved
-   here.
-
-None of the above are implemented or redesigned by this document. They're called out so the gap is
-visible and intentional rather than discovered later as a silent regression.
+1. **`SaleService.CreateAsync`** — currently the only path that creates an `Order`, always with a
+   non-null `FK_SaleId`. With `FK_SaleId` now optional, a new PO-creation path needs to exist.
+   All code that assumes `Order.Sale` is non-null needs auditing.
+2. **`Payment` attachment** — `Payment` currently attaches to `Sale`. Once `Invoice` exists as the
+   real billing document, `Payment` more naturally attaches to `Invoice`. Deferred to
+   [19_finance_accounting.md](../19_finance_accounting.md).
+3. **`05_delivery_ride.md` and `06_sale_ride.md`** go stale when this ships — need rewrite/retirement.
+4. **`LoadingSheet` population** moves from route-scoped to dispatcher-triggered, multi-PO
+   aggregation. See [loading_event.md](./loading_event.md).
 
 ---
 
 ## Open Questions
 
-1. ~~**Signature/OTP mechanism for the Pending → Draft transition**~~ — **Resolved:** dropped
-   entirely. Pending → Draft is driven by a plain PO-confirm action (`POST /api/orders/{id}/confirm`),
-   not a customer signature or OTP. See [State Machine](#state-machine).
-2. **One Invoice per PO, or multiple?** — this document assumes a 1:1 `Order`→`Invoice` relationship
-   for v1. Whether a PO could ever need multiple invoices (e.g. split billing) is not designed here.
-3. **Should `Order.Status` and `Invoice.Status` eventually merge into one status axis?** — kept
-   deliberately separate in this pass (fulfillment progress vs. document/billing lifecycle); not
-   decided whether that separation should be permanent.
-4. **How does `Payment` attach once `Invoice` exists?** — see Impact item 2. Not designed here.
-5. **Is there a cancellation/void path for a PO or Invoice?** — the state machine in this document
-   has no cancel branch (unlike the Ride state machine's `CancelRequested`/`Cancelled`). Not
-   addressed here.
-6. **Does `DeliveryTask.CustomerConfirmed` merge with the Draft transition?** — see Impact item 4.
-7. ~~**How does a PO-scoped `LoadingSheet` get matched to an actual Ride/vehicle?**~~ — **Resolved
-   in [loading_event.md](./loading_event.md):** the sheet starts `Planned` (ride-less), and a new
-   `POST /{id}/assign-ride` action attaches a `Ride` + source warehouse, moving it to `Assigned`.
-8. **Does editing a PO's items after confirm (while still Draft) re-sync the already-generated
-   `LoadingSheet`?** — this document allows PO edits through Draft, but doesn't decide whether the
-   `LoadingSheet` regenerates, gets manually re-synced, or is left to drift until Finalize reconciles
-   it. Not designed here.
+1. ~~**Signature/OTP on PO confirmation**~~ — **Resolved:** dropped. Plain action, no OTP.
+2. ~~**One Invoice per PO or multiple?**~~ — **Resolved:** 1:1 for v1.
+3. **Should `Order.Status` and `Invoice.Status` eventually merge?** — kept separate; not decided.
+4. **How does `Payment` attach to `Invoice`?** — see Impact item 2. Not designed here.
+5. **Cancellation/void path for a Shop PO, Confirmed PO, or Invoice?** — not addressed here.
+6. **Exact adjustment payload for `POST /finalize`** — quantity adjustments, returns, damage, and
+   discounts are assumed but the payload shape is not fully specified here.
 
 ---
 
 ## Migration Notes (for when this is implemented)
 
-Not part of this docs-only pass, but captured for the eventual implementation step:
-
-- Make `Order.FK_SaleId` nullable in `Models/Order.cs` and its EF/Fluent configuration; audit all
-  code paths that currently assume it's non-null.
-- Add `Models/Invoice.cs` (`FK_OrderId`, `Status`, `ConfirmedAt`, `FinalizedAt`, `FinalizedBy`,
-  `TotalAmount`, plus `Template` base fields) and the `InvoiceStatus` enum.
+- Make `Order.FK_SaleId` nullable in `Models/Order.cs`; audit all code paths that assume non-null.
+- Add `Order.InvoiceId` (Guid?, no FK constraint) to `Models/Order.cs` — configure in Fluent API
+  to ensure no referential constraint is generated.
+- Add `Models/Invoice.cs` (`FK_OrderId`, `Status`, `CreatedBy`, `PrintedAt`, `PrintedBy`,
+  `FinalizedAt`, `FinalizedBy`, `TotalAmount`, plus `Template` base fields) and the `InvoiceStatus`
+  enum (`Draft`, `Printed`, `Finalized`).
 - New `Features/Invoice/` folder (`InvoiceController`, `InvoiceService`, `IInvoiceRepository`,
-  `InvoiceRepository`, `InvoiceDTOs`) — do not place this under `Features/PurchaseOrder/` or reuse
-  any of its DTOs/names, to avoid the supplier-PO naming collision flagged above.
-- Add `POST /api/orders/{id}/confirm` on the `Order`/PO feature (not on `Invoice`) — it sets
-  `Invoice.ConfirmedAt`/`Status = Draft` and creates the `LoadingSheet` in one action; no
-  `POST /api/invoices/{id}/draft` endpoint and no signature/OTP capture are needed.
-- `POST /api/invoices/{id}/finalize` endpoint; the finalize endpoint's adjustment/deduction payload
-  should reuse the `CreditNote` shape from [18_returns_claims.md](../18_returns_claims.md) where
-  applicable rather than inventing a parallel mechanism.
-- Add `FK_OrderId` to `Models/LoadingSheet.cs` (or equivalent) and change
-  `LoadingSheetService`/`LoadingSheetRepository` to generate a sheet from a PO's `OrderItem` lines
-  directly, replacing `GetAggregatedOrderItemsByRouteIdAsync`'s route-based aggregation — wire this
-  call into the new PO-confirm action.
-- A new PO-creation path independent of `SaleService.CreateAsync`, to support creating an
-  `Order`/`Invoice` before any `Sale` exists (Impact item 1) — needs its own design, not specified
-  here.
-- Resolve Open Question 2 (one Invoice per PO) before finalizing the `FK_OrderId` uniqueness
-  constraint on `Invoice`; resolve Open Questions 7–8 (LoadingSheet-to-Ride matching, and re-sync on
-  post-confirm PO edits) before wiring the PO-confirm action into `LoadingSheetService`.
+  `InvoiceRepository`, `InvoiceDTOs`) — do not place under `Features/PurchaseOrder/`.
+- Add system configuration flag `InvoiceCreationMode` (`"A"` or `"B"`) — gate Mode A and Mode B
+  endpoints accordingly so only the active mode's endpoints are reachable.
+- **Mode A endpoint:** `POST /api/orders/{id}/confirm-and-create-invoice` — atomic: locks
+  `OrderItem` rows, creates `Invoice` at `Draft`, sets `Order.InvoiceId` in one transaction.
+- **Mode B endpoints:** `POST /api/orders/{id}/confirm` (locks items only) + `POST /api/invoices`
+  `{ orderId }` (creates Invoice at `Draft`, sets `Order.InvoiceId`). Add `GET /api/orders` filter
+  params `agentId`, `routeId`, `shopId` to support the office user's PO selection UI.
+- `POST /api/invoices/{id}/print` — sets `PrintedAt`/`PrintedBy`, transitions to `Printed`.
+- `POST /api/invoices/{id}/finalize` — accepts adjustment payload; locks `TotalAmount`; sets
+  `FinalizedAt`/`FinalizedBy`. Resolve Open Question 6 before specifying the exact payload shape.
+- `LoadingSheet` population is a separate flow — see [dispatch_pipeline.md](./dispatch_pipeline.md).
+- A new PO-creation path independent of `SaleService.CreateAsync` is needed — not specified here.