# CreateProduct

## Permission Scope

product

## Overview

createProduct establishes a new product in DRAFT status with a unique code, name, optional description, and unit of measure reference. Products are the commercial representation of a product and serve as the parent entity for variant generation. All products start in DRAFT to allow review and attribute configuration before activation.

## Business Rules

- Product code is required, must be globally unique across all products, and is immutable after creation
- Product name is required and must be non-empty
- UoM is required and must reference an existing active Unit from the primitives module
- Products are always created in DRAFT status (not configurable)
- Description is optional

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> B{Code provided?}
    B -->|No| C[Return error: MISSING_REQUIRED_FIELD]
    B -->|Yes| D{Code unique?}
    D -->|No| E[Return error: DUPLICATE_CODE]
    D -->|Yes| F{Name provided and non-empty?}
    F -->|No| G[Return error: MISSING_REQUIRED_FIELD]
    F -->|Yes| H{UoM valid and active?}
    H -->|No| I[Return error: INVALID_UOM]
    H -->|Yes| J[Create product in DRAFT status]
    J --> K[Return created product]
```

## External Dependencies

- [primitives::Unit](../../../primitives/docs/models/Unit.md) - Validates that the referenced UoM exists and is active

## Error Scenarios

- **DUPLICATE_CODE**: An entity with the same code already exists within the scope
- **MISSING_REQUIRED_FIELD**: One or more required fields are missing or empty
- **INVALID_UOM**: Referenced unit does not exist or is inactive

## Test Cases

- returns error when code is empty
- returns error when name is empty
- returns error when code already exists
- returns error when UoM is invalid
- creates product in DRAFT status
- passes custom fields through
