# CreateCategory

## Permission Scope

category

## Overview

CreateCategory establishes a new unit of measure category that groups related units where conversions are meaningful. Each category must have a designated reference unit that serves as the base for all conversion calculations within that category. The reference unit is created simultaneously with the category and has a conversion factor of 1.0.

This command supports initial system setup with standard categories (Unit, Weight, Volume, Length, Time) and business-specific category creation.

## Business Rules

- Category name must be unique across all categories (active and inactive)
- Category name is required and must be non-empty
- Reference unit must be specified at category creation time
- Reference unit is created with conversion factor of 1.0
- New categories are created in Active status by default
- Category cannot exist without at least one unit (the reference unit)

## Process Flow

```mermaid
flowchart TD
    A[Receive create category request] --> B{Category name provided?}
    B -->|No| C[Return error: missing name]
    B -->|Yes| D{Category name unique?}
    D -->|No| E[Return error: duplicate name]
    D -->|Yes| F{Reference unit specified?}
    F -->|No| G[Return error: missing reference unit]
    F -->|Yes| H[Create category record]
    H --> I[Create reference unit with factor 1.0]
    I --> J[Link reference unit to category]
    J --> K[Set category status: Active]
    K --> L[Return created category with reference unit]
```

## External Dependencies

- None

## Error Scenarios

- **DUPLICATE_CATEGORY_NAME**: Category with same name already exists

## Test Cases

- throws when category name already exists
- creates category with reference unit
- passes custom fields through to insert