# Warehouse Management

## Overview

Warehouse Management defines the operational storage structure within an organization's physical facilities. A Warehouse represents a logical storage facility linked to an organizational Site, while StorageLocations (zones and bins) describe the internal layout within that warehouse. The organization module owns the Site entity (physical facility identity and address); the inventory module owns Warehouse and StorageLocation entities that layer operational storage concerns on top of a Site.

Each warehouse tracks storage-relevant attributes such as storage conditions, capacity constraints, and operational status. StorageLocations form a tree hierarchy within a warehouse with a maximum depth of three levels: Warehouse → Zone → Bin. Zones group related areas (e.g., cold storage, bulk storage) and are direct children of the warehouse (parentId is null). Bins identify individual addressable slots where stock is placed and must reference a parent zone. Each StorageLocation carries a locationType of either 'zone' or 'bin'.

Zone/bin management is optional. When granular location tracking is not needed, a warehouse with a single zone (and no bins) is sufficient for flat inventory operations. All other inventory features (stock tracking, stock movement, lot tracking, serial number tracking) reference StorageLocation.id as the spatial axis — stock quantities, lots, and serial numbers are always associated with a StorageLocation, never directly with a Warehouse.

## Business Purpose

Warehouses and storage locations serve as the spatial backbone for all inventory operations:

- Map operational storage structures onto company-owned Sites, separating facility identity (organization) from storage layout (inventory)
- Enable multi-warehouse operations across sites, supporting distributed inventory strategies
- Provide granular bin-level addressing for stock placement and retrieval
- Classify storage zones by condition (ambient, cold, hazardous) to enforce proper item placement
- Track capacity at the warehouse and bin level to prevent over-storage and guide putaway decisions
- Support stock movement routing by providing source and destination locations for transfers, receipts, and issues
- Enable inventory counts and cycle counts scoped to specific zones or bins

The lifecycle ensures:

- Warehouses and storage locations are either ACTIVE (available for inventory operations) or INACTIVE (closed to new movements but preserved for historical records)
- Deactivating a warehouse prevents new stock movements while retaining all historical transaction data
- Storage locations can be individually deactivated without affecting the parent warehouse

## Process Flow

Warehouse and storage location setup follows a top-down configuration pattern:

```mermaid
flowchart TD
    A[Select Organizational Site] --> B[Create Warehouse]
    B --> C[Define Warehouse Attributes]
    C --> D[Create Zones within Warehouse]
    D --> E[Create Bins within Zones]
    E --> F[Warehouse Ready for Operations]
    F --> G{Zone/Bin no longer needed?}
    G -->|Yes| H[Deactivate StorageLocation]
    G -->|No| I[Continue Operations]
    H --> J{Reopen location?}
    J -->|Yes| K[Reactivate StorageLocation]
    J -->|No| L[Location remains INACTIVE]
```

Warehouse lifecycle management:

```mermaid
stateDiagram-v2
    [*] --> Active: createWarehouse
    Active --> Inactive: deactivateWarehouse
    Inactive --> Active: reactivateWarehouse
```

## Scenario Patterns

- **Flat Warehouse Setup**: A small business creates a warehouse with a single zone and no bins. All stock movements and inventory tracking reference this single zone as the location. This is sufficient when granular bin-level tracking is not needed
- **New Distribution Center Setup**: A company opens a new distribution site and creates a warehouse linked to that site. Zones are defined for receiving, bulk storage, picking, and shipping. Bins are created within each zone to provide addressable storage slots for inventory placement
- **Cold Chain Warehouse**: A food distributor creates a warehouse with cold-storage zones maintained at specific temperature conditions. Items requiring refrigeration are directed to bins within these zones, ensuring compliance with storage requirements
- **Multi-Warehouse Site**: A large manufacturing site operates multiple warehouses — one for raw materials, one for finished goods, and one for spare parts. Each warehouse is linked to the same site but has distinct zones and bin structures tailored to its purpose
- **Warehouse Consolidation**: A company closes a regional warehouse by deactivating it after transferring all remaining stock to another facility. Historical movement records at the deactivated warehouse remain intact for audit purposes
- **Zone Expansion**: An existing warehouse adds a new storage zone to accommodate increased inventory volume. New bins are created within the zone and immediately become available for stock placement
- **Bin Deactivation for Maintenance**: A bin or zone is temporarily deactivated for maintenance or reconfiguration. No new stock can be placed there, but existing records and historical movements are preserved. Once maintenance completes, the location is reactivated
- **Hazardous Materials Segregation**: A warehouse designates a specific zone for hazardous materials with appropriate storage condition classification, ensuring regulated items are stored separately from general inventory

## Test Cases

- A warehouse must reference an existing, ACTIVE site via siteId
- A warehouse name is required and unique within the same site
- Warehouse lifecycle follows ACTIVE <-> INACTIVE state machine
- Deactivating a warehouse prevents new stock movements to/from that warehouse
- Deactivating a warehouse does not delete or modify historical stock movement records
- A storage location must reference an existing, ACTIVE warehouse via warehouseId
- Each storage location has a locationType of 'zone' or 'bin'
- A zone must be a direct child of the warehouse (parentId is null)
- A bin must reference a parent zone within the same warehouse (parentId is a zone's id)
- A bin cannot be a direct child of the warehouse; it must belong to a zone
- Storage location name or code is required and unique within the same warehouse
- Storage location lifecycle follows ACTIVE <-> INACTIVE state machine independently of its parent warehouse
- Deactivating a zone does not automatically deactivate its child bins (explicit deactivation required)
- Reactivating a storage location is only permitted if its parent warehouse is ACTIVE
- A warehouse cannot be created under an INACTIVE or non-existent site
- Multiple warehouses can exist for the same site
- Storage condition classification (e.g., ambient, cold, hazardous) can be assigned to a warehouse or zone
- Capacity attributes can be set on a warehouse or bin 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
- [Stock Movement](./stock-movement.md) — uses StorageLocations as source and destination for goods flow
- [Odoo Warehouses and Locations](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/inventory/warehouses_storage.html)
- [SAP Warehouse Structure](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/f1a0da84007f4621a36cf73cd38ee3d0/c4a850def48411d1a7020000e829fd11.html)
- [Oracle Warehouse Management](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/25a/famwm/warehouse-management.html)
- [Dynamics 365 Warehouse Configuration](https://learn.microsoft.com/en-us/dynamics365/supply-chain/warehousing/warehouse-configuration)
