Functional contract
Inventory
On-hand stock is per Location and shipped at /app/inventory. Purchasing identity is per Legal Entity. Catalog identity is per Organization. A unit at Location A never decrements Location B. Transfers and purchase orders are still intended.
Stock control
Each catalog item has a master stock_control (not a Location override):
| Mode | Behavior |
|---|---|
No control (none) | No stock rows. Absent from Inventory. Default for services. |
Control without batch (quantity) | One on-hand integer per Location. Default for products. |
Control with batch (batch) | On-hand is the sum of lots at that Location (lot number, optional expiry, quantity). Adjustments must name a lot. |
Changing mode is rejected while stock remains. Quantity cannot go negative. Adjustments write an InventoryAdjustment ledger.
Effective enabled identity still comes from Catalog and pricing. Exclusive items are only stocked where they are granted.
Transfers between Locations
Intended. Not implemented. Sites in the same Organization may move stock with a documented transfer. Traceability is required: who sent, who received, what, how many, when.
| Step | Behavior |
|---|---|
| Create | Source Location (or an Organization admin) starts a transfer to another Location in the same Organization |
| In transit | Quantity has left the source and is not yet available at the destination |
| Receive | Destination confirms; quantity becomes on hand there |
| Cancel / reject | Stock returns to the source if it had already left; no silent disappear |
Do not allow transfers to a Location in another Organization.
Purchase orders
Intended. Not implemented. Purchase orders are issued in the name of a Legal Entity.
- Vendor sees the Legal Entity’s legal name and tax ID.
- One PO may be allocated to several Locations of that Legal Entity.
- Receiving is per Location.
- A Location cannot receive a PO for a Legal Entity it does not belong to.
Visibility
| Actor | Sees |
|---|---|
| Organization admin | On-hand at every Location |
| Location manager / staff | On-hand for granted Locations only |
Acceptance
- Adjusting one unit at A changes A and leaves B unchanged.
- Items with no stock control are absent from Inventory.
- Batch adjustments without a lot are rejected.
- Staff granted only A cannot read B’s on-hand counts.
- Transfers and POs remain unbuilt.
Out of scope: reorder points, lot recalls, controlled-substance registers, vendor EDI, intercompany invoices for cross-EIN transfers.