ifixkart-admin/docs/inventory/inventory.md
Adithiyan bbd3a3e959 feat: initial commit — full platform snapshot
- 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
2026-10-13 12:59:47 +05:30

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.