# ExplodeBillOfMaterial

## Overview

ExplodeBillOfMaterial expands one BOM version into recursive component requirements for planners and engineers who need to inspect multi-level demand on a specific effectivity date.

## Business Rules

- BOM reference is required.
- Effectivity date is required so the query can resolve the root BOM semantics and any lower-level active child BOM versions consistently.
- The explosion must apply the released BOM `bomType` semantics: `MANUFACTURE` preserves make-item boundaries while still showing lower-level demand, `PHANTOM` flattens child lines into the nearest non-phantom parent path, and `KIT` expands to issue-only component demand without routing or work-order context for the kit parent.
- Recursive expansion may only use child BOM versions that are active and effective on the requested date within the same company and applicable site scope.
- The response returns an exploded tree or list with component item references, cumulative required quantities, unit-of-measure context, explosion depth, and the source BOM path used to derive each requirement.

## Process Flow

```mermaid
flowchart TD
    A[Receive BOM reference and effectivity date] --> B[Load root BOM version]
    B --> C{BOM found and effective on date?}
    C -->|No| D[Return BOM_NOT_FOUND or BOM_NOT_EFFECTIVE_ON_DATE]
    C -->|Yes| E[Walk component lines recursively]
    E --> F{Manufactured child requires lower-level BOM?}
    F -->|Yes| G[Resolve active child BOM for date and scope]
    G --> H[Apply MANUFACTURE PHANTOM or KIT explosion semantics]
    F -->|No| H
    H --> I[Accumulate exploded component requirements]
    I --> J[Return exploded structure]
```

## External Dependencies

- None

## Error Scenarios

- **BOM_REFERENCE_REQUIRED**: BOM reference was not provided.
- **EFFECTIVITY_DATE_REQUIRED**: Effectivity date was not provided.
- **BOM_NOT_FOUND**: Referenced BOM does not exist
- **BOM_NOT_EFFECTIVE_ON_DATE**: The requested BOM version is not valid on the specified effectivity date.
- **CHILD_BOM_NOT_RESOLVED**: A manufactured child item required recursive expansion but no active effective child BOM could be resolved.
- **BOM_CIRCULAR_REFERENCE_DETECTED**: The explosion encountered a direct or indirect circular BOM reference.

## Test Cases

- explodes a multi-level manufacture BOM into recursive component requirements
- flattens phantom subassemblies into the nearest non-phantom parent path
- expands a kit BOM into component issue requirements without work-order context for the kit parent
- resolves lower-level child BOM versions using the requested effectivity date
- returns cumulative quantities and source BOM path metadata for exploded components
- returns error when the BOM reference is missing
- returns error when the effectivity date is missing
- returns error when the root BOM is not found
- returns error when the root BOM is not effective on the requested date
- returns error when a required lower-level child BOM cannot be resolved
- returns error when the explosion detects a circular BOM reference
- resolves lower-level child BOMs using the applicable site scope