# CreateStorageLocation

## Permission Scope

location

## Overview

createStorageLocation establishes a new storage location (zone or bin) within a warehouse. Zones are top-level divisions within a warehouse, while bins are subdivisions within a zone. This hierarchy enables granular stock tracking and placement.

## Business Rules

- warehouseId is required and must reference an existing ACTIVE warehouse
- locationType is required and must be either 'zone' or 'bin'
- For zones: parentId must be null
- For bins: parentId is required and must reference a zone in the same warehouse
- Name and code must be unique within the warehouse
- storageCondition and capacity are optional

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> B{Warehouse exists?}
    B -->|No| C[Return error: WAREHOUSE_NOT_FOUND]
    B -->|Yes| D{Warehouse ACTIVE?}
    D -->|No| E[Return error: WAREHOUSE_INACTIVE]
    D -->|Yes| F{Valid locationType?}
    F -->|No| G[Return error: INVALID_LOCATION_TYPE]
    F -->|Yes| H{locationType is bin?}
    H -->|Yes| I{parentId provided?}
    I -->|No| J[Return error: PARENT_ZONE_NOT_FOUND]
    I -->|Yes| K{Parent exists and is a zone?}
    K -->|No - not zone| L[Return error: PARENT_NOT_A_ZONE]
    K -->|No - not found| J
    K -->|Yes| M{Parent in same warehouse?}
    M -->|No| N[Return error: PARENT_IN_DIFFERENT_WAREHOUSE]
    M -->|Yes| O{Name/code unique in warehouse?}
    H -->|No| O
    O -->|No| P[Return error: DUPLICATE_LOCATION_NAME]
    O -->|Yes| Q[Create storage location]
    Q --> R[Return created location]
```

## External Dependencies

- None (internal warehouse reference via [Warehouse](../models/Warehouse.md))

## Error Scenarios

- **WAREHOUSE_NOT_FOUND**: Referenced warehouse does not exist
- **WAREHOUSE_INACTIVE**: Referenced warehouse is not in ACTIVE status
- **INVALID_LOCATION_TYPE**: locationType is not 'zone' or 'bin'
- **PARENT_ZONE_NOT_FOUND**: Bin's parent zone does not exist
- **PARENT_NOT_A_ZONE**: Parent location is a bin, not a zone
- **PARENT_IN_DIFFERENT_WAREHOUSE**: Parent zone belongs to a different warehouse
- **DUPLICATE_LOCATION_NAME**: A location with the same name or code already exists in the warehouse

## Test Cases

- returns error when warehouse not found
- returns error when warehouse inactive
- returns error when invalid location type
- returns error when bin has no parent
- returns error when bin parent is another bin
- returns error when parent zone is in different warehouse
- returns error when location name already exists
- creates zone with null parentId
- creates bin with parent zone
- creates location with storage condition
