# RecordInventoryIssueOutcome

## Permission Scope

productionOrder

## Overview

RecordInventoryIssueOutcome applies one inventory-owned valuation outcome to the manufacturing cost summary for a production order. It is the only valid path for actual material cost to enter manufacturing.

## Business Rules

- Referenced production order and cost summary must exist.
- Cost summary must be in `COLLECTING`.
- Inventory outcome payload must include `productionOrderReference`, `inventoryIssueReference`, `itemReference`, `issuedQuantity`, `unitOfMeasure`, `actualUnitCost`, `actualExtendedCost`, `currency`, `valuationMethod`, `postingDate`, and `siteReference`.
- Inventory issue outcome must already be final-valued by inventory.
- The event must not be double-applied to the same summary.
- Actual material cost is recorded using the payload values rather than manufacturing-side recalculation.

## Process Flow

```mermaid
flowchart TD
    A[Receive inventory issue outcome] --> B[Resolve production order and cost summary]
    B --> C[Validate required payload fields]
    C --> D{Summary collecting?}
    D -->|No| E[Return COST_SUMMARY_NOT_COLLECTING]
    D -->|Yes| F{Inventory valuation final?}
    F -->|No| G[Return ISSUE_OUTCOME_NOT_FINAL]
    F -->|Yes| H{Already applied?}
    H -->|Yes| I[Return DUPLICATE_ISSUE_OUTCOME]
    H -->|No| J[Apply actual material cost to summary]
    J --> K[Return updated summary]
```

## External Dependencies

- [ManufacturingCostSummary](../models/ManufacturingCostSummary.md) - Actual material issue outcomes accumulate on the linked summary.

## Error Scenarios

- **PRODUCTION_ORDER_NOT_FOUND**: Referenced production order does not exist
- **COST_SUMMARY_NOT_FOUND**: Referenced cost summary does not exist
- **COST_SUMMARY_NOT_COLLECTING**: Summary is not in `COLLECTING`.
- **MISSING_INVENTORY_ISSUE_REFERENCE**: `inventoryIssueReference` was not provided in the outcome payload.
- **MISSING_ACTUAL_UNIT_COST**: `actualUnitCost` was not provided in the outcome payload.
- **MISSING_ACTUAL_EXTENDED_COST**: `actualExtendedCost` was not provided in the outcome payload.
- **MISSING_POSTING_DATE**: `postingDate` was not provided in the outcome payload.
- **ISSUE_OUTCOME_NOT_FINAL**: Inventory valuation is not yet final.
- **DUPLICATE_ISSUE_OUTCOME**: The same inventory issue outcome was already applied.

## Test Cases

- applies a final-valued inventory issue outcome to a collecting summary
- returns error when the production order does not exist
- returns error when the linked cost summary does not exist
- returns error when the summary is not collecting
- returns error when `inventoryIssueReference` is missing from the outcome payload
- returns error when `actualUnitCost` is missing from the outcome payload
- returns error when `actualExtendedCost` is missing from the outcome payload
- returns error when `postingDate` is missing from the outcome payload
- returns error when the inventory issue outcome is not yet final
- returns error when the same issue outcome is applied twice
