Skip to content

Book 2 — Inventory & Stock

Status: DRAFT for validation. Five chapters, static-analysis-derived (nav → routes → controllers → models → migrations). Every chapter separates code-proven facts from inferences (§7). This index consolidates the flow, the seams between chapters, and the top items to validate with users/devs. Same format as the Book 1 index.

Chapters

# Chapter Covers File
7 Item Master & Pricing Item master (WaInventoryItem), categories/UOM, reserved stocks, subbins, price change/lists, promotions/hampers/basket, item + price approval workflows, weighted averages 07
8 Stock Operations Stock takes (freeze/count/variance), stock breaking & auto-breaks, stock processing (short/excess), stock & delivery loss, stock debtors 08
9 Goods Receiving & Returns (GRN) Receive purchases (initiate→confirm), advance-payment delivery-note path, weighbridge, returns (from-GRN / from-store), portal returns, credit notes 09
10 Transfers & Internal Requisitions Inter-branch transfers (legacy one-shot vs bin-verification two-step), internal requisition new→authorise→issue/fulfil→processed 10
11 Warehouse Special Stores Store C, Supreme Store, Overflow Stores, Consumables — each store's receive→requisition→issue→stock-take lifecycle 11

The load-bearing fact for the whole book

Quantity-on-hand is not a stored column — it is the running sum of signed rows in a stock-move ledger. The main ledger is wa_stock_moves (note the misspelled qauntity column), with new_qoh snapshotting the balance per row. Every inventory operation in Book 2 reconciles by writing signed rows into a ledger:

flowchart TD
  ITEM[Item master\nWaInventoryItem\nCh7] -->|catalog only, QOH derived| LEDGER[(wa_stock_moves\nsigned qty ledger)]
  GRN[GRN receive / confirm\nCh9] -->|+| LEDGER
  RET[Returns to supplier\nCh9] -->|-| LEDGER
  XFER[Inter-branch transfer\nCh10] -->|- source / + dest| LEDGER
  REQ[Internal requisition issue\nCh10] -->|- source / + dest| LEDGER
  TAKE[Stock take variance\nCh8] -->|+/- adjustment| LEDGER
  BREAK[Stock breaking\nCh8] -->|- parent / + child| LEDGER
  PROC[Processing: short/excess\nCh8] -->|+/-| LEDGER
  LOSS[Stock loss\nCh8] -->|-| LEDGER
  SALE[Sales dispatch\nBook 1] -->|-| LEDGER
  LEDGER -.availability = main − special ledgers.-> SPECIAL[Special-store ledgers\nwa_stock_moves_C / _supreme / overflow\nCh11]

Two important nuances the chapters proved: - Special stores net against main. Store C / Supreme / Overflow keep separate ledgers, but main_available = SUM(wa_stock_moves) − SUM(special ledgers) — reserved stock carved from the same physical inventory, not double-counted. Consumables is the exception: a genuinely separate non-sale catalog with its own opening balances. - Not everything writes a stock move. Delivery loss (Ch8) writes no stock move — only a customer wa_debtor_trans charge + employee penalty. Requisition creation and transfer arrival (bin-verification step) also don't move stock; only confirmation/issue does.

Cross-chapter & cross-book seams

  • Item Master → everything. WaInventoryItem is the shared catalog; QOH is derived from moves, so Ch7 defines what exists and Ch8–11 move how much.
  • GRN (Ch9) ↔ Procurement (Book 3). GRN receives against purchase orders; PO creation, supplier invoicing and AP live in Book 3 — Ch9 flags where the payable is raised (advance-payment path vs standard confirm).
  • Transfers/Requisitions (Ch10) vs Special Stores (Ch11). The branch-level Ferry/Internal Requisition flow (n_wa_internal_requisitions) is distinct from each special store's own *_requisitions tables. Chapter 10 also resolved the Book 1 naming clash: wa_internal_requisitions (no n_) is a Sales table, not inventory.
  • Stock Operations (Ch8) ↔ Banking (Book 1 Ch6). Stock/delivery shortfalls become stock debtors — staff recovery that surfaces on the debtor ledger.
  • Consumables (Ch11) ↔ Fleet/Fuel (Book 5) & AP (Book 3). Consumables issue fuel to vehicles (vehicle fuel report) and post supplier invoices to Accounts Payable.

Recurring themes (consistent with Book 1)

  1. A superseding-redesign pattern is visible in the data. Store C + Supreme (2023, fixed pair) → Overflow Stores (2025, data-driven, many-instance) is an explicit, in-progress migration — the hide setting even says so. Similar "old path kept as backup/compat" shows up in transfers (legacy one-shot vs two-step), price change (batch vs legacy queue), and GRN (ProcessReceiveOrderController "Approve GRN" superseded by confirm). The codebase is mid-modernization in several places.
  2. Approval queues everywhere — item create/edit, price change, requisitions, returns, losses, item retire/block. Same "approvers not curators" surface as Book 1.
  3. Heavily settings-gated per tenant — item-edit approval, cost price lists, subbins, sales-order pricing, special-store hiding. "Which path is live per flavor" remains the standing question.
  4. Data-quality footguns to log — a misspelled ledger column (qauntity), a issued_quanity typo (Ch10), a possible *Demo model mix in transfer approve/processed controllers (Ch10), and a possible wanewstockmove vs wa_stock_moves dual-write (Ch8).

Consolidated open questions — for user/dev validation

A. Which path is live per tenant/flavor?

  • Price-change: direct batch vs legacy Pending history-verify queue — which is authoritative? (Ch7)
  • Transfers: legacy one-shot processTransfer vs bin-verification two-step — permission-driven, no clear setting. (Ch10)
  • GRN: does the standard confirm path raise the payable, or only the invoice does? (Ch9)
  • Special stores: any flavor running Store C/Supreme and Overflow at once (mid-migration)? (Ch11)

B. Confirm dead vs live

  • ProcessReceiveOrderController "Approve GRN" — nav commented out; fully retired? (Ch9)
  • indexReceiveInitial / indexReceiveConfirm routes with no controller methods — dead? (Ch10)
  • Legacy weighted_average_history, commented-out child-cascade in PriceChangeController, Manual Cost Change nav. (Ch7)
  • Store C/Supreme once a flavor moves to Overflow (they persist but hidden). (Ch11)

C. Correctness / data-integrity risks (worth a dev look)

  • Possible *Demo model mix in transfer approve/processed controllers — could hit different tables. (Ch10)
  • Possible wanewstockmove vs wa_stock_moves dual-write. (Ch8)
  • Two blocking concepts (block_this flag vs approval-driven blocked_inventory_items) and two price-change mechanisms coexisting. (Ch7)
  • issued_quanity / qauntity column typos (cosmetic but citation-relevant). (Ch8, Ch10)

D. Logic to confirm with owners

  • Weighted-average recompute trigger. (Ch7)
  • Exact stock-take variance → processing (debtor vs direct GL adjust) linkage. (Ch8)
  • Store C route-based requisition (create2/store2, route_id) — van-sales fulfilment? (Ch11)
  • Store C/Supreme Receive upstream document (supplier vs GRN vs main-store transfer). (Ch11)
  • Credit-note auto-generation timing on return approval; portal-return write path (likely in supplier-portal module). (Ch9)

Coverage & method notes

  • Coverage: ~90–95% of each chapter's nav scope traced to code. Chapter 11's inferences were upgraded to code-proven by three dedicated research threads (Store C/Supreme, Overflow, Consumables) folded in post-hoc.
  • Routes live in routes/web.php, not routes/modules/inventory.php, for most of Book 2 (Consumables is the exception) — noted for future books.
  • Not done by design: no runtime/DB profiling, no screenshots — a "how it's built to work" guide, validated by review.