# sales-order-lifecycle

## Overview

The flow manages a customer sales order from drafting through approval,
execution, cancellation, or closure. Document control is represented by
`orderStatus`; fulfillment and billing are independent projections.

1. A Sales Rep creates a DRAFT order and adds priced lines.
2. The order is submitted for approval.
3. An Approver rejects it back to DRAFT or confirms it.
4. Confirmation initializes `fulfillmentStatus` and `billingStatus`.
5. Posting outbound shipments advances `fulfilledQuantity` and derives
   `fulfillmentStatus` without changing `orderStatus`.
6. A confirmed order may be cancelled only before fulfillment or billing
   progress, and may be closed after execution is complete.

The template does not provide accounts-receivable screens. A future AR
integration can call the sales module's billing recalculation command to update
line `billedQuantity` and `billingStatus`.

## Actors Involved

- [Sales Rep](../../actor/sales-rep.md) — creates, submits, and cancels sales orders
- [Approver](../../actor/approver.md) — reviews, confirms, or rejects submitted sales orders

See [action-matrix.md](./action-matrix.md) for models involved and the action
visibility matrix.

## Flow Diagram

```mermaid
sequenceDiagram
    participant SR as Sales Rep
    participant S as System
    participant A as Approver

    SR->>S: Create sales order with priced lines
    S-->>SR: orderStatus → DRAFT
    SR->>S: Submit order
    S-->>A: orderStatus → SUBMITTED

    alt Confirm
        A->>S: Confirm order
        S-->>A: orderStatus → CONFIRMED
        S->>S: Initialize fulfillmentStatus and billingStatus
    else Reject
        A->>S: Reject order with reason
        S-->>SR: orderStatus → DRAFT
    end

    Note over SR,S: Outbound shipment posting advances fulfilledQuantity and fulfillmentStatus
    Note over SR,S: Receivables integration advances billedQuantity and billingStatus

    SR->>S: Cancel before execution progress
    S-->>SR: orderStatus → CANCELLED

    SR->>S: Close after execution completes
    S-->>SR: orderStatus → CLOSED
```

See [Outbound Shipment Processing](../outbound-shipment-processing/README.md)
for the physical fulfillment flow.

## Stories

- [Create Sales Order](./story/sales-rep--create-sales-order.md)
- [Submit Sales Order](./story/sales-rep--submit-sales-order.md)
- [Confirm or Reject Sales Order](./story/approver--confirm-or-reject-sales-order.md)