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:
2026-03-08 23:38:37 +01:00
parent 2287f4597d
commit f141cc4e6a
140 changed files with 19921 additions and 17723 deletions

View 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