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

2026-07-06T04:17:22Z

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

← Older revision		Revision as of 09:47, 6 July 2026
Line 182:		Line 182:
	* <code>batch</code> is a structured <code>{ lot_number }</code>, not a free-form dict, even though the column is a <code>JSONField</code>.		* <code>batch</code> is a structured <code>{ lot_number }</code>, not a free-form dict, even though the column is a <code>JSONField</code>.
	* Use <code>extensions</code> for deployment-specific key-value data without a schema migration. Values are checked against the schemas registered for the <code>product</code> extension resource.		* Use <code>extensions</code> for deployment-specific key-value data without a schema migration. Values are checked against the schemas registered for the <code>product</code> extension resource.

			{{Navbox supply}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:45:48Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=supply
|title=Product
|order=1
|introduced=3.0
|model=Product
|reference=References/Base models & conventions
}}

A <code>Product</code> is a concrete batch of stock at a facility — a single lot of a medication, nutritional product, or consumable, with its own expiry, lot number, and purchase price. It instantiates a catalogue entry: everything generic about the item (name, codes, dosage form, <code>product_type</code>) lives on the linked [[References/Product Knowledge|<code>ProductKnowledge</code>]], and a <code>Product</code> adds only what's true of one batch.

The Django model is storage; the shape you send and receive is defined by the Pydantic resource specs, which set the enums, narrow the model's opaque <code>JSONField</code>s, enforce validation, and split read from write. The fields below note where the spec diverges from the column; [[#resource-specs-api-schema|Resource specs (API schema)]] covers the full read/write split.

'''Source:'''

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

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>Product</code>
| A concrete, batch-level instantiation of a <code>ProductKnowledge</code> definition at a facility (medication, nutritional product, or consumable)
|}

<code>Product</code> extends [[References/Base models & conventions|<code>EMRBaseModel</code>]], which supplies <code>external_id</code>, audit fields, and soft-delete semantics.

== <code>Product</code> fields ==

=== Relationships ===

All three foreign keys are <code>PROTECT</code>, so a referenced row can't be deleted while a product points at it.

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Product|section=Relationships|name=facility|type=FK → facility.Facility (PROTECT)|notes=Required at storage, but not a spec field — the viewset sets it from the URL, never the request body.}}
{{Field|model=Product|section=Relationships|name=product_knowledge|type=FK → emr.ProductKnowledge (PROTECT)|notes=The catalogue definition this batch instantiates. Write takes a <code>slug</code> string and resolves it; read returns the nested [[References/Product Knowledge}}
{{Field|model=Product|section=Relationships|name=charge_item_definition|type=FK → emr.ChargeItemDefinition (PROTECT, nullable)|notes=Drives charge-item creation when the product is billed. Write takes a <code>slug</code> string; read returns the nested [[References/Charge Item Definition}}
|}

=== Classification & status ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=Product|section=Classification & status|name=status|type=CharField(255)|notes=yes (spec)}}
{{Field|model=Product|section=Classification & status|name=product_type|type=CharField(255)|notes=—}}
|}

=== Batch & pricing ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=Product|section=Batch & pricing|name=batch|type=JSONField (nullable)|notes=no}}
{{Field|model=Product|section=Batch & pricing|name=expiration_date|type=DateTimeField (nullable)|notes=no}}
{{Field|model=Product|section=Batch & pricing|name=standard_pack_size|type=IntegerField (nullable)|notes=no}}
{{Field|model=Product|section=Batch & pricing|name=purchase_price|type=DecimalField(max_digits=20, decimal_places=6) (nullable)|notes=no}}
{{Field|model=Product|section=Batch & pricing|name=extensions|type=JSONField|notes=yes (spec)}}
|}

== Enums ==

=== <code>ProductStatusOptions</code> values ===

Defined in [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/inventory/product/spec.py <code>spec.py</code>] and bound to the model <code>status</code> field.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>active</code>
| Product is in use
|-
| <code>inactive</code>
| Product is no longer in use but retained
|-
| <code>entered_in_error</code>
| Record created in error
|}

=== <code>ProductTypeOptions</code> values ===

Not a field on the <code>Product</code> spec. It's defined in [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/inventory/product_knowledge/spec.py <code>product_knowledge/spec.py</code>] and carried on the linked [[References/Product Knowledge|<code>ProductKnowledge</code>]]; it appears here only because the model keeps a <code>product_type</code> storage column.

{| class="wikitable"
|-
! Value
|-
| <code>medication</code>
|-
| <code>nutritional_product</code>
|-
| <code>consumable</code>
|}

== Nested JSON shapes ==

=== <code>ProductBatch</code> shape ===

Structure of the <code>batch</code> <code>JSONField</code> (<code>care/emr/resources/inventory/product/spec.py</code>).

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=Product|section=ProductBatch shape|name=lot_number|type=str | None|notes=no}}
|}

== Resource specs (API schema) ==

Every spec derives from <code>EMRResource</code> ([<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/base.py <code>care/emr/resources/base.py</code>]), which supplies <code>serialize</code> (DB → pydantic, via the <code>perform_extra_serialization</code> hook) and <code>de_serialize</code> (pydantic → DB, via the <code>perform_extra_deserialization</code> hook).

{| class="wikitable"
|-
! Spec class
! Role
! Fields beyond the base
! Behaviour
|-
| <code>BaseProductSpec</code>
| shared
| <code>id</code>, <code>status</code>, <code>batch</code>, <code>expiration_date</code>, <code>extensions</code>, <code>standard_pack_size</code>, <code>purchase_price</code>
| <code>__model__ = Product</code>. <code>__exclude__ = ["product_knowledge", "charge_item_definition"]</code> — these FKs are resolved by the hooks, not by automatic field mapping. <code>___extension_resource_type__ = ExtensionResource.product</code>.
|-
| <code>ProductWriteSpec</code>
| write · create
| adds <code>product_knowledge: str</code> (slug), <code>charge_item_definition: str | None</code> (slug)
| Mixes in <code>ExtensionValidator</code>. <code>perform_extra_deserialization</code> resolves <code>product_knowledge</code> via <code>get_object_or_404(ProductKnowledge, slug=...)</code> and, when present, <code>charge_item_definition</code> via <code>get_object_or_404(ChargeItemDefinition, slug=...)</code>.
|-
| <code>ProductUpdateSpec</code>
| write · update
| adds <code>charge_item_definition: str | None</code> (slug)
| Mixes in <code>ExtensionValidator</code>. <code>perform_extra_deserialization</code> resolves <code>charge_item_definition</code> via <code>ChargeItemDefinition.objects.get(slug=...)</code> when supplied. <code>product_knowledge</code> is immutable after create, so it is not re-bound.
|-
| <code>ProductReadSpec</code>
| read · list & detail
| adds <code>product_knowledge: dict</code>, <code>charge_item_definition: dict | None</code>
| <code>perform_extra_serialization</code> sets <code>id = external_id</code> and inlines <code>product_knowledge</code> (via <code>ProductKnowledgeReadSpec</code>) and, when set, <code>charge_item_definition</code> (via <code>ChargeItemDefinitionReadSpec</code>). One spec serves both list and detail.
|}

Consequences for an integrator:

* <code>product_type</code> and <code>facility</code> never appear in the request or response. <code>facility</code> comes from the route; <code>product_type</code> comes from <code>ProductKnowledge</code>.
* <code>product_knowledge</code> and <code>charge_item_definition</code> go out as slug strings and come back as fully serialized nested objects.
* <code>extensions</code> is validated on write against the JSON schemas registered for <code>ExtensionResource.product</code>. Keys with no registered handler are silently dropped — current behaviour, with a TODO to make it an error.
* There is no server-side <code>status_history</code>; <code>Product</code> does not track status changes.
* The base <code>de_serialize</code> dumps with <code>exclude_defaults=True</code>, so unset optional fields never reach the model.

== Methods & save behaviour ==

<code>Product</code> adds no methods of its own. Persistence, <code>external_id</code>, audit fields, and soft delete all come from <code>EMRBaseModel</code>.

* '''Write:''' request body → <code>ProductWriteSpec</code> / <code>ProductUpdateSpec</code> → <code>de_serialize</code> → <code>perform_extra_deserialization</code> (FK slug resolution) → <code>obj.save()</code>.
* '''Read:''' <code>Product</code> row → <code>ProductReadSpec.serialize</code> → <code>perform_extra_serialization</code> (inline <code>product_knowledge</code> and <code>charge_item_definition</code>) → JSON.
* <code>PROTECT</code> on every FK blocks deletion of a referenced <code>Facility</code>, <code>ProductKnowledge</code>, or <code>ChargeItemDefinition</code> while products still reference it.

== API integration notes ==

* A <code>Product</code> carries batch data only. Pull name, codes, dosage form, and <code>product_type</code> from the linked [[References/Product Knowledge|<code>ProductKnowledge</code>]] — they aren't duplicated here.
* Send <code>product_knowledge</code> and <code>charge_item_definition</code> as slugs on write; both return as full nested objects on read.
* Set <code>charge_item_definition</code> to wire the product into billing — charge items are created automatically when it's billed.
* <code>batch</code> is a structured <code>{ lot_number }</code>, not a free-form dict, even though the column is a <code>JSONField</code>.
* Use <code>extensions</code> for deployment-specific key-value data without a schema migration. Values are checked against the schemas registered for the <code>product</code> extension resource.

{{Related}}

References/Product - Revision history

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

Admin: OHC identity seed