# CreateInventoryAdjustment

## Permission Scope

inventoryControl

## Overview

createInventoryAdjustment creates a new inventory adjustment record in DRAFT status. The `adjustmentType` determines the behavior:

- **CORRECTION** (default): Manual corrections to on-hand quantities. quantityDelta can be positive or negative.
- **SCRAP**: Controlled disposal of unusable stock. quantityDelta must be negative.

## Business Rules

- adjustmentType is required (CORRECTION or SCRAP, defaults to CORRECTION)
- itemId is required and must reference an existing item
- storageLocationId is required and must reference an existing storage location
- quantityDelta is required
- For CORRECTION: quantityDelta can be positive or negative
- For SCRAP: quantityDelta must be negative
- reasonCode is required
- inventoryCountId is optional (links adjustment to a specific count, CORRECTION only)
- lotId is optional (must reference an existing lot if provided)
- serialNumberId is optional (must reference an existing serial number if provided)
- Adjustment is created in DRAFT status

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> B{Item exists?}
    B -->|No| C[Return error: ITEM_NOT_FOUND]
    B -->|Yes| D{Location exists?}
    D -->|No| E[Return error: STORAGE_LOCATION_NOT_FOUND]
    D -->|Yes| F{reasonCode provided?}
    F -->|No| G[Return error: REASON_CODE_REQUIRED]
    F -->|Yes| FA{adjustmentType is SCRAP?}
    FA -->|Yes| FB{quantityDelta negative?}
    FB -->|No| FC[Return error: SCRAP_QUANTITY_MUST_BE_NEGATIVE]
    FB -->|Yes| H
    FA -->|No| H{lotId provided?}
    H -->|Yes| I{Lot exists?}
    I -->|No| J[Return error: LOT_NOT_FOUND]
    I -->|Yes| K{serialNumberId provided?}
    H -->|No| K
    K -->|Yes| L{Serial number exists?}
    L -->|No| M[Return error: SERIAL_NUMBER_NOT_FOUND]
    L -->|Yes| N[Create adjustment in DRAFT]
    K -->|No| N
    N --> O[Return created adjustment]
```

## External Dependencies

- [item-management::Item](../../../item-management/docs/models/Item.md) - Validates that the referenced item exists

## Error Scenarios

- **ITEM_NOT_FOUND**: Referenced item does not exist
- **STORAGE_LOCATION_NOT_FOUND**: Referenced storage location does not exist
- **REASON_CODE_REQUIRED**: No reason code was provided
- **SCRAP_QUANTITY_MUST_BE_NEGATIVE**: SCRAP type adjustment must have a negative quantityDelta
- **LOT_NOT_FOUND**: Referenced lot does not exist
- **SERIAL_NUMBER_NOT_FOUND**: Referenced serial number does not exist

## Test Cases

- returns error when item not found
- returns error when location not found
- returns error when reason code missing
- returns error when SCRAP type with positive quantityDelta
- returns error when lot not found
- returns error when serial number not found
- creates CORRECTION adjustment with positive quantityDelta
- creates CORRECTION adjustment with negative quantityDelta
- creates SCRAP adjustment with negative quantityDelta
- creates adjustment linked to inventory count
- defaults adjustmentType to CORRECTION when not specified
