157 lines
4.5 KiB
Markdown
157 lines
4.5 KiB
Markdown
# 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. |