Storage Unit Snapshots - Metabox Inventory Service

Overview

Storage Unit Snapshots provide point-in-time captures of inventory states, enabling historical reporting, audit trails, and analysis of inventory changes over time.

Get Storage Unit Snapshots

Retrieves historical snapshots of storage units based on specified criteria and time ranges.

POST /api/snapshots/get-snapshots

Request Body

        {
  "ms_trace": [
    {
      "ms_signature": "snapshots-get-req-123",
      "warning_count": 0
    }
  ],
  "data": {
    "newer_than": "2024-01-01",
    "older_than": "2024-01-31",
    "product_ids": [123, 456, 789]
  }
}
    

Request Parameters

Field	Type	Required	Description
ms_trace	array	Required	Request tracing information
data.newer_than	date	Optional	Get snapshots newer than this date
data.older_than	date	Optional	Get snapshots older than this date
data.product_ids	array	Optional	Array of product IDs to filter by

Response

Returns an array of storage unit snapshots based on the specified filters. The exact response structure depends on the service implementation.

Snapshot Types

Reason	Description	Frequency
DAILY_SNAPSHOT	Automated daily inventory snapshot	Once per day at midnight
WEEKLY_SNAPSHOT	Weekly summary snapshot	Every Sunday at midnight
MONTHLY_SNAPSHOT	End-of-month inventory snapshot	Last day of each month
MANUAL_SNAPSHOT	Manually triggered snapshot	On-demand via admin interface
PROCESS_SNAPSHOT	Snapshot after major process	After bulk operations
AUDIT_SNAPSHOT	Audit trail snapshot	Before/after cycle counts

Filtering Options

Date Range Filtering

        {
  "filters": [
    {
      "field": "snapshot_date",
      "operator": ">=",
      "value": "2024-01-01T00:00:00Z"
    },
    {
      "field": "snapshot_date",
      "operator": "<=",
      "value": "2024-01-31T23:59:59Z"
    }
  ]
}
    

Product-Specific Snapshots

        {
  "filters": [
    {
      "field": "product_id",
      "operator": "=",
      "value": 123
    }
  ]
}
    

Location-Based Filtering

        {
  "filters": [
    {
      "field": "location_id",
      "operator": "IN",
      "value": [321, 322, 323]
    }
  ]
}
    

Quantity Analysis

        {
  "filters": [
    {
      "field": "quantity",
      "operator": ">",
      "value": 0
    },
    {
      "field": "available_quantity",
      "operator": "<",
      "value": 10
    }
  ]
}
    

Snapshot Data Structure

Field	Type	Description
id	integer	Unique snapshot identifier
storage_unit_id	integer	ID of the storage unit at snapshot time
storage_unit_type	string	Type of storage unit (active, reserved, scrap, etc.)
quantity	integer	Total quantity at snapshot time
reserved_quantity	integer	Quantity reserved for orders
available_quantity	integer	Available quantity (total - reserved)
snapshot_date	datetime	When the snapshot was taken
snapshot_reason	string	Reason for taking the snapshot

Snapshot Creation Process

Snapshots are created through the CreateStockSnapshot job, which:

Captures current state of all storage units
Records quantity, location, and status information
Maintains relationships to products, lots, and locations
Applies data retention policies automatically
Ensures consistency across related storage units

Automated Scheduling

Snapshots are automatically scheduled using Laravel's task scheduler:

Daily: 12:00 AM UTC
Weekly: Sunday 12:00 AM UTC
Monthly: Last day of month, 11:59 PM UTC

Performance Considerations

Large Dataset Handling

Use pagination for large result sets
Apply date range filters to reduce data volume
Consider using warehouse-specific queries
Utilize indexing on snapshot_date and warehouse_id

Data Retention

Daily snapshots retained for 3 months
Weekly snapshots retained for 1 year
Monthly snapshots retained for 7 years
Audit snapshots retained indefinitely

Service Implementation

Snapshot operations are handled by the GetSnapshots service class, which provides:

Advanced filtering capabilities
Optimized queries for large datasets
Relationship loading for detailed reports
Export functionality for external analysis

Error Responses

Validation Errors

Standard Laravel validation error responses may be returned for missing or invalid required fields. Exact formats not verified from controller code.

Business Logic Errors

Additional error responses may be returned for business rule violations such as invalid date ranges or overly broad queries. Exact error formats not verified from controller code.