apskel-pos-backend/PRODUCT_STOCK_MANAGEMENT.md

Product Stock Management

This document explains the new product stock management functionality that allows automatic inventory record creation when products are created or updated.

Features

1. Automatic Inventory Creation: When creating a product, you can automatically create inventory records for all outlets in the organization
2. Initial Stock Setting: Set initial stock quantity for all outlets
3. Reorder Level Management: Set reorder levels for all outlets
4. Bulk Inventory Updates: Update reorder levels for all existing inventory records when updating a product

API Usage

Creating a Product with Stock Management

POST /api/v1/products
{
  "category_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Premium Coffee",
  "description": "High-quality coffee beans",
  "price": 15.99,
  "cost": 8.50,
  "business_type": "restaurant",
  "is_active": true,
  "variants": [
    {
      "name": "Large",
      "price_modifier": 2.00,
      "cost": 1.00
    }
  ],
  "initial_stock": 100,
  "reorder_level": 20,
  "create_inventory": true
}

Parameters:

• initial_stock (optional): Initial stock quantity for all outlets (default: 0)
• reorder_level (optional): Reorder level for all outlets (default: 0)
• create_inventory (optional): Whether to create inventory records for all outlets (default: false)

Updating a Product with Stock Management

PUT /api/v1/products/{product_id}
{
  "name": "Premium Coffee Updated",
  "price": 16.99,
  "reorder_level": 25
}

Parameters:

• reorder_level (optional): Updates the reorder level for all existing inventory records

How It Works

Product Creation Flow

1. Validation: Validates product data and checks for duplicates
2. Product Creation: Creates the product in the database
3. Variant Creation: Creates product variants if provided
4. Inventory Creation (if create_inventory: true):
   • Fetches all outlets for the organization
   • Creates inventory records for each outlet with:
     • Initial stock quantity (if provided)
     • Reorder level (if provided)
   • Uses bulk creation for efficiency

Product Update Flow

1. Validation: Validates update data
2. Product Update: Updates the product in the database
3. Inventory Update (if reorder_level provided):
   • Fetches all existing inventory records for the product
   • Updates reorder level for each inventory record

Database Schema

Products Table

• Standard product fields
• No changes to existing schema

Inventory Table

• outlet_id: Reference to outlet
• product_id: Reference to product
• quantity: Current stock quantity
• reorder_level: Reorder threshold
• updated_at: Last update timestamp

Error Handling

• No Outlets: If create_inventory: true but no outlets exist, returns an error
• Duplicate Inventory: Prevents creating duplicate inventory records for the same product-outlet combination
• Validation: Validates stock quantities and reorder levels are non-negative

Performance Considerations

• Bulk Operations: Uses CreateInBatches for efficient bulk inventory creation
• Transactions: Inventory operations are wrapped in transactions for data consistency
• Batch Size: Default batch size of 100 for bulk operations

Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "category_id": "550e8400-e29b-41d4-a716-446655440002",
  "name": "Premium Coffee",
  "description": "High-quality coffee beans",
  "price": 15.99,
  "cost": 8.50,
  "business_type": "restaurant",
  "is_active": true,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "category": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "name": "Beverages"
  },
  "variants": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "name": "Large",
      "price_modifier": 2.00,
      "cost": 1.00
    }
  ],
  "inventory": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440004",
      "outlet_id": "550e8400-e29b-41d4-a716-446655440005",
      "quantity": 100,
      "reorder_level": 20
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440006",
      "outlet_id": "550e8400-e29b-41d4-a716-446655440007",
      "quantity": 100,
      "reorder_level": 20
    }
  ]
}

Migration Notes

This feature requires the existing database schema with:

• products table
• inventory table
• outlets table
• Proper foreign key relationships

No additional migrations are required as the feature uses existing tables.