Documentation / Stock Movement

Stock Movement System

Understanding the automated decision tree system for stock movements and inventory processes.

Overview

The Stock Movement System is the core of the Inventory Service, implementing a sophisticated decision tree that automatically validates and processes storage unit movements based on business rules and process types.

Decision Tree Architecture

The system uses the StockMovementDecisionTree service to process movement requests through a series of validation and execution steps.

Key Components

  • Start/End Steps: Control flow entry and exit points
  • Validation Steps: Business rule and data integrity checks
  • Process Steps: Specific logic for different process types
  • Routing Steps: Decision points that determine the next action

Step Categories

Decision Tree Flow: ├── START_DECISION_TREE ├── Validation Steps │ ├── CHECK_PROCESS_TYPE │ ├── CHECK_WAREHOUSE_INTEGRITY │ └── CHECK_PROCESS_ALLOWED_TO_MANIPULATE_TABLES ├── Process-Specific Steps │ ├── Parcel Process Steps │ │ ├── CHECK_PARCEL_PROCESS_METHOD │ │ ├── CHECK_EXACT_LOT_NUMBERS_QUANTITY │ │ └── CHECK_FULL_STORAGE_QUANTITY │ └── Simple Process Steps │ ├── CHECK_IF_ORIGIN_IS_EXTERNAL │ ├── CHECK_QUANTITY_IN_EXACT_LOCATION │ └── CHECK_WAITING_RESERVATIONS └── END_DECISION_TREE

Process Validation

Warehouse Integrity Checks

The system validates that:

  • Source and destination locations exist
  • Warehouse permissions allow the operation
  • Product associations are valid
  • Location capacity constraints are respected

Process Type Validation

Each process type has specific validation rules:

BATCH_PROCESS: - Origin must be EXTERNAL - Destination: ACTIVE_STORAGE, SCRAP, or PUFFER - Lot information may be required PARCEL_PROCESS: - Origin: ACTIVE_STORAGE or PUFFER - Destination: RESERVED - Requires parcel_id and method - May require exact lot numbers PICKING_PROCESS: - Origin: RESERVED - Destination: PICKING - Requires picker_id and workflow_id PACKING_PROCESS: - Origin: PICKING - Destination: PACKING - Requires packing_point_id

Lot Number Processing

Exact Lot Numbers Method

When using the EXACT_LOT_NUMBERS_METHOD, the system:

  • Validates that specified lot numbers exist
  • Checks available quantities for each lot
  • Ensures total requested quantity matches lot quantities
  • Verifies lot expiration dates if applicable

FIFO/FEFO Processing

For automatic lot selection:

  • FIFO: First In, First Out based on creation dates
  • FEFO: First Expiry, First Out based on expiration dates
  • Automatic quantity allocation across multiple lots
  • Partial lot consumption handling

Transaction Management

Storage Transactions

The system maintains transaction records for each movement:

{ "product_id": 123, "process_type": "BATCH_PROCESS", "quantity": 100, "flow": "IN", "open": 0, "close": 100, "warehouse_id": 456, "location_id": 789 }

State Management

Each step in the decision tree maintains state information:

  • Current step in the process
  • Validation results
  • Error conditions and warnings
  • Processing status

Error Handling

Decision Tree Errors

Error responses may be returned from various decision tree steps for validation failures, business rule violations, or insufficient stock. Exact error formats not verified from controller code.

Waiting Reservations

The system handles waiting reservations when stock is temporarily unavailable:

Reservation Queue

  • Automatic queuing when stock is insufficient
  • Priority-based reservation processing
  • Automatic fulfillment when stock becomes available
  • Expiration handling for time-sensitive reservations

Reservation Fulfillment

{ "reservation_id": 456, "product_id": 123, "quantity_requested": 100, "quantity_fulfilled": 75, "status": "PARTIALLY_FULFILLED", "waiting_quantity": 25 }

Performance Optimizations

Bulk Processing

The system supports batch processing of multiple storage units in a single request to improve performance and maintain consistency.

Cache Management

  • Redis caching for frequently accessed data
  • Query optimization for large inventories
  • Efficient lot number lookups
  • Warehouse integrity caching

Integration Points

External Systems

The stock movement system integrates with:

  • Product Service: Product information and validation
  • Partners Service: Partner permissions and configurations
  • Batch Process Service: Batch processing coordination
  • Courier Services: Shipping and logistics

Event Broadcasting

The system broadcasts events for:

  • Parcel status changes
  • Stock level updates
  • Movement completions
  • Error conditions

Monitoring and Logging

Decision Tree Logging

Every step in the decision tree is logged with:

  • Step name and execution time
  • Input parameters and validation results
  • State changes and transitions
  • Error conditions and recovery actions

Performance Metrics

  • Average processing time per movement
  • Success/failure rates by process type
  • Queue lengths and processing delays
  • Resource utilization metrics