# AssignSerialNumber

## Permission Scope

inventoryMaster

## Overview

assignSerialNumber assigns a unique serial number to an individual unit at goods receipt or production completion. The serial number is created in AVAILABLE state and is associated with a specific item and storage location. Serial numbers enable tracking of individual units throughout their lifecycle.

## Business Rules

- serialNumber is required and must be unique per item
- itemId is required and must reference an existing item
- storageLocationId is required and must reference an existing storage location (where the unit is received)
- Quantity is always 1 (serial numbers track individual units)
- Serial number is created in AVAILABLE state
- The same serial number value can be used for different items

## Process Flow

```mermaid
flowchart TD
    A[Receive assign 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{Serial unique for item?}
    F -->|No| G[Return error: DUPLICATE_SERIAL_NUMBER]
    F -->|Yes| H[Create serial number in AVAILABLE state]
    H --> I[Return created serial number]
```

## 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
- **DUPLICATE_SERIAL_NUMBER**: A serial number with the same value already exists for this item

## Test Cases

- returns error when item not found
- returns error when location not found
- returns error when serial already exists for item
- assigns serial in AVAILABLE state
- allows same serial number for different items
