# Location Management

## Overview

Location Management defines the operational storage structure within an organization's physical facilities. The organization module owns the Site entity (physical facility identity and address); the inventory module owns the StorageLocation entity, which belongs directly to a Site. The inventory module deliberately keeps this 2-tier — Site → StorageLocation — without an intermediate "warehouse" layer.

A StorageLocation is a named type where stock is held. StorageLocations under a single Site are peers: a site may have one (e.g., a flat single-type setup) or many (e.g., "Receiving Dock A", "Main Shelf", "Quarantine Area", "Shipping Area"). StorageLocations are deliberately flat — zone/bin hierarchy is not modeled in the schema. Logical grouping of related locations, when needed, is expressed by naming conventions or by application-specific custom fields on StorageLocation.

All other inventory features (stock tracking, stock movement) reference StorageLocation.id as the spatial axis — stock quantities are always associated with a StorageLocation, never directly with a Site.

## Business Purpose

Storage locations serve as the spatial backbone for all inventory operations:

- Map operational storage types onto company-owned Sites, keeping facility identity (organization) separate from storage layout (inventory)
- Enable multi-location operations within a site, supporting distributed inventory within a single facility
- Classify locations by storage condition (ambient, cold, hazardous) to enforce proper item placement
- Track capacity at the location level to prevent over-storage
- Support stock movement routing by providing source and destination locations for transfers, receipts, and issues
- Enable stock adjustments scoped to specific locations

The lifecycle ensures:

- Storage locations are either ACTIVE (available for inventory operations) or INACTIVE (closed to new movements but preserved for historical records)
- Storage locations can be deactivated and reactivated independently as operational needs change
- Historical transaction data survives location deactivation

## Process Flow

Storage location setup:

```mermaid
flowchart TD
    A[Select Organizational Site] --> B[Create StorageLocation]
    B --> C[Define Location Attributes: condition, capacity]
    C --> D[Location Ready for Operations]
    D --> E{Location no longer needed?}
    E -->|Yes| F[Deactivate StorageLocation]
    E -->|No| G[Continue Operations]
    F --> H{Reopen location?}
    H -->|Yes| I[Reactivate StorageLocation]
    H -->|No| J[Location remains INACTIVE]
```

Storage location lifecycle:

```mermaid
stateDiagram-v2
    [*] --> Active: createStorageLocation
    Active --> Inactive: deactivateStorageLocation
    Inactive --> Active: reactivateStorageLocation
```

## Scenario Patterns

- **Single-Location Site**: A site operates with a single StorageLocation. All stock movements and inventory tracking reference this location
- **Functional Peer Locations**: A distribution site has separate StorageLocations for receiving, main storage, picking, and shipping. Movement between functional areas is modeled as transfers via StockAdjustment (CORRECTION)
- **Cold Chain Handling**: A food distributor creates StorageLocations with `storageCondition=cold`; items requiring refrigeration are directed to those locations to meet storage requirements
- **Hold Location Strategy**: Goods can be isolated by routing them to a dedicated hold location and transferring them to main storage once released
- **Hazardous Materials Segregation**: A site designates StorageLocations for hazardous materials with `storageCondition=hazardous` so regulated items are tracked separately from general inventory
- **Location Consolidation**: A company closes an unused location by deactivating it after transferring all remaining stock. Historical records at the deactivated location remain intact for audit purposes
- **Temporary Maintenance**: A location is temporarily deactivated for maintenance; existing records and historical movements are preserved, and the location is reactivated once maintenance completes

## Test Cases

- A storage location must reference an existing, ACTIVE site via siteId
- Storage location name is required and unique within the same site
- Storage location code, when provided, is unique within the same site
- Storage location lifecycle follows ACTIVE <-> INACTIVE state machine
- Deactivating a storage location prevents new stock placement at that location
- Deactivating a storage location does not delete or modify historical stock records
- Reactivating a storage location is only permitted if its parent Site is ACTIVE
- A storage location cannot be created under an INACTIVE or non-existent site
- Multiple storage locations can exist for the same site
- Storage condition classification (e.g., ambient, cold, hazardous) can be assigned to a location
- Capacity attribute can be set on a location to track storage limits
- Attempting to place stock into an INACTIVE storage location is rejected

## Reference Links

- [Stock Tracking](./stock-tracking.md) — tracks quantities per item per StorageLocation and uses StorageLocations as source and destination for goods flow