Add refactor order_invoice_lifecycle.md file

2026-09-10 15:53:57 +05:30
parent b8836a1e87
commit 2000ba67f4
1 changed files with 196 additions and 0 deletions
@@ -0,0 +1,196 @@
 # [Refactor] Order/Invoice Lifecycle — Unified PO → Invoice Pipeline
 **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 its open
 questions, and this document's design does not depend on it landing first.
 ---
 ## 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:
 1. **Pending** — invoice just created from the PO; the PO's line items are freely editable.
 2. **Draft** — the customer signs once the order is confirmed, moving it out of Pending. 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
   the only state where free-form editing stops.
 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.
 ---
 ## Data Model Changes
 ### Reshaped Entity — `Order` (business term: "PO")
 The existing `Order` entity ([Order.cs](../../Models)) is reshaped into this role, keeping its class
 name as `Order` in code.
 > **Naming note**: `Distribution/Models/PurchaseOrder.cs` and `Distribution/Features/PurchaseOrder/`
 > already exist in the codebase — that's the *supplier-facing* procurement flow (the distributor
 > buying from its own suppliers), completely unrelated to this store-facing PO. To avoid confusion,
 > this document deliberately keeps the class name `Order`, using "PO" only as the business-facing
 > term for what the store ordered. Do **not** name the reshaped entity/class `PurchaseOrder`.
 ```
 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)
 ├── Status (OrderStatus)       — unchanged: Pending, PartiallyFulfilled, Fulfilled, Cancelled.
 │                                 This tracks fulfillment progress, a separate axis from the new
 │                                 InvoiceStatus below — not merged in this pass.
 ├── 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.
 ### 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
 ├── SignedAt (DateTime?)       — set on Pending → Draft
 ├── 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
 ├── IsActive, CreatedAt        — from Template
 ```
 ### New Enum — `InvoiceStatus`
 ```csharp
 public enum InvoiceStatus { Pending, Draft, Finalized }
 ```
 An `Invoice` is created automatically the moment a PO (`Order`) is created, starting at `Pending` —
 there is no separate "create invoice" action.
 ---
 ## State Machine
 ```
 Pending → Draft → Finalized
 ```
 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.
 | Transition | Trigger | What it does |
 |---|---|---|
 | (implicit) → Pending | PO (`Order`) created | Invoice is created automatically, `Status = Pending`. `OrderItem` lines fully editable. |
 | Pending → Draft | `POST /api/invoices/{id}/draft` | Captures customer sign-off. Sets `SignedAt`. **`OrderItem` lines remain editable** — Draft is not a lock. Signature/OTP mechanism itself is an open question (see below), matching `05_delivery_ride.md`'s own prior deferral on customer confirmation. |
 | 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. |
 ---
 ## 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.
 ---
 ## 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.
 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.
 ---
 ## Open Questions
 1. **Signature/OTP mechanism for the Pending → Draft transition** — same deferral as
   `05_delivery_ride.md`'s original "signature (image) or OTP (SMS code) — one, or both, in v1?"
   question. Not resolved here.
 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.
 ---
 ## 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`, `SignedAt`, `FinalizedAt`, `FinalizedBy`,
  `TotalAmount`, plus `Template` base fields) and the `InvoiceStatus` enum.
 - 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.
 - `POST /api/invoices/{id}/draft` and `POST /api/invoices/{id}/finalize` endpoints; 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.
 - 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 Questions 1–2 before implementing the Draft-transition endpoint and the
  one-Invoice-per-PO assumption respectively.