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

2026-07-06T04:04:20Z

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

← Older revision		Revision as of 09:34, 6 July 2026
Line 283:		Line 283:
	* The spec enum-gates <code>status</code> (<code>draft</code>/<code>active</code>/<code>retired</code>); only <code>active</code> definitions should drive new charge items.		* The spec enum-gates <code>status</code> (<code>draft</code>/<code>active</code>/<code>retired</code>); only <code>active</code> definitions should drive new charge items.
	* <code>can_edit_charge_item</code> controls whether a ''derived'' charge item is mutable, not the definition itself.		* <code>can_edit_charge_item</code> controls whether a ''derived'' charge item is mutable, not the definition itself.

			{{Navbox definitions}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:44:37Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=definitions
|title=Charge Item Definition
|order=7
|introduced=3.0
|model=ChargeItemDefinition
|reference=References/Base models & conventions
}}

A charge item definition is a facility's pricing template for a billable resource: it answers "how much does resource X cost". It binds the resource to a set of price components — base rate, surcharges, discounts, and taxes — that get evaluated when a [[References/Charge Item|charge item]] is generated during data entry. You touch it when defining or revising the prices a facility charges.

The resource spans two layers. The Django model (<code>care/emr/models/charge_item_definition.py</code>) is storage: <code>price_components</code> and <code>discount_configuration</code> are opaque <code>JSONField</code>s with no structure of their own. The Pydantic specs (<code>care/emr/resources/charge_item_definition/</code>) are the API: they define the <code>status</code> enum, give those JSON fields a real shape via <code>MonetaryComponent</code> and <code>DiscountConfiguration</code>, enforce validation, and split the read and write schemas. See [[#resource-specs-api-schema|Resource specs (API schema)]].

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/charge_item_definition.py <code>care/emr/models/charge_item_definition.py</code>]
* Resource spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/charge_item_definition/spec.py <code>care/emr/resources/charge_item_definition/spec.py</code>]
* Shared spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/common/monetary_component.py <code>care/emr/resources/common/monetary_component.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>ChargeItemDefinition</code>
| Facility-scoped pricing template defining the price components applied to a billable resource
|}

<code>ChargeItemDefinition</code> extends [[References/Base models & conventions|<code>SlugBaseModel</code>]], the slug-aware Care EMR base, which itself extends <code>EMRBaseModel</code>. From that chain it inherits <code>external_id</code>, <code>created_date</code>/<code>modified_date</code>, soft-delete via <code>deleted</code>, <code>created_by</code>/<code>updated_by</code>, and the <code>history</code>/<code>meta</code> JSON fields, then adds facility-scoped slug helpers (see [[#methods--save-behaviour|Methods & save behaviour]]).

== <code>ChargeItemDefinition</code> fields ==

=== Identity & versioning ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=ChargeItemDefinition|section=Identity & versioning|name=facility|type=FK → facility.Facility|notes=yes}}
{{Field|model=ChargeItemDefinition|section=Identity & versioning|name=version|type=IntegerField|notes=—}}
{{Field|model=ChargeItemDefinition|section=Identity & versioning|name=status|type=CharField(255)|notes=yes}}
{{Field|model=ChargeItemDefinition|section=Identity & versioning|name=title|type=CharField(255)|notes=yes}}
{{Field|model=ChargeItemDefinition|section=Identity & versioning|name=slug|type=CharField(255)|notes=yes}}
{{Field|model=ChargeItemDefinition|section=Identity & versioning|name=derived_from_uri|type=TextField|notes=no}}
|}

=== Descriptive ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=ChargeItemDefinition|section=Descriptive|name=description|type=TextField|notes=no}}
{{Field|model=ChargeItemDefinition|section=Descriptive|name=purpose|type=TextField|notes=no}}
|}

=== Pricing & rules ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=ChargeItemDefinition|section=Pricing & rules|name=price_components|type=JSONField|notes=yes}}
{{Field|model=ChargeItemDefinition|section=Pricing & rules|name=discount_configuration|type=JSONField|notes=no}}
{{Field|model=ChargeItemDefinition|section=Pricing & rules|name=can_edit_charge_item|type=BooleanField|notes=yes}}
{{Field|model=ChargeItemDefinition|section=Pricing & rules|name=category|type=FK → emr.ResourceCategory|notes=no}}
{{Field|model=ChargeItemDefinition|section=Pricing & rules|name=tags|type=ArrayField[int]|notes=—}}
|}

== Enum values ==

=== Status values ===

<code>ChargeItemDefinitionStatusOptions</code> (<code>spec.py</code>) constrains <code>status</code>. The model <code>CharField</code> is unconstrained at the DB level, so the spec is the source of truth.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>draft</code>
| Not yet active; excluded from live billing
|-
| <code>active</code>
| In use; only these should drive new charge items
|-
| <code>retired</code>
| Withdrawn; excluded from live billing
|}

=== Monetary component type values ===

<code>MonetaryComponentType</code> (<code>common/monetary_component.py</code>) sets the <code>monetary_component_type</code> of each price component.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>base</code>
| The base rate. Exactly one allowed; must carry an <code>amount</code>; may not have <code>conditions</code> or a <code>factor</code>
|-
| <code>surcharge</code>
| An additive charge layered on the base
|-
| <code>discount</code>
| A reduction layered on the base
|-
| <code>tax</code>
| A tax component
|-
| <code>informational</code>
| Non-priced informational component
|}

=== Discount applicability values ===

<code>DiscountApplicability</code> (<code>common/monetary_component.py</code>) sets <code>discount_configuration.applicability_order</code>.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>total_asc</code>
| Apply discounts in ascending order of total
|-
| <code>total_desc</code>
| Apply discounts in descending order of total
|}

== JSON field shapes ==

=== Price components shape ===

<code>price_components</code> is a <code>list[MonetaryComponent]</code>. Each entry (<code>common/monetary_component.py</code>):

<syntaxhighlight lang="text">MonetaryComponent {
monetary_component_type : MonetaryComponentType # required; see enum above
code : Coding | null # billing code (system/version/code/display); code required if present
factor : Decimal | null # max_digits=20, decimal_places=6
amount : Decimal | null # max_digits=20, decimal_places=6
tax_included_amount : Decimal | null # max_digits=20, decimal_places=6; base-only
global_component : bool # default false
conditions : list[EvaluatorConditionSpec] # default []
}</syntaxhighlight>
<code>Coding</code> (<code>common/coding.py</code>, <code>extra="forbid"</code>): <code>{ system: str|null, version: str|null, code: str (required), display: str|null }</code>.

<code>EvaluatorConditionSpec</code> (<code>common/condition_evaluator.py</code>): <code>{ metric: str, operation: str, value: dict|str }</code>. <code>metric</code> is validated against <code>EvaluatorMetricsRegistry</code>, and that metric's evaluator validates <code>operation</code> and <code>value</code>.

Each <code>MonetaryComponent</code> is checked against these rules:

{| class="wikitable"
|-
! Rule
! Detail
|-
| <code>tax_included_amount</code> base-only
| Allowed only when <code>monetary_component_type == base</code>
|-
| base no conditions
| A <code>base</code> component must have no <code>conditions</code>
|-
| base requires amount
| A <code>base</code> component must have an <code>amount</code>
|-
| amount xor factor
| <code>amount</code> and <code>factor</code> cannot both be present
|-
| amount or factor required
| One of <code>amount</code>/<code>factor</code> must be present — except when <code>global_component</code> is true and a <code>code</code> is set
|}

=== Discount configuration shape ===

<code>discount_configuration</code> is a <code>DiscountConfiguration | null</code> (<code>common/monetary_component.py</code>):

<syntaxhighlight lang="text">DiscountConfiguration {
max_applicable : int # required; >= 0
applicability_order : DiscountApplicability # required; total_asc | total_desc
}</syntaxhighlight>
== Resource specs (API schema) ==

The API never serializes the Django model directly. It routes through Pydantic specs built on <code>EMRResource</code> (<code>resources/base.py</code>), which provide <code>serialize</code> (DB → API) and <code>de_serialize</code> (API → DB).

{| class="wikitable"
|-
! Spec class
! Role
! Exposes / behaviour
|-
| <code>ChargeItemDefinitionSpec</code>
| shared base
| <code>id</code>, <code>status</code>, <code>title</code>, <code>derived_from_uri</code>, <code>description</code>, <code>purpose</code>, <code>price_components</code>, <code>can_edit_charge_item</code>, <code>discount_configuration</code>. <code>__exclude__ = []</code>
|-
| <code>ChargeItemDefinitionWriteSpec</code>
| write · create + update
| Adds <code>slug_value: SlugType</code> and `category: ExtendedSlugType
|-
| <code>ChargeItemDefinitionReadSpec</code>
| read · list + detail
| Adds read-only <code>version</code>, <code>category: dict</code>, <code>slug_config: dict</code>, <code>tags: list[dict]</code>, <code>slug: str</code>, <code>created_by</code>, <code>updated_by</code>, <code>created_date</code>, <code>updated_date</code>
|}

These specs reuse several nested specs: <code>MonetaryComponent</code> (price component), <code>DiscountConfiguration</code> (discount rules), <code>Coding</code> (component code), and <code>EvaluatorConditionSpec</code> (component conditions).

=== Write-spec validation & side effects ===

* '''Duplicate (code, type) check''' (<code>check_components_with_duplicate_codes</code> field validator): no two <code>price_components</code> may share the same <code>(code.code, monetary_component_type)</code> pair. Only components that carry a <code>code</code> are checked.
* '''<code>perform_extra_deserialization</code>''' (<code>ChargeItemDefinitionWriteSpec</code>):
** When <code>category</code> (slug) is supplied, resolves it via <code>ResourceCategory.objects.get(slug=category)</code> and sets <code>obj.category</code>.
** Sets <code>obj.slug = self.slug_value</code> (the unprefixed value; the model's slug helpers prefix it — see below).

=== Read-spec serialization ===

* '''<code>perform_extra_serialization</code>''' (<code>ChargeItemDefinitionReadSpec</code>):
** <code>id</code> ← <code>obj.external_id</code>.
** <code>category</code> ← <code>ResourceCategoryReadSpec.serialize(obj.category)</code> when set.
** <code>slug_config</code> ← <code>obj.parse_slug(obj.slug)</code> (decomposes the stored slug into <code>{facility, slug_value}</code> or <code>{slug_value}</code>).
** <code>tags</code> ← <code>SingleFacilityTagManager().render_tags(obj)</code>.
** <code>created_by</code> / <code>updated_by</code> ← serialized via <code>serialize_audit_users</code>.

=== Slug type constraints ===

{| class="wikitable"
|-
! Type
! Constraints
|-
| <code>SlugType</code> (<code>slug_value</code>)
| <code>min_length=5</code>, <code>max_length=50</code>; pattern <code>^[a-zA-Z0-9][a-zA-Z0-9_-]*[a-zA-Z0-9]$</code> (URL-safe; alphanumeric start/end)
|-
| <code>ExtendedSlugType</code> (<code>category</code>)
| <code>min_length=7</code>, <code>max_length=88</code>; same pattern, and must start with <code>f-</code> or <code>i-</code>
|}

== Related models ==

<code>ChargeItemDefinition</code> references two other models by foreign key:

<syntaxhighlight lang="text">facility → FK facility.Facility (PROTECT)
category → FK emr.ResourceCategory (CASCADE, nullable)</syntaxhighlight>
* <code>facility</code> is protected: a facility cannot be deleted while definitions reference it.
* <code>category</code> cascades: deleting the [[References/Resource Category|resource category]] removes the link.

== Methods & save behaviour ==

<code>ChargeItemDefinition</code> overrides nothing of its own; slug behaviour comes from <code>SlugBaseModel</code> (<code>FACILITY_SCOPED = True</code>):

{| class="wikitable"
|-
! Method
! Behaviour
|-
| <code>calculate_slug()</code>
| Returns <code>f-{facility.external_id}-{slug}</code> when facility-scoped with a facility, otherwise <code>i-{slug}</code>
|-
| <code>calculate_slug_from_facility(facility_external_id, slug)</code>
| Classmethod — builds a facility-scoped slug string
|-
| <code>calculate_slug_from_instance(slug)</code>
| Classmethod — builds an instance-scoped slug string
|-
| <code>parse_slug(slug)</code>
| Splits a stored slug back into <code>{facility, slug_value}</code> (facility-scoped, <code>f-</code> prefix) or <code>{slug_value}</code> (instance-scoped, <code>i-</code> prefix); validates the embedded facility UUID; raises on length <code><= 2</code> or an unknown prefix
|}

Because slugs are namespaced by the owning facility's <code>external_id</code>, the same <code>slug_value</code> (for example <code>consultation-fee</code>) can coexist across facilities without colliding.

== API integration notes ==

* The structure is FHIR-aligned (<code>ChargeItemDefinition</code>), and <code>price_components</code> mirror the FHIR <code>MonetaryComponent</code> shape.
* Field names diverge between write and read: the client sends <code>slug_value</code>, not <code>slug</code>, and <code>category</code> is a slug string on write but an object on read. <code>slug_config</code>, <code>tags</code>, <code>category</code>, and audit users are computed server-side and appear only on read.
* The spec enum-gates <code>status</code> (<code>draft</code>/<code>active</code>/<code>retired</code>); only <code>active</code> definitions should drive new charge items.
* <code>can_edit_charge_item</code> controls whether a ''derived'' charge item is mutable, not the definition itself.

{{Related}}

References/Charge Item Definition - Revision history

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

Admin: OHC identity seed