# ReportWorkOrderProgress

## Permission Scope

workOrder

## Overview

ReportWorkOrderProgress records partial execution evidence such as completed quantity, scrap quantity, actual time, and exception notes. It also emits any required manufacturing scrap handoff when the report contains scrapped quantity.

## Business Rules

- Target work order must exist and be in `IN_PROGRESS`.
- Reported completed quantity and scrap quantity must be zero or greater.
- At least one of completed quantity, scrap quantity, or actual time must be positive.
- Scrap reporting emits `ManufacturingScrapHandoff` exactly once per submitted scrap transaction.
- Manufacturing-originated stock loss with a resolvable production or work-order reference must not bypass the manufacturing scrap handoff path.
- Progress reporting updates parent production-order rollup.

## Process Flow

```mermaid
flowchart TD
    A[Receive progress report] --> B{Work order exists and is IN_PROGRESS?}
    B -->|No| C[Return WORK_ORDER_NOT_REPORTABLE]
    B -->|Yes| D[Validate quantities and time]
    D --> E{Positive scrap reported?}
    E -->|Yes| F[Emit ManufacturingScrapHandoff]
    E -->|No| G[Skip scrap handoff]
    F --> H[Persist execution event]
    G --> H
    H --> I[Roll up parent order progress]
    I --> J[Return updated work order]
```

## External Dependencies

- [ProductionOrder](../model/ProductionOrder.md) - Progress rolls up into parent order execution state.

## Error Scenarios

- **WORK_ORDER_NOT_FOUND**: Referenced work order does not exist
- **WORK_ORDER_NOT_REPORTABLE**: Work order is not in `IN_PROGRESS`.
- **INVALID_REPORTED_QUANTITY**: Reported completed or scrap quantity is negative.
- **EMPTY_PROGRESS_TRANSACTION**: No positive quantity or time was reported.
- **SCRAP_HANDOFF_REQUIRED**: Positive scrap was reported but required scrap-handoff data is incomplete.

## Test Cases

- records partial completed quantity and time on an in-progress work order
- returns error when the work order does not exist
- returns error when the work order is not in progress
- returns error when completed or scrap quantity is negative
- returns error when no positive quantity or time is provided
- emits manufacturing scrap handoff when positive scrap is reported
- returns error when positive scrap is reported without scrap handoff data
- accumulates completed quantity, setup time, and run time on the work order