# CreateProductionOrder

## Permission Scope

productionOrder

## Overview

CreateProductionOrder creates a draft manufacturing request with produced item, quantity, site, and planned dates. It records planner intent without yet freezing BOM, routing, work orders, or cost assumptions.

## Business Rules

- Produced item, company, site, and planned quantity are required.
- Planned quantity must be greater than zero.
- Produced item must be an active manufacturable item.
- Referenced company and site must exist and belong to the same scope.
- Optional BOM or routing references must belong to the same company and site context.
- New production orders are created in `DRAFT`.

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> B[Validate item, quantity, and scope]
    B --> C[Validate optional BOM and routing references]
    C --> D[Create draft production order]
    D --> E[Return draft order]
```

## External Dependencies

- [Item](../../../item-management/docs/model/Item.md) - Produced item must be valid and manufacturable.
- [Company](../../../organization/docs/model/Company.md) - Order company scope must be valid.
- [Site](../../../organization/docs/model/Site.md) - Execution site must be valid for the company scope.

## Error Scenarios

- **PRODUCTION_ITEM_NOT_FOUND**: Produced item does not exist.
- **PRODUCTION_ITEM_NOT_MANUFACTURABLE**: Produced item cannot be built through manufacturing.
- **INVALID_PLANNED_QUANTITY**: Planned quantity is zero or negative.
- **INVALID_SITE_SCOPE**: Company and site scope are missing or inconsistent.
- **CROSS_SCOPE_MASTER_REFERENCE**: BOM or routing reference belongs to another company or site.

## Test Cases

- creates a draft production order for a manufacturable item
- returns error when the produced item does not exist
- returns error when the produced item is not manufacturable
- returns error when planned quantity is not positive
- returns error when site scope is inconsistent with company
- returns error when site does not exist
- returns error when an optional BOM reference is outside scope
- returns error when an optional routing reference is outside scope