Admin: Add Navbox platform (via update-page on MediaWiki MCP Server)

2026-07-06T04:24:45Z

Add Navbox platform (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:54, 6 July 2026
Line 267:		Line 267:
	* Monetary-component propagation runs through Celery, so descendants' <code>calculated_monetary_components</code> is eventually consistent after a write.		* Monetary-component propagation runs through Celery, so descendants' <code>calculated_monetary_components</code> is eventually consistent after a write.
	* Monetary-component fields serialize only for <code>resource_type == "charge_item_definition"</code>; during merges, component identity rests on the nested <code>code.system</code> + <code>code.code</code> pair.		* Monetary-component fields serialize only for <code>resource_type == "charge_item_definition"</code>; during merges, component identity rests on the nested <code>code.system</code> + <code>code.code</code> pair.

			{{Navbox platform}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:45:34Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=platform
|title=Resource Category
|order=5
|introduced=3.0
|model=ResourceCategory
|reference=References/Base models & conventions
}}

<code>ResourceCategory</code> is a facility-scoped, self-nesting category tree that classifies resources — <code>product_knowledge</code>, <code>activity_definition</code>, and <code>charge_item_definition</code> — and carries charge-item monetary components that inherit down the tree.

The Django model is just storage. The behaviour you code against lives in the Pydantic resource specs in <code>care/emr/resources/resource_category/</code>: the <code>resource_type</code> enum, the <code>MonetaryComponent</code> shape behind the <code>*_monetary_components</code> JSON fields, slug validation, and the split between read and write schemas. Several model fields are opaque <code>JSONField</code>s whose real structure exists only in the specs — see [[#resource-specs-api-schema|Resource specs (API schema)]].

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/resource_category.py <code>care/emr/models/resource_category.py</code>]
* Spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/resource_category/spec.py <code>care/emr/resources/resource_category/spec.py</code>]
* Shared: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/base.py <code>base.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/common/monetary_component.py <code>common/monetary_component.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/common/coding.py <code>common/coding.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>ResourceCategory</code>
| A facility-scoped, self-nesting category tree node that classifies resources (<code>product_knowledge</code>, <code>activity_definition</code>, <code>charge_item_definition</code>) and carries inheritable charge-item monetary components
|}

<code>ResourceCategory</code> extends [[References/Base models & conventions|<code>SlugBaseModel</code>]] with <code>FACILITY_SCOPED = True</code>, the facility-scoped slug variant of the base. It inherits the EMR base fields — <code>external_id</code>, audit fields, soft-delete, <code>history</code>/<code>meta</code> JSON — and adds <code>slug</code> handling on top.

== <code>ResourceCategory</code> fields ==

=== Core ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=ResourceCategory|section=Core|name=facility|type=FK → facility.Facility (PROTECT)|notes=yes}}
{{Field|model=ResourceCategory|section=Core|name=resource_type|type=CharField(255)|notes=yes}}
{{Field|model=ResourceCategory|section=Core|name=resource_sub_type|type=CharField(255)|notes=yes}}
{{Field|model=ResourceCategory|section=Core|name=title|type=CharField(255)|notes=yes}}
{{Field|model=ResourceCategory|section=Core|name=slug|type=CharField(255)|notes=yes}}
{{Field|model=ResourceCategory|section=Core|name=description|type=TextField|notes=no}}
|}

<code>Meta</code> declares a composite index on <code>(slug, facility)</code> for slug lookups within a facility.

=== Tree structure ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=ResourceCategory|section=Tree structure|name=parent|type=FK → emr.ResourceCategory (CASCADE)|notes=Self-reference to the parent node; nullable. <code>related_name="children"</code>. <code>__exclude__</code>d from spec serialization — written via slug lookup, read via <code>get_parent_json()</code>}}
{{Field|model=ResourceCategory|section=Tree structure|name=is_child|type=BooleanField|notes=Default <code>False</code>. Exposed on write (<code>ResourceCategoryWriteSpec</code>) and read}}
{{Field|model=ResourceCategory|section=Tree structure|name=has_children|type=BooleanField|notes=Default <code>False</code>. Flips to <code>True</code> on the parent when a child is created (see [[#methods--save-behaviour}}
{{Field|model=ResourceCategory|section=Tree structure|name=root_org|type=FK → emr.ResourceCategory (CASCADE)|notes=Self-reference to the root of this node's tree; nullable. <code>related_name="root"</code>. Not exposed in specs}}
|}

=== Tree caches ===

<code>set_organization_cache()</code> and <code>get_parent_json()</code> denormalize the ancestor chain into these fields, so reads resolve it without recursive joins. They are platform-maintained; clients never write them.

{| class="wikitable"
|-
! Field
! Type
! Rebuilt by
|-
| <code>parent_cache</code>
| <code>ArrayField[int]</code>
| <code>set_organization_cache()</code> — the parent's <code>parent_cache</code> plus the parent's id
|-
| <code>level_cache</code>
| <code>IntegerField</code>
| <code>set_organization_cache()</code> — parent's <code>level_cache + 1</code> (default <code>0</code> for roots). Exposed read-only (<code>level_cache: int = 0</code>)
|-
| <code>cached_parent_json</code>
| <code>JSONField</code>
| <code>get_parent_json()</code> — nested snapshot (shape below) with a <code>cache_expiry</code> timestamp; refreshed after <code>cache_expiry_days</code> (15)
|}

<code>get_parent_json()</code> builds <code>cached_parent_json</code> in this shape, which is also the shape of the <code>parent</code> field in <code>ResourceCategoryReadSpec</code>:

<syntaxhighlight lang="text">{
"id": str, # parent.external_id (UUID)
"slug": str, # parent.slug (encoded)
"title": str,
"description": str | null,
"parent": { ... }, # recursively the grandparent's cached_parent_json ({} at root)
"cache_expiry": str # ISO datetime; now + 15 days
}</syntaxhighlight>
Root nodes (no <code>parent_id</code>) serialize <code>parent</code> as <code>{}</code>.

=== Charge item monetary components ===

Both are <code>JSONField(default=list)</code> in the model; the spec types each element as a <code>MonetaryComponent</code> (see [[#monetarycomponent-nested-shape|shape]]). They serialize only when <code>resource_type == charge_item_definition</code>.

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=ResourceCategory|section=Charge item monetary components|name=configured_monetary_components|type=JSONField → list[MonetaryComponent] | None|notes=Components configured directly on this category}}
{{Field|model=ResourceCategory|section=Charge item monetary components|name=calculated_monetary_components|type=JSONField → list[MonetaryComponent] | None|notes=Effective components after merging the parent's calculated components with this node's configured components (see [[#methods--save-behaviour}}
|}

== Enums ==

=== <code>ResourceCategoryResourceTypeOptions</code> values ===

<code>care/emr/resources/resource_category/spec.py</code> — bound to <code>resource_type</code>.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>product_knowledge</code>
| Category classifies [[References/Product Knowledge]] entries
|-
| <code>activity_definition</code>
| Category classifies [[References/Activity Definition
|-
| <code>charge_item_definition</code>
| Category classifies [[References/Charge Item Definition
|}

=== <code>MonetaryComponentType</code> values ===

<code>care/emr/resources/common/monetary_component.py</code> — bound to <code>MonetaryComponent.monetary_component_type</code>.

{| class="wikitable"
|-
! Value
|-
| <code>base</code>
|-
| <code>surcharge</code>
|-
| <code>discount</code>
|-
| <code>tax</code>
|-
| <code>informational</code>
|}

== Resource specs (API schema) ==

All specs extend <code>EMRResource</code> (<code>serialize</code>/<code>de_serialize</code>; reads run <code>perform_extra_serialization</code>, writes run <code>perform_extra_deserialization</code>). With <code>__model__ = ResourceCategory</code> and <code>__exclude__ = ["parent"]</code>, the <code>parent</code> FK is never auto-mapped — every spec resolves it explicitly.

{| class="wikitable"
|-
! Spec class
! Role
! Exposes / behaviour
|-
| <code>ResourceCategoryBaseSpec</code>
| shared base
| <code>id</code> (UUID, read), <code>title</code>, <code>description</code>, <code>resource_type</code> (enum), <code>resource_sub_type</code>
|-
| <code>ResourceCategoryWriteSpec</code>
| write · create
| Base + <code>parent: str | None</code> (parent '''slug'''), <code>is_child: bool = False</code>, <code>slug_value: SlugType</code>. When <code>parent</code> is set, <code>perform_extra_deserialization</code> resolves <code>obj.parent = ResourceCategory.objects.get(slug=self.parent)</code>, and sets <code>obj.slug = self.slug_value</code>
|-
| <code>ResourceCategoryUpdateSpec</code>
| write · update
| Base + <code>slug_value: SlugType</code>. <code>perform_extra_deserialization</code> sets <code>obj.slug = self.slug_value</code>; update never reassigns <code>parent</code>
|-
| <code>ResourceCategoryReadSpec</code>
| read · list & detail
| Base + <code>parent: dict</code>, <code>has_children: bool</code>, <code>level_cache: int = 0</code>, <code>is_child: bool</code>, <code>slug: str</code>, <code>slug_config: dict</code>, <code>calculated_monetary_components</code>, <code>configured_monetary_components</code>. See serialization below
|}

<blockquote>Docstrings label these "ChargeItemDefinition Category", but the model is <code>ResourceCategory</code>. There is no separate <code>*ListSpec</code>/<code>*RetrieveSpec</code> — <code>ResourceCategoryReadSpec</code> serves both list and detail.
</blockquote>
=== <code>ResourceCategoryReadSpec</code> serialization (<code>perform_extra_serialization</code>) ===

* <code>id = obj.external_id</code>
* <code>parent = obj.get_parent_json()</code> — the nested ancestor snapshot (shape above)
* <code>slug_config = obj.parse_slug(obj.slug)</code> — a facility-scoped slug returns <code>{"facility": <uuid str>, "slug_value": <str>}</code>; an instance slug returns <code>{"slug_value": <str>}</code>
* <code>calculated_monetary_components</code> / <code>configured_monetary_components</code> — set only when <code>resource_type == "charge_item_definition"</code>; otherwise these default-<code>None</code> fields are omitted

=== <code>SlugType</code> validation ===

<code>slug_value</code> is <code>Annotated[str, Field(min_length=5, max_length=50), AfterValidator(slug_validator)]</code>:

* length 5–50
* regex <code>^[a-zA-Z0-9][a-zA-Z0-9_-]*[a-zA-Z0-9]$</code> — URL-safe (letters, digits, <code>-</code>, <code>_</code>), starting and ending alphanumeric

The stored <code>slug</code> is the encoded form <code>f-<facility_external_id>-<slug_value></code> (via <code>SlugBaseModel.calculate_slug()</code>); <code>slug_config</code> round-trips it back to <code>{facility, slug_value}</code>.

=== <code>MonetaryComponent</code> (nested shape) ===

Element type of <code>configured_monetary_components</code> / <code>calculated_monetary_components</code> (<code>common/monetary_component.py</code>).

{| class="wikitable"
|-
! Field
! Type
! Default
! Notes
{{Field|model=ResourceCategory|section=MonetaryComponent (nested shape)|name=monetary_component_type|type=MonetaryComponentType enum|notes=—}}
{{Field|model=ResourceCategory|section=MonetaryComponent (nested shape)|name=code|type=Coding | None|notes=<code>None</code>}}
{{Field|model=ResourceCategory|section=MonetaryComponent (nested shape)|name=factor|type=Decimal | None|notes=<code>None</code>}}
{{Field|model=ResourceCategory|section=MonetaryComponent (nested shape)|name=amount|type=Decimal | None|notes=<code>None</code>}}
{{Field|model=ResourceCategory|section=MonetaryComponent (nested shape)|name=tax_included_amount|type=Decimal | None|notes=<code>None</code>}}
{{Field|model=ResourceCategory|section=MonetaryComponent (nested shape)|name=global_component|type=bool|notes=<code>False</code>}}
{{Field|model=ResourceCategory|section=MonetaryComponent (nested shape)|name=conditions|type=list[EvaluatorConditionSpec]|notes=<code>[]</code>}}
|}

<code>MonetaryComponent</code> model validators:

* <code>tax_included_amount</code> only allowed when type is <code>base</code>
* <code>base</code> must have no <code>conditions</code>
* <code>base</code> must have an <code>amount</code>
* <code>amount</code> and <code>factor</code> are mutually exclusive (not both)
* either <code>amount</code> or <code>factor</code> must be present (unless <code>global_component and code</code>)

<blockquote>The category stores and validates these per element as <code>MonetaryComponent</code>. The stricter collection validators — <code>MonetaryComponents</code>/<code>MonetaryComponentsWithoutBase</code> (single base, no duplicate codes, tax-sum balance) — live with the charge-item resources, not the category list.
</blockquote>
== Methods & save behaviour ==

<code>ResourceCategory</code> overrides <code>save()</code> to populate the tree caches on create. A handful of helper methods plus a Celery task maintain those caches and the inherited monetary components.

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

* On '''create''' (<code>self.id</code> not yet set): runs <code>super().save()</code>, then <code>set_organization_cache()</code>, then enqueues monetary-component summarisation via <code>summarise_monetary_components(self)</code>.
* On '''update''': a plain <code>super().save(*args, **kwargs)</code>, no cache rebuild.

=== <code>set_organization_cache()</code> ===

Runs once on creation when a <code>parent</code> is present:

* Sets <code>parent_cache = [*parent.parent_cache, parent.id]</code> and <code>level_cache = parent.level_cache + 1</code>.
* Sets <code>root_org</code> to the parent's <code>root_org</code>, or to the parent itself if the parent is a root.
* If the parent's <code>has_children</code> was <code>False</code>, flips it to <code>True</code> and persists it with <code>save(update_fields=["has_children"])</code>.
* Persists the node via <code>super().save()</code>.

=== <code>get_parent_json()</code> ===

Returns <code>cached_parent_json</code>, rebuilding it lazily. A snapshot still within its <code>cache_expiry</code> is returned as-is. Past expiry, the method walks the parent chain, builds a fresh nested snapshot with a new expiry (<code>now + cache_expiry_days</code>), persists it via <code>save(update_fields=["cached_parent_json"])</code>, and returns it. Root nodes (no <code>parent_id</code>) return <code>{}</code>.

=== <code>summarise_monetary_components(category)</code> — Celery task ===

A <code>@shared_task</code> that recomputes <code>calculated_monetary_components</code> down the subtree:

* For a root (no <code>parent</code>), <code>calculated_monetary_components = configured_monetary_components</code>.
* Otherwise it merges the parent's <code>calculated_monetary_components</code> with this node's <code>configured_monetary_components</code> via <code>merge_monetary_components()</code>, then persists with <code>save(update_fields=["calculated_monetary_components"])</code>.
* It re-dispatches itself (<code>.delay(component.id)</code>) for every child, propagating changes through the tree.

<code>merge_monetary_components(parent, child)</code> keys components by <code>code.system + code.code</code>; child components override parent components sharing a key, and components without a <code>code</code> are appended unmerged.

== API integration notes ==

* Categories are facility-scoped. The <code>(slug, facility)</code> index and <code>SlugBaseModel</code> encoding (<code>f-<facility>-<slug></code>) keep slugs unique per facility. Clients send <code>slug_value</code> (5–50, URL-safe); the server encodes it and <code>slug_config</code> decodes it.
* Write <code>parent</code> by '''slug''' (<code>ResourceCategoryWriteSpec.parent</code> → <code>ResourceCategory.objects.get(slug=...)</code>), not by id. On read it comes back as the nested <code>get_parent_json()</code> snapshot.
* <code>parent_cache</code>, <code>level_cache</code>, <code>root_org</code>, <code>has_children</code>, <code>cached_parent_json</code>, and <code>calculated_monetary_components</code> are platform-maintained — don't set them. Write <code>parent</code> and <code>configured_monetary_components</code>; <code>save()</code> and the Celery task derive the rest.
* Cache rebuilds (<code>set_organization_cache</code>, monetary-component summarisation) run only on '''create'''. Changing an existing node's <code>parent</code> or configured components does not rebuild the caches.
* Monetary-component propagation runs through Celery, so descendants' <code>calculated_monetary_components</code> is eventually consistent after a write.
* Monetary-component fields serialize only for <code>resource_type == "charge_item_definition"</code>; during merges, component identity rests on the nested <code>code.system</code> + <code>code.code</code> pair.

{{Related}}

References/Resource Category - Revision history

Admin: Add Navbox platform (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed