# CreateBillOfMaterial

## Permission Scope

manufacturingMaster

## Overview

CreateBillOfMaterial creates a draft BOM version for one manufactured parent item at company or site scope. The command establishes the initial `bomType`, effectivity window, default-selection intent, and component-line payload that later activation validates.

## Business Rules

- Parent item is required and must be an active manufactured item.
- Company scope is required; site scope is optional.
- `bomType` must be `MANUFACTURE`, `PHANTOM`, or `KIT`.
- At least one component line is required.
- Each component line requires positive quantity and a compatible unit of measure.
- Inactive items cannot be added as components.
- Initial version identity must be unique within the same parent item and scope.
- New BOMs are created in `DRAFT`.

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> B[Validate parent item and scope]
    B --> C[Validate bomType and lines]
    C --> D{Version identity unique?}
    D -->|No| E[Return BOM_VERSION_CONFLICT]
    D -->|Yes| F[Create draft BOM and lines]
    F --> G[Return draft BOM]
```

## External Dependencies

- [Item](../../../item-management/docs/models/Item.md) - Parent and component references must resolve to valid items.

## Error Scenarios

- **PARENT_ITEM_NOT_FOUND**: Referenced parent item does not exist.
- **PARENT_ITEM_NOT_MANUFACTURED**: Parent item is not eligible for manufacturing BOM ownership.
- **INVALID_BOM_TYPE**: `bomType` is not one of the supported values.
- **COMPONENT_LINE_REQUIRED**: BOM has no component lines
- **INVALID_COMPONENT_QUANTITY**: A component quantity is zero or negative
- **COMPONENT_ITEM_INACTIVE**: A referenced component item is not in ACTIVE status
- **BOM_VERSION_CONFLICT**: The proposed version or effectivity identity already exists in the same scope.

## Test Cases

- creates a draft BOM for an active manufactured item
- returns error when the parent item does not exist
- returns error when the parent item is not manufacturable
- returns error when `bomType` is invalid
- returns error when no component lines are provided
- returns error when a component quantity is not positive
- returns error when a component item is inactive
- returns error when a component item exists but is inactive
- returns error when the version identity already exists in scope
- returns error when the parent item is inactive
