# CreateSite

## Permission Scope

organizationUnit

## Overview

CreateSite establishes a new physical facility for a company in ACTIVE status. Each site has a name, type classification, structured address, country, and timezone. Sites are created ready for operational use with no DRAFT state.

This command supports facility registration for warehouses, offices, stores, factories, and distribution centers.

## Business Rules

- Site name is required and must be non-empty
- Site name must be unique within the same company
- Site type is required and must be one of: OFFICE, WAREHOUSE, STORE, FACTORY, DISTRIBUTION_CENTER
- companyId is required and references an existing ACTIVE company
- Structured address fields (street, city, postalCode, country) are required
- State/province is optional
- Country must be a valid country code
- Timezone is required and must be a valid IANA timezone identifier
- Site is always created in ACTIVE status
- companyId is immutable after creation

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> B{Validate name and type}
    B -->|Invalid| C[Return error: INVALID_NAME or INVALID_TYPE]
    B -->|Valid| D{Company exists and ACTIVE?}
    D -->|No| E[Return error: COMPANY_NOT_FOUND or COMPANY_INACTIVE]
    D -->|Yes| F{Name unique in company?}
    F -->|No| G[Return error: DUPLICATE_NAME]
    F -->|Yes| H{Address fields complete?}
    H -->|No| I[Return error: MISSING_REQUIRED_FIELDS]
    H -->|Yes| J{Valid country code?}
    J -->|No| K[Return error: INVALID_COUNTRY]
    J -->|Yes| L{Valid timezone?}
    L -->|No| M[Return error: INVALID_TIMEZONE]
    L -->|Yes| N[Create site record]
    N --> O[Set status: ACTIVE]
    O --> P[Return created site]
```

## External Dependencies

- None

## Error Scenarios

- **INVALID_NAME**: Name is empty, whitespace-only, or not provided
- **INVALID_TYPE**: Site type is not one of the allowed classifications
- **COMPANY_NOT_FOUND**: Specified company ID does not exist
- **COMPANY_INACTIVE**: Referenced company is not in ACTIVE status
- **DUPLICATE_NAME**: Site with same name already exists in the same company
- **MISSING_REQUIRED_FIELDS**: One or more required fields are missing or empty
- **INVALID_COUNTRY**: Country code is not a valid country code
- **INVALID_TIMEZONE**: Timezone is not a valid IANA timezone identifier

## Test Cases

- creates site in ACTIVE status
- throws when name is empty
- throws when type is invalid
- throws when company does not exist
- throws when company is not ACTIVE
- throws when site name already exists in same company
- allows same site name in different companies
- throws when address street is missing
- throws when address city is missing
- throws when address postalCode is missing
- throws when address country is missing
- creates site without state/province
- creates site with state/province
- throws when country code is invalid
- throws when timezone is invalid