# UpdateBillOfMaterial

## Permission Scope

manufacturingMaster

## Overview

UpdateBillOfMaterial revises mutable draft BOM content before activation. It supports changes to effectivity, default flags, `bomType`, and component lines while preserving released production-order snapshots.

## Business Rules

- Target BOM must exist.
- Only `DRAFT` BOM versions are mutable through this command.
- Updated component lines must still satisfy positive quantity and unit compatibility rules.
- Inactive items cannot be introduced as new components.
- Changing effectivity or default selection must not create an ambiguous active-selection plan once activated.
- Updating a draft BOM must not alter any production-order snapshot already taken from another version.

## Process Flow

```mermaid
flowchart TD
    A[Receive update request] --> B{BOM exists?}
    B -->|No| C[Return BOM_NOT_FOUND]
    B -->|Yes| D{Status is DRAFT?}
    D -->|No| E[Return BOM_NOT_MUTABLE]
    D -->|Yes| F[Validate revised fields and lines]
    F --> G[Persist updated draft]
    G --> H[Return updated BOM]
```

## External Dependencies

- [Item](../../../item-management/docs/model/Item.md) - Any newly referenced component item must remain valid.

## Error Scenarios

- **BOM_NOT_FOUND**: Referenced BOM does not exist
- **BOM_NOT_MUTABLE**: The BOM is not in `DRAFT`.
- **INVALID_COMPONENT_QUANTITY**: A component quantity is zero or negative
- **COMPONENT_ITEM_INACTIVE**: A referenced component item is not in ACTIVE status
- **AMBIGUOUS_EFFECTIVITY_RULE**: Revised effectivity or default flags would create ambiguous selection behavior.

## Test Cases

- updates draft BOM metadata and component lines
- returns error when the BOM does not exist
- returns error when the BOM is not in `DRAFT`
- returns error when a revised component quantity is invalid
- returns error when a newly referenced component is inactive
- returns error when effectivity changes would create ambiguous selection