# CreateUnit

## Permission Scope

unit

## Overview

CreateUnit adds a new unit of measure to an existing category with its symbol, display name, and conversion factor relative to the category's reference unit. The conversion factor defines how many reference units equal one of this unit.

This command supports adding industry-specific units (like "Pallet" or "Roll"), regional units (metric and imperial), and precision units for specialized tracking.

## Business Rules

- Target category must exist and be active
- Unit symbol must be unique within the category
- Unit symbol is required and typically 1-5 characters
- Conversion factor must be a positive decimal number (greater than zero)
- Rounding precision must be a non-negative integer
- New units are created as non-reference units (only one reference unit per category)
- The conversion formula is: `quantity_in_reference = quantity_in_this_unit × conversion_factor`

## Process Flow

```mermaid
flowchart TD
    A[Receive create unit request] --> B{Category exists and active?}
    B -->|No| C[Return error: invalid category]
    B -->|Yes| D{Symbol provided?}
    D -->|No| E[Return error: missing symbol]
    D -->|Yes| F{Symbol unique in category?}
    F -->|No| G[Return error: duplicate symbol]
    F -->|Yes| H{Conversion factor > 0?}
    H -->|No| I[Return error: invalid conversion factor]
    H -->|Yes| J{Rounding precision valid?}
    J -->|No| K[Return error: invalid rounding precision]
    J -->|Yes| L[Create unit record]
    L --> M[Link unit to category]
    M --> N[Return created unit]
```

## External Dependencies

- None

## Error Scenarios

- **UOM_CATEGORY_NOT_FOUND**: Specified UoM category does not exist
- **CATEGORY_NOT_ACTIVE**: Category is inactive
- **DUPLICATE_UNIT_SYMBOL**: Unit with same symbol already exists in category
- **INVALID_CONVERSION_FACTOR**: Factor is zero, negative, or not a valid number
- **INVALID_ROUNDING_PRECISION**: Precision is negative

## Test Cases

- throws when category doesn't exist
- throws when category is inactive
- throws when symbol already exists in category
- throws when conversion factor is not positive
- throws when rounding precision is negative
- creates unit successfully
- passes custom fields through to insert