# Stock Tracking

## Overview

Stock Tracking provides real-time visibility into inventory quantities for every item at every storage location. The system maintains four core quantity types per item-location pair: on-hand (physically present), reserved (committed to outbound orders), incoming (expected from inbound orders), and blocked (unusable due to damage, recall, or other holds). Available quantity is derived as on-hand minus reserved minus blocked, giving an accurate picture of what can be promised to new demand.

Quantities are updated automatically as stock movements are processed — goods receipts increase on-hand and clear incoming, goods issues decrease on-hand, reservations shift quantity between available and reserved, and block/unblock operations shift quantity between available and blocked. Each stock level record is scoped to a specific item and storage location, enabling granular tracking down to the bin level within a warehouse.

## Business Purpose

- Provides a single source of truth for current inventory positions across all warehouses and locations
- Enables accurate available-to-promise calculations by separating on-hand from reserved and blocked quantities
- Tracks incoming quantities so planners can see expected future supply without manual lookups
- Supports multi-location visibility, allowing businesses to locate stock across warehouses, zones, and bins
- Drives downstream decisions in sales (order promising), purchasing (reorder triggers), and manufacturing (material availability)
- Maintains quantity accuracy through automatic updates from stock movements, eliminating manual ledger maintenance
- Supports multi-unit-of-measure scenarios via UoM conversions from the primitives module

## Process Flow

```mermaid
flowchart TD
    A[Stock Movement Executed] --> B{Movement Type}
    B -->|Goods Receipt| C[Increase On-Hand at Destination]
    C --> C2[Decrease Incoming]
    B -->|Goods Issue| D[Decrease On-Hand at Source]
    B -->|Transfer| E[Decrease On-Hand at Source]
    E --> F[Increase On-Hand at Destination]
    B -->|Reservation| G[Increase Reserved]
    B -->|Reservation Release| H[Decrease Reserved]
    B -->|Block| BL[Increase Blocked]
    B -->|Unblock| UB[Decrease Blocked]
    C2 --> I[Recalculate Available Qty]
    D --> I
    F --> I
    G --> I
    H --> I
    BL --> I
    UB --> I
    I --> J[Available = On-Hand - Reserved - Blocked]
    J --> K[Stock Level Updated]
```

## Scenario Patterns

- **Basic Stock Inquiry**: A warehouse operator checks the on-hand and available quantity of an item at a specific bin location before picking
- **Available-to-Promise Check**: Sales checks available quantity (on-hand minus reserved minus blocked) across all locations to determine if a new order can be fulfilled
- **Incoming Visibility**: A planner reviews incoming quantities to understand when expected purchase orders will replenish stock at a given warehouse
- **Reservation Lifecycle**: A sales order reserves quantity, reducing available stock; upon shipment the reservation is released and on-hand is decremented via goods issue
- **Multi-Location Lookup**: A transfer planner queries stock levels across multiple warehouses to identify the best source location for an internal transfer
- **Stock Blocking**: A quality inspector or warehouse manager blocks a quantity of stock at a location due to damage, recall, or suspected defect; the blocked quantity is excluded from available stock and cannot be reserved or issued
- **Stock Unblocking**: After investigation, blocked stock is released back to available inventory via an unblock operation
- **Zero-Stock Detection**: The system identifies item-location pairs where available quantity has dropped to zero, signaling potential stockout risk
- **UoM-Aware Tracking**: Stock is tracked in the item's base UoM; queries can request quantities converted to alternative UoMs using primitives module conversions

## Test Cases

- Stock level record is created per unique item-location pair on first movement
- On-hand quantity increases when a goods receipt is processed for the item-location
- On-hand quantity decreases when a goods issue is processed for the item-location
- Incoming quantity increases when an inbound order is confirmed and decreases when the corresponding goods receipt is processed
- Reserved quantity increases when stock is reserved and decreases when the reservation is released or fulfilled
- Blocked quantity increases when stock is blocked and decreases when stock is unblocked
- Available quantity always equals on-hand minus reserved minus blocked
- Available quantity cannot go negative — reservation must be rejected if it would exceed available (on-hand minus reserved minus blocked)
- Block operation must be rejected if the requested quantity would exceed available (on-hand minus reserved minus currently blocked)
- Stock levels are tracked independently per storage location; a transfer decreases one location and increases another
- Warehouse-level aggregation correctly sums quantities across all storage locations within the warehouse
- Cross-warehouse query correctly sums quantities across all warehouses
- Stock level quantities are stored in the item's base unit of measure
- Concurrent stock movements to the same item-location produce correct final quantities (no lost updates)
- Stock level record persists with zero quantities rather than being deleted, preserving location history

## Reference Links

- [SAP Inventory Management — Stock Overview](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/f18f0acdc5f04a35badc70e96e8d4549/4f36a7addfae4f32e10000000a11466f.html)
- [Oracle Inventory — On-Hand Quantity](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/25a/famoh/inventory-on-hand-balances.html)
- [NetSuite Inventory Management](https://www.netsuite.com/portal/resource/articles/inventory-management/inventory-management.shtml)
