docs: migrate module documentation to single source of truth
Move 39 documentation files from top-level docs/ into each module's docs/ folder, accessible via symlinks from docs/modules/. Create data-model.md files for 10 modules with full schema documentation. Replace originals with redirect stubs. Remove empty guide stubs. Modules migrated: tenancy, billing, loyalty, marketplace, orders, messaging, cms, catalog, inventory, hosting, prospecting. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
82
app/modules/inventory/docs/data-model.md
Normal file
82
app/modules/inventory/docs/data-model.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user