Admin: Automated edit (via update-page on MediaWiki MCP Server)

2026-07-06T04:17:33Z

Automated edit (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:47, 6 July 2026
Line 182:		Line 182:
	* Read responses inline the full <code>product</code> (with <code>product_knowledge</code>) and <code>location</code> objects, not just their ids.		* Read responses inline the full <code>product</code> (with <code>product_knowledge</code>) and <code>location</code> objects, not just their ids.
	* <code>location</code> and <code>product</code> are <code>PROTECT</code> foreign keys, so referenced products and locations can't be hard-deleted while stock rows exist.		* <code>location</code> and <code>product</code> are <code>PROTECT</code> foreign keys, so referenced products and locations can't be hard-deleted while stock rows exist.

			{{Navbox supply}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:45:46Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=supply
|title=Inventory Item
|order=3
|introduced=3.0
|model=InventoryItem
|reference=References/Base models & conventions
}}

<code>InventoryItem</code> records how much of one [[References/Product|<code>Product</code>]] is on hand at one [[References/Location|facility location]]. Deliveries move product in, dispenses move it out, and the server recomputes the balance into <code>net_content</code>. You never create these rows — the server does, and the only field a client can write is <code>status</code>, such as marking a line <code>inactive</code> when stock is damaged or pulled from circulation.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/inventory_item.py <code>care/emr/models/inventory_item.py</code>]
* Spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/inventory/inventory_item/spec.py <code>care/emr/resources/inventory/inventory_item/spec.py</code>]
* Helpers: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/inventory/inventory_item/create_inventory_item.py <code>create_inventory_item.py</code>], [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/inventory/inventory_item/sync_inventory_item.py <code>sync_inventory_item.py</code>]

The Django model is storage. The Pydantic resource specs (<code>care/emr/resources/inventory/inventory_item/</code>) define the <code>status</code> enum and the read schema, inlining the <code>product</code> and <code>location</code> objects that the model holds only as foreign keys.

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>InventoryItem</code>
| Stock of one product at one location, with its current net quantity
|}

<code>InventoryItem</code> extends <code>EMRBaseModel</code>, the shared Care EMR base providing <code>external_id</code>, audit fields, and soft-delete semantics. See [[References/Base models & conventions|Base model]].

== <code>InventoryItem</code> fields ==

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=InventoryItem|section=InventoryItem fields|name=location|type=FK → FacilityLocation|notes=yes}}
{{Field|model=InventoryItem|section=InventoryItem fields|name=product|type=FK → Product|notes=yes}}
{{Field|model=InventoryItem|section=InventoryItem fields|name=status|type=CharField(255)|notes=yes}}
{{Field|model=InventoryItem|section=InventoryItem fields|name=net_content|type=DecimalField|notes=no}}
|}

The <code>(location, product)</code> pair is unique — one inventory item per product per location — enforced in <code>save()</code> (see [[#methods--save-behaviour|Methods & save behaviour]]).

=== <code>InventoryItemStatusOptions</code> values ===

Defined in [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/inventory/inventory_item/spec.py <code>spec.py</code>]. The spec accepts only these three values; the model field itself stays an open <code>CharField</code>:

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>active</code>
| Live and dispensable. Set when the server auto-creates a row.
|-
| <code>inactive</code>
| No longer dispensed — damaged stock, or another hold.
|-
| <code>entered_in_error</code>
| Record created in error.
|}

== Related models ==

Two foreign keys anchor the row; two transactional sources set its quantity:

<syntaxhighlight lang="text">location → FK FacilityLocation (PROTECT)
product → FK Product (PROTECT)

drives net_content (read in sync_inventory_item):
SupplyDelivery (incoming completed, outgoing in-progress/completed)
MedicationDispense (dispensed-out, excluding cancelled statuses)</syntaxhighlight>
Both foreign keys are <code>on_delete=PROTECT</code>: a location or product can't be hard-deleted while an inventory row references it. The records that move <code>net_content</code> live in [[References/Supply Delivery]] and [[References/Medication Dispense]].

== Resource specs (API schema) ==

All specs extend <code>EMRResource</code> (<code>care/emr/resources/base.py</code>), which supplies <code>serialize</code> / <code>de_serialize</code> and the <code>perform_extra_serialization</code> hook that inlines the nested <code>product</code> and <code>location</code> objects.

{| class="wikitable"
|-
! Spec class
! Role
! Fields exposed
! Notes
|-
| <code>BaseInventoryItemSpec</code>
| shared
| <code>id</code>, <code>status</code>
| <code>__model__ = InventoryItem</code>, <code>__exclude__ = []</code>. <code>status</code> typed as <code>InventoryItemStatusOptions</code>.
|-
| <code>InventoryItemWriteSpec</code>
| write
| <code>id</code>, <code>status</code>
| Inherits <code>BaseInventoryItemSpec</code> unchanged. Only <code>status</code> is client-writable; <code>product</code>, <code>location</code>, and <code>net_content</code> are server-maintained.
|-
| <code>InventoryItemReadSpec</code>
| read · list
| <code>id</code>, <code>status</code>, <code>net_content</code>, <code>product</code>, <code>location</code>
| See serialization below.
|-
| <code>InventoryItemRetrieveSpec</code>
| read · detail
| same as <code>InventoryItemReadSpec</code>
| A <code>pass</code> subclass — identical shape to the list spec.
|}

=== Read serialization (<code>InventoryItemReadSpec.perform_extra_serialization</code>) ===

{| class="wikitable"
|-
! Field
! Serialized shape
! Source
|-
| <code>id</code>
| <code>UUID4</code>
| <code>obj.external_id</code> — the public id, not the internal pk.
|-
| <code>net_content</code>
| <code>Decimal</code> (<code>max_digits=20</code>, <code>decimal_places=0</code> on the read field)
| model <code>net_content</code>.
|-
| <code>product</code>
| nested <code>dict</code>
| <code>ProductReadSpec.serialize(obj.product).to_json()</code> — carries nested <code>product_knowledge</code> and optional <code>charge_item_definition</code>. See [[References/Product]].
|-
| <code>location</code>
| nested <code>dict</code>
| <code>FacilityLocationListSpec.serialize(obj.location).to_json()</code> — carries <code>parent</code>, <code>mode</code>, <code>has_children</code>, <code>system_availability_status</code>, and optional <code>current_encounter</code>. See [[References/Location]].
|}

<code>status</code> (typed <code>InventoryItemStatusOptions</code>) carries through from <code>BaseInventoryItemSpec</code>. There is no <code>CreateSpec</code>; rows are never created through a client write path.

== Methods & save behaviour ==

=== <code>save()</code> ===

On creation only (when <code>self.id</code> is unset), <code>save()</code> enforces the <code>(location, product)</code> uniqueness:

<syntaxhighlight lang="text">if creating and InventoryItem with same (location, product) exists:
raise ValueError("Inventory item already exists")</syntaxhighlight>
* The check runs only for new rows; updates to an existing item skip it.
* A violation raises a plain <code>ValueError</code>, not a database <code>IntegrityError</code>, so callers creating items through the ORM must handle it.

=== <code>create_inventory_item(product, location)</code> ===

Helper in [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/inventory/inventory_item/create_inventory_item.py <code>create_inventory_item.py</code>]. Idempotent get-or-create:

* Returns the existing <code>(product, location)</code> row if one exists.
* Otherwise creates one with <code>status=active</code>, <code>net_content=0</code>, and saves it.

=== <code>sync_inventory_item()</code> ===

Helper in [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/inventory/inventory_item/sync_inventory_item.py <code>sync_inventory_item.py</code>], the source of truth for <code>net_content</code>. Holding <code>InventoryLock(product, location)</code>, it recomputes the balance from the transactional records and writes it back:

<syntaxhighlight lang="text">net_content =
Σ incoming completed deliveries (SupplyDelivery.status == completed,
order.destination == location,
supplied_inventory_item.product == product)
- Σ outgoing in-progress + completed deliveries
(SupplyDelivery.order.origin is not null,
supplied_inventory_item == this item,
status in {in_progress, completed})
- Σ dispenses (MedicationDispense.item == this item,
excluding cancelled statuses)</syntaxhighlight>
* If no row exists for <code>(product, location)</code>, one is auto-created (<code>status=active</code>, <code>net_content=0</code>) before computing.
* <code>net_content</code> is the aggregate sum of <code>supplied_item_quantity</code> / dispense <code>quantity</code>, and can be negative.
* Runs whenever a delivery completes or a dispense changes, so the balance stays current.

== API integration notes ==

* Rows are server-maintained: they come from <code>create_inventory_item</code> / <code>sync_inventory_item</code>, never a direct client create. The only meaningful client write is <code>status</code> (for example, setting <code>inactive</code>).
* One row exists per <code>(location, product)</code> pair. <code>net_content</code> is adjusted on that row, not by inserting duplicates.
* Don't patch <code>net_content</code> directly — <code>sync_inventory_item</code> recomputes it under an <code>InventoryLock</code>, and the next sync overwrites your value.
* Read responses inline the full <code>product</code> (with <code>product_knowledge</code>) and <code>location</code> objects, not just their ids.
* <code>location</code> and <code>product</code> are <code>PROTECT</code> foreign keys, so referenced products and locations can't be hard-deleted while stock rows exist.

{{Related}}

References/Inventory Item - Revision history

Admin: Automated edit (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed