# WorkOrder

## Description

WorkOrder is the operation-level execution record created from a released production-order routing snapshot. It owns one executable step, its work-center context, planned and actual quantities, actual time, pause or exception history, and the execution lifecycle that drives progress rollup, inventory handoff, and cost accumulation.

## Domain Model Definitions

### Model type

Stateful

#### State Transitions

```mermaid
stateDiagram-v2
    [*] --> PENDING: releaseProductionOrder
    PENDING --> IN_PROGRESS: startWorkOrder
    IN_PROGRESS --> IN_PROGRESS: reportWorkOrderProgress
    IN_PROGRESS --> PAUSED: pauseWorkOrder
    PAUSED --> IN_PROGRESS: resumeWorkOrder
    IN_PROGRESS --> COMPLETE: completeWorkOrder
    PENDING --> CANCELLED: cancelProductionOrder
```

| Operation | From | To | Command |
|-----------|------|----|---------|
| start | PENDING | IN_PROGRESS | [startWorkOrder](../command/StartWorkOrder.md) |
| pause | IN_PROGRESS | PAUSED | [pauseWorkOrder](../command/PauseWorkOrder.md) |
| resume | PAUSED | IN_PROGRESS | [resumeWorkOrder](../command/ResumeWorkOrder.md) |
| complete | IN_PROGRESS | COMPLETE | [completeWorkOrder](../command/CompleteWorkOrder.md) |
| cancel | PENDING | CANCELLED | [cancelProductionOrder](../command/CancelProductionOrder.md) |

### Command Definitions

- [startWorkOrder](../command/StartWorkOrder.md) - Start execution on one released work order.
- [pauseWorkOrder](../command/PauseWorkOrder.md) - Pause an in-progress work order with an exception reason.
- [resumeWorkOrder](../command/ResumeWorkOrder.md) - Resume a paused work order without losing prior history.
- [reportWorkOrderProgress](../command/ReportWorkOrderProgress.md) - Record partial quantities, time, scrap, and execution notes.
- [completeWorkOrder](../command/CompleteWorkOrder.md) - Finish the operation and emit required completion handoffs.
- [cancelProductionOrder](../command/CancelProductionOrder.md) - Cascade cancellation to pending work orders when the parent order is cancelled before execution.

### Query Definitions

- [getWorkOrder](../query/GetWorkOrder.md) - Retrieve one work order with execution evidence and handoff status.
- [listWorkOrdersByProductionOrder](../query/ListWorkOrdersByProductionOrder.md) - List work orders under one production order in sequence order.
- [listWorkOrdersByWorkCenter](../query/ListWorkOrdersByWorkCenter.md) - List work orders assigned to one work center across production orders for bottleneck review.

### Models

- WorkOrder
- WorkOrderExecutionEvent

### Invariants

- Every work order belongs to exactly one production order and one released routing-operation snapshot.
- Every work order is created from a single sequential routing operation within the parent production order.
- `plannedQuantity`, `completedQuantity`, `scrapQuantity`, and captured time values are always zero or greater.
- A work order may move to `IN_PROGRESS` only while its parent production order is in an execution-capable state.
- A work order in `PAUSED` preserves prior execution evidence and can resume without resetting accumulated quantities or time.
- Completing a later sequential work order before its required predecessor is done is invalid unless the routing snapshot explicitly allows it.
- Receipt and scrap handoffs must carry the production-order and work-order references that preserve manufacturing traceability.
- `COMPLETE` and `CANCELLED` work orders reject further execution reporting.

### Relationships

- **Belongs To ProductionOrder**: each work order is created under one [ProductionOrder](./ProductionOrder.md).
- **References Routing and WorkCenter snapshots**: executable operation context comes from released [Routing](./Routing.md) and [WorkCenter](./WorkCenter.md) data.
- **Emits ManufacturingReceiptHandoff**: completion reporting sends the named receipt contract to inventory.
- **Emits ManufacturingScrapHandoff**: scrap reporting sends the named scrap contract to inventory.
- **Feeds ManufacturingCostSummary**: actual time, quantity, and scrap roll up into [ManufacturingCostSummary](./ManufacturingCostSummary.md).