# 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

```json
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

```json
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

```json
{
  "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.