# 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 when InventoryLedger entries are created (which occurs via atomic commands — receiveStock, issueStock — or via confirmStockAdjustment and confirmStockAdjustment) — goods receipts increase on-hand and clear incoming, goods issues decrease on-hand, corrections apply deltas, scrap decreases 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 per-location tracking within a Site.

## Business Purpose

- Provides a single source of truth for current inventory positions across all sites 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 sites and their storage locations
- Drives downstream decisions in sales (order promising), purchasing (reorder triggers), and manufacturing (material availability)
- Maintains quantity accuracy through automatic updates triggered by InventoryLedger entries (created by atomic commands such as receiveStock/issueStock and by confirmStockAdjustment), eliminating manual ledger maintenance
- Supports multi-unit-of-measure scenarios via UoM conversions from the primitives module

## Process Flow

```mermaid
flowchart TD
    A[Atomic command / confirmStockAdjustment] --> A1[InventoryLedger Created]
    A1 --> B{Source Type}
    B -->|GOODS_RECEIPT| C[Increase On-Hand at Destination]
    C --> C2[Decrease Incoming]
    B -->|GOODS_ISSUE| D[Decrease On-Hand at Source]
    B -->|CORRECTION| CR[Apply quantity delta]
    B -->|SCRAP| SC[Decrease On-Hand at Source]
    B -->|BLOCK| BL[Increase Blocked]
    B -->|UNBLOCK| UB[Decrease Blocked]
    A2[Reservation Command] --> G[Increase Reserved]
    A3[Reservation Release] --> H[Decrease Reserved]
    C2 --> I[Recalculate Available Qty]
    D --> I
    CR --> I
    SC --> 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**: An operator checks the on-hand and available quantity of an item at a specific storage 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 site
- **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 planner queries stock levels across multiple sites to identify stock positions
- **Stock Blocking**: A quality inspector or site 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 InventoryLedger
- On-hand quantity increases when a GOODS_RECEIPT InventoryLedger is created for the item-location
- On-hand quantity decreases when a GOODS_ISSUE InventoryLedger is created 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
- Site-level aggregation correctly sums quantities across all storage locations within the site
- Cross-site query correctly sums quantities across all sites
- 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)
