- Backend: FastAPI app with all models, services, schemas, routes - Admin Panel: Next.js dashboard with all modules (CRM, POS, repairs, warranties, billing, notifications, etc.) - Ecommerce: storefront (submodule) + product catalog - AI Agents: .agents/ skill library for Antigravity IDE - Docs: architecture, billing, notification gateway markdown - Submodules: Backend/OpenWA, Ecommerce/File 2/storefront
32 lines
1.7 KiB
Markdown
32 lines
1.7 KiB
Markdown
# Inventory Management & Immutable Ledger Architecture
|
|
|
|
## Stock Bucket Calculation Formula
|
|
|
|
$$\text{Available Stock} = \text{Physical} - \text{Reserved} - \text{POSAllocated} - \text{Damaged} - \text{OtherBlocked}$$
|
|
|
|
---
|
|
|
|
## Ledger Event Semantics Matrix
|
|
|
|
Managed via `InventoryRouter.py`. Balances are calculated by summing append-only `inventory_ledger` entries.
|
|
|
|
| Ledger Event Type | Physical Change | Reserved Change | POSAllocated Change | Damaged Change | Net Available Effect |
|
|
| :--- | :---: | :---: | :---: | :---: | :---: |
|
|
| `RECEIPT` | $+1$ | $0$ | $0$ | $0$ | $+1$ |
|
|
| `ONLINE_RESERVE` | $0$ | $+1$ | $0$ | $0$ | $-1$ |
|
|
| `ONLINE_RESERVE_RELEASE` | $0$ | $-1$ | $0$ | $0$ | $+1$ |
|
|
| `ONLINE_SALE_FROM_RESERVATION` | $-1$ | $-1$ | $0$ | $0$ | $0$ *(Transition)* |
|
|
| `DIRECT_ONLINE_SALE` | $-1$ | $0$ | $0$ | $0$ | $-1$ |
|
|
| `POS_ALLOCATION` | $0$ | $0$ | $+1$ | $0$ | $-1$ |
|
|
| `POS_SALE_FROM_ALLOCATION` | $-1$ | $0$ | $-1$ | $0$ | $0$ *(Transition)* |
|
|
| `DIRECT_POS_SALE` | $-1$ | $0$ | $0$ | $0$ | $-1$ |
|
|
| `RETURN` | $+1$ | $0$ | $0$ | $0$ | $+1$ |
|
|
| `DAMAGE` | $-1$ | $0$ | $0$ | $+1$ | $-1$ |
|
|
|
|
## Sellable catalog stock (e-commerce)
|
|
|
|
Opening stock is not stored as a column on `product_variants`. Admin **Stock Qty** on product create/edit writes a ledger `RECEIPT` or `ADJUSTMENT` via `apply_stock_target`.
|
|
|
|
- `GET /api/v1/inventory/skus?page&limit&q=` returns one page of sellable variants with `SUM(inventory_ledger.qty)` (safe at 500k+ SKUs).
|
|
- Storefront listing/detail attach `available_stock` only for the current page or PDP, never the full catalog.
|
|
- Checkout locks the `product_variants` row (`SELECT ... FOR UPDATE`) before reserving, so concurrent COD checkouts on the same SKU cannot oversell.
|