# Inventory Data Model

Entity relationships and database schema for the inventory module.

## Entity Relationship Overview

```
Store 1──* Inventory *──1 Product
                │
                └──* InventoryTransaction
                         │
                         └──? Order (for reserve/fulfill/release)
```

## Models

### Inventory

Stock quantities at warehouse bin locations. Supports multi-location inventory with reservation tracking.

| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| `id` | Integer | PK | Primary key |
| `product_id` | Integer | FK, not null, indexed | Product reference |
| `store_id` | Integer | FK, not null, indexed | Store reference |
| `warehouse` | String | not null, default "strassen", indexed | Warehouse identifier |
| `bin_location` | String | not null, indexed | Bin code (e.g., "SA-10-02") |
| `quantity` | Integer | not null, default 0 | Total quantity at bin |
| `reserved_quantity` | Integer | default 0 | Reserved/allocated quantity |
| `gtin` | String | indexed | GTIN reference (duplicated for reporting) |
| `created_at` | DateTime | tz-aware | Record creation time |
| `updated_at` | DateTime | tz-aware | Record update time |

**Unique Constraint**: `(product_id, warehouse, bin_location)`
**Composite Indexes**: `(store_id, product_id)`, `(warehouse, bin_location)`

**Key Property**: `available_quantity` = max(0, quantity - reserved_quantity)

### InventoryTransaction

Complete audit trail for all stock movements with before/after snapshots.

| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| `id` | Integer | PK | Primary key |
| `store_id` | Integer | FK, not null, indexed | Store reference |
| `product_id` | Integer | FK, not null, indexed | Product reference |
| `inventory_id` | Integer | FK, nullable, indexed | Inventory record reference |
| `transaction_type` | Enum | not null, indexed | Type of stock movement |
| `quantity_change` | Integer | not null | Change amount (+ add, - remove) |
| `quantity_after` | Integer | not null | Quantity snapshot after transaction |
| `reserved_after` | Integer | not null, default 0 | Reserved quantity snapshot |
| `location` | String | nullable | Location context |
| `warehouse` | String | nullable | Warehouse context |
| `order_id` | Integer | FK, nullable, indexed | Related order |
| `order_number` | String | nullable | Order number for display |
| `reason` | Text | nullable | Human-readable reason |
| `created_by` | String | nullable | User/system identifier |
| `created_at` | DateTime | not null, indexed | Timestamp (UTC) |

**Composite Indexes**: `(store_id, product_id)`, `(store_id, created_at)`, `(transaction_type, created_at)`

## Enums

### TransactionType

| Value | Description |
|-------|-------------|
| `reserve` | Stock reserved for order |
| `fulfill` | Reserved stock consumed (shipped) |
| `release` | Reserved stock released (cancelled) |
| `adjust` | Manual adjustment (+/-) |
| `set` | Set to exact quantity |
| `import` | Initial import/sync |
| `return` | Stock returned from customer |

## Design Patterns

- **Multi-location**: Inventory tracked per warehouse + bin location
- **Reservation system**: Separate quantity and reserved_quantity for order holds
- **Full audit trail**: Every stock change recorded with before/after snapshots
- **Order integration**: Transactions linked to orders for reserve/fulfill/release cycle