From d3abd70400b270a01a6c0ba04d7920442c3908a1 Mon Sep 17 00:00:00 2001 From: Bodhish Thomas Date: Wed, 30 Apr 2025 04:19:41 +0530 Subject: [PATCH 01/13] Dump AI generated docs for billing --- docs/care/HMIS/Billing/Account.md | 97 ++++++++ docs/care/HMIS/Billing/Billing.md | 42 ++++ docs/care/HMIS/Billing/ChargeItem.md | 114 +++++++++ .../care/HMIS/Billing/ChargeItemDefinition.md | 116 +++++++++ docs/care/HMIS/Billing/Invoice.md | 220 ++++++++++++++++++ .../HMIS/Billing/PaymentReconciliation.md | 203 ++++++++++++++++ 6 files changed, 792 insertions(+) create mode 100644 docs/care/HMIS/Billing/Account.md create mode 100644 docs/care/HMIS/Billing/Billing.md create mode 100644 docs/care/HMIS/Billing/ChargeItem.md create mode 100644 docs/care/HMIS/Billing/ChargeItemDefinition.md create mode 100644 docs/care/HMIS/Billing/Invoice.md create mode 100644 docs/care/HMIS/Billing/PaymentReconciliation.md diff --git a/docs/care/HMIS/Billing/Account.md b/docs/care/HMIS/Billing/Account.md new file mode 100644 index 0000000..817f592 --- /dev/null +++ b/docs/care/HMIS/Billing/Account.md @@ -0,0 +1,97 @@ +# Account + +## Summary +The **Account** module manages financial accounts that accumulate charges and payments for a patient or specific purpose (e.g. an inpatient stay or department cost center). An Account serves as a “billing bucket” or ledger for tracking healthcare costs over time ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=A%20financial%20tool%20for%20tracking,a%20patient%2C%20cost%20centers%2C%20etc)). Charges (for services or items) are applied to an Account, and payments or adjustments credit the Account. In essence, it is a central record against which charges, payments, and adjustments are recorded ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=The%20Account%20resource%20acts%20as,for%20payment%20of%20the%20account)). This allows the system to keep a running total of what a patient (or their insurance) owes. Accounts contain information about who the account is for (the patient or entity) and who is responsible for paying the balance (such as insurance or a guarantor). *For example, when a patient is admitted, an Account is opened to track all charges during that hospitalization, and later, an invoice will be generated from this account.* + +**Note (Developers):** The Account concept aligns with the FHIR **Account** resource, providing a tool to track values accrued for a particular purpose in healthcare billing ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=A%20financial%20tool%20for%20tracking,a%20patient%2C%20cost%20centers%2C%20etc)). While an account will have a running balance conceptually, it typically does **not** store a live balance field. Instead, the current balance is computed from all associated charges and payments ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=While%20the%20Account%20does%20conceptually,in%20consideration%20as%20future%20work)). The system may provide a function to calculate the balance on demand by summing charges minus payments. + +## Key Fields, Statuses, and Business Logic +**Key Fields:** +- **Account Identifier:** Unique number or code for the account (often auto-generated) used to reference the account in the system. This might be visible on invoices or receipts for reference. +- **Name/Description:** A human-friendly name (optional) for the account, e.g. “John Doe – 2025 Inpatient Stay”, to help staff identify it. +- **Subject (Patient):** The patient (or entity) for whom the account is managed. Only charges for this patient should be applied. The account might also be tied to a specific **Encounter** or admission in the hospital (e.g. an account per hospitalization). +- **Account Type:** Categorizes the account, such as *inpatient*, *outpatient*, *pharmacy*, or other billing categories. This helps route the account to proper workflows. *(Developers: this corresponds to FHIR Account.type, and can be used for reporting or business rules.)* +- **Status:** The lifecycle state of the account. Common statuses include **active**, **on-hold**, **inactive** (closed), **entered-in-error**, or **unknown** ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=%3Cstatus%20value%3D%22%5Bcode%5D%22%2F%3E%3C%21,billingStatus)). + - *Active:* The account is currently open and usable – new charges can be posted and invoices can be generated. Most patient accounts will be **active** during a patient’s care period. + - *On-hold:* The account is temporarily suspended (e.g. due to billing disputes or pending insurance information). Charges should not be added or invoices issued while on-hold. *(UI behavior: if staff attempt to add a charge or invoice on a held account, the system should block it and show a message.)* + - *Inactive (Closed):* The account is closed, typically after the care episode is finished and all charges have been billed and paid. No new transactions should occur. *(UI: the account may become read-only; any attempt to post charges should be prevented.)* + - *Entered-in-error:* The account was created by mistake and should not be used (e.g. duplicate account). Such accounts are ignored in billing. + - *Unknown:* The status is not known (this is rarely used; generally, an account will be deliberately set to one of the above states). + **Business logic:** New charges can only be applied to accounts in **active** status. If an account is **inactive** or on **on-hold**, the system must validate and disallow posting charges or creating invoices until the status is active. When closing an account (setting to inactive), ensure all pending charges are billed and no outstanding balance remains to avoid orphan transactions. +- **Coverage:** Insurance or coverage details associated with the account. This is the list of one or more insurance policies or payers that might pay for charges on this account (often with a priority order) ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=,when%20processing%20billing%20coverage)). For example, a patient’s primary insurance coverage would be listed first, and perhaps secondary insurance next. This field helps determine how invoices/claims might be sent to insurers. + *(UI: When creating an account, staff can attach the patient’s insurance coverage. The interface might allow selecting from the patient’s known insurance policies, and marking the primary vs secondary coverage.)* +- **Guarantor:** The person or organization responsible for any remaining balance on the account (after insurance). Often this is the patient themselves or a guardian/related person ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=Reference%20,Organization%20%C2%BBA%20guarantor%20may%20be)). If insurance doesn’t fully cover the charges, the guarantor will be billed for the remainder. +- **Owner (Managing Organization):** The department or organization that manages the account. For example, the hospital or a specific clinic department might “own” the account for internal tracking. *(This is mostly for internal bookkeeping; not always exposed to end-users.)* +- **Billing Period:** The date range that the account covers (e.g. admission and discharge dates, or a specific billing cycle). Charges with service dates outside this period might not be allowed. The system can use this to ensure charges fall within an episode of care. +- **Account Balance:** *This is not a stored field, but a computed value.* The current balance is calculated as **total charges** minus **payments/adjustments**. Staff will see the balance on the account UI, but under the hood it’s derived from the linked transactions. The account **balance** updates in real-time as new charges or payments are recorded (e.g., adding a charge increases the balance; recording a payment decreases it). ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=While%20the%20Account%20does%20conceptually,in%20consideration%20as%20future%20work)) + +**Business Logic Highlights:** +- An account can accumulate many **Charge Items** (individual billed services) over time. Each Charge Item references the Account it belongs to. The Account itself does not list every charge internally; instead, charges “point” to the account ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=The%20Account%20itself%20does%20not,have%20not%20yet%20been%20developed)). The system can retrieve all charges linked to a given account to compute the balance or prepare an invoice. +- **Adding Charges:** Only allowed on active accounts. If a user tries to add a charge to an inactive/on-hold account, the system should prevent it and alert the user (e.g., “Cannot add charges to a closed account”). This ensures data integrity. +- **Account Closure:** Typically done when the patient’s episode of care is complete and billing is finalized. The staff will mark the account as **inactive** (closed) after all invoices are issued and the balance is zero. The system might enforce that an account with outstanding balance cannot be closed. *(Developer note: implement a check that blocks closing an account if any unpaid invoices or unbilled charges exist.)* If closure is forced (exception cases), it should perhaps trigger warnings or require managerial approval. +- **On-hold Behavior:** Placing an account on hold might be used if, for example, insurance eligibility is in question or a billing dispute arises. In this state, new charges can be collected in the background (if necessary) but not officially billed until hold is released. The UI should visibly flag held accounts, and possibly require a note or reason for hold. +- **Responsible Parties:** The account’s **coverage** and **guarantor** information drive who gets billed in the **Invoice** process. For instance, an invoice might be split by coverage – first sent as a claim to insurance, then a remaining patient-responsible invoice to the guarantor. (This system is inspired by FHIR but may be simplified in implementation.) +- **Retrieving Balance:** Because the balance isn’t a stored field, whenever staff view the account, the system will calculate the balance by summing all *Charge Items* minus *Payments* related to that account. This ensures accuracy but requires that all related data be queried. *(Developer note: Consider providing an optimized way to compute balance, such as a database view or cached value updated on each transaction, if performance is a concern.)* + +## Step-by-Step User Workflows and UI Interaction + +**Creating a New Account:** +1. **Navigation:** A billing staff or registrar navigates to the **Accounts** section of the HMIS. This might be accessible via a “Billing” menu or during patient admission in the system. +2. **Initiate Account Creation:** The user clicks on **“New Account”** (or an equivalent action). If the account is being created as part of patient registration or admission, some fields may be auto-filled (e.g., patient name, admission date). +3. **Enter Account Details:** A form is presented for the account details: + - Select or confirm the **Patient** for whom the account is being created (often this is pre-selected if coming from a patient context). + - Optionally enter an **Account Name/Description** (e.g., “2025-03 Ortho Surgery”). + - Choose an **Account Type** (from a dropdown, e.g., *Inpatient* vs *Outpatient*, if applicable). + - Initially, the **Status** will default to **active** (since we are opening a new active account). + - Add **Coverage details:** The user can attach insurance coverage. For example, they might pick the patient’s insurance policy from a list of the patient’s insurances on file. If multiple insurances apply, they can add more than one, possibly specifying the order (primary, secondary). + - The **Guarantor** will default to the patient (or guardian for a minor). The user can change it if, say, a company or another family member is responsible for the bill. + - Ensure the **start date** (or admission date) is correct; enter an end date if known (for example, if creating an account for a scheduled procedure on a single day, the end date might be that day). +4. **Save Account:** The user submits the form (by clicking **“Save”** or **“Create”**). The system validates the input (e.g., patient must be selected, type may be required, etc.). If everything is valid, a new Account record is created. The account is now **active** and ready to accept charges. + - *System response:* The UI might display a confirmation like “Account #12345 created successfully.” The account’s unique ID/number is generated (if not manually entered) and shown. The account detail page opens, showing the information entered and a current balance of $0.00. +5. **Post-Creation Actions:** From the new account’s page, staff can now perform actions like **“Add Charge”** (to add billable items) or **“Generate Invoice”** when ready. Initially, the account has no charges, so the balance is zero. The coverage and guarantor info is visible so staff know who will be billed. + +**Viewing and Updating an Account:** +- Staff can search or browse for an existing account (for example, by patient name or account number). Selecting the account will typically bring up an **Account Details** screen. This screen shows: + - Account info (patient, status, type, etc.) at the top. + - Coverage/Insurance details and guarantor. + - A list of all **Charge Items** posted to this account (often in a table format, with columns for date, description, amount, status). + - A list of **Invoices** associated with the account (with invoice dates, amounts, status). + - A list of **Payments** applied (with payment dates, amounts, and references). + - The **Current Balance** calculated. +- Staff can update certain fields by clicking an **“Edit”** button (if the account is active): + - For example, if the patient got a new insurance card mid-way, they could add a new Coverage or update the guarantor. Or they might correct the account name or type. + - Some fields are not editable after creation: typically the patient and possibly the start date (since those are fundamental). If a mistake was made (wrong patient), often the recommended approach is to mark the account entered-in-error and create a new one. + - Changing **Status:** Staff might set the account on **hold** if needed (the UI might require entering a reason note when doing so). They might also mark it **inactive** (close it) if the episode of care is over and billing is completed. +- When the user saves changes, the system validates them. For instance, if setting status to **inactive**, it might check if the balance is zero. If not, a warning “Cannot close account with outstanding balance” would appear and the action is blocked. + +**Handling Account Holds:** +- If an account is on hold, the UI should prominently indicate this (e.g., a banner “On Hold”). While on hold, typical billing actions might be disabled or require override: + - The “Add Charge” button might be hidden or greyed out with a tooltip “Account is on hold – cannot add charges.” + - The “Generate Invoice” action might be disabled as well. +- To remove a hold, a staff user (often with appropriate permission) would edit the account and change status back to **active**. The system might log who removed the hold and when. + +**Closing an Account (End of Cycle):** +- When all charges have been billed and paid, or the patient’s treatment cycle is over, the account should be closed. To do this, staff edits the account and sets **Status = Inactive**. +- The system will likely prompt “Are you sure you want to close this account? This action will mark the account as closed and no further charges can be added.” If confirmed, and validation passes (balance is zero, etc.), the status updates to inactive. +- Once inactive, the account is essentially archived for that episode. The UI might label it as **Closed**. Staff can still view details and history, but cannot add new entries. If somehow a late charge comes in after closure, typically a new account or special process is needed (or re-open the account, if the system allows toggling back to active with authorization). + +**Account Balance Inquiry:** +- At any point, staff might need to inform a patient of their current balance. The account screen’s balance is calculated from charges and payments in real-time. If the patient or billing staff want a detailed statement, they can generate an **Account Statement** (which is essentially an on-demand invoice or report of all transactions). This is usually separate from the official Invoice process, but it gives a breakdown of charges, payments, and remaining due. +- *UI Example:* A “Print Statement” button could produce a PDF listing all charges on the account, any payments received, and the net balance, useful for interim updates to patients before final billing. + +## Developer Notes (Account Backend & Validation) +- **Data Model:** Each Account record should include references to the patient, coverage, guarantor, etc. Use relational links (e.g., patient ID foreign key) to quickly fetch related data. If modeling after FHIR, the Account is a standalone resource identified by an ID, with references to Patient, Coverage, etc. +- **Balance Calculation:** As noted, the account’s balance is computed, not stored. Implement a reliable method to sum all *ChargeItem* amounts linked to the account minus all *Payment* (PaymentReconciliation) amounts linked to the account. This might involve summing potentially many records, so consider indexing and efficient queries. Alternatively, maintain a running balance that updates on each transaction (though this must be carefully synchronized to avoid errors). +- **Status Transitions:** Enforce rules when updating account status: + - Only allow **inactive** if balance is 0 and no pending charges. If there is a balance, return a clear error to the UI. + - Only allow **on-hold** or **active** transitions for appropriate user roles. Possibly log these changes for audit. + - **entered-in-error** should only be used shortly after creation or if truly needed, and might require admin privileges, since it essentially invalidates the account. +- **Unique Constraints:** Ensure account identifiers are unique (to avoid confusion in billing). If using human-readable numbers, implement a sequence or check to not duplicate an old account number. +- **Link to Encounter:** If the system ties accounts to encounters (common in hospital systems), ensure that one encounter is associated with only one primary billing account. Conversely, an account might cover multiple encounters in some models (like a global account for outpatient visits). Clarify this in design and enforce accordingly. +- **Coverage Priority:** If multiple coverages are attached, store the priority order. During invoice generation (especially if integrating with insurance claim logic), the order will determine who is billed first. The data model should capture priority (e.g., an integer rank or boolean for primary). +- **Auto-Creation Hooks:** In many systems, an account is automatically created when a patient is admitted or registered for a visit (to ensure every encounter has an account). As a developer, consider triggers: e.g., on creating an Encounter record, auto-generate an Account if none exists, and link them. This reduces manual workload on staff. +- **Deletion vs Error:** Generally, avoid deleting account records outright (especially if transactions exist). Instead, use the entered-in-error status or another flag to exclude erroneous accounts. This preserves an audit trail. If absolutely needed, only allow deletion on accounts with no charges or payments and done by admin. +- **Audit Logs:** Keep logs of changes to critical fields (status changes, coverage changes) for compliance. For example, if an account is put on hold, record who did it and why (perhaps as an internal note). +- **Integration Consideration:** If the HMIS integrates with a general ledger or financial system, the Account might map to a ledger account or sub-ledger. Developers might need to propagate account creation/closure events to that system. +- **Performance:** Accounts with a very large number of charges (e.g., a long hospitalization) might cause slow queries for balance or invoice generation. Mitigate by optimizing queries or splitting accounts by time periods if necessary (for instance, monthly billing accounts). +- **FHIR Alignment:** (Optional) If exposing an API or storing internally following FHIR, note that the Account resource doesn’t carry a balance field ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=While%20the%20Account%20does%20conceptually,in%20consideration%20as%20future%20work)). Use FHIR operations (like `$balance` if defined) or custom operations to retrieve balances. Keep the FHIR resource updated with pointers to ChargeItem, Invoice, and PaymentReconciliation resources as appropriate to maintain referential integrity within the API. diff --git a/docs/care/HMIS/Billing/Billing.md b/docs/care/HMIS/Billing/Billing.md new file mode 100644 index 0000000..97a35ee --- /dev/null +++ b/docs/care/HMIS/Billing/Billing.md @@ -0,0 +1,42 @@ +# Billing Module + +This folder contains documentation for the **Billing** section of the HMIS (Hospital Management Information System) built with FHIR-inspired design principles. + +The goal of these documents is to help both **developers** (for integration and validation logic) and **hospital billing staff** (for understanding workflows) navigate and use the billing system effectively. + +--- + +## 📁 Documentation Structure + +| File | Description | +|------|-------------| +| `Account.md` | Explains how patient accounts are managed — including statuses, coverage, and linkage with charges and payments. | +| `ChargeItem.md` | Covers how billable services/items are posted to accounts, their status transitions, and validation rules. | +| `ChargeItemDefinition.md` | The source-of-truth catalog of all billable services and goods, with pricing, constraints, and usage rules. | +| `Invoice.md` | Workflow for generating, issuing, and managing invoices from charge items, including partial billing and cancellations. | +| `PaymentReconciliation.md` | Documentation on recording and applying payments to invoices/accounts, including bulk insurance payments. | +| `Notes.md` | Additional guidelines, clarifications, or decisions around the billing logic and implementation. | +| `Readme.md` | You are here — overview of this documentation folder. | + +--- + +## 📌 Guidelines for Use + +- **For Developers**: + - Use this to implement frontend validations, enforce backend rules, and understand field relationships and status transitions. + - Refer to flowcharts and step-by-step sections to implement the UI in sync with billing logic. + +- **For Staff and Admins**: + - Refer to individual module docs to understand workflows such as creating invoices, posting charges, reconciling payments, etc. + - Use this as a training/reference tool for new billing operators. + +--- + +## 🧭 Entry Points + +1. Start with `Account.md` — it is the anchor for billing operations. +2. Move to `ChargeItem.md` and `ChargeItemDefinition.md` to understand how charges work. +3. Review `Invoice.md` for generating bills. +4. Go through `PaymentReconciliation.md` to handle payments. + + diff --git a/docs/care/HMIS/Billing/ChargeItem.md b/docs/care/HMIS/Billing/ChargeItem.md new file mode 100644 index 0000000..3cfddc6 --- /dev/null +++ b/docs/care/HMIS/Billing/ChargeItem.md @@ -0,0 +1,114 @@ +# Charge Item + +## Summary +A **Charge Item** represents a single billable service, procedure, medication, or product that a patient received, which should be charged on their account ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=The%20resource%20ChargeItem%20describes%20the,process%20and%20internal%20cost%20allocation)). Essentially, each charge item is like a line item in a bill, detailing what was provided, to whom, when, and in what quantity. For example, a charge item could be “Chest X-Ray” or “Blood Test CBC” or “Medication: Antibiotic 500mg – 10 tablets.” Charge Items capture the necessary details (date, provider, etc.) to support billing and are later summed up on invoices. The main purpose of recording charge items is to enable the billing process and internal cost allocation ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=The%20resource%20ChargeItem%20describes%20the,process%20and%20internal%20cost%20allocation)) – they feed into the Invoice generation and financial reporting. + +Each Charge Item is linked to an **Account** (the bucket of charges for a patient or encounter) so that the system knows where to accumulate the cost. Charge Items typically reference a predefined **Charge Item Definition** (the billing code) to fetch pricing and any special billing rules. They also have a status that tracks their billing state (e.g., whether they’ve been billed yet or not). This ensures that each service is billed exactly once and helps in workflows like charge review and approval before billing. + +## Key Fields and Lifecycle Statuses +**Key Fields:** +- **Charge Item Code:** A code or identifier for the service or product provided. This usually corresponds to a entry in the Charge Item Definitions (the “catalog” of billable items). For example, a code might be “XRAY001” for a chest X-ray. The code is often selected from a list in the UI, and it brings along a description (e.g., “Chest X-Ray, 2 views”) and price. *(In FHIR terms, this might be represented as a CodeableConcept or reference to a ChargeItemDefinition ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=ChargeItem)).)* +- **Description:** A human-readable description of the charge, if not obvious from the code. In many systems, this auto-fills when a code is selected. E.g., “Complete Blood Count (CBC) test”. +- **Quantity:** The number of units provided. If the charge item is for a service, quantity is often 1 (each service instance). If it’s for an item (like medication or supplies), quantity could be multiple (e.g., 10 tablets). The UI allows the user to input quantity. The total price for the charge item will be **quantity × unit price**. +- **Account Reference:** The account (or patient encounter) to which this charge is applied. This links the charge to the correct bucket for billing ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=8)) ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=,37%20and%20PaymentReconciliation)). In the UI, if you are adding a charge from within an Account screen, this may be implicit (the system knows which account you are viewing). If adding from a general charges interface, the user must specify the target account/patient. +- **Service Date/Time:** When the service was provided or the item was supplied to the patient. This is important for record-keeping and also for checking against any billing rules (e.g., after-hours charges, or whether the service falls within the account’s billing period). The field may be a single date/time or a range (start/end) if the service lasted a span of time ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=ChargeItem.occurrence)). +- **Performing Practitioner/Department:** (If applicable) Who performed the service or which department it belongs to (for routing and information). E.g., a lab test might list the lab department or the lab technician, a radiology exam lists the radiologist or radiology dept. This can help with internal tracking or if different departments have different billing responsibilities. +- **Price (Unit Price and Total):** The monetary amount to charge for this item. In a FHIR-pure approach, the ChargeItem may not have the price explicitly stored on it, relying on the ChargeItemDefinition for pricing ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=Since%20the%20individual%20ChargeItem%20resources,the%20context%20of%20the%20ChargeItem)). However, in an HMIS it’s common to calculate and store the price when the charge is recorded, so that staff can review it. For example, if “Chest X-Ray” costs $100, and quantity is 1, the total for that charge item is $100. If quantity were 2 (for something like two units of a supply at $5 each), total is $10. + - *The UI usually shows the price when a code is selected.* If any discounts or surcharges apply, those might adjust the price (see **Charge Item Definition** rules). Developers might implement this by fetching the price from the definition and applying any relevant rules at the moment of charge entry. +- **Override Reason / Adjustments:** (Optional) If a price is manually overridden or a charge is waived, the system might allow recording a reason. For instance, if staff set the price to $0 for a courtesy service, they should note why (e.g., “free sample – not billable”). This keeps a trail for auditors. In a strict FHIR model this could be an extension since ChargeItem doesn’t normally include a price override field in the core spec. +- **Status:** The billing status of the charge item, indicating where it is in the billing process. The statuses commonly include **planned**, **billable**, **not-billable**, **aborted**, **billed**, **entered-in-error**, or **unknown** ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=The%20current%20state%20of%20the,ChargeItem)). This field is crucial for workflow: it prevents double billing and indicates if a charge needs attention. + - *Planned:* The charge is anticipated but not yet ready to be billed. For example, a procedure is scheduled for tomorrow – a charge item might be pre-created as planned. It hasn’t actually occurred or is pending confirmation. Planned items do not count towards the account balance until they become billable. + - *Billable:* The service has been provided and the charge is confirmed, making it ready to bill. Most charges added after a service is delivered will start in the **billable** state (meaning they should appear on the next invoice). + - *Not-billable:* The service was provided but will not be billed to the patient (perhaps it’s covered by a flat rate or part of a package, or given as courtesy). Setting a charge to not-billable excludes it from invoicing. For instance, if a hospital does a second X-ray at no charge due to a previous issue, they might record it for history but mark it not-billable. + - *Aborted:* The service was not completed, so it should not be billed. For example, a surgery was started but aborted due to complications – there might be other ways to bill partial costs, but this particular scheduled charge might be aborted. Aborted is similar to not-billable in that it won’t be invoiced, but it specifically indicates the procedure didn’t occur as planned. + - *Billed:* The charge has already been billed on an invoice ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=The%20current%20state%20of%20the,ChargeItem)). Once an invoice including this charge is finalized (issued), the system should update the charge’s status to **billed**. This prevents the charge from being accidentally billed again on another invoice. From a UI perspective, billed items are usually locked from editing (since they’ve been sent out on an invoice). + - *Entered-in-error:* The charge entry was a mistake and should be voided. Perhaps the wrong code was entered or it was a duplicate entry. Marking a Charge Item as entered-in-error means it is invalid and should not be billed or counted. The item might be hidden from normal views or shown with a strike-through. (In some systems, deletion of a charge item might be allowed if truly wrong, but often they keep it with an error status to maintain an audit trail ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=Terminology%20Binding%20%20%2044,Summary%20true%20Comments)).) + - *Unknown:* The status of the charge item isn’t known. This is uncommon in practice; it might be used if the system imported data from elsewhere and isn’t sure of the state. Generally, this would be treated similar to not-billable or would require staff resolution. + +- **Related Charge Items:** (Optional/Advanced) Sometimes one charge item may be logically grouped with others. For example, a surgical procedure might include multiple components (surgeon fee, anesthesiologist fee, operating room fee). In FHIR, ChargeItem has a `partOf` field to reference a parent charge item ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=ChargeItem)), creating a hierarchy. In practice, our HMIS might not require explicit linking, but if it does, it could show one charge as a parent with others indented beneath it. This is more for internal grouping and doesn’t typically change billing, except perhaps to treat the whole group as one package for discounting or not-billable decisions. + +**Business Logic for Charge Items:** +- When a new charge item is recorded as **billable**, it increases the patient’s account balance by the amount of the charge. If it’s marked not-billable or aborted, it should not affect the balance (or may even be excluded from the account’s charge list used for balance calculation, depending on implementation). +- **Status Transitions:** A charge might move through several statuses: + - Planned -> Billable (when the service is done or confirmed). + - Billable -> Billed (once included on an invoice). + - Billable -> Not-billable/Aborted (if decided not to charge). + - Billed -> (possibly back to Billable if an invoice is cancelled; see below). + - Any -> Entered-in-error (if identified as wrong entry). +- Once a charge is **billed**, it generally should not revert to **billable** unless a billing error occurred (like an invoice was cancelled). If an invoice is canceled or marked in error, the system may automatically revert its charges back to **billable** so they can be invoiced again correctly. *(Developers: implement logic that upon invoice cancellation, iterates through its charge items and sets them back to billable or whatever is appropriate, so they can be reused.)* +- **Applicability Rules:** Charge items often must meet certain criteria to be billable. The Charge Item Definition can carry rules – for example, a certain code might only be billable if the patient is over a certain age, or only once per encounter ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=,from%20the%20same%20billing%20system)). The system should enforce these: e.g., if a user tries to add a second charge of a type that is “only billable once per encounter,” the UI should prevent it and notify the user (instead of allowing duplicate charges). Another example: a code might require another code (e.g., a surgical fee might require an associated surgery procedure charge exists). If the prerequisite is not present, the system might warn “Cannot bill this item without XYZ also on the account.” These business rules ensure billing consistency and can reduce claim denials for incorrect coding. +- **Price Calculation:** By default, when a charge is marked billable, the system determines its price via the linked Charge Item Definition. If any conditions (like time of service or patient age) alter the price (surcharges/discounts), those should be computed. The *total* charge amount is then stored or at least displayed. This way, when staff reviews the account or draft invoice, they see the actual dollar amounts. If a price needs to be overridden (perhaps manager approval required), it should trigger a specific workflow (like requiring an “override reason” and possibly raising a flag for review). +- **Link to Clinical Data:** Optionally, charge items may be triggered from clinical actions. For example, when a lab test is ordered and resulted, the system could automatically generate a corresponding Charge Item. In such cases, the charge item might start as planned (when ordered) and become billable when the test is completed. This automation ensures charges aren’t missed. From a user perspective, they might just verify or adjust auto-generated charges rather than enter them all manually. +- **Auditing and Edits:** It’s important for financial integrity that once a charge is billed or marked not-billable, it isn’t silently changed. The system should restrict editing of key fields (especially price and code) after the fact, or log any changes. For instance, if a staff corrects a quantity from 2 to 1 after initial entry, that should be tracked. If a charge was billed and needs correction, usually the proper approach is to issue an adjustment (credit) rather than editing the original charge. The HMIS may or may not support direct credit adjustments at the Charge Item level (some do via negative charges or special adjustment entries). + +## Step-by-Step User Workflows (Charge Item UI) + +**Adding a Charge Item (Posting a Charge):** +1. **Identify Account/Patient:** To add a charge, the billing staff first navigates to the relevant patient’s **Account** (as described in the Account workflow). Typically, there will be an “Add Charge” button on the account’s page or a similar function in a charges module where the user selects the account/patient. +2. **Initiate New Charge:** The user clicks **“Add Charge”**. A charge entry form or dialog appears. +3. **Select Service (Code):** The first field usually is to choose the service or item to charge for. This could be a dropdown or an auto-complete field tied to the **Charge Item Definitions** (the catalog of billable services). The user can type keywords or code, and select the appropriate item from the list (e.g., typing “X-Ray” shows “XRAY001 – Chest X-Ray”). + - Once a code is selected, the form may auto-fill the **Description** and **Unit Price** for reference, based on the definition. For example, after choosing “XRAY001,” the description might show “Chest X-Ray (2 views)” and price “$100.” +4. **Enter Quantity:** The user specifies the quantity if applicable. For many services, this remains “1”. For items like medication, they enter the number of units (e.g., 10 tablets). The form might have a default quantity of 1 which the user can adjust. +5. **Verify/Enter Date:** Ensure the **Service Date** is correct. By default, it might populate with today’s date (or the encounter date). If entering charges retrospectively, the user should set the date to when the service was actually provided. For ongoing services or multi-day items, there might be start/end date fields. +6. **Review Price:** The system calculates the total price = unit price × quantity. For instance, if unit price is $100 and quantity is 1, total is $100. This might be displayed as read-only or editable (depending on permissions). If the user has rights to override the price (e.g., apply a discount or adjust for some reason), they might be able to enter a new price or a discount percentage. In a standard workflow, price override is not common; they’d instead use predefined discount codes or mark it not-billable if waiving. +7. **Additional Details:** If needed, the user can fill in extra fields like performing practitioner (if the form includes it), or add any note about this charge (for example, “Patient requested private room upgrade”). +8. **Submit Charge:** The user clicks **“Save”** or **“Add”**. The system performs validations: + - Required fields must be present (code, quantity, date, etc.). + - Check any rules from the Charge Item Definition (if the system can – e.g., if this code is not allowed twice, see if it’s already on this account). + - If the account is on hold or inactive, the system should block this action (with a clear error as discussed). + - If all is well, the charge is recorded in the database. +9. **System Response:** The new charge item now appears in the account’s charge list. It will typically show up with its details: date, description, quantity, price, and status. Initially, since this is a fresh charge, its status would likely be **billable** (because it’s ready to be billed). The account balance will instantly reflect the addition of this charge (e.g., was $0, now $100 if that was the charge). + - The UI might highlight newly added charges or list them in chronological order. Some systems group charges by date or category on screen for readability. + - If the charge item triggered any warnings (say it’s an unusual combination), the system might show those. For example, “Warning: This service is typically not done for patients under 12 (pediatric rule)” – but still allow it if user confirms. Or “Error: Duplicate charge – that item already exists for today” and refuse saving if it violates a rule. +10. **Confirmation to User:** Possibly a toast or message “Charge added successfully” appears. Staff can then proceed to add more charges or do other tasks. Each charge item added will accumulate in the account until invoicing. + +**Editing/Reviewing Charges:** +- Staff can click on a charge item in the account view to see its details. If it’s in a status that is editable (e.g., billable and not yet billed), they may have an option to **Edit** or **Delete** it. +- **Edit Charge:** Perhaps the patient’s name was spelled wrong in description or quantity was entered incorrectly. The user clicks “Edit” next to the charge. The system opens a form similar to the add form, pre-filled with the current values. The user can adjust allowable fields (maybe quantity or date; code might be locked if changes are not allowed, or maybe they can change code if they entered a wrong one initially). After saving, the changes reflect and the account balance updates if the amount changed. + *(Developers: if a charge’s code is changed, that effectively is like removing one charge and adding another – consider how to audit this. Often better to require deletion and re-add to avoid confusion in records.)* +- **Delete Charge (Entered-in-error):** If a charge was a mistake (e.g., entered on wrong patient’s account), and it hasn’t been billed yet, staff might have the ability to delete it. Upon deletion, the system might actually mark it as entered-in-error behind the scenes (to keep an audit). The UI would remove it from the visible list and adjust the account balance down accordingly. If deletion is not allowed via UI, the alternative is staff mark it “entered-in-error” if that status is provided in a dropdown. That status would exclude it from billing. In either case, once removed/marked error, the effect is the same: the patient is not billed for it. The system should log who removed it and when. +- If a charge is already **billed** (on an invoice that was finalized), the UI will likely **not allow editing or deletion**. Instead, if a change is needed, staff would have to cancel the invoice (which reverts the charges to billable) or issue an adjustment via another process. The charge item on a billed invoice is locked to ensure the invoice remains an accurate snapshot of what was sent out. +- **Marking Not-Billable:** As an alternative to deleting, if the service was real but they decide not to bill it, staff can edit the charge’s status to **not-billable** (if the system allows directly toggling that). The UI might provide a checkbox or status dropdown for charges (again, only if not billed yet). They would select “Not Billable” and possibly input a reason (like “included in research study” or “free re-test”). After saving, the charge would be excluded from invoices. It might appear grayed out or with a tag in the list. The account balance might immediately drop that amount (since we no longer intend to collect it). Essentially, this is a write-off of that charge. + +**Automatic Charge Generation:** (Just for context, not a user action) +- Some charges might appear automatically. For instance, if the system is integrated with an order entry system, when a lab test is marked completed, a charge item could be auto-posted. In such cases, the billing staff’s role is to **review** these auto-posted charges for accuracy. The workflow would be: + - The charge shows up on the account (maybe flagged as new or unreviewed). + - Staff checks that it has the correct code and quantity. If something’s off (e.g., a test was cancelled but charge still posted), they can adjust status or remove it. + - If everything is correct, they don’t need to do anything further; it will flow into the invoice. This reduces manual data entry. + +**Charge Review & Approval:** (If applicable) +- In some hospital workflows, especially for complex cases, charges might be entered by clinical staff and then reviewed by billing staff before invoicing. The system might use the **planned** status for preliminary entries. For example, a nurse enters the items used during a surgery into the system as planned charges. A billing specialist later reviews and switches them to **billable** once verified. In our HMIS UI, this could be done by listing planned charges and providing an “Approve” action that changes their status to billable (and perhaps assigns prices). +- The UI could also allow batch actions, e.g., select multiple charges and mark all as not-billable or move to billable, etc., if many need updating at once. + +## Developer Notes (Charge Item Logic & Validation) +- **Database Model:** Each ChargeItem record should store references to the account (account_id), possibly the definition (charge_code or an ID linking to ChargeItemDefinition), quantity, and an amount. If following FHIR strictly, you might store only the reference to ChargeItemDefinition and not the price, but practically storing the calculated price is useful for consistent reporting (especially if prices can change in the catalog later; you’d want the charge to reflect the price at time of service). +- **Status Field Enforcement:** Use enumerated values for status (to avoid free-text). Enforce via business logic: + - Only certain transitions are allowed (e.g., can go from billable to billed, but not from billed back to billable unless an invoice is undone). + - If a user tries an invalid transition, throw an error. + - If using FHIR codes, map them appropriately (e.g., “billed” corresponds to FHIR’s *billed* status code ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=The%20current%20state%20of%20the,ChargeItem))). +- **Pricing Engine:** Implement logic to fetch and apply ChargeItemDefinition when a charge is created or edited: + - On charge save (if new or if code changed), retrieve the base price from the definition table. + - Check for any applicable *price modifiers*: for example, if the definition indicates “after hours surcharge +20%” and the service date is 10pm, you might calculate that and either adjust the price or perhaps add an additional charge item for the surcharge. FHIR’s design would use a PriceComponent in Invoice for transparency ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=balanced%20with%20this%20Invoice%20account,to%20the%20recipient%20of%20the)), but in our system we might simply adjust the price or create a separate predefined surcharge item. + - Ensure the final price is stored or at least ready to be displayed. + - If an override is allowed, set a flag (so we know this price didn’t follow standard rules). + - Consider rounding issues (especially if percentages involved). +- **Rule Enforcement:** The ChargeItemDefinition might contain rules (applicability conditions) ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=Many%20billing%20systems%20have%20rules,Rules%20for%20applicability%20may%20include)). To implement these: + - E.g., “once per encounter” – before saving a new charge, query if another charge with the same code exists on the same account (and perhaps same encounter). If yes, block or warn. + - “Only in outpatient setting” – if the account type is inpatient and the code is outpatient-only, then prevent adding it (or warn and require override authorization). + - “Only for age < 14” – check patient’s DOB against service date, calculate age, enforce accordingly. + - “Must accompany code X” – if code Y is added, verify code X is also on the account (maybe in planned or billable). If not, warn like “Code Y typically requires code X. Please ensure X is also added if appropriate.” + - These checks can be complex. A simpler implementation is to warn the user to review, rather than outright block, in some cases. But critical ones (like duplicate charge that will definitely cause issues) should be blocked. + - Document any override capability: perhaps a supervisor can override and add a duplicate charge if absolutely needed. +- **Batch Operations:** Provide efficient ways to update statuses in bulk (for backend processing). For example, when an Invoice is finalized containing N charges, instead of updating each charge in a slow loop, use a batch update query to set all their statuses to billed in one go, for performance and consistency. +- **Integrity with Invoice:** When generating an invoice, ensure only charges with status **billable** (and belonging to the account) are considered. Mark them billed atomically with invoice creation. If invoice creation fails halfway, no charge should remain incorrectly marked as billed – handle rollback. +- **Concurrency:** If two users try to bill the same account simultaneously (rare but possible in large systems), or one is adding charges while another is invoicing, you need to handle it: + - Potential solution: lock the account or the involved charges during invoice generation. + - Or check right before finalizing invoice that none of the charges were already billed by another process (and if they were, refresh the list). + - This prevents double-billing or missing charges. +- **Entered-in-error vs Deletion:** Decide how to implement charge removal. The FHIR way would mark entered-in-error ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=Terminology%20Binding%20%20%2044,Summary%20true%20Comments)). If you choose to allow deletion in the UI, consider still keeping a record behind the scenes. Perhaps have a deleted flag or move the record to an audit log table. This avoids data loss which could be important if someone asks “Why was patient billed then credit given?” +- **Logging:** Log who added each charge and when. If changes are made (status change, price override, deletion), log those actions too (user ID, timestamp, old vs new values). This is crucial for auditing and resolving disputes (e.g., “why was this charge removed?”). +- **Link to Orders:** If integrated, maintain reference IDs to clinical orders or procedures that generated the charge, if applicable. This can help trace back from a bill to the clinical event. +- **Future Dating/Planned Items:** If a charge is marked planned (for a future procedure), you might want an automated job or trigger: when the date arrives or the procedure is completed, automatically flip it to billable. Alternatively, require manual confirmation. Ensure planned items don’t inadvertently slip into invoices without review (maybe the invoice generation code filters them out unless explicitly told to include planned ones). +- **Data Exposure:** If there is an API or external reporting, ensure that sensitive charges (like those marked not-billable or error) are either clearly flagged or filtered out as needed to avoid confusion. +- **Calculate Totals by Category:** Some invoices might group charges by type (e.g., Room charges vs Medications). If needed, tag Charge Items with categories (possibly derived from the definition) to facilitate such grouping on invoices or statements. +- **FHIR Note:** In FHIR R4+, ChargeItem is a resource and can reference ChargeItemDefinition for price. If aligning with FHIR, consider using the `$apply` operation at runtime to let a rules engine calculate price components ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=A%20billing%20engine%20will%20apply,Operation)). This could be a more dynamic but heavier approach. For a simpler HMIS, custom code as described above is likely sufficient. diff --git a/docs/care/HMIS/Billing/ChargeItemDefinition.md b/docs/care/HMIS/Billing/ChargeItemDefinition.md new file mode 100644 index 0000000..e57ea7c --- /dev/null +++ b/docs/care/HMIS/Billing/ChargeItemDefinition.md @@ -0,0 +1,116 @@ +# Charge Item Definition + +## Summary +The **Charge Item Definition** module is essentially the **catalog or tariff** of billable services and goods in the hospital system. Each Charge Item Definition represents a template for a billable item – including its code, description, pricing, and any rules about when or how it is billed ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=The%20ChargeItemDefinition%20resource%20provides%20the,type%20of%20billing%20code%20system)). In other words, if a Charge Item is an instance of something being billed to a patient, the Charge Item Definition is the definition of that billable thing in general (the price list entry). This is inspired by the FHIR ChargeItemDefinition resource, which “provides the properties that apply to the (billing) codes necessary to calculate costs and prices” ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=The%20ChargeItemDefinition%20resource%20provides%20the,type%20of%20billing%20code%20system)). + +The Charge Item Definition holds all relevant billing information for a given service or product. For example, there might be a definition for “General Physician Consultation” with code CONS100, base price $50, and rule that it’s only billable for outpatient visits. Another definition might be “MRI Scan – Brain” with code MRI001, price $500, and perhaps an additional surcharge rule for use of contrast material. The module ensures that all charges use consistent codes and pricing, and allows updates to pricing and rules in a centralized way. + +## Key Fields and Configuration +**Key Fields:** +- **Code (Billing Code):** A unique identifier for the chargeable item. This could be an alphanumeric code (like “MRI001” or “LAB123”). Staff will use this code to add charges. Codes may correspond to standard billing codes or internal codes. Each code in the system maps to one definition. *(In FHIR, this would be ChargeItemDefinition.code or part of a coded element.)* +- **Display Name/Description:** A clear name or description of the service/product. E.g., “MRI Scan - Brain with Contrast” or “Complete Blood Count (CBC)”. This is what shows up in drop-down lists and on bills. It should be understandable to both staff and patients. +- **Category:** (Optional) A grouping for reporting or UI organization (e.g., “Laboratory Tests”, “Radiology”, “Consultations”). This helps filter and find definitions when adding charges, and to group them on invoices. +- **Price/Rate:** The base price for the item. This could be a fixed amount (e.g., $500 per MRI) or a rate (e.g., $100 per hour for physiotherapy). If the item is time-based or quantity-based, the definition explains the unit. For example, a medication might be priced “per tablet” or a service “per session.” The price is typically stored as an amount with currency. +- **Unit of Measure:** If needed, the unit that the price applies to (each, per day, per kg, etc.). This field clarifies how to interpret quantity. E.g., “each” for most discrete items, or “hour” for hourly services. In many cases, this is implicit or included in description instead (like “Physio (per hour)”). +- **Applicable Period:** The date range during which this price is effective. There might be versioning of prices. For instance, if prices are updated annually, a definition can have an effective start date (and possibly end date). The system should pick the correct price based on the service date of the charge. If a charge date is outside the effective period of a definition, the system might warn or use the appropriate version of the definition (if multiple versions exist). +- **Applicability Conditions/Usage Rules:** Rules that define when this charge item definition can or should be applied ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=Many%20billing%20systems%20have%20rules,Rules%20for%20applicability%20may%20include)) ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=A%20billing%20engine%20will%20apply,Operation)). These can be quite complex or simple, for example: + - The service is only billable in certain contexts (e.g., *outpatient only*, not for inpatient). + - It may only be charged for patients within certain age ranges (e.g., pediatric vs adult pricing). + - It can only be charged once per encounter or day (to prevent duplicates). + - It must be used in combination with another code (or cannot be used together with another code). + - Certain preconditions like time of day (e.g., an after-hours code that only applies outside 8am-5pm). + - Limit frequency: e.g., “only one physical therapy session per day is billable”. + These conditions might be described in text for human understanding and also encoded in a structured way for the system to enforce. In FHIR, these could be in properties and expressions within ChargeItemDefinition, and are applied via a billing engine ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=A%20billing%20engine%20will%20apply,Operation)). +- **Price Components (Surcharges/Discounts):** Some definitions might include additional price components besides the base price ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=,from%20the%20same%20billing%20system)). For example, “MRI with Contrast” might have a base price plus an additional contrast material charge. The definition can list these components so the system knows to add them. Another example: “After-hours service surcharge 20%” could be a separate definition that is referenced by rule. In FHIR, price components are part of Invoice for transparency ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=balanced%20with%20this%20Invoice%20account,to%20the%20recipient%20of%20the)), but the logic originates from definitions (e.g., a flag that says “apply 1.2x price if after hours”). +- **Multiple Currency or Payer-specific Rates:** (If applicable) Some systems allow different prices for different payer types (e.g., insurance vs self-pay) or tiers. This could be handled by multiple definitions or extensions (like a specific contract price list for an insurer). Our documentation will assume a single standard price, but be aware this complexity exists. +- **Active/Inactive Flag:** Just like accounts, definitions can be active or inactive. An inactive definition means that code should no longer be used for new charges (perhaps it was replaced or the service is discontinued). The UI might hide inactive items from selection lists. If an inactive code is on an old invoice, it remains for historical data but no new charge should reference it. +- **Version or Identifier:** Optionally, a version number or reference ID if the catalog is maintained externally or for regulatory coding systems (like CPT codes version). This helps track if definitions were updated. +- **Associated Entities:** If relevant, link to the actual department or service entity. E.g., a definition for a lab test might reference the lab department, which could be used for routing approvals or notifications. +- **Narrative or Guidance:** Free-text notes explaining the usage of this code. For example, “Use this code for all standard chest X-rays. Do not use for portable X-ray, see code XRAY002 for portable.” These notes help human users choose correctly. + +**Business Logic in Definitions:** +- **Single Source of Truth:** All chargeable items must have a definition entry. When adding a Charge Item, users pick from these definitions, ensuring consistency in naming and pricing. If a user attempts to enter a code that doesn’t exist in the definitions, the system should not allow it (or at least strongly discourage it). This prevents billing for undefined items. +- **Automated Price Calculation:** When a Charge Item is created, the system looks up the corresponding Charge Item Definition to retrieve the price and any conditional rules ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=Since%20the%20individual%20ChargeItem%20resources,the%20context%20of%20the%20ChargeItem)). If the conditions in the definition apply, they are executed. For example, the definition might say “if quantity > 5, give 10% discount” (for bulk supplies). The system would then adjust pricing accordingly. Another example: “Service outside business hours – use surcharge code SURCH10.” The system might automatically add that surcharge as a separate charge or adjust the price as per definition. +- **Consistency and Updates:** If the hospital updates prices (say at the start of a new year, or due to inflation/cost changes), they will update the Charge Item Definitions. New charges will use the new prices. Historical charges remain with the old prices they were charged at (since those were recorded at the time of service with the then-effective price). This means the definition has to possibly store old prices or the system should keep track of from when a new price is effective. +- **Validation of Combinations:** The definitions drive the validation when adding charges: + - They can specify incompatibilities or requirements. E.g., a definition could indicate “not billable with code X on the same day” – if the user tries to add both, the system can catch it. + - They may specify prerequisites (like one code auto-adds another). The system could then auto-add the required code or prompt the user. +- **Optional Auto-Addition:** Some definitions might be configured to automatically add related charges. For example, if a certain procedure always includes a separate consumable fee, the system could prompt “Also add [consumable]?” or just add it when the main code is added. This behavior would be defined in the Charge Item Definition (like a linked supplementary charge). +- **Modifiability:** Usually, only authorized users (like billing administrators) can create or modify Charge Item Definitions, since it affects billing for all patients. Regular billing staff will have read-only access to this catalog when posting charges. +- **Impacts on UI:** The definitions might be used to populate drop-down lists. They might also determine how fields are presented. For example, if a service’s price is per hour, the UI could show a field to enter hours. If per item, it shows quantity. If a code has multiple price components (base + X), the UI might show a breakdown after selection. The goal is to give the user immediate feedback on what will be charged. + +## Step-by-Step Workflows (Maintaining the Catalog) + +**Adding a New Charge Item Definition (for Admin/Billing Manager):** +1. **Navigate to Charge Definitions:** A user with proper permission (e.g., Billing Manager) goes to the **Charge Item Definitions** or “Service Catalog” section of the HMIS. This could be under an admin or billing configuration menu. +2. **Initiate New Definition:** Click **“New Charge Item Definition”**. A form appears to input the details. +3. **Enter Code and Name:** Provide a unique **Code** for the item (the system might enforce uniqueness). Enter the **Description** name. For example, code: `CARD100`, name: “Cardiology Consultation (New Patient)”. +4. **Set Price:** Enter the **Price** for this service. E.g., $150.00. Optionally specify the unit (if not each). For the consultation, unit might be “per visit” (which could be implicit, so maybe no separate unit field needed). +5. **Category/Type:** Choose a **Category** like “Consultation” or “Cardiology”. (This helps in organizing items. The system might have a list of categories.) +6. **Applicability Rules:** Define any rules for this code: + - If it’s specific to a setting: e.g., check a box “Outpatient only” or conversely “Inpatient only” if applicable. + - If it’s age-specific: maybe fields to input min age or max age. + - If it should not be combined with certain codes: possibly a multi-select to pick codes that conflict. + - If it requires another code: a field to select the prerequisite code. + - If there’s a frequency limit: input something like “Max 1 per day” or similar. + Some systems might allow entering these via a simple UI, others might require writing an expression or just documenting it in notes. At minimum, an **internal note** can be recorded (like “Do not bill with follow-up consult on same day”). We assume a UI where common constraints can be toggled. +7. **Price Components/Surcharges:** If this item inherently includes multiple components, list them. For instance, if `MRI001` includes a contrast fee, one approach is to create a separate definition for contrast and then note it here. Alternatively, add a sub-entry in the form: “Additional Fee: Contrast Material $100 (applies if contrast used)”. Let’s say our UI allows adding a sub-line in the definition for surcharges or discounts. The admin could add: Condition: “Uses Contrast = Yes” then “Additional charge $100”. Another example: “Weekend surcharge 15%” as a condition (Day of week = Saturday/Sunday -> price * 1.15). + - If the UI doesn’t support conditional components, the admin might instead create separate definitions for surcharges and rely on business rules to add them in combination. +8. **Effective Date:** Set when this price is effective. If this is a new code, it could be effective immediately (today’s date). If planning a price increase, one could set the effective date in the future. If the form allows, also set an end date if known (often left open-ended until changed). +9. **Activate Definition:** Ensure the definition is marked **Active** so it’s available for use. (Sometimes new entries might default to active unless a checkbox is provided to set it active/inactive.) +10. **Save:** Submit the form. The system validates uniqueness of code, required fields, numeric formats for prices, etc. If all good, it creates the new definition entry. + - The new definition now appears in the catalog list. It should be available in the Charge Item selection UI for any new charges. + - If there’s a sync or caching mechanism for the list of codes (for performance), ensure it refreshes so that the new code shows up for users immediately. + +**Updating a Charge Item Definition (Price change or rule change):** +1. Go to the **Charge Item Definitions** list and search for the code or name in question. E.g., find “MRI Brain”. +2. Click **“Edit”** on that entry. +3. Change the necessary fields: + - If updating the price: you might not want to overwrite the old price if charges already used it. Ideally, to handle price changes, one would *add* a new effective period. For instance, the form might allow adding a new price effective from a certain date. If the UI is simpler, an admin might just change the price field. In such case, the system should possibly warn “This will change the price for all future charges; existing charges are not affected.” and maybe automatically set an effective date for the new price (like today). + - Adjust description if needed (maybe to clarify something). + - Modify rules: e.g., broaden age range, or add a new incompatible code. + - Possibly mark the old price as ended yesterday and new price from today if system supports multiple records or a history. +4. Save changes. The system validates and updates the definition. If versioning is supported, it might actually create a new version entry under the hood rather than simply editing (so that historical data remains tied to old version). +5. After saving, new charges added will use the updated definition. Existing Charge Items already posted are not retroactively changed (they retain the price at which they were added, since those are stored with the charge). + +**Deactivating (Retiring) a Charge Item Definition:** +- If a service is no longer offered or a code is deprecated, an admin can mark it as **Inactive**. This usually involves editing the definition and unchecking an “Active” box or setting a termination date. +- Save the change. Inactive definitions are typically hidden from the charge entry UI so that staff won’t accidentally use them. If they try to use an inactive code (say by typing it manually), the system should reject it. +- The definition remains in the database for reference (especially for old records that used it), but it’s not available for new charges. If there’s a replacement code, the admin might add a note like “Replaced by CODE123 as of 2025”. + +**Viewing the Catalog:** +- The Charge Item Definition list can usually be viewed in a table format by authorized users. It might show columns: Code, Description, Price, Unit, Active/Inactive, etc. +- Users (like billing staff) with view-only access can search this list to find how something is billed. For example, “How much is the charge for an MRI spine?” They can find the definition entry for MRI spine which says, e.g., $400. +- This ensures transparency: staff can answer patient queries about costs using the official catalog. + +**Using Definitions during Charge Entry (UI perspective):** +- As mentioned earlier, when adding a charge (Charge Item), the system references this catalog. The search or dropdown is driven by the definitions. If a code is updated or newly added, that is immediately reflected to the end user adding charges. +- If a user somehow doesn’t find a desired code (maybe it’s new or they are using an old term), there might be a process to either look up synonyms or request a new code. The definitions can have synonyms or keywords for searching. E.g., if a user types “blood sugar”, it could match a definition for “Glucose test”. +- If the user selects a code that has specific rules, the UI might give immediate feedback. For instance, if a code is “Inpatient only” and they’re trying to add it on an outpatient account, upon selection the system could show a warning “This code is typically for inpatient use; please verify.” It might still allow if the user insists (or might block entirely depending on strictness). + +## Developer Notes (Definition Module & Pricing Engine) +- **Data Structure:** Maintain a table for ChargeItemDefinitions with fields as above (code, description, price, etc.). If you need to support price history, you might have a linked table for prices with effective dates. Alternatively, include validity dates in the main table and create a new record for the same code when updating price (differentiated by version or effective date). Ensure that there’s a way to fetch the correct price by date. +- **Unique Code Constraint:** Enforce unique codes at the database level. Also possibly enforce no overlap of effective periods for the same code (to avoid ambiguity in price on a given date). +- **Performance (Lookup):** The list of definitions could be large if the hospital has many services. Use indexing on code and description for fast search. When a user is typing to search, consider a search service or caching popular terms in memory for quick auto-complete. Ensure inactive codes are either filtered out or clearly marked. +- **Applying Definitions to Charges:** Implement a function like `applyDefinition(charge, definition)` that: + - Checks each rule in the definition against the context (patient, account, other charges). + - Adjusts the charge’s allowed status or price accordingly. + - For example, if definition says “not billable for age > 14” and patient is 20, then perhaps `charge.status = not-billable` by default or a warning is raised. However, usually one wouldn’t add such a charge for an adult at all (the UI might filter it out). + - Another example: definition has a condition “if after hours, add 50”. If charge time is 9pm, either add a separate charge automatically or append a component. A simple method: create a hidden surcharge definition and auto-add a ChargeItem for it. Or adjust the price of the current charge. Decide on one approach and implement consistently. +- **Compound Pricing:** FHIR suggests multiple price components (like base price, surcharge, discount) for transparency ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=balanced%20with%20this%20Invoice%20account,to%20the%20recipient%20of%20the)). If implementing that, your ChargeItemDefinition might list components rather than a single price. For instance, base = 100, night surcharge = 20%. At runtime, you’d calculate total = 100 + (20% of 100). You might want to store both components to show on invoice (like “Base fee $100, After-hours surcharge $20”). This can be done by generating two separate line items (which could confuse patients) or by supporting a composite structure in the invoice line. We discuss invoice presentation in the Invoice section. +- **Validation vs Enforcement:** Some rules might be soft (warnings) and some hard (errors). Decide which rules absolutely prevent charge entry (and implement as such). Others implement as warnings that the user can override with a justification (store that justification). +- **Administration UI:** Provide a secure UI for managing definitions. Only certain roles should access this. Also, consider logging changes (who changed a price or rule, old vs new values). +- **Impacts of Changes:** Changing a price definition should not retroactively update already posted charges. Ensure that when applying definitions to a ChargeItem, you stamp the price at that time. If you store just a reference to the definition and calculate on the fly, then historical invoices might change if definitions change – which is undesirable. Therefore, better to store the resolved price in ChargeItem (or invoice line). If you need to reproduce an old invoice exactly, you cannot rely on current definition data. + - Some implementations handle this by version: each invoice or charge stores the code *and a reference to the definition version*. If someone needs to understand that price, they refer to the definition version record. +- **Interdependence of Definitions:** If you have rules like “code A requires code B”, ensure both exist. Possibly create a mechanism of linking definitions (like references or foreign keys for prerequisites). If code B is removed or changed, update code A’s rule as well. +- **Testing Scenarios:** It’s important to test various combinations: + - A charge with multiple applicable rules (e.g., patient under 14 AND after hours – does it get two modifications?). + - Ensure no double-counting surcharges (applying same rule twice). + - If two different rules conflict (unlikely if curated well, but e.g., one rule says “price = 100” another says “price = 80 for same condition” – the system should have a clear precedence or just not allow contradictory rules). +- **Bulk Updates:** If prices increase by a percentage across the board, it might be helpful to have a script or tool to update many definitions at once (rather than manually editing each). Consider designing an import or bulk update interface, especially if prices come from an external source like a national fee schedule. +- **FHIR Alignment:** The structure here corresponds to FHIR’s ChargeItemDefinition. If planning to export or import FHIR resources: + - The rules might be represented as `applicability` expressions in FHIR or `propertyGroup` with `priceComponent`. You would map your internal representation to those. + - The $apply operation in FHIR can take a ChargeItemDefinition and a context (patient, etc.) and return computed price components ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=A%20billing%20engine%20will%20apply,Operation)). You may implement something analogous internally. For example, when finalizing an invoice, for each charge, you could conceptually perform a mini `$apply` to ensure all pricing rules have been applied correctly. +- **Error Handling:** If a user tries to add a charge and the system can’t find a definition (which shouldn’t happen if UI prevents it), handle it gracefully – maybe show “Unknown code” error. Similarly, if a definition exists but has no price (maybe an oversight), do not charge $0 silently; flag it so it can be corrected. +- **Edge Cases:** Consider a scenario where a definition is updated while someone is in the middle of entering charges. If they had the form open with old data and then save, could that conflict? To avoid issues, you might lock definitions editing during peak usage or have the charge posting always re-fetch the latest definition when saving. +- **Security:** Because charge definitions determine revenue, they should be secure. Only authorized changes, and perhaps double-check expensive items. Sometimes an approval is needed for major price changes (two sets of eyes rule). This might be beyond our current scope but keep audit logs for definition changes to catch any accidental or malicious edits. diff --git a/docs/care/HMIS/Billing/Invoice.md b/docs/care/HMIS/Billing/Invoice.md new file mode 100644 index 0000000..d11ef44 --- /dev/null +++ b/docs/care/HMIS/Billing/Invoice.md @@ -0,0 +1,220 @@ + +# Invoice + +## Summary +The **Invoice** module handles the generation of formal bills based on accumulated charges for an account. An **Invoice** is a financial document issued by the healthcare provider (hospital/clinic) to the responsible party (patient, insurance, or other payor) that lists the goods and services provided (the Charge Items) along with their quantities and prices ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=Tracking%20Financial%20information%20is%20vital,with%20their%20quantities%20and%20prices)). In simpler terms, it’s the bill that the patient or insurer receives, detailing what they are being asked to pay for. + +The Invoice pulls together all relevant Charge Items from an Account (or a subset of them for a given billing period) and calculates the total amount due. It serves as the hospital’s record of what was charged, and it’s also used by patients or insurers to process payments. In an HMIS inspired by FHIR, the Invoice correlates with the FHIR Invoice resource, which is designed for structured billing communication ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=towards%20patients,view%20on%20the%20performed%20services)). The invoice is the provider’s view of the charges, as opposed to an insurance Claim which is for payer’s adjudication purposes ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=Competing%20invoicing%20standards%20such%20as,view%20on%20the%20performed%20services)). + +Key points about invoices: +- An invoice can be in different states (draft, issued, paid, etc.), reflecting its lifecycle. +- Invoices reference the account and the specific charge items included. +- Invoices typically have unique numbers for external reference, along with dates and payment terms. +- Once an invoice is issued (finalized), the charges on it are considered billed, and the invoice amount becomes a receivable for the hospital to collect from the payor. + +## Key Fields and Lifecycle +**Key Fields:** +- **Invoice Number:** A unique identifier for the invoice (often a sequential number or alphanumeric). This is what will be printed on the invoice document and used by patients or accounting to reference the bill. The system may auto-generate this when finalizing the invoice (e.g., “INV-2025-000123”). +- **Account/Patient:** A reference to the **Account** (and implicitly the patient) this invoice is for. All charges on the invoice should belong to that account. Typically, an invoice is for one account (one patient’s set of charges) ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=Reference,balanced)). (In some cases, a combined invoice could cover multiple accounts for one payer, but our scope assumes one account per invoice for simplicity). +- **Invoice Date (Issue Date):** The date the invoice is generated/finalized. This is important for payment due calculations and auditing. If an invoice is drafted on one day and finalized on another, the issue date is when it’s finalized. +- **Billing Period (Service Period):** The date range of services covered by the invoice. For example, “Services from Jan 1, 2025 to Jan 31, 2025.” If the invoice is for a hospital stay, it might be the admission to discharge dates. This field is often included on the invoice so the recipient knows which period the charges correspond to. +- **Line Items (Invoice Lines):** Each charge on the invoice becomes a line item. A line item typically includes: + - A description of the service (from the Charge Item Definition). + - The service date (or date range if applicable). + - Quantity. + - Unit price and line total. Some systems may also show any adjustments on the line (like a discount applied). + - Optionally, a code or reference number for each line (for cross-reference). + The invoice line items come directly from the selected **Charge Items**. If the system allows, you might combine or summarize some charges (though usually each charge is a separate line to match audit trail). +- **Subtotal, Taxes, Adjustments:** If applicable, the invoice will compute a subtotal of all line items. If there are any taxes (some jurisdictions tax certain medical services or supplies) or additional fees, those are added as separate lines or in summary. Adjustments or discounts at the invoice level (like a one-time discount or write-off) might appear as a line or summary deduction. +- **Total Amount:** The grand total the invoice recipient is responsible for. This considers all charges, plus taxes, minus any discounts. (It would not subtract payments; payments are handled separately, not on the original invoice). +- **Payor/Recipient:** Who the invoice is addressed to. Often this is the patient (for self-pay portions) or an insurance company if you’re billing them directly. The invoice might have fields like “Bill To: John Doe” or “Bill To: XYZ Insurance, Policy #12345”. In FHIR terms, there might be a `recipient` which could be an organization (insurer) or patient ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=Tracking%20Financial%20information%20is%20vital,with%20their%20quantities%20and%20prices)) ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=code%20draft%20,error%20Binding%3A%20Invoice%20Status%20%28Required)). In our HMIS, if the account has an insurance coverage as primary, the initial invoice might be addressed to the insurance. +- **Issuer (Provider):** The organization issuing the invoice (e.g., the hospital name and address). This is usually a constant (the hospital’s details) and printed on the invoice header. It might be stored or configured globally rather than per invoice, but the field exists to identify who is charging. +- **Status:** The state of the invoice in its lifecycle. The main statuses include **draft**, **issued**, **balanced**, **cancelled**, and **entered-in-error** ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=code%20draft%20,error%20Binding%3A%20Invoice%20Status%20%28Required)). + - *Draft:* The invoice is in preparation. It’s not yet finalized or sent out. In this state, staff can still add/remove charges or make corrections. Draft invoices are essentially internal working documents. They may not have an official number assigned until finalization, or might have a provisional identifier. + - *Issued:* The invoice has been finalized (approved and sent to the payor). This status indicates the invoice is now an official claim of money. According to FHIR, “issued” means the invoice has been finalized and sent to the recipient ([OPENIMIS.FHIR.R4\Status (Invoice) - FHIR v4.0.1](https://fhir.openimis.org/ValueSet-invoice-status.html#:~:text=status%20hl7,cancelledCancelled%20the%20invoice%20was%20cancelled)). At this stage, the invoice is considered outstanding debt that needs to be paid. + - *Balanced:* The invoice has been completely paid off ([OPENIMIS.FHIR.R4\Status (Invoice) - FHIR v4.0.1](https://fhir.openimis.org/ValueSet-invoice-status.html#:~:text=status%20hl7,cancelledCancelled%20the%20invoice%20was%20cancelled)). In other words, the balance due on the invoice is zero because payment(s) matching the full amount have been reconciled. This is essentially a terminal state indicating no further money is owed on this invoice. + - *Cancelled:* The invoice was cancelled and is not to be paid ([OPENIMIS.FHIR.R4\Status (Invoice) - FHIR v4.0.1](https://fhir.openimis.org/ValueSet-invoice-status.html#:~:text=status%20hl7,cancelledCancelled%20the%20invoice%20was%20cancelled)). Perhaps it was created in error or the charges were moved to another invoice. A cancelled invoice is usually not sent out, or if it was, a cancellation notice is issued. The invoice number might be retired or might reference a reason for cancellation. + - *Entered-in-error:* If the invoice record was a mistake (e.g., completely wrong target or duplicate entry), it can be marked as entered-in-error. This is similar to cancelled but specifically denotes a data entry error. It should not be considered a valid invoice at all. In systems, often “cancelled” covers most scenarios (entered-in-error might be used in FHIR contexts for tracking, but practically a cancelled invoice can also cover erroneous ones with an explanation). + - *(Partial Payments?:)* Not a separate status, but it’s worth noting that if an invoice is partially paid, it typically remains in “issued” status (since it’s not fully settled, thus not balanced yet). There might be fields to track how much has been paid and what remains, but the status doesn’t change to a special “partially paid” value. Staff would look at payment records to know the outstanding balance on an issued invoice. +- **Payment Terms/Due Date:** Often invoices will say “Payment due in X days” or a specific due date (e.g., due 30 days from issue). The system might calculate a due date based on issue date plus a standard term (like 30 days). This isn’t exactly a status, but it’s an important piece of info. If the invoice is to an insurance, due date might not apply in the same way (it goes through adjudication). If to a patient, due date indicates when the patient should pay by. +- **Related References:** Possibly fields like *PaymentReconciliation reference* (if payment for this invoice has been recorded, a link to that), or *Claim reference* if this invoice was also submitted as an insurance claim. These help tie the invoice to other financial records. +- **Cancelled Reason:** If status is cancelled, a field to capture why (e.g., “Duplicate invoice”, “Charge error, invoice voided”) ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=%3CcancelledReason%20value%3D%22%5Bstring%5D%22%2F%3E%3C%21,cancellation%20of%20this%20Invoice)). This helps with audit and clarity. +- **Notes/Comments:** Any additional notes to include on the invoice, such as “Thank you for your prompt payment” or “Includes 10% discount as per management approval”. Also could include internal notes not printed, about special arrangements. + +**Business Logic (Lifecycle & Rules):** +- **Drafting vs Finalizing:** Invoices can be prepared as draft, allowing staff to review and possibly get approval before issuing. While in draft, modifications are allowed: + - Staff can add or remove line items (which corresponds to adding or removing Charge Items to the invoice). Usually, only charges that are in “billable” status and not yet invoiced can be added. + - They might adjust quantities or give discounts in this phase as well (for example, perhaps a manager can apply a manual discount line). + - The invoice total is recalculated with each change. +- **Finalization (Issuing):** When staff are satisfied, they will finalize the invoice. At this point: + - The invoice status changes to **issued**. + - The system may assign the official invoice number (if it wasn’t assigned at creation). + - The issue date is set (if not already). + - All included Charge Items are marked as **billed** (their status updated, as discussed in Charge Item section). + - The invoice becomes read-only for content; you generally shouldn’t edit line items after issuing (short of cancelling the invoice). + - The invoice is now ready to be sent to the recipient (could be printed or electronically transmitted). +- **Posting/Printing:** Once issued, the invoice can be delivered. The system might have a function to print the invoice (generating a PDF or printout) or to send it via email. This doesn’t change the status, but it’s a crucial part of the workflow. The invoice document will list all charges and the total due. +- **Payments:** After issuance, the invoice sits in “issued” status until payment(s) are received: + - If a payment comes in (via the Payment Reconciliation process), the invoice doesn’t immediately disappear; it just gains a record of payment. The invoice might show amount paid and remaining due. + - When the total amount of the invoice has been paid, the system should mark the invoice as **balanced** automatically ([OPENIMIS.FHIR.R4\Status (Invoice) - FHIR v4.0.1](https://fhir.openimis.org/ValueSet-invoice-status.html#:~:text=status%20hl7,cancelledCancelled%20the%20invoice%20was%20cancelled)), indicating it’s fully settled. This could be done by the Payment Reconciliation logic (when it notices full payment). + - Partial payments do not change the status (remain “issued”), but internal tracking of outstanding balance is updated. +- **Cancellation:** If an error is discovered on an issued invoice (e.g., a charge was wrong or the invoice was sent to the wrong payer), you may need to cancel it. Business rules: + - Only allow cancellation if no (or minimal) payments have been applied. If payments exist, typically you can’t outright cancel; you might have to refund or reallocate payments first. + - When cancelled, set status = cancelled, and record a cancellation reason ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=%3Cstatus%20value%3D%22%5Bcode%5D%22%2F%3E%3C%21,cancellation%20of%20this%20Invoice)). The system should also free up the underlying charge items to be billed on another invoice if appropriate. (i.e., change their status back to billable or even planned, depending on scenario). + - Possibly generate a new invoice if needed (for correct charges). Or if the entire thing was wrong, just cancel and start over. + - Cancelled invoices are kept for audit, but are not considered collectible. +- **Avoiding Duplicate Invoices:** The system should ensure the same charge isn’t invoiced twice. This is handled by charge status (once included on an issued invoice, a charge shouldn’t appear on another invoice). When creating an invoice, the selection of charges should exclude any that are already billed. If a user somehow attempts to include a charge that’s been billed, the system should flag it as not allowed. +- **Multiple Invoices per Account:** It’s possible to have multiple invoices for one account. For example, in a long hospital stay, they might generate interim invoices monthly, or one at discharge and then a supplementary one for late charges. The system should support picking which charges to include each time. Typically, an invoice might include all currently uninvoiced charges up to a cutoff date. If doing partial billing, the UI might allow selecting specific items or setting a date range. +- **Invoice for Insurance vs Patient:** If insurance is involved, an initial invoice might be created to send to the insurer (or an electronic claim, depending on integration). After insurer pays or responds, a secondary invoice (often called patient statement) might be created for the patient for any remaining amount. In our HMIS, the Invoice module could handle both by marking who it’s addressed to. For instance, invoice #100 to Insurance (for full charges) and after insurance adjustments, an invoice #101 to patient for copay/deductible. However, in FHIR, such coordination might use Claim/ClaimResponse for insurance and Invoice for patient billing. Here we can allow Invoice to represent any bill request. +- **Interfacing with Insurance Claims:** If the HMIS uses a separate Claim process, an invoice to insurance might effectively be a Claim record. But if not, the invoice itself could be used as the claim. Developer note: Decide if invoices to insurance will be recorded as Invoice in system (with a flag or recipient = insurance), or if they bypass invoice and only use Claim. For simplicity, assume all billing to any payer results in an Invoice in this module (ensuring consistent handling of payments via Payment Reconciliation). +- **Reminders/Overdue:** If an invoice remains unpaid past its due date, the system might flag it as overdue. It might trigger reminders or follow-ups. (This is more workflow after issuance: e.g., the UI could show a red “Overdue” label if today > due date and not balanced.) The status doesn’t change, but an additional field or calculation shows it’s overdue. +- **Invoice Adjustments/Credits:** If after issuing an invoice, one charge amount needs to be reduced (but not fully cancel the invoice), an approach is to add an adjustment line (negative line item) to the invoice. Some systems allow adjusting an issued invoice by adding a “- $50 adjustment: courtesy discount” and updating total. However, in strict accounting, once issued you’d rather cancel and reissue or issue a separate credit note. Implementation can vary. We mention it as an option: e.g., if a minor correction, maybe allow one to add an adjustment line in draft or require cancellation and new invoice. +- **Resending or Reissuing:** If a patient loses the invoice or an insurance needs a copy, staff can reprint the same invoice (with same number). If an invoice was lost before sending, you wouldn’t typically change its contents unless needed; you’d just send again. + +## Step-by-Step User Workflow (Invoice Creation & Management) + +**A. Creating and Finalizing an Invoice:** + +1. **Initiate Invoice Creation:** A billing staff user navigates to the **Invoices** section for a particular account. Often, on the Account page, there will be a button like **“Generate Invoice”** or **“Create Invoice”**. They click this to start the process. +2. **Select Charges to Include:** The system will gather all **billable** Charge Items on that account that have not yet been invoiced ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=towards%20patients,view%20on%20the%20performed%20services)). These charges are typically listed out for the user to review. In many cases, the default is to include all of them. If needed, the user may have options to: + - Remove certain items from this invoice (perhaps to bill them later or handle separately). + - Confirm the date range of charges (maybe the UI says “Include all charges up to today” which is common). + - If partial billing is supported, maybe the user can uncheck some items if they plan to invoice those another time. + But by default, assume all open charges for that account are going into this invoice. +3. **Review Draft Invoice Details:** The system now shows a **draft invoice** view. This will look like an invoice with line items listed, but not finalized. The user should check: + - All expected charges are present and none are missing or extra. + - Each line has correct description, quantity, and price. + - The subtotal and total calculations at the bottom seem correct. + - The invoice is being addressed to the correct party (by default, perhaps the patient or primary insurance based on account’s coverage/guarantor settings). + - The invoice date (which will default to today) and billing period (maybe from first charge date to last charge date). + - If there are any automatic adjustments or discounts (for example, if the patient has a package deal, maybe some charges zeroed out or a discount line is present). + The UI might allow editing certain fields in draft: + - Changing the **Bill To**: e.g., user could switch the recipient from insurance to patient if needed for this invoice. + - Adding a manual line item: e.g., a one-off adjustment or a service that was not captured as a Charge Item (less ideal, but some systems let you add an ad-hoc line with a description and price). + - Removing a line: unchecking or deleting it from this invoice (the charge would remain in account and could be invoiced later). + - Possibly adding a comment/note to the invoice (like “Payment plans available, contact billing” or any special message). + Typically, the line item details themselves (description, price) come from the charges and can’t be edited here except by going back to edit the Charge Item. +4. **(Optional) Save as Draft:** If the user is not ready to finalize (maybe needs supervisor approval or waiting for end of day), they can save the invoice as **Draft**. The system will save the current invoice with a temporary ID (maybe no official number yet, or a draft number). + - In draft state, the invoice is not yet considered sent. Staff can come back later, open the draft, and continue editing. + - The advantage is that the selection of charges is frozen to that draft, so new charges that come in won’t automatically jump onto that draft until it’s finalized or updated. Some systems might still allow updating the draft with newly added charges if needed. + - Draft invoices might show in an “Unissued Invoices” list for that account or in a billing worklist. They could be printed as “Pro Forma Invoice” for internal use if needed. +5. **Finalize (Issue) the Invoice:** When ready, the user clicks **“Finalize”** or **“Approve & Issue Invoice”**. A confirmation like “Once finalized, this invoice will be issued to the payer and no further edits will be possible. Continue?” might appear. On confirmation: + - The system assigns the official **Invoice Number** (if not already assigned at creation). + - Sets **Status = Issued** ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=code%20draft%20,error%20Binding%3A%20Invoice%20Status%20%28Required)). + - Records the **Issue Date** (often the current date-time). + - Locks the invoice content from further changes. + - Updates all the included charge items: marks their status to **billed** ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=The%20current%20state%20of%20the,ChargeItem)) and links them to this invoice record (so it’s easy to find which invoice a charge went to). + - The invoice is now saved as an official record. +6. **Output the Invoice Document:** Immediately after finalizing, the system will typically prompt to **print** or **view** the invoice PDF. The user can then print it out to send by mail or hand to the patient, or it could be emailed if the system supports (with patient consent etc.). The printed invoice will show the invoice number, date, patient info, list of charges, total due, etc. + - If the invoice is to insurance, the output might be a standardized form or electronic claim — but if we treat invoice as multi-purpose, perhaps we still generate a readable invoice and separately send an electronic claim via another process. +7. **Post-Finalization UI Changes:** The invoice now appears in the account’s invoice list as an **Issued** invoice with its number and total. The charges that were on it no longer show as outstanding charges (they might move to a “Billed charges” section or simply not appear in the add-charge list anymore). The account’s balance might still remain the same until payment comes, but now that balance is associated with an issued invoice. + - If the invoice was to insurance, perhaps the account might show “Pending Insurance: $X” to differentiate that portion. + - The user can still open and view the invoice details, but all fields will be read-only, and a big “Status: Issued” label is shown. + - The user might see options like “Record Payment” or “Cancel Invoice” now available for that invoice. + + An example workflow for creating an invoice is illustrated above. It begins with selecting an account and gathering all unbilled charges into a draft invoice for review. The user can save it as a draft if it’s not ready to issue, or finalize it to mark it as issued. Once issued, the invoice is considered outstanding for payment. *Figure: Creating and issuing an invoice (UI workflow).* + +**B. Canceling an Invoice (Voiding a bill):** + +1. **Locate the Issued Invoice:** If an invoice needs cancellation (e.g., it was generated with incorrect information or patient decided on a different payment route before paying), the user finds that invoice in the system. Only **Issued** (or possibly Draft) invoices can be cancelled. If it’s draft, they might simply delete the draft. If issued, proceed with cancellation. +2. **Cancellation Action:** Click **“Cancel Invoice”** (sometimes shown as “Void” or “Delete Invoice” depending on terminology, but it should preserve record ideally). The system will likely prompt for a **Cancellation Reason** (a required input). The user provides an explanation like “Charges incorrect – will reissue” or selects a reason code (if predefined reasons). +3. **Confirm Cancellation:** On confirmation, the system: + - Sets the invoice status to **Cancelled** ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=code%20draft%20,error%20Binding%3A%20Invoice%20Status%20%28Required)). + - Stores the cancellation reason text ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=%3CcancelledReason%20value%3D%22%5Bstring%5D%22%2F%3E%3C%21,cancellation%20of%20this%20Invoice)). + - Possibly updates an “Cancelled Date”. + - Crucially, it must **unlock the charges** that were on this invoice: those charge items should be marked back from billed to their prior state (usually back to **billable**, as they haven’t truly been paid or anything). This allows them to be included on a new invoice later. + - If any payments had somehow been applied to this invoice (which is unlikely if we cancel early; but suppose a partial payment was recorded), the system should warn or prevent cancellation until that is resolved (the payment would need to be unlinked or refunded). + - The invoice record remains in the system for audit, but is tagged as cancelled and should not appear as an active receivable. +4. **Post-Cancellation Outcome:** The account will now show those charges as unbilled again. The cancelled invoice might be visible in an invoice history list (marked clearly as cancelled, maybe with a strikethrough or red status). It might not count towards any financial totals except in audit reports. If printed, the invoice would typically not be used, but if needed, it might have a watermark “VOID”. +5. The user can now correct whatever was wrong (maybe fix some charge items, or combine into a single invoice differently) and then create a new invoice as per steps above. + +**C. Recording a Payment for an Invoice:** + +*(Detailed payment workflows are covered in the Payment Reconciliation section, but from an invoice user’s perspective:)* +- A user can select an issued invoice and choose **“Record Payment”** if a patient pays or an insurance EOB comes in. This usually pre-fills the invoice details into the payment entry form (so it knows which invoice to credit). The steps then align with the Payment Reconciliation process (enter amount, method, etc.). Once a payment is saved: + - The invoice screen will update to show payments applied (like listing a payment of $100 on date X, possibly reducing “amount due”). + - If the full amount gets paid, the invoice status might update to **Balanced** automatically, and perhaps a “Paid in full on [date]” note is shown. + - If partially paid, the status stays Issued, but maybe a “Balance remaining: $Y” is displayed. +- The invoice could also be marked balanced by the system when a Payment Reconciliation covering its full amount is finalized. + +**D. Viewing and Managing Invoices:** + +- On the account page, staff can see all invoices associated with that account: + - **Drafts:** listed separately maybe, to differentiate from issued ones. + - **Issued:** with status, number, date, amount, outstanding balance. + - **Balanced (Paid):** might be filtered out or marked as paid. + - **Cancelled:** likely either hidden by default or shown in an archive list. +- They can click on any invoice to open details. For issued ones, they can reprint or see payment history. For drafts, they can edit or continue processing. +- The system might allow searching all invoices in the system by number, patient, or status (for billing office overview). For example, a billing manager might list all “Unpaid Invoices over 60 days” to follow up. +- If the HMIS supports integration, an invoice might have an option like “Submit Claim” if sending to insurance electronically (which could change status to something like “Submitted” in an extended workflow, but in basic terms it’s still issued from provider side). + +In summary, from a staff perspective, generating an invoice is a guided process where the system pulls in charges, the user reviews, and then the invoice is finalized and sent out. The system tracks its status through payment and closure. + +## Developer Notes (Invoice Processing & Integration) +- **Invoice Generation Logic:** When the user initiates an invoice creation, implement logic to fetch all eligible charges: + - Query the ChargeItem table for all records linked to the account with status = billable (and possibly any additional criteria, like within certain date if partial billing by date). + - If an account can have multiple draft invoices concurrently (probably not typical), decide how to handle allocation of charges between them. Usually, one invoice at a time per account to avoid confusion. + - Once charges are selected for an invoice, mark them in some way (perhaps lock them or mark as "invoicing in progress") to prevent them being scooped up by another invoice process or accidentally double-charged. +- **Draft State Persistence:** When saving a draft invoice: + - Store which charges are associated with it (maybe a join table InvoiceLine linking invoice draft to charge items). + - Do not yet modify the charge item status; only do that on final issue. + - Possibly generate a temporary ID. You might use a separate sequence for invoice numbers vs draft IDs. Some implementers use negative IDs or a prefix for drafts. Alternatively, treat draft similarly but mark status = draft and number = null or "DRAFT". +- **Invoice Number Generation:** Ensure invoice numbers are unique and sequential or follow required format. This likely happens at finalize. Consider concurrency: two users finalizing different invoices at same time should get different numbers without conflict. A robust approach is to have a transaction-safe sequence in the database. +- **Status Transitions & Enforcement:** + - Only allow moving from Draft -> Issued, Issued -> Balanced (via payment), Issued -> Cancelled, Issued -> (possibly entered-in-error), and Balanced -> (maybe allow cancel if a mistake but usually once paid you wouldn’t cancel). + - Do not allow editing content when status is Issued or Balanced. + - If someone tries to cancel a balanced (paid) invoice, either block it or require first reversing the payments. +- **Linking Charges to Invoice:** When finalizing: + - Update each charge: set status to billed, and optionally add a reference to invoice ID on the charge record (if you want quick backward links). FHIR doesn’t explicitly have an invoice reference on ChargeItem, but nothing prevents an extension or a search by account+status. Many implementations will put an “invoiceId” field in charge for convenience. + - Conversely, create invoice line entries that reference the original charge IDs (so you can trace from invoice line back to charge details if needed). + - Once that’s done, future attempts to invoice those same charges should find them as already billed and skip them. +- **Printing/Formatting:** Generate an invoice document (PDF/printout) with a clear layout. Possibly include hospital logo, address, invoice number, patient details, list of charges (with maybe codes or dates), total, and payment instructions. If multiple languages or localization is needed, design templates accordingly. +- **Partial Invoice Selection:** If supporting partial selection in UI, ensure the backend can handle arbitrary subsets. The UI might pass specific charge IDs to include/exclude. The default can be “all billable charges now”. +- **Payment Tracking on Invoice:** + - Maintain a field for amountPaid on invoice, updated whenever a payment is applied. This can make checking fully paid easy (amountPaid vs total). + - Or calculate it by summing PaymentReconciliation allocations referencing that invoice each time (slower but single source of truth). + - Possibly maintain amountDue = total - amountPaid. + - When amountDue reaches 0, auto-set status to Balanced. This could be done via a trigger when posting payments or explicitly in payment application code. +- **Automating Status Balanced:** For safety, one might only mark Balanced when explicitly triggered (like after recording a payment covering full amount). But also consider edge case: if an invoice is $100 and two different payments $60 and $40 are applied at different times, after second payment, code should detect total paid equals invoice total and then set Balanced. This means the Payment Reconciliation process needs to check the invoice’s amounts or sum payments so far. + - Alternatively, provide a batch job that scans invoices for fully paid ones and marks them balanced, if synchronous updates are tricky. +- **Cancelling Invoice Implementation:** + - Ensure atomicity: update invoice status, free up charges (set them to billable) within one transaction. If any part fails, roll back all, to avoid stranded charges (e.g., invoice cancelled but charges not restored). + - If a charge had been partially paid (rare scenario, but maybe they paid something before cancellation), you may either not allow cancel or if allowed, handle that: possibly keep the payment but without an invoice? That’s messy — better to not cancel in that case or require refund. Usually, one wouldn’t cancel after payment; instead would issue a correcting credit. + - Mark the invoice number as cancelled in case numbering needs to skip or reuse? Typically, do not reuse numbers – even cancelled invoice keeps its number. +- **Reissuing after Cancel:** The same charges can now go to a new invoice. That new invoice might get a new number. Optionally, you could link the new invoice to the old cancelled one for reference (not required but could be useful context). +- **Multiple Payers (Insurance then Patient):** If the workflow includes insurance, consider: + - Possibly generating an invoice to insurance (with status maybe stays issued until insurer responds, then PaymentRec comes in). After insurer pays or denies certain items, the remaining can be billed to patient. There are a couple of approaches: + - Create separate invoices: one for insurance, one for patient balance. If doing so, one must split the charges or amounts accordingly. + - Or one invoice listing insurance portion and patient portion (less common, usually separate statements). + - A simpler approach: treat the insurance claim outside of Invoice; only use Invoice for patient billing after insurance. But since the spec mentions PaymentReconciliation referencing invoices ([PaymentReconciliation - FHIR v6.0.0-ballot2](https://build.fhir.org/paymentreconciliation.html#:~:text=the%20individual%20payment%20amounts%20indicated,or%20%2031%20for%20example)), one can indeed track insurance payments against an invoice too. + - Perhaps an invoice is always ultimately to the patient/guarantor, and insurance is handled by Claim. However, openIMIS and others seem to use Invoice for insurance too. Decide based on requirement. + - Developers might need to incorporate logic: If account has insurance, maybe don’t invoice patient until insurance results are back; or generate an invoice but mark it as to insurance (which in effect is like a claim). + - For our documentation, we haven’t deeply distinguished, so implementation can vary. +- **Overdue & Reminders:** Could implement a job to mark invoices as overdue if current date > issue date + terms and status still issued (not balanced). This might trigger notifications or at least a visible flag. Not mandatory but typical in real systems. +- **Invoice Adjustments:** If the system allows editing an invoice after issuance by adding an adjustment line: + - That effectively changes the total. If the invoice was $100 and you add a -$10 line, total becomes $90. One must ensure consistency: the underlying charge items still sum to $100, but invoice says $90 due. In accounting, that -$10 should be recorded as a write-off or discount entry somewhere. + - Possibly better to avoid mid-flight changes and instead handle via PaymentReconciliation (like enter a $10 adjustment as a PaymentReconciliation of type adjustment). + - Simpler: do not allow adding lines post-issue; require cancel and reissue if changes needed. That keeps invoice = sum of its charges strictly. +- **Query by Account/Status:** Implement convenient queries: + - Find all invoices for an account (for account view). + - Find all unpaid invoices for accounts, etc. + - Ensure that when retrieving account balance via account, you consider partially paid invoices correctly (i.e., you might sum all charges - payments; or sum all invoice totals - payments). + - Might double count if not careful: maybe simpler to rely on charges and payments at account level, ignoring invoices for balance calc, as FHIR suggests. +- **Integration with PaymentReconciliation:** The FHIR invoice resource references PaymentReconciliation ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=8,Resource)). In implementation: + - When a PaymentReconciliation is created (payment posted), allow linking which invoices it covers. If one payment covers multiple invoices, all those should be updated. + - PaymentReconciliation might itself store invoice references in its details, or you have a join table. + - Ensure partial payments update invoice record (either store remaining balance or track via PaymentReconciliation records). +- **Security & Roles:** Limit who can cancel or edit issued invoices (maybe only supervisors). Normal clerks might only record payments. This can prevent malicious or erroneous cancellations of valid bills. +- **FHIR API Note:** If exposing these as FHIR: + - The Invoice resource in FHIR R5 is still trial but has similar fields. Use the same statuses (draft, issued, balanced, cancelled, entered-in-error) ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=code%20draft%20,error%20Binding%3A%20Invoice%20Status%20%28Required)) to maintain compatibility. + - PaymentReconciliation and Invoice linking should conform to FHIR (e.g., PaymentReconciliation.detail might point to Invoice). + - For now, internal workings can be done without strictly following all FHIR mechanics, but keep in mind for future interoperability. +- **Testing Scenarios:** + - Create invoice when no charges exist (system should not allow or show a message “No billable items to invoice”). + - Create multiple invoices sequentially as new charges come in (one at discharge, then a supplemental later). + - Cancel after partial payment, see what happens. + - Ensure a balance invoice cannot be cancelled or edited. + - Large invoices (many lines): test performance of rendering and summing. +- **Edge Case - Account with zero charges:** If for some reason an invoice is needed for a zero amount (maybe just to close out?), decide if allowed or skip since it’s pointless. Usually no invoice if nothing to bill. +- **Linking invoice to account balance:** Possibly update account’s notion of outstanding receivable. But since account balance can be derived from charges minus payments (not caring how many invoices), you may not need a separate field. The account could optionally track total invoiced vs not invoiced. +- **Open/Closed Accounting Periods:** In some hospital billing, once an account is discharged, they want all charges on one final bill. Late charges pose a problem. The system might allow generating another invoice for late charges or require managerial approval to add charges to a closed account. We touched on that. Implementation should allow invoicing any charges that appear later even if account was inactive (maybe temporarily reactivate or allow invoice generation even if account inactive but has unbilled charges). \ No newline at end of file diff --git a/docs/care/HMIS/Billing/PaymentReconciliation.md b/docs/care/HMIS/Billing/PaymentReconciliation.md new file mode 100644 index 0000000..41291ce --- /dev/null +++ b/docs/care/HMIS/Billing/PaymentReconciliation.md @@ -0,0 +1,203 @@ +# Payment Reconciliation + +## Summary +The **Payment Reconciliation** module is responsible for recording payments (and adjustments) that the hospital receives and matching them to the corresponding invoices or accounts. In essence, it’s how the system knows an invoice has been paid, and by whom and when. Each Payment Reconciliation entry represents a payment transaction and how that payment is allocated to one or more invoices or other receivables ([PaymentReconciliation - FHIR v6.0.0-ballot2](https://build.fhir.org/paymentreconciliation.html#:~:text=The%20PaymentReconciliation%20resource%20provides%20the,or%20%2031%20for%20example)). This is aligned with the FHIR PaymentReconciliation resource, which “provides the details including amount of a payment and allocates the payment items being paid” ([PaymentReconciliation - FHIR v6.0.0-ballot2](https://build.fhir.org/paymentreconciliation.html#:~:text=This%20resource%20provides%20the%20details,the%20payment%20items%20being%20paid)). + +In a hospital billing context, payments can come from patients (cash, credit card, checks) or from insurance companies (bulk payments for multiple claims, often via electronic remittances or checks covering several patients). The Payment Reconciliation module must handle both scenarios: +- **Patient Payments:** e.g., a patient pays their bill at the cashier or online, which goes toward their invoice. +- **Insurance Payments:** e.g., an insurer sends a lump sum that covers multiple invoices (claims) for multiple patients, often with an explanation of benefits detailing how to split it. + +Key points: +- A Payment Reconciliation entry will have information about the payment (date, amount, method, identifier like check # or transaction ID). +- It will list one or more **allocations** – basically, references to the invoices (or accounts) that this money was applied to, along with how much of the payment went to each ([PaymentReconciliation - FHIR v6.0.0-ballot2](https://build.fhir.org/paymentreconciliation.html#:~:text=the%20individual%20payment%20amounts%20indicated,or%20%2031%20for%20example)). +- If the payment exactly matches an invoice, there will be one allocation for that invoice covering the full amount. If one payment is split, there are multiple allocations. +- Recording a payment will update the status of invoices (like marking them balanced if fully paid) and adjust account balances accordingly. +- The module should also handle reversals or cancellations of payments (for example, if a check bounces or a credit card charge is disputed, one must remove that payment). + +## Key Fields +**Key Fields:** +- **Payment Reference/Identifier:** An ID for the payment record, often the check number, transaction ID, or an internally generated receipt number. For example, “PMT-1001” or using bank ref like “CHK123456”. This helps trace the payment in case of queries. +- **Payment Date:** The date (and possibly time) when the payment was received. If a patient pays at the cashier, that’s the current date. If processing an insurance check received by mail, it might be the date on the check or the date it was processed. +- **Payment Amount:** The total amount of money received in this payment transaction. E.g., $250.00. +- **Payment Method:** How the payment was made. Common values: *Cash*, *Check*, *Credit Card*, *Bank Transfer*, *Mobile Payment*, etc. This is important for routing (e.g., checks need check numbers, credit cards have auth codes). The UI likely has a dropdown for method. +- **Payer (Source):** Who paid. If it’s a patient payment, the payer might be the patient or a family member (could have a name field). If it’s an insurance payment, the payer is the insurance company (and maybe a specific plan or reference). +- **Payee (Recipient):** Typically the hospital organization or department that received the money. Often implicit (the hospital’s name), but in multi-organization systems might be relevant (like which clinic’s bank account it went into). +- **Allocations (Applied To):** A breakdown of how the payment was applied: + - Each allocation entry might include: + - Reference to an **Invoice** (or possibly directly to an Account or Charge, but invoice is the usual granularity in our case) ([PaymentReconciliation - FHIR v6.0.0-ballot2](https://build.fhir.org/paymentreconciliation.html#:~:text=the%20individual%20payment%20amounts%20indicated,or%20%2031%20for%20example)). + - The amount of the payment applied to that invoice. + - (If integrated with insurance claims: possibly a reference to a Claim or ClaimResponse as well, but let’s assume invoice or account). + - A short note or code about the allocation, e.g., indicating if it was an adjustment or interest, etc. + - For example, a $100 insurance payment might be split: $80 to invoice 1001, $20 to invoice 1002. That means two allocation lines inside this Payment Reconciliation. + - If the payment exactly matches one invoice: one allocation of full amount to that invoice. + - If the payment is not tied to an invoice yet (like someone pre-pays before an invoice is generated), the allocation might just reference the Account (or be left unapplied temporarily, though ideally every payment ties to something). +- **Total Allocated vs Unallocated:** The sum of allocations ideally equals the payment amount. If not, then either there is an *unallocated remainder* (money received but not yet applied to any invoice) or *overallocation* (shouldn’t happen logically). For instance, insurance might send $100 but only 95 is for known invoices, 5 might be an overpayment or to be clarified. The system should track if any part of the payment isn’t allocated. +- **Status:** The status of the payment record. Likely values: **active/posted**, **cancelled**, **draft**, **entered-in-error** (following the FinancialResourceStatusCodes) ([Claim - FHIR Implementation Guide for ABDM v6.5.0 - NRCeS](https://www.nrces.in/preview/ndhm/fhir/r4/StructureDefinition-Claim.html#:~:text=Claim%20,state%20of%20the%20resource%20instance)). + - *Posted/Completed (Active):* Indicates the payment has been fully received and recorded (this is the normal state for a finalized payment). We can equate “active” to a completed payment record. + - *Draft:* If someone started entering a payment but didn’t finish (maybe awaiting confirmation), but in practice payments are usually recorded in one go, so draft might not be heavily used. + - *Cancelled/Reversed:* If the payment was voided (e.g., bounced check, or a credit card refund). Cancelled means the payment should no longer count. This typically would result in the corresponding invoices going back to unpaid. + - *Entered-in-error:* If the payment entry was a mistake (e.g., recorded twice by accident). That would also effectively remove it from balances. +- **Payment Details:** Additional info depending on method: + - If **Check**: check number, bank name. + - If **Credit Card**: maybe last 4 digits of card, transaction auth code. + - If **Transfer**: reference number, account number, etc. + - If **Cash**: maybe cashier name or location. + These might be captured in separate fields or a single notes field. +- **Notes/Comments:** Free text notes about the payment. E.g., “Patient paid $50 now, will pay rest next month” or “Insurance EOB 123456 dated 2025-04-01”. +- **Adjustment Type:** If this record also includes adjustments not actually money received (like a contractual adjustment from insurance), some systems include those as negative payment allocations or separate records. To keep it simpler, Payment Reconciliation entries should represent actual money transactions. Adjustments like write-offs can be recorded as zero-amount PaymentReconciliation with just allocations for adjustments, or as special allocation items. For now, assume payments only, but mention that insurance often comes with adjustments (insurance may pay less than billed, the difference is an adjustment that reduces invoice balance without payment). +- **Related Claim/EOB:** If tying to insurance, possibly reference to a Claim or ExplanationOfBenefit that this payment corresponds to. This helps in audit to know which claim the payment is for. Not needed in patient payments. + +**Business Logic:** +- When a payment is recorded, the amount gets distributed to invoices: + - If the user is recording a payment for a single invoice (like patient pays their bill), the system will auto-allocate full amount to that invoice (and check if it matches the invoice amount, if not, treat as partial payment). + - If the payment is meant for multiple invoices (like an insurance bulk payment or patient paying multiple bills at once), the UI should allow selecting multiple target invoices and specifying amounts for each. The sum of allocations should equal the payment. + - The account’s balance and each invoice’s balance need to update accordingly: subtract the paid amounts. +- If a payment fully covers an invoice, mark the invoice **balanced** (paid in full) ([OPENIMIS.FHIR.R4\Status (Invoice) - FHIR v4.0.1](https://fhir.openimis.org/ValueSet-invoice-status.html#:~:text=status%20hl7,cancelledCancelled%20the%20invoice%20was%20cancelled)). If partially, invoice remains **issued** with remaining balance. +- If a payment exceeds what was due (overpayment), the system might either hold the extra as a credit on the account (unallocated) or ask the user to adjust the allocation (maybe the patient intended to pay only what was due). +- Payment records can also represent **refunds or chargebacks** if negative amounts are allowed or by using cancellation: + - e.g., if a refund is given, one might record a payment with a negative amount or a separate process for refunds (some systems would record a negative payment). + - We'll keep it simpler by saying to cancel or reverse the payment rather than negative entries. +- The Payment Reconciliation acts as a receipt internally. It might also produce a receipt for the patient at point of sale: e.g., printing a “Payment Receipt” acknowledging their payment and listing what it was for. +- For insurance, one Payment Reconciliation might cover many accounts, so it’s not tied to one account like invoices are. This module must be able to cross-reference multiple accounts/invoices in one go. +- The module also likely handles **adjustments** from insurance (like contractual adjustments where the hospital agrees not to charge the difference). These might be recorded as a special kind of allocation (with no actual payment but reduces invoice balance). Some systems treat that as part of the insurance payment posting process. We can consider that an “allocation” that doesn’t correspond to received money but an adjustment amount. +- Ensuring that after posting all payments, any remaining balance on an invoice is correctly represented (which might then be billed to patient or written off). +- Payments should update the **Account** as well: since account balance is charges minus payments, adding a payment will reduce the account’s balance. +- If a Payment Reconciliation is cancelled (like a bounced check), the system should re-open those invoice balances: + - The invoice status goes back from balanced to issued if it was fully paid by that payment. + - If partial, increase the outstanding amount accordingly. + - Possibly log the reason (bounced check fee maybe separate). +- There should be integrity: you shouldn’t be able to apply more money to an invoice than its amount (except if intentionally overpay, which then needs handling like credit). +- Payment Reconciliation records also help in reconciling with bank deposits (each day’s cash, check, credit totals). So you might have reports grouping payments by date/method for bank reconciliation. + +## Step-by-Step User Workflows (Payment Posting) + +**Recording a Patient Payment (Single Invoice, typical scenario):** +1. **Access Payment Screen:** The billing staff (or cashier) goes to record a payment. They might do this either from: + - The **Invoice** view: e.g., viewing an issued invoice and clicking a “Record Payment” button on that screen (which will start a payment entry form linked to that invoice). + - Or from a general **Payments** module: e.g., a “New Payment” function where they then search for the patient or invoice to apply it to. + In either case, assume we have an invoice reference or at least an account/patient context. +2. **Enter Payment Details:** A form appears to input payment data: + - ****Recording a Patient Payment (Single Invoice, typical scenario continued):** +2. **Enter Payment Details:** A form appears to input the payment data: + - **Invoice/Account Selection:** If not already pre-filled, the user selects which **Invoice** or **Account** the payment is for. (If they started from an invoice, this will be locked to that invoice). + - **Amount:** Enter the payment amount (e.g., the patient is paying $200). + - **Method:** Select the payment method (e.g., Cash, Credit Card, Check). Depending on choice, additional fields may appear (for check: check number; for card: transaction ID or last 4 digits). + - **Date:** Defaults to today. They can adjust if recording a payment that was received on a different date. + - **Payer Name:** By default the patient’s name might fill in. The staff can adjust if, say, a family member is paying on the patient’s behalf or if an insurance payment is being entered here (then would be the insurance name). + - **Reference/Notes:** Enter any reference number or note. For example, for a check: input the check # and bank name; for credit card: an authorization code or receipt number. Notes could include “Partial payment, patient will pay rest later” or any relevant remark. + - If the payment is less than the full invoice amount, some systems allow indicating if it’s an installment vs full settlement. Usually, just recording the amount is enough; the remaining balance will be tracked on the invoice. +3. **Apply Payment (Allocation):** Since this scenario is a single invoice, the system will allocate the entire amount to that invoice by default. The user should see something like “Apply $200 to Invoice #1234 (Total due $500).” They could adjust the allocation if they intend to split between multiple invoices (see multi-invoice scenario). Here, assume it’s just this one invoice. + - The form might show the invoice’s outstanding amount as a reference, e.g., “Invoice #1234 – Outstanding $500. Payment $200 will leave $300 remaining.” This helps the cashier confirm the amount. + - If the user accidentally entered more than outstanding (e.g., $600 on a $500 bill), the system should warn or require confirmation that this will result in an overpayment/credit. +4. **Save/Post Payment:** The user submits the payment. The system validates: + - Amount > 0 (for a payment). + - Required fields (method, etc.) are provided. + - Allocations sum to total amount (here trivial single allocation). + - If method is check or card, ensure reference info is entered. + - If all good, the system creates a **Payment Reconciliation** record representing this payment. + - It also updates the relevant invoice’s records: adds this payment allocation under that invoice. +5. **System Response:** After saving: + - The invoice’s status/fields update. If the invoice is now partially paid (not fully covered), it remains **Issued** but might show “Paid $200, Remaining $300”. If the payment covered the invoice fully (say the patient paid $500 on a $500 invoice), the system would mark that invoice as **Balanced (Paid in Full)** automatically ([OPENIMIS.FHIR.R4\Status (Invoice) - FHIR v4.0.1](https://fhir.openimis.org/ValueSet-invoice-status.html#:~:text=status%20hl7,cancelledCancelled%20the%20invoice%20was%20cancelled)). + - The account’s overall balance is reduced by $200 as well (since a payment was applied). + - The Payment record is now stored and can be viewed in the Payments module or under that account’s payment history. + - The UI likely displays a confirmation message “Payment of $200 recorded.” Often, it will also prompt to **print a receipt** for the patient. +6. **Receipt Printing:** The staff can print a **Payment Receipt** which typically includes: Hospital name, receipt number, date, patient name, amount paid, method, reference (check # etc.), invoice number it was applied to, and remaining balance if any. This is given to the patient as proof of payment. +7. **Ending Transaction:** The user’s workflow for that payment is done. If the patient only paid part, they might schedule another payment later. The invoice will remain open with the remaining balance. If paid in full, the invoice is closed out. + +**Recording a Bulk/Insurance Payment (Multiple invoices scenario):** +This is more complex, typically done by billing staff when reconciling an insurance remittance or when a patient pays multiple bills in one go. +1. **Initiate Bulk Payment:** In the Payments module, user chooses **“New Payment – Multiple Invoices”** (could be the same form but allows multiple allocations). If it’s an insurance payment, the user might input the insurance company name as the payer. +2. **Enter Total Amount and Method:** For example, an insurance sends a check of $1000 that covers 3 patients. The staff enters $1000, method “Check”, check #, date, payer “ABC Insurance Co.”. +3. **Select Invoices and Allocate:** The user then adds allocation lines for each portion: + - They might have a list or search to add invoices by number or patient name. For each invoice they add, they enter how much of the $1000 goes to that invoice. + - E.g., Invoice #1001: $400, Invoice #1005: $500, Invoice #1010: $100 (these sum to $1000). + - The system could help by showing each invoice’s outstanding amount and not allowing allocation more than due. If an invoice is due $500 and user tries $600, give error or highlight. + - If the insurance short-paid an invoice (allowed by contract), the allocation could be less than full amount, leaving some balance. Possibly the staff would then immediately record an adjustment for the remainder (maybe as another allocation line of type adjustment or they will handle that by marking that portion as insurance write-off separately). + - The UI ensures the sum of allocations equals the total payment before allowing save. +4. **Save Payment:** Once allocations are entered, the user saves. The system creates one Payment Reconciliation record of $1000, and within it, stores the details of $400 to inv #1001, $500 to #1005, $100 to #1010. +5. **System Updates:** Each invoice referenced is updated: + - Invoice #1001, #1005, #1010 get their paid amounts increased accordingly. If any hit full payment, mark them Balanced. Others remain issued with reduced balances. + - All three patients’ account balances are reduced as well. + - The Payment Reconciliation record can be retrieved later to see which invoices it covered. + - If there was a remainder not allocated (shouldn’t be if done correctly), the system might either keep the remainder as unallocated credit or not allow it in the first place. +6. **Insurance Adjustments:** If the insurance didn’t pay an invoice in full due to contract adjustments, typically the staff would also record those adjustments. This might be done by adding an allocation line of type "adjustment" for the remaining amount on that invoice (which doesn’t tie to a payment but indicates the invoice is settled). Some systems handle this by posting a separate transaction or as part of the claim response processing. For documentation: staff could, for example, mark the remaining $50 on invoice #1001 as an adjustment which zeroes out the invoice. This could be recorded as a zero-dollar Payment Reconciliation entry or a special flag on the invoice. Implementation may vary (but the result is invoice becomes balanced with $400 paid + $50 adjusted off on a $450 bill). +7. **Confirmation:** The system confirms the bulk payment entry. The staff may then move on to next payment. They often reconcile these entries with the insurance explanation of benefits to ensure correctness. + + The flowchart above outlines the payment reconciliation process. It starts when a payment is received, followed by selecting the target invoice(s) or account and entering the payment details. The payment is then allocated to the respective invoice(s). If an invoice is fully covered by the payment, it is marked as paid (balanced); if not, it remains open with an outstanding balance. Finally, a PaymentReconciliation record is saved and the payment is reflected in the system. *Figure: Workflow for recording a payment and reconciling it with invoices.* + +**Handling a Payment Reversal (Bounced check or error):** +1. Locate the Payment record (e.g., search by check number or patient). +2. Use a **“Cancel Payment”** or **“Reverse Payment”** action. The system might ask for a reason (“Check bounced due to insufficient funds”). +3. On confirmation, the Payment Reconciliation status changes to **Cancelled** (or enters an error state). The system effectively **negates the effects** of that payment: + - The associated invoices’ balances are increased back by the amounts that this payment had covered. + - If those invoices were marked paid, they revert to issued (not paid). If partially paid, their outstanding increases. + - The account balance goes up accordingly. + - Optionally log an internal note on the invoice or account about this reversal. +4. The cancelled payment record remains for audit, perhaps with a note, but is not counted in totals. + +**Viewing Payment History:** +- On a patient account or invoice screen, staff can see a list of payments applied. For each payment: date, amount, method, reference. If one payment covered multiple invoices, that payment might show up in each relevant account’s history (with the portion that applied). +- There may also be a standalone Payment Reconciliation list (for all payments) where staff (like finance) can search by date range, method, etc., to do end-of-day reconciliation (e.g., total cash collected today). +- Reports can be generated, like “Daily Cash Collection Report” summing all payments by type, which should match actual cash in hand or bank deposits. + + +## Developer Notes (Payment Processing & Validation) +- **Data Model:** A PaymentReconciliation (PR) can be modeled with a main table (payment header) and a related table for allocations (line items): + - Payment table: id, date, amount, method, payer, status, etc. + - Payment allocation table: id, payment_id, invoice_id (or account_id), amount, type (payment or adjustment), note. + - This is a one-to-many relationship (one payment, many allocations). +- **Status Handling:** Use **FinancialResourceStatusCodes** for the payment record: *active* for completed, *cancelled* for reversed, *draft* if you allow saving incomplete, *entered-in-error* for deletion mistakes ([Claim - FHIR Implementation Guide for ABDM v6.5.0 - NRCeS](https://www.nrces.in/preview/ndhm/fhir/r4/StructureDefinition-Claim.html#:~:text=Claim%20,state%20of%20the%20resource%20instance)). +- **Atomic Allocation:** Ensure that when saving a payment with multiple allocations, the entire operation is atomic. Use transactions – if any part of applying it fails (e.g., invoice not found, or amount mismatch), roll back everything, so you don’t end up with half-applied payments. +- **Validation Rules:** + - The sum of allocation amounts must equal the payment amount (unless you allow partial allocation with remainder, but that complicates things; better to force full allocation). + - None of the allocations should allocate more than the current outstanding on that invoice. If an invoice has $300 due and user tries to allocate $350, block or auto-trim it to $300 and maybe warn about $50 remainder. + - Payment amount should generally not be 0 (except if using it to record pure adjustments, but those could be separate records or flagged). + - If method is check, ensure check number is provided; if credit card, maybe gather a transaction ID. + - The date should not be in the future (and perhaps not too far past if you want to warn, though you might back-date to when check was received). +- **Linking to Invoices/Accounts:** Ideally allocate to invoices. If a payment comes that is not specific to an invoice (say a patient gives an advance deposit), you could allow allocation to the Account without invoice. This would credit the account as a whole (like a prepayment). Later when an invoice is generated, that prepayment could be applied. Implementation: either treat it as an unallocated payment and then implement a way to apply credit to invoice, or encourage they hold money in a pseudo-invoice (some create a credit invoice). Possibly beyond current scope, but keep in mind. +- **Updating Invoice Records:** When a payment is posted: + - Update a field on Invoice for amountPaid or outstanding balance. This avoids calculating every time. Alternatively, one can compute outstanding by invoice.total - sum(payments allocated), but storing it can improve performance for lists. + - If `invoice.amountPaid >= invoice.total`, set `invoice.status = balanced`. Use `>=` to account for any slight overpayment scenario or float rounding. + - If `invoice.status` was balanced and a payment is cancelled, recalc or store the new paid amount and adjust status back if needed. +- **Updating Account Balance:** Account balance is typically computed from charges - payments. If you are not storing account balance, no update needed (just compute on the fly). If you keep a running balance, then on payment posting subtract the payment amount from the account’s balance field. +- **Receipt Generation:** Similar to invoices, provide a standardized receipt template. Could reuse invoice number or generate a separate receipt number sequence for payments. +- **Audit Trail:** Log the user who recorded each payment (and who cancels any payment). Financial transactions must be audit-logged for security. +- **Concurrent Payments:** If two payments are being applied to the same invoice concurrently (rare but possible in online systems), you must avoid race conditions. E.g., both try to pay remaining $100 at same time: + - Solutions: lock the invoice during payment allocation, or after each payment commit, check if invoice balance went negative (which indicates double payment) and handle accordingly (maybe refund one or notify staff). + - Also ensure invoice status check is up-to-date when posting. Possibly requery the invoice's latest outstanding just before saving each allocation. +- **Partial vs Full Payment Flows:** If a payment doesn’t fully pay an invoice, consider if you need to prompt the user for next steps (like scheduling or reminding about remaining). That’s more a business workflow; technically just keep invoice open with remaining amount. +- **Insurance Payment Adjustments:** Decide how to capture adjustments: + - Could allow an allocation line with no invoice but with an account reference and mark it as an adjustment (like -$X) to indicate a write-off. However, a better approach: treat adjustments as separate records (like a special Adjustment resource or use PaymentReconciliation with a different type code). + - FHIR PaymentReconciliation has a concept of detail with a `type` (payment, adjustment, advance, etc.) ([Class PaymentReconciliation - HAPI FHIR](https://hapifhir.io/hapi-fhir/apidocs/hapi-fhir-structures-r5/org/hl7/fhir/r5/model/PaymentReconciliation.html#:~:text=Code%20to%20indicate%20the%20nature,contained%2C)). You could incorporate a `type` field in allocation: e.g., type = payment or adjustment. If adjustment, maybe you allow linking to an invoice and amount that reduces its balance without actual cash. + - For simplicity, if insurer short-pays, you can directly reduce invoice total or mark something on invoice. But it's cleaner to explicitly record adjustments for transparency (so financial reports show that difference). + - Possibly implement: Payment Reconciliation entry with amount 0 and one detail of type adjustment for invoice #X of $50. But probably easier: after posting insurance payment, user records adjustments by another interface. We won't fully detail that here. +- **Unallocated Payments:** If the system allows accepting money without applying it (like patient deposits), have a way to hold that. Maybe create a PaymentReconciliation with no invoice allocation yet (store it with a flag or temp account). Later, when an invoice is available, allow applying that credit. This is advanced; many HMIS simply apply to an invoice or create an invoice for deposit. +- **Balance Forward / Credits:** If a patient overpays and has a credit, you might either keep the credit on account or refund it. If keeping on account, you could leave a PaymentReconciliation with an unallocated portion or apply it to a special "credit invoice". Alternatively, track a negative balance on account. This area can be complex; a straightforward approach is to avoid overpayments (or treat them as prepayments for next bill). +- **Search and Reports:** Provide ability to search payments by: + - Date range (for daily closeouts). + - Method (for reconciling with bank statements, e.g., sum of all check payments vs sum of bank deposits). + - Payer (find all payments by a certain insurance or patient). + - Invoice or account (show all payments that hit a specific bill). +- **Security:** Payments involve money, so ensure only authorized roles can record or cancel payments. Possibly require dual approval for cancellations above a threshold. +- **Notifications:** Optionally, trigger notifications. E.g., when a big payment is recorded or when an invoice gets fully paid, perhaps notify relevant staff or thank patient via email, etc. +- **Integration with Accounting:** Payment records might be exported to a general ledger. For example, daily totals for cash, etc., might flow to finance. If required, categorize transactions by type for GL mapping. +- **Integration with External Systems:** If using an online payment portal, those could feed into Payment Reconciliation entries automatically. The design should accommodate creation of payments via API or automated process in addition to manual UI entry. +- **FHIR Consideration:** A PaymentReconciliation in FHIR often corresponds to an insurer’s bulk payment with allocations to claims ([PaymentReconciliation - FHIR v6.0.0-ballot2](https://build.fhir.org/paymentreconciliation.html#:~:text=The%20PaymentReconciliation%20resource%20provides%20the,or%20%2031%20for%20example)). Our usage extends it to patient payments as well. If mapping to FHIR: + - Use `PaymentReconciliation.detail` for allocations with reference to `Invoice` (FHIR allows Invoice reference here since R5). + - Status mapping: posted vs cancelled as discussed. + - The payer could map to PaymentReconciliation.organization or request/response references, though FHIR might not have a direct field for payer name (in FHIR they often assume PaymentReconciliation from insurer implies the insurer is payer). + - Might also consider using `PaymentNotice` resource in cases where needed, but for internal HMIS, PaymentReconciliation is enough. +- **Testing:** + - Test single invoice payment, check invoice status and balance. + - Test underpayment, ensure remainder is correct. + - Test overpayment scenario, see how system behaves (should ideally flag). + - Test multi-invoice allocation: totals match, each invoice updated. + - Test cancellation: invoice balances restored. + - Test concurrency: two payments at once on same invoice (simulate if possible). + - Edge: Payment amount = 0 or negative (shouldn’t be allowed except perhaps negative for refunds, which we handle via cancellation instead). +- **User Feedback:** If a user tries to record a payment and the invoice is already balanced, block it (“Invoice already paid”) to prevent confusion. +- **Linking to Patient Account:** After a payment, you might update some summary on patient account like “Last Payment: $X on [date]”. Not essential but user-friendly. +- **Partial Refunds:** If a patient requests a refund for an overpayment, one way is to record a negative payment (which many systems avoid) or simply cancel part of the payment. Possibly simpler: have a “Refund” function that creates a new PaymentReconciliation with negative amount. But implementing negative amounts can complicate sum calculations. Alternatively, treat refunds as separate processes outside PaymentReconciliation. This depends on requirements; mention for completeness. + +By implementing the above, the Payment Reconciliation module will robustly handle the flow of funds in the HMIS, ensuring invoices are properly marked as paid or unpaid, and giving both staff and developers a clear view of the financial state of each account. + From 4c367ee3e4cc39ab61bf0b8e023ae4268376c1eb Mon Sep 17 00:00:00 2001 From: Bodhish Thomas Date: Wed, 30 Apr 2025 19:09:03 +0530 Subject: [PATCH 02/13] Update account --- docs/care/HMIS/Billing/Account.md | 229 +++++++++++++++++++----------- 1 file changed, 150 insertions(+), 79 deletions(-) diff --git a/docs/care/HMIS/Billing/Account.md b/docs/care/HMIS/Billing/Account.md index 817f592..e00c6b5 100644 --- a/docs/care/HMIS/Billing/Account.md +++ b/docs/care/HMIS/Billing/Account.md @@ -1,68 +1,151 @@ # Account ## Summary -The **Account** module manages financial accounts that accumulate charges and payments for a patient or specific purpose (e.g. an inpatient stay or department cost center). An Account serves as a “billing bucket” or ledger for tracking healthcare costs over time ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=A%20financial%20tool%20for%20tracking,a%20patient%2C%20cost%20centers%2C%20etc)). Charges (for services or items) are applied to an Account, and payments or adjustments credit the Account. In essence, it is a central record against which charges, payments, and adjustments are recorded ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=The%20Account%20resource%20acts%20as,for%20payment%20of%20the%20account)). This allows the system to keep a running total of what a patient (or their insurance) owes. Accounts contain information about who the account is for (the patient or entity) and who is responsible for paying the balance (such as insurance or a guarantor). *For example, when a patient is admitted, an Account is opened to track all charges during that hospitalization, and later, an invoice will be generated from this account.* - -**Note (Developers):** The Account concept aligns with the FHIR **Account** resource, providing a tool to track values accrued for a particular purpose in healthcare billing ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=A%20financial%20tool%20for%20tracking,a%20patient%2C%20cost%20centers%2C%20etc)). While an account will have a running balance conceptually, it typically does **not** store a live balance field. Instead, the current balance is computed from all associated charges and payments ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=While%20the%20Account%20does%20conceptually,in%20consideration%20as%20future%20work)). The system may provide a function to calculate the balance on demand by summing charges minus payments. - -## Key Fields, Statuses, and Business Logic -**Key Fields:** -- **Account Identifier:** Unique number or code for the account (often auto-generated) used to reference the account in the system. This might be visible on invoices or receipts for reference. -- **Name/Description:** A human-friendly name (optional) for the account, e.g. “John Doe – 2025 Inpatient Stay”, to help staff identify it. -- **Subject (Patient):** The patient (or entity) for whom the account is managed. Only charges for this patient should be applied. The account might also be tied to a specific **Encounter** or admission in the hospital (e.g. an account per hospitalization). -- **Account Type:** Categorizes the account, such as *inpatient*, *outpatient*, *pharmacy*, or other billing categories. This helps route the account to proper workflows. *(Developers: this corresponds to FHIR Account.type, and can be used for reporting or business rules.)* -- **Status:** The lifecycle state of the account. Common statuses include **active**, **on-hold**, **inactive** (closed), **entered-in-error**, or **unknown** ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=%3Cstatus%20value%3D%22%5Bcode%5D%22%2F%3E%3C%21,billingStatus)). - - *Active:* The account is currently open and usable – new charges can be posted and invoices can be generated. Most patient accounts will be **active** during a patient’s care period. - - *On-hold:* The account is temporarily suspended (e.g. due to billing disputes or pending insurance information). Charges should not be added or invoices issued while on-hold. *(UI behavior: if staff attempt to add a charge or invoice on a held account, the system should block it and show a message.)* - - *Inactive (Closed):* The account is closed, typically after the care episode is finished and all charges have been billed and paid. No new transactions should occur. *(UI: the account may become read-only; any attempt to post charges should be prevented.)* - - *Entered-in-error:* The account was created by mistake and should not be used (e.g. duplicate account). Such accounts are ignored in billing. - - *Unknown:* The status is not known (this is rarely used; generally, an account will be deliberately set to one of the above states). - **Business logic:** New charges can only be applied to accounts in **active** status. If an account is **inactive** or on **on-hold**, the system must validate and disallow posting charges or creating invoices until the status is active. When closing an account (setting to inactive), ensure all pending charges are billed and no outstanding balance remains to avoid orphan transactions. -- **Coverage:** Insurance or coverage details associated with the account. This is the list of one or more insurance policies or payers that might pay for charges on this account (often with a priority order) ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=,when%20processing%20billing%20coverage)). For example, a patient’s primary insurance coverage would be listed first, and perhaps secondary insurance next. This field helps determine how invoices/claims might be sent to insurers. - *(UI: When creating an account, staff can attach the patient’s insurance coverage. The interface might allow selecting from the patient’s known insurance policies, and marking the primary vs secondary coverage.)* -- **Guarantor:** The person or organization responsible for any remaining balance on the account (after insurance). Often this is the patient themselves or a guardian/related person ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=Reference%20,Organization%20%C2%BBA%20guarantor%20may%20be)). If insurance doesn’t fully cover the charges, the guarantor will be billed for the remainder. -- **Owner (Managing Organization):** The department or organization that manages the account. For example, the hospital or a specific clinic department might “own” the account for internal tracking. *(This is mostly for internal bookkeeping; not always exposed to end-users.)* -- **Billing Period:** The date range that the account covers (e.g. admission and discharge dates, or a specific billing cycle). Charges with service dates outside this period might not be allowed. The system can use this to ensure charges fall within an episode of care. -- **Account Balance:** *This is not a stored field, but a computed value.* The current balance is calculated as **total charges** minus **payments/adjustments**. Staff will see the balance on the account UI, but under the hood it’s derived from the linked transactions. The account **balance** updates in real-time as new charges or payments are recorded (e.g., adding a charge increases the balance; recording a payment decreases it). ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=While%20the%20Account%20does%20conceptually,in%20consideration%20as%20future%20work)) - -**Business Logic Highlights:** -- An account can accumulate many **Charge Items** (individual billed services) over time. Each Charge Item references the Account it belongs to. The Account itself does not list every charge internally; instead, charges “point” to the account ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=The%20Account%20itself%20does%20not,have%20not%20yet%20been%20developed)). The system can retrieve all charges linked to a given account to compute the balance or prepare an invoice. -- **Adding Charges:** Only allowed on active accounts. If a user tries to add a charge to an inactive/on-hold account, the system should prevent it and alert the user (e.g., “Cannot add charges to a closed account”). This ensures data integrity. -- **Account Closure:** Typically done when the patient’s episode of care is complete and billing is finalized. The staff will mark the account as **inactive** (closed) after all invoices are issued and the balance is zero. The system might enforce that an account with outstanding balance cannot be closed. *(Developer note: implement a check that blocks closing an account if any unpaid invoices or unbilled charges exist.)* If closure is forced (exception cases), it should perhaps trigger warnings or require managerial approval. -- **On-hold Behavior:** Placing an account on hold might be used if, for example, insurance eligibility is in question or a billing dispute arises. In this state, new charges can be collected in the background (if necessary) but not officially billed until hold is released. The UI should visibly flag held accounts, and possibly require a note or reason for hold. -- **Responsible Parties:** The account’s **coverage** and **guarantor** information drive who gets billed in the **Invoice** process. For instance, an invoice might be split by coverage – first sent as a claim to insurance, then a remaining patient-responsible invoice to the guarantor. (This system is inspired by FHIR but may be simplified in implementation.) -- **Retrieving Balance:** Because the balance isn’t a stored field, whenever staff view the account, the system will calculate the balance by summing all *Charge Items* minus *Payments* related to that account. This ensures accuracy but requires that all related data be queried. *(Developer note: Consider providing an optimized way to compute balance, such as a database view or cached value updated on each transaction, if performance is a concern.)* - -## Step-by-Step User Workflows and UI Interaction - -**Creating a New Account:** -1. **Navigation:** A billing staff or registrar navigates to the **Accounts** section of the HMIS. This might be accessible via a “Billing” menu or during patient admission in the system. -2. **Initiate Account Creation:** The user clicks on **“New Account”** (or an equivalent action). If the account is being created as part of patient registration or admission, some fields may be auto-filled (e.g., patient name, admission date). -3. **Enter Account Details:** A form is presented for the account details: - - Select or confirm the **Patient** for whom the account is being created (often this is pre-selected if coming from a patient context). - - Optionally enter an **Account Name/Description** (e.g., “2025-03 Ortho Surgery”). - - Choose an **Account Type** (from a dropdown, e.g., *Inpatient* vs *Outpatient*, if applicable). - - Initially, the **Status** will default to **active** (since we are opening a new active account). - - Add **Coverage details:** The user can attach insurance coverage. For example, they might pick the patient’s insurance policy from a list of the patient’s insurances on file. If multiple insurances apply, they can add more than one, possibly specifying the order (primary, secondary). - - The **Guarantor** will default to the patient (or guardian for a minor). The user can change it if, say, a company or another family member is responsible for the bill. - - Ensure the **start date** (or admission date) is correct; enter an end date if known (for example, if creating an account for a scheduled procedure on a single day, the end date might be that day). -4. **Save Account:** The user submits the form (by clicking **“Save”** or **“Create”**). The system validates the input (e.g., patient must be selected, type may be required, etc.). If everything is valid, a new Account record is created. The account is now **active** and ready to accept charges. - - *System response:* The UI might display a confirmation like “Account #12345 created successfully.” The account’s unique ID/number is generated (if not manually entered) and shown. The account detail page opens, showing the information entered and a current balance of $0.00. -5. **Post-Creation Actions:** From the new account’s page, staff can now perform actions like **“Add Charge”** (to add billable items) or **“Generate Invoice”** when ready. Initially, the account has no charges, so the balance is zero. The coverage and guarantor info is visible so staff know who will be billed. - -**Viewing and Updating an Account:** -- Staff can search or browse for an existing account (for example, by patient name or account number). Selecting the account will typically bring up an **Account Details** screen. This screen shows: - - Account info (patient, status, type, etc.) at the top. - - Coverage/Insurance details and guarantor. - - A list of all **Charge Items** posted to this account (often in a table format, with columns for date, description, amount, status). - - A list of **Invoices** associated with the account (with invoice dates, amounts, status). - - A list of **Payments** applied (with payment dates, amounts, and references). - - The **Current Balance** calculated. -- Staff can update certain fields by clicking an **“Edit”** button (if the account is active): - - For example, if the patient got a new insurance card mid-way, they could add a new Coverage or update the guarantor. Or they might correct the account name or type. - - Some fields are not editable after creation: typically the patient and possibly the start date (since those are fundamental). If a mistake was made (wrong patient), often the recommended approach is to mark the account entered-in-error and create a new one. - - Changing **Status:** Staff might set the account on **hold** if needed (the UI might require entering a reason note when doing so). They might also mark it **inactive** (close it) if the episode of care is over and billing is completed. -- When the user saves changes, the system validates them. For instance, if setting status to **inactive**, it might check if the balance is zero. If not, a warning “Cannot close account with outstanding balance” would appear and the action is blocked. +The **Account** module manages financial accounts that accumulate charges and payments for a patient or specific purpose (e.g. an inpatient stay or service request cost). An Account serves as a “billing bucket” or ledger for tracking healthcare costs over time. Charges (for services or items) are applied to an Account, and payments or adjustments credit the Account. In essence, it is a central record against which charges, payments, and adjustments are recorded. This allows the system to keep a running total of what a patient (or their insurance) owes. Accounts contain information about who the account is for (the patient or entity) and who is responsible for paying the balance (such as insurance or a guarantor). *For example, when a patient is admitted, an Account is opened to track all charges during that hospitalization, and later, an invoice will be generated from this account.* + +:::info Note for Developers +The Account concept aligns with the FHIR **Account** resource, providing a tool to track values accrued for a particular purpose in healthcare billing. While an account will have a running balance conceptually, it typically does **not** store a live balance field. Instead, the current balance is computed from all associated charges and payments and cached. The system will provide a function to calculate the balance on demand by summing charges minus payments, you can use the `calculated_at` field to track when the balance was last computed and ensure data consistency. +::: + +## Schema Definition + +```json +{ + "id": "", // Internal Identifier + "status": "", // active | inactive | entered-in-error | on-hold | unknown + "billing_status": "", // Bound to https://build.fhir.org/valueset-account-billing-status.html + "name": "", // Human-readable label + "patient": "", // The entity that caused the expenses + "facility" : "", // Facility where this Account is created + "service_period": "Period", // Transaction window + "description": "", // Explanation of purpose/use + "balance": [ + { + "aggregate": "", // Patient or Insurer - Bound to https://build.fhir.org/valueset-account-aggregate.html + "amount": { + "value": "", // Numerical value (with implicit precision) + "currency": "" // ISO 4217 Currency Code + } // Calculated amount + } + ], + "calculated_at": "" // Time the balance amount was calculated +} +``` + +## Core Data Structure + +### Essential Fields + +| Field | Description | Technical Notes | +|-------|-------------|----------------| +| **id** | Internal system identifier for the Account | Primary key, auto-generated | +| **name** | Human-readable label (e.g., "John Doe – 2025 Inpatient Stay") | Helpful for staff identification | +| **patient** | Foreign key reference to the patient | Only charges for this patient should be applied to this Account | +| **facility** | Reference to the healthcare facility | Used for organizational tracking and reporting | +| **status** | Current lifecycle state of the Account | Controls available operations (see Status section) | +| **billing_status** | FHIR-compliant billing status code | Provides additional context beyond basic status | +| **service_period** | Date range covered by the Account | Typically maps to admission/discharge dates or specific billing cycle | +| **description** | Markdown-formatted explanation of purpose | Provides additional context for staff | +| **balance** | Array of calculated balances by payer type | Segmented by responsible party (patient vs. insurer) | +| **calculated_at** | Timestamp of last balance calculation | Ensures data freshness awareness | + +### Account Status Lifecycle + +| Status Value | Description | System Behavior | +|--------|-------------|----------------| +| **active** | Account is open and operational | Allows new charges, payments, and invoice generation | +| **on_hold** | Account is temporarily suspended | Blocks new charges and invoices; requires resolution | +| **inactive** | Account is permanently closed | Prevents all new transactions; read-only mode | +| **entered_in_error** | Account was created by mistake | Excluded from billing processes and reporting | + + +### Billing Status Values + +| Billing Status | Description | Typical Usage | +|----------------|-------------|--------------| +| **open** | Account is actively receiving charges | Default for new accounts | +| **carecomplete_notbilled** | Care is complete but billing process hasn't started | Transitional state after discharge | +| **billing** | Invoicing and payment collection in progress | Active billing cycle | +| **closed_baddebt** | Account closed due to uncollectible debt | After collection attempts failed | +| **closed_voided** | Account canceled/voided | For erroneously created accounts | +| **closed_completed** | Account fully settled and closed | After full payment received | +| **closed_combined** | Account merged with another account | After account consolidation | + +### Balance Aggregate Types + +| Aggregate Type | Description | Purpose | +|----------------|-------------|---------| +| **patient** | Portion of balance patient is responsible for | Track patient's direct financial responsibility | +| **insurance** | Portion of balance expected from insurance | Track expected insurance payments | +| **total** | Combined total balance | Overall account balance | + + +## Business Logic Highlights +- An account can accumulate many **Charge Items** (individual billed services) over time. Each Charge Item references the Account it belongs to. The Account itself does not list every charge internally; instead, charges “point” to the account. The system can retrieve all charges linked to a given account to compute the balance or prepare an invoice. +- **Adding Charges:** Only allowed on active accounts. If a user tries to add a charge to an inactive/on-hold account, the system should prevent it and alert the user. +- **Account Closure:** Typically done when the patient’s episode of care is complete and billing is finalized. The staff will mark the account as **inactive** (closed) after all invoices are issued and the balance is zero. The system might enforce that an account with outstanding balance cannot be closed. If closure is forced, it can only be done at managerial level. *(Developer note: implement a check that blocks closing an account if any unpaid invoices or unbilled charges exist.)* +- **On-hold Behavior:** Placing an account on hold might be used if, for example, insurance eligibility is in question or a billing dispute arises. In this state, new charges can be collected in the background but not officially billed until hold is released. The UI should visibly flag held accounts, and possibly require a note or reason for hold. + +```mermaid +flowchart TD + A[Account Creation] --> B{Set Initial Status} + B -->|Default| C[Active] + + C --> D{Account Management Options} + D -->|Add Charge| E[Validate Charge] + D -->|Record Payment| F[Process Payment] + D -->|Generate Invoice| G[Create Invoice] + D -->|Change Status| H{New Status} + + E --> E1{Is Account Active?} + E1 -->|Yes| E2[Create Charge Record] + E1 -->|No| E3[Error: Cannot add charge] + E2 --> E4[Update Account Balance] + + F --> F1[Create Payment Record] + F1 --> F2[Update Account Balance] + + G --> G1{Is Account Active?} + G1 -->|Yes| G2[Generate Invoice from Charges] + G1 -->|No| G3[Error: Cannot invoice] + + H -->|On-Hold| I[Verify Permission] + H -->|Inactive| J[Validate for Closure] + H -->|Entered-in-Error| K[Verify Admin Permission] + + I --> I1[Require Reason Note] + I1 --> I2[Update Status to On-Hold] + I2 --> I3[Disable Billing Actions] + + J --> J1{Is Balance Zero?} + J1 -->|Yes| J2[Update Status to Inactive] + J1 -->|No| J3{Manager Override?} + J3 -->|Yes| J4[Update with Override Note] + J3 -->|No| J5[Error: Cannot close with balance] + + K --> K1[Mark as Error] + K1 --> K2[Remove from Billing] + + J2 --> L[Account Closed] + J4 --> L + + classDef status fill:#f9f,stroke:#333,stroke-width:2px + classDef error fill:#f66,stroke:#333,stroke-width:2px + classDef success fill:#6f6,stroke:#333,stroke-width:2px + + class C,I2,J2,J4,K1 status + class E3,G3,J5 error + class E4,F2,G2,L success +``` + +**Creating a New Account** + +Accounts can be created in two ways: +1. Manual Creation from Patient Page +2. Automatic Creation on First Charge + +In both cases, the account becomes immediately available for billing operations once created. + **Handling Account Holds:** - If an account is on hold, the UI should prominently indicate this (e.g., a banner “On Hold”). While on hold, typical billing actions might be disabled or require override: @@ -72,26 +155,14 @@ The **Account** module manages financial accounts that accumulate charges and pa **Closing an Account (End of Cycle):** - When all charges have been billed and paid, or the patient’s treatment cycle is over, the account should be closed. To do this, staff edits the account and sets **Status = Inactive**. -- The system will likely prompt “Are you sure you want to close this account? This action will mark the account as closed and no further charges can be added.” If confirmed, and validation passes (balance is zero, etc.), the status updates to inactive. -- Once inactive, the account is essentially archived for that episode. The UI might label it as **Closed**. Staff can still view details and history, but cannot add new entries. If somehow a late charge comes in after closure, typically a new account or special process is needed (or re-open the account, if the system allows toggling back to active with authorization). +- The system will prompt “Are you sure you want to close this account? This action will mark the account as closed and no further charges can be added.” If confirmed, and validation passes (balance is zero, etc.), the status updates to inactive. +- Once inactive, the account is essentially archived for that episode. The UI might label it as **Closed**. Staff can still view details and history, but cannot add new entries. If somehow a late charge comes in after closure, typically a new account is needed. **Account Balance Inquiry:** -- At any point, staff might need to inform a patient of their current balance. The account screen’s balance is calculated from charges and payments in real-time. If the patient or billing staff want a detailed statement, they can generate an **Account Statement** (which is essentially an on-demand invoice or report of all transactions). This is usually separate from the official Invoice process, but it gives a breakdown of charges, payments, and remaining due. -- *UI Example:* A “Print Statement” button could produce a PDF listing all charges on the account, any payments received, and the net balance, useful for interim updates to patients before final billing. +- At any point, staff might need to inform a patient of their current balance. The account screen’s balance is calculated from charges and payments. If the patient or billing staff want a detailed statement, they can generate an **Account Statement** (which is essentially an on-demand invoice or report of all transactions). This is usually separate from the official Invoice process, but it gives a breakdown of charges, payments, and remaining due. -## Developer Notes (Account Backend & Validation) -- **Data Model:** Each Account record should include references to the patient, coverage, guarantor, etc. Use relational links (e.g., patient ID foreign key) to quickly fetch related data. If modeling after FHIR, the Account is a standalone resource identified by an ID, with references to Patient, Coverage, etc. -- **Balance Calculation:** As noted, the account’s balance is computed, not stored. Implement a reliable method to sum all *ChargeItem* amounts linked to the account minus all *Payment* (PaymentReconciliation) amounts linked to the account. This might involve summing potentially many records, so consider indexing and efficient queries. Alternatively, maintain a running balance that updates on each transaction (though this must be carefully synchronized to avoid errors). -- **Status Transitions:** Enforce rules when updating account status: +**Status Transitions:** +- Enforce rules when updating account status: - Only allow **inactive** if balance is 0 and no pending charges. If there is a balance, return a clear error to the UI. - Only allow **on-hold** or **active** transitions for appropriate user roles. Possibly log these changes for audit. - **entered-in-error** should only be used shortly after creation or if truly needed, and might require admin privileges, since it essentially invalidates the account. -- **Unique Constraints:** Ensure account identifiers are unique (to avoid confusion in billing). If using human-readable numbers, implement a sequence or check to not duplicate an old account number. -- **Link to Encounter:** If the system ties accounts to encounters (common in hospital systems), ensure that one encounter is associated with only one primary billing account. Conversely, an account might cover multiple encounters in some models (like a global account for outpatient visits). Clarify this in design and enforce accordingly. -- **Coverage Priority:** If multiple coverages are attached, store the priority order. During invoice generation (especially if integrating with insurance claim logic), the order will determine who is billed first. The data model should capture priority (e.g., an integer rank or boolean for primary). -- **Auto-Creation Hooks:** In many systems, an account is automatically created when a patient is admitted or registered for a visit (to ensure every encounter has an account). As a developer, consider triggers: e.g., on creating an Encounter record, auto-generate an Account if none exists, and link them. This reduces manual workload on staff. -- **Deletion vs Error:** Generally, avoid deleting account records outright (especially if transactions exist). Instead, use the entered-in-error status or another flag to exclude erroneous accounts. This preserves an audit trail. If absolutely needed, only allow deletion on accounts with no charges or payments and done by admin. -- **Audit Logs:** Keep logs of changes to critical fields (status changes, coverage changes) for compliance. For example, if an account is put on hold, record who did it and why (perhaps as an internal note). -- **Integration Consideration:** If the HMIS integrates with a general ledger or financial system, the Account might map to a ledger account or sub-ledger. Developers might need to propagate account creation/closure events to that system. -- **Performance:** Accounts with a very large number of charges (e.g., a long hospitalization) might cause slow queries for balance or invoice generation. Mitigate by optimizing queries or splitting accounts by time periods if necessary (for instance, monthly billing accounts). -- **FHIR Alignment:** (Optional) If exposing an API or storing internally following FHIR, note that the Account resource doesn’t carry a balance field ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=While%20the%20Account%20does%20conceptually,in%20consideration%20as%20future%20work)). Use FHIR operations (like `$balance` if defined) or custom operations to retrieve balances. Keep the FHIR resource updated with pointers to ChargeItem, Invoice, and PaymentReconciliation resources as appropriate to maintain referential integrity within the API. From 8ae9c764ccd9260066f71c8dae720c61ded37796 Mon Sep 17 00:00:00 2001 From: Bodhish Thomas Date: Wed, 30 Apr 2025 19:33:31 +0530 Subject: [PATCH 03/13] Update CID --- .../care/HMIS/Billing/ChargeItemDefinition.md | 206 +++++++++--------- 1 file changed, 101 insertions(+), 105 deletions(-) diff --git a/docs/care/HMIS/Billing/ChargeItemDefinition.md b/docs/care/HMIS/Billing/ChargeItemDefinition.md index e57ea7c..ea49859 100644 --- a/docs/care/HMIS/Billing/ChargeItemDefinition.md +++ b/docs/care/HMIS/Billing/ChargeItemDefinition.md @@ -1,77 +1,105 @@ + # Charge Item Definition -## Summary -The **Charge Item Definition** module is essentially the **catalog or tariff** of billable services and goods in the hospital system. Each Charge Item Definition represents a template for a billable item – including its code, description, pricing, and any rules about when or how it is billed ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=The%20ChargeItemDefinition%20resource%20provides%20the,type%20of%20billing%20code%20system)). In other words, if a Charge Item is an instance of something being billed to a patient, the Charge Item Definition is the definition of that billable thing in general (the price list entry). This is inspired by the FHIR ChargeItemDefinition resource, which “provides the properties that apply to the (billing) codes necessary to calculate costs and prices” ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=The%20ChargeItemDefinition%20resource%20provides%20the,type%20of%20billing%20code%20system)). - -The Charge Item Definition holds all relevant billing information for a given service or product. For example, there might be a definition for “General Physician Consultation” with code CONS100, base price $50, and rule that it’s only billable for outpatient visits. Another definition might be “MRI Scan – Brain” with code MRI001, price $500, and perhaps an additional surcharge rule for use of contrast material. The module ensures that all charges use consistent codes and pricing, and allows updates to pricing and rules in a centralized way. - -## Key Fields and Configuration -**Key Fields:** -- **Code (Billing Code):** A unique identifier for the chargeable item. This could be an alphanumeric code (like “MRI001” or “LAB123”). Staff will use this code to add charges. Codes may correspond to standard billing codes or internal codes. Each code in the system maps to one definition. *(In FHIR, this would be ChargeItemDefinition.code or part of a coded element.)* -- **Display Name/Description:** A clear name or description of the service/product. E.g., “MRI Scan - Brain with Contrast” or “Complete Blood Count (CBC)”. This is what shows up in drop-down lists and on bills. It should be understandable to both staff and patients. -- **Category:** (Optional) A grouping for reporting or UI organization (e.g., “Laboratory Tests”, “Radiology”, “Consultations”). This helps filter and find definitions when adding charges, and to group them on invoices. -- **Price/Rate:** The base price for the item. This could be a fixed amount (e.g., $500 per MRI) or a rate (e.g., $100 per hour for physiotherapy). If the item is time-based or quantity-based, the definition explains the unit. For example, a medication might be priced “per tablet” or a service “per session.” The price is typically stored as an amount with currency. -- **Unit of Measure:** If needed, the unit that the price applies to (each, per day, per kg, etc.). This field clarifies how to interpret quantity. E.g., “each” for most discrete items, or “hour” for hourly services. In many cases, this is implicit or included in description instead (like “Physio (per hour)”). -- **Applicable Period:** The date range during which this price is effective. There might be versioning of prices. For instance, if prices are updated annually, a definition can have an effective start date (and possibly end date). The system should pick the correct price based on the service date of the charge. If a charge date is outside the effective period of a definition, the system might warn or use the appropriate version of the definition (if multiple versions exist). -- **Applicability Conditions/Usage Rules:** Rules that define when this charge item definition can or should be applied ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=Many%20billing%20systems%20have%20rules,Rules%20for%20applicability%20may%20include)) ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=A%20billing%20engine%20will%20apply,Operation)). These can be quite complex or simple, for example: - - The service is only billable in certain contexts (e.g., *outpatient only*, not for inpatient). - - It may only be charged for patients within certain age ranges (e.g., pediatric vs adult pricing). - - It can only be charged once per encounter or day (to prevent duplicates). - - It must be used in combination with another code (or cannot be used together with another code). - - Certain preconditions like time of day (e.g., an after-hours code that only applies outside 8am-5pm). - - Limit frequency: e.g., “only one physical therapy session per day is billable”. - These conditions might be described in text for human understanding and also encoded in a structured way for the system to enforce. In FHIR, these could be in properties and expressions within ChargeItemDefinition, and are applied via a billing engine ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=A%20billing%20engine%20will%20apply,Operation)). -- **Price Components (Surcharges/Discounts):** Some definitions might include additional price components besides the base price ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=,from%20the%20same%20billing%20system)). For example, “MRI with Contrast” might have a base price plus an additional contrast material charge. The definition can list these components so the system knows to add them. Another example: “After-hours service surcharge 20%” could be a separate definition that is referenced by rule. In FHIR, price components are part of Invoice for transparency ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=balanced%20with%20this%20Invoice%20account,to%20the%20recipient%20of%20the)), but the logic originates from definitions (e.g., a flag that says “apply 1.2x price if after hours”). -- **Multiple Currency or Payer-specific Rates:** (If applicable) Some systems allow different prices for different payer types (e.g., insurance vs self-pay) or tiers. This could be handled by multiple definitions or extensions (like a specific contract price list for an insurer). Our documentation will assume a single standard price, but be aware this complexity exists. -- **Active/Inactive Flag:** Just like accounts, definitions can be active or inactive. An inactive definition means that code should no longer be used for new charges (perhaps it was replaced or the service is discontinued). The UI might hide inactive items from selection lists. If an inactive code is on an old invoice, it remains for historical data but no new charge should reference it. -- **Version or Identifier:** Optionally, a version number or reference ID if the catalog is maintained externally or for regulatory coding systems (like CPT codes version). This helps track if definitions were updated. -- **Associated Entities:** If relevant, link to the actual department or service entity. E.g., a definition for a lab test might reference the lab department, which could be used for routing approvals or notifications. -- **Narrative or Guidance:** Free-text notes explaining the usage of this code. For example, “Use this code for all standard chest X-rays. Do not use for portable X-ray, see code XRAY002 for portable.” These notes help human users choose correctly. - -**Business Logic in Definitions:** -- **Single Source of Truth:** All chargeable items must have a definition entry. When adding a Charge Item, users pick from these definitions, ensuring consistency in naming and pricing. If a user attempts to enter a code that doesn’t exist in the definitions, the system should not allow it (or at least strongly discourage it). This prevents billing for undefined items. -- **Automated Price Calculation:** When a Charge Item is created, the system looks up the corresponding Charge Item Definition to retrieve the price and any conditional rules ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=Since%20the%20individual%20ChargeItem%20resources,the%20context%20of%20the%20ChargeItem)). If the conditions in the definition apply, they are executed. For example, the definition might say “if quantity > 5, give 10% discount” (for bulk supplies). The system would then adjust pricing accordingly. Another example: “Service outside business hours – use surcharge code SURCH10.” The system might automatically add that surcharge as a separate charge or adjust the price as per definition. -- **Consistency and Updates:** If the hospital updates prices (say at the start of a new year, or due to inflation/cost changes), they will update the Charge Item Definitions. New charges will use the new prices. Historical charges remain with the old prices they were charged at (since those were recorded at the time of service with the then-effective price). This means the definition has to possibly store old prices or the system should keep track of from when a new price is effective. -- **Validation of Combinations:** The definitions drive the validation when adding charges: - - They can specify incompatibilities or requirements. E.g., a definition could indicate “not billable with code X on the same day” – if the user tries to add both, the system can catch it. - - They may specify prerequisites (like one code auto-adds another). The system could then auto-add the required code or prompt the user. -- **Optional Auto-Addition:** Some definitions might be configured to automatically add related charges. For example, if a certain procedure always includes a separate consumable fee, the system could prompt “Also add [consumable]?” or just add it when the main code is added. This behavior would be defined in the Charge Item Definition (like a linked supplementary charge). -- **Modifiability:** Usually, only authorized users (like billing administrators) can create or modify Charge Item Definitions, since it affects billing for all patients. Regular billing staff will have read-only access to this catalog when posting charges. -- **Impacts on UI:** The definitions might be used to populate drop-down lists. They might also determine how fields are presented. For example, if a service’s price is per hour, the UI could show a field to enter hours. If per item, it shows quantity. If a code has multiple price components (base + X), the UI might show a breakdown after selection. The goal is to give the user immediate feedback on what will be charged. - -## Step-by-Step Workflows (Maintaining the Catalog) - -**Adding a New Charge Item Definition (for Admin/Billing Manager):** -1. **Navigate to Charge Definitions:** A user with proper permission (e.g., Billing Manager) goes to the **Charge Item Definitions** or “Service Catalog” section of the HMIS. This could be under an admin or billing configuration menu. -2. **Initiate New Definition:** Click **“New Charge Item Definition”**. A form appears to input the details. -3. **Enter Code and Name:** Provide a unique **Code** for the item (the system might enforce uniqueness). Enter the **Description** name. For example, code: `CARD100`, name: “Cardiology Consultation (New Patient)”. -4. **Set Price:** Enter the **Price** for this service. E.g., $150.00. Optionally specify the unit (if not each). For the consultation, unit might be “per visit” (which could be implicit, so maybe no separate unit field needed). -5. **Category/Type:** Choose a **Category** like “Consultation” or “Cardiology”. (This helps in organizing items. The system might have a list of categories.) -6. **Applicability Rules:** Define any rules for this code: - - If it’s specific to a setting: e.g., check a box “Outpatient only” or conversely “Inpatient only” if applicable. - - If it’s age-specific: maybe fields to input min age or max age. - - If it should not be combined with certain codes: possibly a multi-select to pick codes that conflict. - - If it requires another code: a field to select the prerequisite code. - - If there’s a frequency limit: input something like “Max 1 per day” or similar. - Some systems might allow entering these via a simple UI, others might require writing an expression or just documenting it in notes. At minimum, an **internal note** can be recorded (like “Do not bill with follow-up consult on same day”). We assume a UI where common constraints can be toggled. -7. **Price Components/Surcharges:** If this item inherently includes multiple components, list them. For instance, if `MRI001` includes a contrast fee, one approach is to create a separate definition for contrast and then note it here. Alternatively, add a sub-entry in the form: “Additional Fee: Contrast Material $100 (applies if contrast used)”. Let’s say our UI allows adding a sub-line in the definition for surcharges or discounts. The admin could add: Condition: “Uses Contrast = Yes” then “Additional charge $100”. Another example: “Weekend surcharge 15%” as a condition (Day of week = Saturday/Sunday -> price * 1.15). - - If the UI doesn’t support conditional components, the admin might instead create separate definitions for surcharges and rely on business rules to add them in combination. -8. **Effective Date:** Set when this price is effective. If this is a new code, it could be effective immediately (today’s date). If planning a price increase, one could set the effective date in the future. If the form allows, also set an end date if known (often left open-ended until changed). -9. **Activate Definition:** Ensure the definition is marked **Active** so it’s available for use. (Sometimes new entries might default to active unless a checkbox is provided to set it active/inactive.) -10. **Save:** Submit the form. The system validates uniqueness of code, required fields, numeric formats for prices, etc. If all good, it creates the new definition entry. - - The new definition now appears in the catalog list. It should be available in the Charge Item selection UI for any new charges. - - If there’s a sync or caching mechanism for the list of codes (for performance), ensure it refreshes so that the new code shows up for users immediately. - -**Updating a Charge Item Definition (Price change or rule change):** -1. Go to the **Charge Item Definitions** list and search for the code or name in question. E.g., find “MRI Brain”. -2. Click **“Edit”** on that entry. -3. Change the necessary fields: - - If updating the price: you might not want to overwrite the old price if charges already used it. Ideally, to handle price changes, one would *add* a new effective period. For instance, the form might allow adding a new price effective from a certain date. If the UI is simpler, an admin might just change the price field. In such case, the system should possibly warn “This will change the price for all future charges; existing charges are not affected.” and maybe automatically set an effective date for the new price (like today). - - Adjust description if needed (maybe to clarify something). - - Modify rules: e.g., broaden age range, or add a new incompatible code. - - Possibly mark the old price as ended yesterday and new price from today if system supports multiple records or a history. -4. Save changes. The system validates and updates the definition. If versioning is supported, it might actually create a new version entry under the hood rather than simply editing (so that historical data remains tied to old version). -5. After saving, new charges added will use the updated definition. Existing Charge Items already posted are not retroactively changed (they retain the price at which they were added, since those are stored with the charge). +A **Charge Item Definition** specifies **what** items/services can be billed and **how** pricing or conditions are applied. Think of it as the **price catalog** plus rule engine for your billing system. Each definition includes a billing code, base price or rate, plus optional surcharges, discounts, or taxes. It can also contain rules about when to apply these pricing components—for example, a certain code might only apply to patients of a specific age group, or only for inpatient encounters. + +This resource allows your HMIS to automatically derive the appropriate cost of a service or product by referencing the relevant **Charge Item Definition**. If you later update your official price list, that change is made once in the definition, and all future charges referencing it will use the updated pricing logic. Complex logic (like time-of-day surcharges, tax rules, or special discounts) can also be embedded here. + +## Schema Definition + +```json +{ + "id": "", // Internal Identifier + "version": "", // Version + "title": "", // Name for this charge item definition + "slug": "", // URL-friendly identifier + "derivedFromUri": "", // Was this from a URL + "status": "", // draft | active | retired | unknown + "facility": "", // Facility where this Charge Item Definition is created + "description": "", // Natural language description of the charge item definition + "purpose": "", // Why this charge item definition is defined + "code": "", // Billing code or product type this definition applies to + "instance": [ + { "ActivityDefinition|Medication" } // Resources this definition can apply to + ], + "propertyGroup": [{ // Group of properties which are applicable under the same conditions + "applicability": [{ // Whether or not the billing code is applicable + "condition": { "Expression" } // Boolean-valued expression + }], + "priceComponent": [{ "MonetaryComponent" }] // Components of total line item price + }] +} +``` + +## Core Data Structure + +### Essential Fields + +| Field | Description | Technical Notes | +|-------|-------------|----------------| +| **id** | Internal system identifier | Primary key, auto-generated | +| **version** | Version number of the definition | Supports tracking changes over time | +| **title** | Human-readable name of the charge item | Used in selection interfaces and reports | +| **slug** | URL-friendly identifier | Used for API endpoints and references | +| **status** | Current state of the definition | Controls whether it can be used for billing | +| **facility** | Healthcare facility reference | Used for facility-specific pricing | +| **description** | Detailed description of the charge item | Provides context for billing staff | +| **code** | Billing code or identifier | Links to standard coding systems when possible | +| **instance** | Reference to clinical resources | Shows which clinical activities can trigger this charge | +| **propertyGroup** | Container for pricing rules | Groups related pricing components | + +### Status Values + +| Status Value | Description | System Behavior | +|--------------|-------------|----------------| +| **draft** | Definition is being created or updated | Not yet available for charging | +| **active** | Definition is currently in use | Can be selected for charging | +| **retired** | Definition is no longer used | Not available for new charges but preserved for historical records | +| **unknown** | Status cannot be determined | Used for imported data with unclear status | + +### Price Component Types + +| Component Type | Description | Usage | +|----------------|-------------|-------| +| **base** | Core price of the service or item | Starting point for all calculations | +| **surcharge** | Additional charge on top of base price | Used for extras or special conditions (e.g., after-hours service) | +| **discount** | Reduction from base price | Used for special programs or agreements | +| **tax** | Statutory charges required by law | Applied based on tax regulations | +| **informational** | Non-charging line items | Used to show calculations or for documentation | + + +## Business Logic +1. **Single Source of Truth**: All billable items must have a corresponding Charge Item Definition. Users can only bill codes that exist here, ensuring consistent naming/pricing. +2. **Lifecycle**: + - **draft** definitions should not appear in standard picklists for charge entry. + - **active** definitions appear in the billing UI. + - **retired** definitions are hidden from new usage but remain valid for historical bills. +3. **Price Calculation**: At the moment a user (or system) creates a Charge Item referencing this definition: + - Evaluate each `propertyGroup` in order. For those whose conditions pass, accumulate the price components (base, surcharge, discount, tax, etc.). + - Derive the final unit price or total by combining those components. + - If multiple property groups apply, they can be additive. For example, base price = 100, night surcharge = 20, tax = 5% → final = 126. + +## Step-by-Step User Workflows +Though staff typically do not interact with Charge Item Definitions daily (they are more of an admin function), here is how the workflow might look for a billing administrator: + +1. **Navigate to “Charge Item Definitions” Admin Screen** + - Only users with proper roles (billing manager) can edit these definitions. + +2. **Create or Edit a Definition** + - Enter basic info: code, title, description. + - Set **status** to `active` once ready. + - Define or update `propertyGroup` details—like base price, potential surcharges, discount conditions. + +3. **Save & Activate** + - The definition now appears in the system’s reference data. + - If staff add charges referencing this code, the system automatically uses these pricing rules. + +4. **Retire a Definition** + - If no longer used, set status to `retired`. The system hides it from new charge entry. Existing references remain valid historically. + +5. **Verify Pricing** + - Admin or finance staff can test conditions to confirm the definition yields correct amounts. E.g., “Patient over 60 -> 10% discount is working as intended.” + **Deactivating (Retiring) a Charge Item Definition:** - If a service is no longer offered or a code is deprecated, an admin can mark it as **Inactive**. This usually involves editing the definition and unchecking an “Active” box or setting a termination date. @@ -81,36 +109,4 @@ The Charge Item Definition holds all relevant billing information for a given se **Viewing the Catalog:** - The Charge Item Definition list can usually be viewed in a table format by authorized users. It might show columns: Code, Description, Price, Unit, Active/Inactive, etc. - Users (like billing staff) with view-only access can search this list to find how something is billed. For example, “How much is the charge for an MRI spine?” They can find the definition entry for MRI spine which says, e.g., $400. -- This ensures transparency: staff can answer patient queries about costs using the official catalog. - -**Using Definitions during Charge Entry (UI perspective):** -- As mentioned earlier, when adding a charge (Charge Item), the system references this catalog. The search or dropdown is driven by the definitions. If a code is updated or newly added, that is immediately reflected to the end user adding charges. -- If a user somehow doesn’t find a desired code (maybe it’s new or they are using an old term), there might be a process to either look up synonyms or request a new code. The definitions can have synonyms or keywords for searching. E.g., if a user types “blood sugar”, it could match a definition for “Glucose test”. -- If the user selects a code that has specific rules, the UI might give immediate feedback. For instance, if a code is “Inpatient only” and they’re trying to add it on an outpatient account, upon selection the system could show a warning “This code is typically for inpatient use; please verify.” It might still allow if the user insists (or might block entirely depending on strictness). - -## Developer Notes (Definition Module & Pricing Engine) -- **Data Structure:** Maintain a table for ChargeItemDefinitions with fields as above (code, description, price, etc.). If you need to support price history, you might have a linked table for prices with effective dates. Alternatively, include validity dates in the main table and create a new record for the same code when updating price (differentiated by version or effective date). Ensure that there’s a way to fetch the correct price by date. -- **Unique Code Constraint:** Enforce unique codes at the database level. Also possibly enforce no overlap of effective periods for the same code (to avoid ambiguity in price on a given date). -- **Performance (Lookup):** The list of definitions could be large if the hospital has many services. Use indexing on code and description for fast search. When a user is typing to search, consider a search service or caching popular terms in memory for quick auto-complete. Ensure inactive codes are either filtered out or clearly marked. -- **Applying Definitions to Charges:** Implement a function like `applyDefinition(charge, definition)` that: - - Checks each rule in the definition against the context (patient, account, other charges). - - Adjusts the charge’s allowed status or price accordingly. - - For example, if definition says “not billable for age > 14” and patient is 20, then perhaps `charge.status = not-billable` by default or a warning is raised. However, usually one wouldn’t add such a charge for an adult at all (the UI might filter it out). - - Another example: definition has a condition “if after hours, add 50”. If charge time is 9pm, either add a separate charge automatically or append a component. A simple method: create a hidden surcharge definition and auto-add a ChargeItem for it. Or adjust the price of the current charge. Decide on one approach and implement consistently. -- **Compound Pricing:** FHIR suggests multiple price components (like base price, surcharge, discount) for transparency ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=balanced%20with%20this%20Invoice%20account,to%20the%20recipient%20of%20the)). If implementing that, your ChargeItemDefinition might list components rather than a single price. For instance, base = 100, night surcharge = 20%. At runtime, you’d calculate total = 100 + (20% of 100). You might want to store both components to show on invoice (like “Base fee $100, After-hours surcharge $20”). This can be done by generating two separate line items (which could confuse patients) or by supporting a composite structure in the invoice line. We discuss invoice presentation in the Invoice section. -- **Validation vs Enforcement:** Some rules might be soft (warnings) and some hard (errors). Decide which rules absolutely prevent charge entry (and implement as such). Others implement as warnings that the user can override with a justification (store that justification). -- **Administration UI:** Provide a secure UI for managing definitions. Only certain roles should access this. Also, consider logging changes (who changed a price or rule, old vs new values). -- **Impacts of Changes:** Changing a price definition should not retroactively update already posted charges. Ensure that when applying definitions to a ChargeItem, you stamp the price at that time. If you store just a reference to the definition and calculate on the fly, then historical invoices might change if definitions change – which is undesirable. Therefore, better to store the resolved price in ChargeItem (or invoice line). If you need to reproduce an old invoice exactly, you cannot rely on current definition data. - - Some implementations handle this by version: each invoice or charge stores the code *and a reference to the definition version*. If someone needs to understand that price, they refer to the definition version record. -- **Interdependence of Definitions:** If you have rules like “code A requires code B”, ensure both exist. Possibly create a mechanism of linking definitions (like references or foreign keys for prerequisites). If code B is removed or changed, update code A’s rule as well. -- **Testing Scenarios:** It’s important to test various combinations: - - A charge with multiple applicable rules (e.g., patient under 14 AND after hours – does it get two modifications?). - - Ensure no double-counting surcharges (applying same rule twice). - - If two different rules conflict (unlikely if curated well, but e.g., one rule says “price = 100” another says “price = 80 for same condition” – the system should have a clear precedence or just not allow contradictory rules). -- **Bulk Updates:** If prices increase by a percentage across the board, it might be helpful to have a script or tool to update many definitions at once (rather than manually editing each). Consider designing an import or bulk update interface, especially if prices come from an external source like a national fee schedule. -- **FHIR Alignment:** The structure here corresponds to FHIR’s ChargeItemDefinition. If planning to export or import FHIR resources: - - The rules might be represented as `applicability` expressions in FHIR or `propertyGroup` with `priceComponent`. You would map your internal representation to those. - - The $apply operation in FHIR can take a ChargeItemDefinition and a context (patient, etc.) and return computed price components ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=A%20billing%20engine%20will%20apply,Operation)). You may implement something analogous internally. For example, when finalizing an invoice, for each charge, you could conceptually perform a mini `$apply` to ensure all pricing rules have been applied correctly. -- **Error Handling:** If a user tries to add a charge and the system can’t find a definition (which shouldn’t happen if UI prevents it), handle it gracefully – maybe show “Unknown code” error. Similarly, if a definition exists but has no price (maybe an oversight), do not charge $0 silently; flag it so it can be corrected. -- **Edge Cases:** Consider a scenario where a definition is updated while someone is in the middle of entering charges. If they had the form open with old data and then save, could that conflict? To avoid issues, you might lock definitions editing during peak usage or have the charge posting always re-fetch the latest definition when saving. -- **Security:** Because charge definitions determine revenue, they should be secure. Only authorized changes, and perhaps double-check expensive items. Sometimes an approval is needed for major price changes (two sets of eyes rule). This might be beyond our current scope but keep audit logs for definition changes to catch any accidental or malicious edits. +- This ensures transparency: staff can answer patient queries about costs using the official catalog. \ No newline at end of file From 4c84ac53ac1678f4dfb405f9b84dbd14624199ee Mon Sep 17 00:00:00 2001 From: Bodhish Thomas Date: Wed, 30 Apr 2025 19:40:45 +0530 Subject: [PATCH 04/13] Update CI and CID --- docs/care/HMIS/Billing/ChargeItem.md | 172 +++++++----------- .../care/HMIS/Billing/ChargeItemDefinition.md | 12 ++ 2 files changed, 82 insertions(+), 102 deletions(-) diff --git a/docs/care/HMIS/Billing/ChargeItem.md b/docs/care/HMIS/Billing/ChargeItem.md index 3cfddc6..b6ef9a1 100644 --- a/docs/care/HMIS/Billing/ChargeItem.md +++ b/docs/care/HMIS/Billing/ChargeItem.md @@ -1,114 +1,82 @@ # Charge Item +A **Charge Item** is the actual **instance** of billing for a specific service or product provided to a patient. It references a **Charge Item Definition** (i.e., the priced “catalog entry”) to derive the cost, plus actual usage details (quantity, date, any overrides). Each Charge Item links to a specific **Account** (which accumulates charges for a patient or episode of care) and often to an **Encounter** (the clinical context). -## Summary -A **Charge Item** represents a single billable service, procedure, medication, or product that a patient received, which should be charged on their account ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=The%20resource%20ChargeItem%20describes%20the,process%20and%20internal%20cost%20allocation)). Essentially, each charge item is like a line item in a bill, detailing what was provided, to whom, when, and in what quantity. For example, a charge item could be “Chest X-Ray” or “Blood Test CBC” or “Medication: Antibiotic 500mg – 10 tablets.” Charge Items capture the necessary details (date, provider, etc.) to support billing and are later summed up on invoices. The main purpose of recording charge items is to enable the billing process and internal cost allocation ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=The%20resource%20ChargeItem%20describes%20the,process%20and%20internal%20cost%20allocation)) – they feed into the Invoice generation and financial reporting. +For example, if a nurse administers 2 doses of an expensive medication, the system may create a Charge Item for “Medication: XYZ” with quantity=2, referencing the relevant charge definition for medication pricing. Once a Charge Item is **billable**, it can appear on an **Invoice**. -Each Charge Item is linked to an **Account** (the bucket of charges for a patient or encounter) so that the system knows where to accumulate the cost. Charge Items typically reference a predefined **Charge Item Definition** (the billing code) to fetch pricing and any special billing rules. They also have a status that tracks their billing state (e.g., whether they’ve been billed yet or not). This ensures that each service is billed exactly once and helps in workflows like charge review and approval before billing. -## Key Fields and Lifecycle Statuses -**Key Fields:** -- **Charge Item Code:** A code or identifier for the service or product provided. This usually corresponds to a entry in the Charge Item Definitions (the “catalog” of billable items). For example, a code might be “XRAY001” for a chest X-ray. The code is often selected from a list in the UI, and it brings along a description (e.g., “Chest X-Ray, 2 views”) and price. *(In FHIR terms, this might be represented as a CodeableConcept or reference to a ChargeItemDefinition ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=ChargeItem)).)* -- **Description:** A human-readable description of the charge, if not obvious from the code. In many systems, this auto-fills when a code is selected. E.g., “Complete Blood Count (CBC) test”. -- **Quantity:** The number of units provided. If the charge item is for a service, quantity is often 1 (each service instance). If it’s for an item (like medication or supplies), quantity could be multiple (e.g., 10 tablets). The UI allows the user to input quantity. The total price for the charge item will be **quantity × unit price**. -- **Account Reference:** The account (or patient encounter) to which this charge is applied. This links the charge to the correct bucket for billing ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=8)) ([Account - FHIR v6.0.0-ballot2](https://build.fhir.org/account.html#:~:text=,37%20and%20PaymentReconciliation)). In the UI, if you are adding a charge from within an Account screen, this may be implicit (the system knows which account you are viewing). If adding from a general charges interface, the user must specify the target account/patient. -- **Service Date/Time:** When the service was provided or the item was supplied to the patient. This is important for record-keeping and also for checking against any billing rules (e.g., after-hours charges, or whether the service falls within the account’s billing period). The field may be a single date/time or a range (start/end) if the service lasted a span of time ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=ChargeItem.occurrence)). -- **Performing Practitioner/Department:** (If applicable) Who performed the service or which department it belongs to (for routing and information). E.g., a lab test might list the lab department or the lab technician, a radiology exam lists the radiologist or radiology dept. This can help with internal tracking or if different departments have different billing responsibilities. -- **Price (Unit Price and Total):** The monetary amount to charge for this item. In a FHIR-pure approach, the ChargeItem may not have the price explicitly stored on it, relying on the ChargeItemDefinition for pricing ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=Since%20the%20individual%20ChargeItem%20resources,the%20context%20of%20the%20ChargeItem)). However, in an HMIS it’s common to calculate and store the price when the charge is recorded, so that staff can review it. For example, if “Chest X-Ray” costs $100, and quantity is 1, the total for that charge item is $100. If quantity were 2 (for something like two units of a supply at $5 each), total is $10. - - *The UI usually shows the price when a code is selected.* If any discounts or surcharges apply, those might adjust the price (see **Charge Item Definition** rules). Developers might implement this by fetching the price from the definition and applying any relevant rules at the moment of charge entry. -- **Override Reason / Adjustments:** (Optional) If a price is manually overridden or a charge is waived, the system might allow recording a reason. For instance, if staff set the price to $0 for a courtesy service, they should note why (e.g., “free sample – not billable”). This keeps a trail for auditors. In a strict FHIR model this could be an extension since ChargeItem doesn’t normally include a price override field in the core spec. -- **Status:** The billing status of the charge item, indicating where it is in the billing process. The statuses commonly include **planned**, **billable**, **not-billable**, **aborted**, **billed**, **entered-in-error**, or **unknown** ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=The%20current%20state%20of%20the,ChargeItem)). This field is crucial for workflow: it prevents double billing and indicates if a charge needs attention. - - *Planned:* The charge is anticipated but not yet ready to be billed. For example, a procedure is scheduled for tomorrow – a charge item might be pre-created as planned. It hasn’t actually occurred or is pending confirmation. Planned items do not count towards the account balance until they become billable. - - *Billable:* The service has been provided and the charge is confirmed, making it ready to bill. Most charges added after a service is delivered will start in the **billable** state (meaning they should appear on the next invoice). - - *Not-billable:* The service was provided but will not be billed to the patient (perhaps it’s covered by a flat rate or part of a package, or given as courtesy). Setting a charge to not-billable excludes it from invoicing. For instance, if a hospital does a second X-ray at no charge due to a previous issue, they might record it for history but mark it not-billable. - - *Aborted:* The service was not completed, so it should not be billed. For example, a surgery was started but aborted due to complications – there might be other ways to bill partial costs, but this particular scheduled charge might be aborted. Aborted is similar to not-billable in that it won’t be invoiced, but it specifically indicates the procedure didn’t occur as planned. - - *Billed:* The charge has already been billed on an invoice ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=The%20current%20state%20of%20the,ChargeItem)). Once an invoice including this charge is finalized (issued), the system should update the charge’s status to **billed**. This prevents the charge from being accidentally billed again on another invoice. From a UI perspective, billed items are usually locked from editing (since they’ve been sent out on an invoice). - - *Entered-in-error:* The charge entry was a mistake and should be voided. Perhaps the wrong code was entered or it was a duplicate entry. Marking a Charge Item as entered-in-error means it is invalid and should not be billed or counted. The item might be hidden from normal views or shown with a strike-through. (In some systems, deletion of a charge item might be allowed if truly wrong, but often they keep it with an error status to maintain an audit trail ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=Terminology%20Binding%20%20%2044,Summary%20true%20Comments)).) - - *Unknown:* The status of the charge item isn’t known. This is uncommon in practice; it might be used if the system imported data from elsewhere and isn’t sure of the state. Generally, this would be treated similar to not-billable or would require staff resolution. +## Schema Definition +```json +{ + "id": "", // Internal Identifier + "definition": "", // Definition pointing to Charge Definition + "status": "", // planned | billable | not-billable | aborted | billed | entered-in-error | unknown + "code": "", // A code that identifies the charge, like a billing code + "patient": "", // Patient Associated with the charge + "encounter": "", // Encounter associated with this ChargeItem + "facility": "", // Facility where this Charge Item is created + "quantity": "", // Quantity of which the charge item has been serviced + "unitPriceComponent": [ + "MonetaryComponent" // Unit price components + ], + "totalPriceComponent": [ + "MonetaryComponent" // Total price components + ], + "total_price": { // Total Price in Amount + "Money" + }, + "overrideReason": { // Reason for overriding the list price/factor + "text": "", + "code": "" + }, + "service": { // Why was the charged service rendered? + "resource": "", + "id": "id" + }, + "account": "", // Account to place this charge + "note": "", // Comments made about the ChargeItem + "supportingInformation": [ + { "Reference(Any)" } // Further information supporting this charge + ] +} +``` -- **Related Charge Items:** (Optional/Advanced) Sometimes one charge item may be logically grouped with others. For example, a surgical procedure might include multiple components (surgeon fee, anesthesiologist fee, operating room fee). In FHIR, ChargeItem has a `partOf` field to reference a parent charge item ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=ChargeItem)), creating a hierarchy. In practice, our HMIS might not require explicit linking, but if it does, it could show one charge as a parent with others indented beneath it. This is more for internal grouping and doesn’t typically change billing, except perhaps to treat the whole group as one package for discounting or not-billable decisions. +## Core Data Structure -**Business Logic for Charge Items:** -- When a new charge item is recorded as **billable**, it increases the patient’s account balance by the amount of the charge. If it’s marked not-billable or aborted, it should not affect the balance (or may even be excluded from the account’s charge list used for balance calculation, depending on implementation). -- **Status Transitions:** A charge might move through several statuses: - - Planned -> Billable (when the service is done or confirmed). - - Billable -> Billed (once included on an invoice). - - Billable -> Not-billable/Aborted (if decided not to charge). - - Billed -> (possibly back to Billable if an invoice is cancelled; see below). - - Any -> Entered-in-error (if identified as wrong entry). -- Once a charge is **billed**, it generally should not revert to **billable** unless a billing error occurred (like an invoice was cancelled). If an invoice is canceled or marked in error, the system may automatically revert its charges back to **billable** so they can be invoiced again correctly. *(Developers: implement logic that upon invoice cancellation, iterates through its charge items and sets them back to billable or whatever is appropriate, so they can be reused.)* -- **Applicability Rules:** Charge items often must meet certain criteria to be billable. The Charge Item Definition can carry rules – for example, a certain code might only be billable if the patient is over a certain age, or only once per encounter ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=,from%20the%20same%20billing%20system)). The system should enforce these: e.g., if a user tries to add a second charge of a type that is “only billable once per encounter,” the UI should prevent it and notify the user (instead of allowing duplicate charges). Another example: a code might require another code (e.g., a surgical fee might require an associated surgery procedure charge exists). If the prerequisite is not present, the system might warn “Cannot bill this item without XYZ also on the account.” These business rules ensure billing consistency and can reduce claim denials for incorrect coding. -- **Price Calculation:** By default, when a charge is marked billable, the system determines its price via the linked Charge Item Definition. If any conditions (like time of service or patient age) alter the price (surcharges/discounts), those should be computed. The *total* charge amount is then stored or at least displayed. This way, when staff reviews the account or draft invoice, they see the actual dollar amounts. If a price needs to be overridden (perhaps manager approval required), it should trigger a specific workflow (like requiring an “override reason” and possibly raising a flag for review). -- **Link to Clinical Data:** Optionally, charge items may be triggered from clinical actions. For example, when a lab test is ordered and resulted, the system could automatically generate a corresponding Charge Item. In such cases, the charge item might start as planned (when ordered) and become billable when the test is completed. This automation ensures charges aren’t missed. From a user perspective, they might just verify or adjust auto-generated charges rather than enter them all manually. -- **Auditing and Edits:** It’s important for financial integrity that once a charge is billed or marked not-billable, it isn’t silently changed. The system should restrict editing of key fields (especially price and code) after the fact, or log any changes. For instance, if a staff corrects a quantity from 2 to 1 after initial entry, that should be tracked. If a charge was billed and needs correction, usually the proper approach is to issue an adjustment (credit) rather than editing the original charge. The HMIS may or may not support direct credit adjustments at the Charge Item level (some do via negative charges or special adjustment entries). +### Essential Fields -## Step-by-Step User Workflows (Charge Item UI) +| Field | Description | Technical Notes | +|-------|-------------|----------------| +| **id** | Internal system identifier | Primary key, auto-generated | +| **definition** | Reference to the Charge Item Definition | Links to the catalog entry for this service/item | +| **status** | Current state in the billing lifecycle | Controls whether the item can be invoiced | +| **code** | Billing code for the service | Often derived from the definition | +| **patient** | Reference to the patient | Person receiving the service | +| **encounter** | Reference to the healthcare encounter | Links to the clinical context | +| **facility** | Reference to the healthcare facility | Location where service was provided | +| **quantity** | Number of units provided | Default is 1 for most services | +| **unitPriceComponent** | Price breakdown per unit | Includes base, surcharges, discounts, taxes | +| **totalPriceComponent** | Price breakdown for all units | Unit price × quantity with all components | +| **total_price** | Final calculated amount | Sum of all price components | +| **account** | Reference to the billing account | Where this charge accumulates | -**Adding a Charge Item (Posting a Charge):** -1. **Identify Account/Patient:** To add a charge, the billing staff first navigates to the relevant patient’s **Account** (as described in the Account workflow). Typically, there will be an “Add Charge” button on the account’s page or a similar function in a charges module where the user selects the account/patient. -2. **Initiate New Charge:** The user clicks **“Add Charge”**. A charge entry form or dialog appears. -3. **Select Service (Code):** The first field usually is to choose the service or item to charge for. This could be a dropdown or an auto-complete field tied to the **Charge Item Definitions** (the catalog of billable services). The user can type keywords or code, and select the appropriate item from the list (e.g., typing “X-Ray” shows “XRAY001 – Chest X-Ray”). - - Once a code is selected, the form may auto-fill the **Description** and **Unit Price** for reference, based on the definition. For example, after choosing “XRAY001,” the description might show “Chest X-Ray (2 views)” and price “$100.” -4. **Enter Quantity:** The user specifies the quantity if applicable. For many services, this remains “1”. For items like medication, they enter the number of units (e.g., 10 tablets). The form might have a default quantity of 1 which the user can adjust. -5. **Verify/Enter Date:** Ensure the **Service Date** is correct. By default, it might populate with today’s date (or the encounter date). If entering charges retrospectively, the user should set the date to when the service was actually provided. For ongoing services or multi-day items, there might be start/end date fields. -6. **Review Price:** The system calculates the total price = unit price × quantity. For instance, if unit price is $100 and quantity is 1, total is $100. This might be displayed as read-only or editable (depending on permissions). If the user has rights to override the price (e.g., apply a discount or adjust for some reason), they might be able to enter a new price or a discount percentage. In a standard workflow, price override is not common; they’d instead use predefined discount codes or mark it not-billable if waiving. -7. **Additional Details:** If needed, the user can fill in extra fields like performing practitioner (if the form includes it), or add any note about this charge (for example, “Patient requested private room upgrade”). -8. **Submit Charge:** The user clicks **“Save”** or **“Add”**. The system performs validations: - - Required fields must be present (code, quantity, date, etc.). - - Check any rules from the Charge Item Definition (if the system can – e.g., if this code is not allowed twice, see if it’s already on this account). - - If the account is on hold or inactive, the system should block this action (with a clear error as discussed). - - If all is well, the charge is recorded in the database. -9. **System Response:** The new charge item now appears in the account’s charge list. It will typically show up with its details: date, description, quantity, price, and status. Initially, since this is a fresh charge, its status would likely be **billable** (because it’s ready to be billed). The account balance will instantly reflect the addition of this charge (e.g., was $0, now $100 if that was the charge). - - The UI might highlight newly added charges or list them in chronological order. Some systems group charges by date or category on screen for readability. - - If the charge item triggered any warnings (say it’s an unusual combination), the system might show those. For example, “Warning: This service is typically not done for patients under 12 (pediatric rule)” – but still allow it if user confirms. Or “Error: Duplicate charge – that item already exists for today” and refuse saving if it violates a rule. -10. **Confirmation to User:** Possibly a toast or message “Charge added successfully” appears. Staff can then proceed to add more charges or do other tasks. Each charge item added will accumulate in the account until invoicing. +### Status Lifecycle -**Editing/Reviewing Charges:** -- Staff can click on a charge item in the account view to see its details. If it’s in a status that is editable (e.g., billable and not yet billed), they may have an option to **Edit** or **Delete** it. -- **Edit Charge:** Perhaps the patient’s name was spelled wrong in description or quantity was entered incorrectly. The user clicks “Edit” next to the charge. The system opens a form similar to the add form, pre-filled with the current values. The user can adjust allowable fields (maybe quantity or date; code might be locked if changes are not allowed, or maybe they can change code if they entered a wrong one initially). After saving, the changes reflect and the account balance updates if the amount changed. - *(Developers: if a charge’s code is changed, that effectively is like removing one charge and adding another – consider how to audit this. Often better to require deletion and re-add to avoid confusion in records.)* -- **Delete Charge (Entered-in-error):** If a charge was a mistake (e.g., entered on wrong patient’s account), and it hasn’t been billed yet, staff might have the ability to delete it. Upon deletion, the system might actually mark it as entered-in-error behind the scenes (to keep an audit). The UI would remove it from the visible list and adjust the account balance down accordingly. If deletion is not allowed via UI, the alternative is staff mark it “entered-in-error” if that status is provided in a dropdown. That status would exclude it from billing. In either case, once removed/marked error, the effect is the same: the patient is not billed for it. The system should log who removed it and when. -- If a charge is already **billed** (on an invoice that was finalized), the UI will likely **not allow editing or deletion**. Instead, if a change is needed, staff would have to cancel the invoice (which reverts the charges to billable) or issue an adjustment via another process. The charge item on a billed invoice is locked to ensure the invoice remains an accurate snapshot of what was sent out. -- **Marking Not-Billable:** As an alternative to deleting, if the service was real but they decide not to bill it, staff can edit the charge’s status to **not-billable** (if the system allows directly toggling that). The UI might provide a checkbox or status dropdown for charges (again, only if not billed yet). They would select “Not Billable” and possibly input a reason (like “included in research study” or “free re-test”). After saving, the charge would be excluded from invoices. It might appear grayed out or with a tag in the list. The account balance might immediately drop that amount (since we no longer intend to collect it). Essentially, this is a write-off of that charge. +| Status Value | Description | System Behavior | +|--------------|-------------|----------------| +| **planned** | Service is scheduled but not yet provided | Not counted in account balance; not billable | +| **billable** | Service provided and ready to bill | Included in account balance; can be invoiced | +| **not-billable** | Service provided but won't be billed | Not included in account balance; excluded from invoices | +| **aborted** | Service was not completed | Not included in account balance; excluded from invoices | +| **billed** | Charge included on an invoice | Included in account balance; cannot be invoiced again | +| **entered-in-error** | Charge was created by mistake | Excluded from all calculations and invoices | -**Automatic Charge Generation:** (Just for context, not a user action) -- Some charges might appear automatically. For instance, if the system is integrated with an order entry system, when a lab test is marked completed, a charge item could be auto-posted. In such cases, the billing staff’s role is to **review** these auto-posted charges for accuracy. The workflow would be: - - The charge shows up on the account (maybe flagged as new or unreviewed). - - Staff checks that it has the correct code and quantity. If something’s off (e.g., a test was cancelled but charge still posted), they can adjust status or remove it. - - If everything is correct, they don’t need to do anything further; it will flow into the invoice. This reduces manual data entry. -**Charge Review & Approval:** (If applicable) -- In some hospital workflows, especially for complex cases, charges might be entered by clinical staff and then reviewed by billing staff before invoicing. The system might use the **planned** status for preliminary entries. For example, a nurse enters the items used during a surgery into the system as planned charges. A billing specialist later reviews and switches them to **billable** once verified. In our HMIS UI, this could be done by listing planned charges and providing an “Approve” action that changes their status to billable (and perhaps assigns prices). -- The UI could also allow batch actions, e.g., select multiple charges and mark all as not-billable or move to billable, etc., if many need updating at once. +## User Workflows -## Developer Notes (Charge Item Logic & Validation) -- **Database Model:** Each ChargeItem record should store references to the account (account_id), possibly the definition (charge_code or an ID linking to ChargeItemDefinition), quantity, and an amount. If following FHIR strictly, you might store only the reference to ChargeItemDefinition and not the price, but practically storing the calculated price is useful for consistent reporting (especially if prices can change in the catalog later; you’d want the charge to reflect the price at time of service). -- **Status Field Enforcement:** Use enumerated values for status (to avoid free-text). Enforce via business logic: - - Only certain transitions are allowed (e.g., can go from billable to billed, but not from billed back to billable unless an invoice is undone). - - If a user tries an invalid transition, throw an error. - - If using FHIR codes, map them appropriately (e.g., “billed” corresponds to FHIR’s *billed* status code ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=The%20current%20state%20of%20the,ChargeItem))). -- **Pricing Engine:** Implement logic to fetch and apply ChargeItemDefinition when a charge is created or edited: - - On charge save (if new or if code changed), retrieve the base price from the definition table. - - Check for any applicable *price modifiers*: for example, if the definition indicates “after hours surcharge +20%” and the service date is 10pm, you might calculate that and either adjust the price or perhaps add an additional charge item for the surcharge. FHIR’s design would use a PriceComponent in Invoice for transparency ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=balanced%20with%20this%20Invoice%20account,to%20the%20recipient%20of%20the)), but in our system we might simply adjust the price or create a separate predefined surcharge item. - - Ensure the final price is stored or at least ready to be displayed. - - If an override is allowed, set a flag (so we know this price didn’t follow standard rules). - - Consider rounding issues (especially if percentages involved). -- **Rule Enforcement:** The ChargeItemDefinition might contain rules (applicability conditions) ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=Many%20billing%20systems%20have%20rules,Rules%20for%20applicability%20may%20include)). To implement these: - - E.g., “once per encounter” – before saving a new charge, query if another charge with the same code exists on the same account (and perhaps same encounter). If yes, block or warn. - - “Only in outpatient setting” – if the account type is inpatient and the code is outpatient-only, then prevent adding it (or warn and require override authorization). - - “Only for age < 14” – check patient’s DOB against service date, calculate age, enforce accordingly. - - “Must accompany code X” – if code Y is added, verify code X is also on the account (maybe in planned or billable). If not, warn like “Code Y typically requires code X. Please ensure X is also added if appropriate.” - - These checks can be complex. A simpler implementation is to warn the user to review, rather than outright block, in some cases. But critical ones (like duplicate charge that will definitely cause issues) should be blocked. - - Document any override capability: perhaps a supervisor can override and add a duplicate charge if absolutely needed. -- **Batch Operations:** Provide efficient ways to update statuses in bulk (for backend processing). For example, when an Invoice is finalized containing N charges, instead of updating each charge in a slow loop, use a batch update query to set all their statuses to billed in one go, for performance and consistency. -- **Integrity with Invoice:** When generating an invoice, ensure only charges with status **billable** (and belonging to the account) are considered. Mark them billed atomically with invoice creation. If invoice creation fails halfway, no charge should remain incorrectly marked as billed – handle rollback. -- **Concurrency:** If two users try to bill the same account simultaneously (rare but possible in large systems), or one is adding charges while another is invoicing, you need to handle it: - - Potential solution: lock the account or the involved charges during invoice generation. - - Or check right before finalizing invoice that none of the charges were already billed by another process (and if they were, refresh the list). - - This prevents double-billing or missing charges. -- **Entered-in-error vs Deletion:** Decide how to implement charge removal. The FHIR way would mark entered-in-error ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=Terminology%20Binding%20%20%2044,Summary%20true%20Comments)). If you choose to allow deletion in the UI, consider still keeping a record behind the scenes. Perhaps have a deleted flag or move the record to an audit log table. This avoids data loss which could be important if someone asks “Why was patient billed then credit given?” -- **Logging:** Log who added each charge and when. If changes are made (status change, price override, deletion), log those actions too (user ID, timestamp, old vs new values). This is crucial for auditing and resolving disputes (e.g., “why was this charge removed?”). -- **Link to Orders:** If integrated, maintain reference IDs to clinical orders or procedures that generated the charge, if applicable. This can help trace back from a bill to the clinical event. -- **Future Dating/Planned Items:** If a charge is marked planned (for a future procedure), you might want an automated job or trigger: when the date arrives or the procedure is completed, automatically flip it to billable. Alternatively, require manual confirmation. Ensure planned items don’t inadvertently slip into invoices without review (maybe the invoice generation code filters them out unless explicitly told to include planned ones). -- **Data Exposure:** If there is an API or external reporting, ensure that sensitive charges (like those marked not-billable or error) are either clearly flagged or filtered out as needed to avoid confusion. -- **Calculate Totals by Category:** Some invoices might group charges by type (e.g., Room charges vs Medications). If needed, tag Charge Items with categories (possibly derived from the definition) to facilitate such grouping on invoices or statements. -- **FHIR Note:** In FHIR R4+, ChargeItem is a resource and can reference ChargeItemDefinition for price. If aligning with FHIR, consider using the `$apply` operation at runtime to let a rules engine calculate price components ([ChargeItemDefinition - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitemdefinition.html#:~:text=A%20billing%20engine%20will%20apply,Operation)). This could be a more dynamic but heavier approach. For a simpler HMIS, custom code as described above is likely sufficient. +### Editing or Canceling a Charge +- If a charge is still **billable** (and not on an issued invoice), staff can adjust quantity, override price, or mark it **not-billable**. +- If it is **billed** (already invoiced), any correction typically requires reversing that invoice or adding a credit note. +- Marking **entered-in-error** will remove it from the account’s balance. Log who performed this action. + +### Automatic Charge Creation +- The system will automatically create charges when certain clinical events occur (e.g., lab test result posted). Staff can still review them before they become “billable.” \ No newline at end of file diff --git a/docs/care/HMIS/Billing/ChargeItemDefinition.md b/docs/care/HMIS/Billing/ChargeItemDefinition.md index ea49859..0599778 100644 --- a/docs/care/HMIS/Billing/ChargeItemDefinition.md +++ b/docs/care/HMIS/Billing/ChargeItemDefinition.md @@ -31,6 +31,18 @@ This resource allows your HMIS to automatically derive the appropriate cost of a } ``` +### Monetary Component Definition +```json +{ + "type": "", // base | surcharge | discount | tax | informational + "code": "", // Codes to differentiate taxes, surcharges, discounts etc. + "factor": "", // Factor used for calculating this component + "amount": { + "value": "", // Numerical value (with implicit precision) + "currency": "" // ISO 4217 Currency Code + } +} +``` ## Core Data Structure ### Essential Fields From ca9f47ed0ebdc1ab7a0aecd2237de522fd62887f Mon Sep 17 00:00:00 2001 From: Bodhish Thomas Date: Wed, 30 Apr 2025 22:50:07 +0530 Subject: [PATCH 05/13] Add notes about invoice --- docs/care/HMIS/Billing/Invoice.md | 321 +++++++++++++----------------- 1 file changed, 133 insertions(+), 188 deletions(-) diff --git a/docs/care/HMIS/Billing/Invoice.md b/docs/care/HMIS/Billing/Invoice.md index d11ef44..e48303b 100644 --- a/docs/care/HMIS/Billing/Invoice.md +++ b/docs/care/HMIS/Billing/Invoice.md @@ -1,10 +1,7 @@ # Invoice -## Summary -The **Invoice** module handles the generation of formal bills based on accumulated charges for an account. An **Invoice** is a financial document issued by the healthcare provider (hospital/clinic) to the responsible party (patient, insurance, or other payor) that lists the goods and services provided (the Charge Items) along with their quantities and prices ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=Tracking%20Financial%20information%20is%20vital,with%20their%20quantities%20and%20prices)). In simpler terms, it’s the bill that the patient or insurer receives, detailing what they are being asked to pay for. - -The Invoice pulls together all relevant Charge Items from an Account (or a subset of them for a given billing period) and calculates the total amount due. It serves as the hospital’s record of what was charged, and it’s also used by patients or insurers to process payments. In an HMIS inspired by FHIR, the Invoice correlates with the FHIR Invoice resource, which is designed for structured billing communication ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=towards%20patients,view%20on%20the%20performed%20services)). The invoice is the provider’s view of the charges, as opposed to an insurance Claim which is for payer’s adjudication purposes ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=Competing%20invoicing%20standards%20such%20as,view%20on%20the%20performed%20services)). +An **Invoice** groups multiple **Charge Items** into a formal bill for a patient or payer. Once an invoice is **issued**, those charges are considered billed. The invoice can then be sent to the patient or insurer for payment. The invoice includes line items referencing the original Charge Items, plus any summary of taxes or adjustments. Once fully paid, the invoice is marked **balanced**. Key points about invoices: - An invoice can be in different states (draft, issued, paid, etc.), reflecting its lifecycle. @@ -12,35 +9,134 @@ Key points about invoices: - Invoices typically have unique numbers for external reference, along with dates and payment terms. - Once an invoice is issued (finalized), the charges on it are considered billed, and the invoice amount becomes a receivable for the hospital to collect from the payor. -## Key Fields and Lifecycle -**Key Fields:** -- **Invoice Number:** A unique identifier for the invoice (often a sequential number or alphanumeric). This is what will be printed on the invoice document and used by patients or accounting to reference the bill. The system may auto-generate this when finalizing the invoice (e.g., “INV-2025-000123”). -- **Account/Patient:** A reference to the **Account** (and implicitly the patient) this invoice is for. All charges on the invoice should belong to that account. Typically, an invoice is for one account (one patient’s set of charges) ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=Reference,balanced)). (In some cases, a combined invoice could cover multiple accounts for one payer, but our scope assumes one account per invoice for simplicity). -- **Invoice Date (Issue Date):** The date the invoice is generated/finalized. This is important for payment due calculations and auditing. If an invoice is drafted on one day and finalized on another, the issue date is when it’s finalized. -- **Billing Period (Service Period):** The date range of services covered by the invoice. For example, “Services from Jan 1, 2025 to Jan 31, 2025.” If the invoice is for a hospital stay, it might be the admission to discharge dates. This field is often included on the invoice so the recipient knows which period the charges correspond to. -- **Line Items (Invoice Lines):** Each charge on the invoice becomes a line item. A line item typically includes: - - A description of the service (from the Charge Item Definition). - - The service date (or date range if applicable). - - Quantity. - - Unit price and line total. Some systems may also show any adjustments on the line (like a discount applied). - - Optionally, a code or reference number for each line (for cross-reference). - The invoice line items come directly from the selected **Charge Items**. If the system allows, you might combine or summarize some charges (though usually each charge is a separate line to match audit trail). -- **Subtotal, Taxes, Adjustments:** If applicable, the invoice will compute a subtotal of all line items. If there are any taxes (some jurisdictions tax certain medical services or supplies) or additional fees, those are added as separate lines or in summary. Adjustments or discounts at the invoice level (like a one-time discount or write-off) might appear as a line or summary deduction. -- **Total Amount:** The grand total the invoice recipient is responsible for. This considers all charges, plus taxes, minus any discounts. (It would not subtract payments; payments are handled separately, not on the original invoice). -- **Payor/Recipient:** Who the invoice is addressed to. Often this is the patient (for self-pay portions) or an insurance company if you’re billing them directly. The invoice might have fields like “Bill To: John Doe” or “Bill To: XYZ Insurance, Policy #12345”. In FHIR terms, there might be a `recipient` which could be an organization (insurer) or patient ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=Tracking%20Financial%20information%20is%20vital,with%20their%20quantities%20and%20prices)) ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=code%20draft%20,error%20Binding%3A%20Invoice%20Status%20%28Required)). In our HMIS, if the account has an insurance coverage as primary, the initial invoice might be addressed to the insurance. -- **Issuer (Provider):** The organization issuing the invoice (e.g., the hospital name and address). This is usually a constant (the hospital’s details) and printed on the invoice header. It might be stored or configured globally rather than per invoice, but the field exists to identify who is charging. -- **Status:** The state of the invoice in its lifecycle. The main statuses include **draft**, **issued**, **balanced**, **cancelled**, and **entered-in-error** ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=code%20draft%20,error%20Binding%3A%20Invoice%20Status%20%28Required)). - - *Draft:* The invoice is in preparation. It’s not yet finalized or sent out. In this state, staff can still add/remove charges or make corrections. Draft invoices are essentially internal working documents. They may not have an official number assigned until finalization, or might have a provisional identifier. - - *Issued:* The invoice has been finalized (approved and sent to the payor). This status indicates the invoice is now an official claim of money. According to FHIR, “issued” means the invoice has been finalized and sent to the recipient ([OPENIMIS.FHIR.R4\Status (Invoice) - FHIR v4.0.1](https://fhir.openimis.org/ValueSet-invoice-status.html#:~:text=status%20hl7,cancelledCancelled%20the%20invoice%20was%20cancelled)). At this stage, the invoice is considered outstanding debt that needs to be paid. - - *Balanced:* The invoice has been completely paid off ([OPENIMIS.FHIR.R4\Status (Invoice) - FHIR v4.0.1](https://fhir.openimis.org/ValueSet-invoice-status.html#:~:text=status%20hl7,cancelledCancelled%20the%20invoice%20was%20cancelled)). In other words, the balance due on the invoice is zero because payment(s) matching the full amount have been reconciled. This is essentially a terminal state indicating no further money is owed on this invoice. - - *Cancelled:* The invoice was cancelled and is not to be paid ([OPENIMIS.FHIR.R4\Status (Invoice) - FHIR v4.0.1](https://fhir.openimis.org/ValueSet-invoice-status.html#:~:text=status%20hl7,cancelledCancelled%20the%20invoice%20was%20cancelled)). Perhaps it was created in error or the charges were moved to another invoice. A cancelled invoice is usually not sent out, or if it was, a cancellation notice is issued. The invoice number might be retired or might reference a reason for cancellation. - - *Entered-in-error:* If the invoice record was a mistake (e.g., completely wrong target or duplicate entry), it can be marked as entered-in-error. This is similar to cancelled but specifically denotes a data entry error. It should not be considered a valid invoice at all. In systems, often “cancelled” covers most scenarios (entered-in-error might be used in FHIR contexts for tracking, but practically a cancelled invoice can also cover erroneous ones with an explanation). - - *(Partial Payments?:)* Not a separate status, but it’s worth noting that if an invoice is partially paid, it typically remains in “issued” status (since it’s not fully settled, thus not balanced yet). There might be fields to track how much has been paid and what remains, but the status doesn’t change to a special “partially paid” value. Staff would look at payment records to know the outstanding balance on an issued invoice. -- **Payment Terms/Due Date:** Often invoices will say “Payment due in X days” or a specific due date (e.g., due 30 days from issue). The system might calculate a due date based on issue date plus a standard term (like 30 days). This isn’t exactly a status, but it’s an important piece of info. If the invoice is to an insurance, due date might not apply in the same way (it goes through adjudication). If to a patient, due date indicates when the patient should pay by. -- **Related References:** Possibly fields like *PaymentReconciliation reference* (if payment for this invoice has been recorded, a link to that), or *Claim reference* if this invoice was also submitted as an insurance claim. These help tie the invoice to other financial records. -- **Cancelled Reason:** If status is cancelled, a field to capture why (e.g., “Duplicate invoice”, “Charge error, invoice voided”) ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=%3CcancelledReason%20value%3D%22%5Bstring%5D%22%2F%3E%3C%21,cancellation%20of%20this%20Invoice)). This helps with audit and clarity. -- **Notes/Comments:** Any additional notes to include on the invoice, such as “Thank you for your prompt payment” or “Includes 10% discount as per management approval”. Also could include internal notes not printed, about special arrangements. +## Schema Definition +```json +{ + "id": "", // Internal Identifier + "status": "", // draft | issued | balanced | cancelled | entered-in-error + "cancelled_reason": "", // Reason if status=cancelled + "type": "", // E.g., "professional", "pharmacy", etc. + "patient": "", + "facility": "", // Facility issuing the invoice + "account": "", // The billing account associated + + "total_net": { "value": "", "currency": "" }, + "total_gross": { "value": "", "currency": "" }, + "payment_terms": "", // e.g. "Net 30 days" + "note": "" // Extra comments about the invoice +} +``` + +## Core Data Structure + +### Essential Fields + +| Field | Description | Technical Notes | +|-------|-------------|----------------| +| **id** | Internal system identifier | Primary key, auto-generated | +| **status** | Current state in the billing lifecycle | Controls available actions and payment status | +| **cancelled_reason** | Explanation if invoice is cancelled | Required when status is "cancelled" | +| **type** | Classification of the invoice | Categorizes for reporting and workflow routing | +| **patient** | Reference to the patient | Person who received the services | +| **facility** | Reference to the healthcare facility | Location that issued the invoice | +| **account** | Reference to the billing account | Account containing the charges | +| **total_price_component** | Breakdown of invoice total | Includes subtotal, taxes, discounts, etc. | +| **total_net** | Net amount before adjustments | Sum of charge items before taxes/discounts | +| **total_gross** | Final billing amount | Final amount after all adjustments | +| **payment_terms** | Payment instructions | Due date, payment methods, etc. | + +### Status Lifecycle + +| Status Value | Description | System Behavior | +|--------------|-------------|----------------| +| **draft** | Invoice is in preparation | Can be edited; not yet sent to recipient | +| **issued** | Invoice is finalized and sent | Read-only; pending payment | +| **balanced** | Invoice is fully paid | Read-only; no balance due | +| **cancelled** | Invoice has been voided | Inactive; requires reason | +| **entered-in-error** | Invoice created by mistake | Excluded from all calculations | + +## Business Logic Highlights + +- **Draft Creation**: Invoices begin as drafts, allowing staff to review and adjust before finalization. + +- **Charge Item Selection**: The system allows selecting which billable Charge Items to include on an invoice, typically gathering all unbilled charges from an account. + +- **Finalization Process**: When an invoice is issued, all included Charge Items are marked as "billed" to prevent duplicate billing. + +- **Payment Tracking**: The invoice status reflects payment completion, changing to "balanced" when fully paid. + +- **Cancellation Handling**: If an invoice is cancelled, the system reverts its Charge Items to "billable" status so they can be included on a new invoice if needed. + +- **Invoice Integrity**: Once issued, an invoice becomes read-only to maintain financial integrity. Changes require cancellation and reissuance. + +```mermaid +flowchart TD + B[Create Invoice Page] + B --> C[Gather Billable Charges] + C --> D[Review Draft Invoice] + + D --> E{Ready to Issue?} + E -->|No| F[Save as Draft] + F --> F1[Can Edit Later] + F1 --> D + + E -->|Yes| G[Finalize Invoice] + G --> H[Generate Invoice Number] + H --> I[Set Status to Issued] + I --> J[Mark Charges as Billed] + J --> K[Send to Recipient] + + K --> L{Payment Received?} + L -->|Full Payment| M[Set Status to Balanced] + L -->|Partial Payment| N[Record Payment] + N --> L + L -->|Problem Identified| O[Cancel Invoice] + + O --> P[Enter Cancellation Reason] + P --> Q[Return Charges to Billable] + Q --> R[Create New Invoice if needed] + + classDef process fill:#f9f,stroke:#333,stroke-width:2px + classDef decision fill:#bbf,stroke:#333,stroke-width:2px + classDef state fill:#6f6,stroke:#333,stroke-width:2px + + class A,B,C,D,F,F1,G,H,I,J,K,N,P,Q,R process + class E,L decision + class M,O state +``` + +**Creating an Invoice**: +1. Select the patient's account +2. The system gathers all billable (unbilled) Charge Items +3. Review the draft invoice and make any adjustments +4. When ready, finalize the invoice to generate an official invoice number +5. The system marks all included charges as "billed" +6. The invoice is now ready to be sent to the patient or insurer + +**Payment Handling**: +1. When payments are received, they are recorded against the invoice +2. Partial payments keep the invoice in "issued" status +3. When the full amount is paid, the invoice status changes to "balanced" +4. The invoice remains as a permanent record of the billing transaction + +**Cancellation Process**: +1. If an invoice needs to be cancelled, select "Cancel Invoice" +2. Enter a cancellation reason (required) +3. The system reverts all charges to "billable" status +4. If needed, create a new corrected invoice + +**Multiple Invoice Scenarios**: +- Interim billing during long stays +- Separate invoices for different service types +- Insurance billing followed by patient responsibility billing +- Corrected invoices after error identification + + + + + +## Key Fields and Lifecycle **Business Logic (Lifecycle & Rules):** - **Drafting vs Finalizing:** Invoices can be prepared as draft, allowing staff to review and possibly get approval before issuing. While in draft, modifications are allowed: - Staff can add or remove line items (which corresponds to adding or removing Charge Items to the invoice). Usually, only charges that are in “billable” status and not yet invoiced can be added. @@ -53,168 +149,17 @@ Key points about invoices: - All included Charge Items are marked as **billed** (their status updated, as discussed in Charge Item section). - The invoice becomes read-only for content; you generally shouldn’t edit line items after issuing (short of cancelling the invoice). - The invoice is now ready to be sent to the recipient (could be printed or electronically transmitted). -- **Posting/Printing:** Once issued, the invoice can be delivered. The system might have a function to print the invoice (generating a PDF or printout) or to send it via email. This doesn’t change the status, but it’s a crucial part of the workflow. The invoice document will list all charges and the total due. +- **Posting/Printing:** Once issued, the invoice can be delivered. The system might have a function to print the invoice or to send it via email. The invoice document will list all charges and the total due. - **Payments:** After issuance, the invoice sits in “issued” status until payment(s) are received: - If a payment comes in (via the Payment Reconciliation process), the invoice doesn’t immediately disappear; it just gains a record of payment. The invoice might show amount paid and remaining due. - - When the total amount of the invoice has been paid, the system should mark the invoice as **balanced** automatically ([OPENIMIS.FHIR.R4\Status (Invoice) - FHIR v4.0.1](https://fhir.openimis.org/ValueSet-invoice-status.html#:~:text=status%20hl7,cancelledCancelled%20the%20invoice%20was%20cancelled)), indicating it’s fully settled. This could be done by the Payment Reconciliation logic (when it notices full payment). + - When the total amount of the invoice has been paid, the system should mark the invoice as **balanced** automatically, indicating it’s fully settled. This could be done by the Payment Reconciliation logic (when it notices full payment). - Partial payments do not change the status (remain “issued”), but internal tracking of outstanding balance is updated. - **Cancellation:** If an error is discovered on an issued invoice (e.g., a charge was wrong or the invoice was sent to the wrong payer), you may need to cancel it. Business rules: - Only allow cancellation if no (or minimal) payments have been applied. If payments exist, typically you can’t outright cancel; you might have to refund or reallocate payments first. - - When cancelled, set status = cancelled, and record a cancellation reason ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=%3Cstatus%20value%3D%22%5Bcode%5D%22%2F%3E%3C%21,cancellation%20of%20this%20Invoice)). The system should also free up the underlying charge items to be billed on another invoice if appropriate. (i.e., change their status back to billable or even planned, depending on scenario). + - When cancelled, set status = cancelled, and record a cancellation reason. The system should also free up the underlying charge items to be billed on another invoice if appropriate. (i.e., change their status back to billable or even planned, depending on scenario). - Possibly generate a new invoice if needed (for correct charges). Or if the entire thing was wrong, just cancel and start over. - Cancelled invoices are kept for audit, but are not considered collectible. - **Avoiding Duplicate Invoices:** The system should ensure the same charge isn’t invoiced twice. This is handled by charge status (once included on an issued invoice, a charge shouldn’t appear on another invoice). When creating an invoice, the selection of charges should exclude any that are already billed. If a user somehow attempts to include a charge that’s been billed, the system should flag it as not allowed. - **Multiple Invoices per Account:** It’s possible to have multiple invoices for one account. For example, in a long hospital stay, they might generate interim invoices monthly, or one at discharge and then a supplementary one for late charges. The system should support picking which charges to include each time. Typically, an invoice might include all currently uninvoiced charges up to a cutoff date. If doing partial billing, the UI might allow selecting specific items or setting a date range. -- **Invoice for Insurance vs Patient:** If insurance is involved, an initial invoice might be created to send to the insurer (or an electronic claim, depending on integration). After insurer pays or responds, a secondary invoice (often called patient statement) might be created for the patient for any remaining amount. In our HMIS, the Invoice module could handle both by marking who it’s addressed to. For instance, invoice #100 to Insurance (for full charges) and after insurance adjustments, an invoice #101 to patient for copay/deductible. However, in FHIR, such coordination might use Claim/ClaimResponse for insurance and Invoice for patient billing. Here we can allow Invoice to represent any bill request. -- **Interfacing with Insurance Claims:** If the HMIS uses a separate Claim process, an invoice to insurance might effectively be a Claim record. But if not, the invoice itself could be used as the claim. Developer note: Decide if invoices to insurance will be recorded as Invoice in system (with a flag or recipient = insurance), or if they bypass invoice and only use Claim. For simplicity, assume all billing to any payer results in an Invoice in this module (ensuring consistent handling of payments via Payment Reconciliation). -- **Reminders/Overdue:** If an invoice remains unpaid past its due date, the system might flag it as overdue. It might trigger reminders or follow-ups. (This is more workflow after issuance: e.g., the UI could show a red “Overdue” label if today > due date and not balanced.) The status doesn’t change, but an additional field or calculation shows it’s overdue. -- **Invoice Adjustments/Credits:** If after issuing an invoice, one charge amount needs to be reduced (but not fully cancel the invoice), an approach is to add an adjustment line (negative line item) to the invoice. Some systems allow adjusting an issued invoice by adding a “- $50 adjustment: courtesy discount” and updating total. However, in strict accounting, once issued you’d rather cancel and reissue or issue a separate credit note. Implementation can vary. We mention it as an option: e.g., if a minor correction, maybe allow one to add an adjustment line in draft or require cancellation and new invoice. -- **Resending or Reissuing:** If a patient loses the invoice or an insurance needs a copy, staff can reprint the same invoice (with same number). If an invoice was lost before sending, you wouldn’t typically change its contents unless needed; you’d just send again. - -## Step-by-Step User Workflow (Invoice Creation & Management) - -**A. Creating and Finalizing an Invoice:** - -1. **Initiate Invoice Creation:** A billing staff user navigates to the **Invoices** section for a particular account. Often, on the Account page, there will be a button like **“Generate Invoice”** or **“Create Invoice”**. They click this to start the process. -2. **Select Charges to Include:** The system will gather all **billable** Charge Items on that account that have not yet been invoiced ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=towards%20patients,view%20on%20the%20performed%20services)). These charges are typically listed out for the user to review. In many cases, the default is to include all of them. If needed, the user may have options to: - - Remove certain items from this invoice (perhaps to bill them later or handle separately). - - Confirm the date range of charges (maybe the UI says “Include all charges up to today” which is common). - - If partial billing is supported, maybe the user can uncheck some items if they plan to invoice those another time. - But by default, assume all open charges for that account are going into this invoice. -3. **Review Draft Invoice Details:** The system now shows a **draft invoice** view. This will look like an invoice with line items listed, but not finalized. The user should check: - - All expected charges are present and none are missing or extra. - - Each line has correct description, quantity, and price. - - The subtotal and total calculations at the bottom seem correct. - - The invoice is being addressed to the correct party (by default, perhaps the patient or primary insurance based on account’s coverage/guarantor settings). - - The invoice date (which will default to today) and billing period (maybe from first charge date to last charge date). - - If there are any automatic adjustments or discounts (for example, if the patient has a package deal, maybe some charges zeroed out or a discount line is present). - The UI might allow editing certain fields in draft: - - Changing the **Bill To**: e.g., user could switch the recipient from insurance to patient if needed for this invoice. - - Adding a manual line item: e.g., a one-off adjustment or a service that was not captured as a Charge Item (less ideal, but some systems let you add an ad-hoc line with a description and price). - - Removing a line: unchecking or deleting it from this invoice (the charge would remain in account and could be invoiced later). - - Possibly adding a comment/note to the invoice (like “Payment plans available, contact billing” or any special message). - Typically, the line item details themselves (description, price) come from the charges and can’t be edited here except by going back to edit the Charge Item. -4. **(Optional) Save as Draft:** If the user is not ready to finalize (maybe needs supervisor approval or waiting for end of day), they can save the invoice as **Draft**. The system will save the current invoice with a temporary ID (maybe no official number yet, or a draft number). - - In draft state, the invoice is not yet considered sent. Staff can come back later, open the draft, and continue editing. - - The advantage is that the selection of charges is frozen to that draft, so new charges that come in won’t automatically jump onto that draft until it’s finalized or updated. Some systems might still allow updating the draft with newly added charges if needed. - - Draft invoices might show in an “Unissued Invoices” list for that account or in a billing worklist. They could be printed as “Pro Forma Invoice” for internal use if needed. -5. **Finalize (Issue) the Invoice:** When ready, the user clicks **“Finalize”** or **“Approve & Issue Invoice”**. A confirmation like “Once finalized, this invoice will be issued to the payer and no further edits will be possible. Continue?” might appear. On confirmation: - - The system assigns the official **Invoice Number** (if not already assigned at creation). - - Sets **Status = Issued** ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=code%20draft%20,error%20Binding%3A%20Invoice%20Status%20%28Required)). - - Records the **Issue Date** (often the current date-time). - - Locks the invoice content from further changes. - - Updates all the included charge items: marks their status to **billed** ([ChargeItem - FHIR v6.0.0-ballot2](https://build.fhir.org/chargeitem-definitions.html#:~:text=The%20current%20state%20of%20the,ChargeItem)) and links them to this invoice record (so it’s easy to find which invoice a charge went to). - - The invoice is now saved as an official record. -6. **Output the Invoice Document:** Immediately after finalizing, the system will typically prompt to **print** or **view** the invoice PDF. The user can then print it out to send by mail or hand to the patient, or it could be emailed if the system supports (with patient consent etc.). The printed invoice will show the invoice number, date, patient info, list of charges, total due, etc. - - If the invoice is to insurance, the output might be a standardized form or electronic claim — but if we treat invoice as multi-purpose, perhaps we still generate a readable invoice and separately send an electronic claim via another process. -7. **Post-Finalization UI Changes:** The invoice now appears in the account’s invoice list as an **Issued** invoice with its number and total. The charges that were on it no longer show as outstanding charges (they might move to a “Billed charges” section or simply not appear in the add-charge list anymore). The account’s balance might still remain the same until payment comes, but now that balance is associated with an issued invoice. - - If the invoice was to insurance, perhaps the account might show “Pending Insurance: $X” to differentiate that portion. - - The user can still open and view the invoice details, but all fields will be read-only, and a big “Status: Issued” label is shown. - - The user might see options like “Record Payment” or “Cancel Invoice” now available for that invoice. - - An example workflow for creating an invoice is illustrated above. It begins with selecting an account and gathering all unbilled charges into a draft invoice for review. The user can save it as a draft if it’s not ready to issue, or finalize it to mark it as issued. Once issued, the invoice is considered outstanding for payment. *Figure: Creating and issuing an invoice (UI workflow).* - -**B. Canceling an Invoice (Voiding a bill):** - -1. **Locate the Issued Invoice:** If an invoice needs cancellation (e.g., it was generated with incorrect information or patient decided on a different payment route before paying), the user finds that invoice in the system. Only **Issued** (or possibly Draft) invoices can be cancelled. If it’s draft, they might simply delete the draft. If issued, proceed with cancellation. -2. **Cancellation Action:** Click **“Cancel Invoice”** (sometimes shown as “Void” or “Delete Invoice” depending on terminology, but it should preserve record ideally). The system will likely prompt for a **Cancellation Reason** (a required input). The user provides an explanation like “Charges incorrect – will reissue” or selects a reason code (if predefined reasons). -3. **Confirm Cancellation:** On confirmation, the system: - - Sets the invoice status to **Cancelled** ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=code%20draft%20,error%20Binding%3A%20Invoice%20Status%20%28Required)). - - Stores the cancellation reason text ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=%3CcancelledReason%20value%3D%22%5Bstring%5D%22%2F%3E%3C%21,cancellation%20of%20this%20Invoice)). - - Possibly updates an “Cancelled Date”. - - Crucially, it must **unlock the charges** that were on this invoice: those charge items should be marked back from billed to their prior state (usually back to **billable**, as they haven’t truly been paid or anything). This allows them to be included on a new invoice later. - - If any payments had somehow been applied to this invoice (which is unlikely if we cancel early; but suppose a partial payment was recorded), the system should warn or prevent cancellation until that is resolved (the payment would need to be unlinked or refunded). - - The invoice record remains in the system for audit, but is tagged as cancelled and should not appear as an active receivable. -4. **Post-Cancellation Outcome:** The account will now show those charges as unbilled again. The cancelled invoice might be visible in an invoice history list (marked clearly as cancelled, maybe with a strikethrough or red status). It might not count towards any financial totals except in audit reports. If printed, the invoice would typically not be used, but if needed, it might have a watermark “VOID”. -5. The user can now correct whatever was wrong (maybe fix some charge items, or combine into a single invoice differently) and then create a new invoice as per steps above. - -**C. Recording a Payment for an Invoice:** - -*(Detailed payment workflows are covered in the Payment Reconciliation section, but from an invoice user’s perspective:)* -- A user can select an issued invoice and choose **“Record Payment”** if a patient pays or an insurance EOB comes in. This usually pre-fills the invoice details into the payment entry form (so it knows which invoice to credit). The steps then align with the Payment Reconciliation process (enter amount, method, etc.). Once a payment is saved: - - The invoice screen will update to show payments applied (like listing a payment of $100 on date X, possibly reducing “amount due”). - - If the full amount gets paid, the invoice status might update to **Balanced** automatically, and perhaps a “Paid in full on [date]” note is shown. - - If partially paid, the status stays Issued, but maybe a “Balance remaining: $Y” is displayed. -- The invoice could also be marked balanced by the system when a Payment Reconciliation covering its full amount is finalized. - -**D. Viewing and Managing Invoices:** - -- On the account page, staff can see all invoices associated with that account: - - **Drafts:** listed separately maybe, to differentiate from issued ones. - - **Issued:** with status, number, date, amount, outstanding balance. - - **Balanced (Paid):** might be filtered out or marked as paid. - - **Cancelled:** likely either hidden by default or shown in an archive list. -- They can click on any invoice to open details. For issued ones, they can reprint or see payment history. For drafts, they can edit or continue processing. -- The system might allow searching all invoices in the system by number, patient, or status (for billing office overview). For example, a billing manager might list all “Unpaid Invoices over 60 days” to follow up. -- If the HMIS supports integration, an invoice might have an option like “Submit Claim” if sending to insurance electronically (which could change status to something like “Submitted” in an extended workflow, but in basic terms it’s still issued from provider side). - -In summary, from a staff perspective, generating an invoice is a guided process where the system pulls in charges, the user reviews, and then the invoice is finalized and sent out. The system tracks its status through payment and closure. - -## Developer Notes (Invoice Processing & Integration) -- **Invoice Generation Logic:** When the user initiates an invoice creation, implement logic to fetch all eligible charges: - - Query the ChargeItem table for all records linked to the account with status = billable (and possibly any additional criteria, like within certain date if partial billing by date). - - If an account can have multiple draft invoices concurrently (probably not typical), decide how to handle allocation of charges between them. Usually, one invoice at a time per account to avoid confusion. - - Once charges are selected for an invoice, mark them in some way (perhaps lock them or mark as "invoicing in progress") to prevent them being scooped up by another invoice process or accidentally double-charged. -- **Draft State Persistence:** When saving a draft invoice: - - Store which charges are associated with it (maybe a join table InvoiceLine linking invoice draft to charge items). - - Do not yet modify the charge item status; only do that on final issue. - - Possibly generate a temporary ID. You might use a separate sequence for invoice numbers vs draft IDs. Some implementers use negative IDs or a prefix for drafts. Alternatively, treat draft similarly but mark status = draft and number = null or "DRAFT". -- **Invoice Number Generation:** Ensure invoice numbers are unique and sequential or follow required format. This likely happens at finalize. Consider concurrency: two users finalizing different invoices at same time should get different numbers without conflict. A robust approach is to have a transaction-safe sequence in the database. -- **Status Transitions & Enforcement:** - - Only allow moving from Draft -> Issued, Issued -> Balanced (via payment), Issued -> Cancelled, Issued -> (possibly entered-in-error), and Balanced -> (maybe allow cancel if a mistake but usually once paid you wouldn’t cancel). - - Do not allow editing content when status is Issued or Balanced. - - If someone tries to cancel a balanced (paid) invoice, either block it or require first reversing the payments. -- **Linking Charges to Invoice:** When finalizing: - - Update each charge: set status to billed, and optionally add a reference to invoice ID on the charge record (if you want quick backward links). FHIR doesn’t explicitly have an invoice reference on ChargeItem, but nothing prevents an extension or a search by account+status. Many implementations will put an “invoiceId” field in charge for convenience. - - Conversely, create invoice line entries that reference the original charge IDs (so you can trace from invoice line back to charge details if needed). - - Once that’s done, future attempts to invoice those same charges should find them as already billed and skip them. -- **Printing/Formatting:** Generate an invoice document (PDF/printout) with a clear layout. Possibly include hospital logo, address, invoice number, patient details, list of charges (with maybe codes or dates), total, and payment instructions. If multiple languages or localization is needed, design templates accordingly. -- **Partial Invoice Selection:** If supporting partial selection in UI, ensure the backend can handle arbitrary subsets. The UI might pass specific charge IDs to include/exclude. The default can be “all billable charges now”. -- **Payment Tracking on Invoice:** - - Maintain a field for amountPaid on invoice, updated whenever a payment is applied. This can make checking fully paid easy (amountPaid vs total). - - Or calculate it by summing PaymentReconciliation allocations referencing that invoice each time (slower but single source of truth). - - Possibly maintain amountDue = total - amountPaid. - - When amountDue reaches 0, auto-set status to Balanced. This could be done via a trigger when posting payments or explicitly in payment application code. -- **Automating Status Balanced:** For safety, one might only mark Balanced when explicitly triggered (like after recording a payment covering full amount). But also consider edge case: if an invoice is $100 and two different payments $60 and $40 are applied at different times, after second payment, code should detect total paid equals invoice total and then set Balanced. This means the Payment Reconciliation process needs to check the invoice’s amounts or sum payments so far. - - Alternatively, provide a batch job that scans invoices for fully paid ones and marks them balanced, if synchronous updates are tricky. -- **Cancelling Invoice Implementation:** - - Ensure atomicity: update invoice status, free up charges (set them to billable) within one transaction. If any part fails, roll back all, to avoid stranded charges (e.g., invoice cancelled but charges not restored). - - If a charge had been partially paid (rare scenario, but maybe they paid something before cancellation), you may either not allow cancel or if allowed, handle that: possibly keep the payment but without an invoice? That’s messy — better to not cancel in that case or require refund. Usually, one wouldn’t cancel after payment; instead would issue a correcting credit. - - Mark the invoice number as cancelled in case numbering needs to skip or reuse? Typically, do not reuse numbers – even cancelled invoice keeps its number. -- **Reissuing after Cancel:** The same charges can now go to a new invoice. That new invoice might get a new number. Optionally, you could link the new invoice to the old cancelled one for reference (not required but could be useful context). -- **Multiple Payers (Insurance then Patient):** If the workflow includes insurance, consider: - - Possibly generating an invoice to insurance (with status maybe stays issued until insurer responds, then PaymentRec comes in). After insurer pays or denies certain items, the remaining can be billed to patient. There are a couple of approaches: - - Create separate invoices: one for insurance, one for patient balance. If doing so, one must split the charges or amounts accordingly. - - Or one invoice listing insurance portion and patient portion (less common, usually separate statements). - - A simpler approach: treat the insurance claim outside of Invoice; only use Invoice for patient billing after insurance. But since the spec mentions PaymentReconciliation referencing invoices ([PaymentReconciliation - FHIR v6.0.0-ballot2](https://build.fhir.org/paymentreconciliation.html#:~:text=the%20individual%20payment%20amounts%20indicated,or%20%2031%20for%20example)), one can indeed track insurance payments against an invoice too. - - Perhaps an invoice is always ultimately to the patient/guarantor, and insurance is handled by Claim. However, openIMIS and others seem to use Invoice for insurance too. Decide based on requirement. - - Developers might need to incorporate logic: If account has insurance, maybe don’t invoice patient until insurance results are back; or generate an invoice but mark it as to insurance (which in effect is like a claim). - - For our documentation, we haven’t deeply distinguished, so implementation can vary. -- **Overdue & Reminders:** Could implement a job to mark invoices as overdue if current date > issue date + terms and status still issued (not balanced). This might trigger notifications or at least a visible flag. Not mandatory but typical in real systems. -- **Invoice Adjustments:** If the system allows editing an invoice after issuance by adding an adjustment line: - - That effectively changes the total. If the invoice was $100 and you add a -$10 line, total becomes $90. One must ensure consistency: the underlying charge items still sum to $100, but invoice says $90 due. In accounting, that -$10 should be recorded as a write-off or discount entry somewhere. - - Possibly better to avoid mid-flight changes and instead handle via PaymentReconciliation (like enter a $10 adjustment as a PaymentReconciliation of type adjustment). - - Simpler: do not allow adding lines post-issue; require cancel and reissue if changes needed. That keeps invoice = sum of its charges strictly. -- **Query by Account/Status:** Implement convenient queries: - - Find all invoices for an account (for account view). - - Find all unpaid invoices for accounts, etc. - - Ensure that when retrieving account balance via account, you consider partially paid invoices correctly (i.e., you might sum all charges - payments; or sum all invoice totals - payments). - - Might double count if not careful: maybe simpler to rely on charges and payments at account level, ignoring invoices for balance calc, as FHIR suggests. -- **Integration with PaymentReconciliation:** The FHIR invoice resource references PaymentReconciliation ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=8,Resource)). In implementation: - - When a PaymentReconciliation is created (payment posted), allow linking which invoices it covers. If one payment covers multiple invoices, all those should be updated. - - PaymentReconciliation might itself store invoice references in its details, or you have a join table. - - Ensure partial payments update invoice record (either store remaining balance or track via PaymentReconciliation records). -- **Security & Roles:** Limit who can cancel or edit issued invoices (maybe only supervisors). Normal clerks might only record payments. This can prevent malicious or erroneous cancellations of valid bills. -- **FHIR API Note:** If exposing these as FHIR: - - The Invoice resource in FHIR R5 is still trial but has similar fields. Use the same statuses (draft, issued, balanced, cancelled, entered-in-error) ([Invoice - FHIR v6.0.0-ballot2](https://build.fhir.org/invoice.html#:~:text=code%20draft%20,error%20Binding%3A%20Invoice%20Status%20%28Required)) to maintain compatibility. - - PaymentReconciliation and Invoice linking should conform to FHIR (e.g., PaymentReconciliation.detail might point to Invoice). - - For now, internal workings can be done without strictly following all FHIR mechanics, but keep in mind for future interoperability. -- **Testing Scenarios:** - - Create invoice when no charges exist (system should not allow or show a message “No billable items to invoice”). - - Create multiple invoices sequentially as new charges come in (one at discharge, then a supplemental later). - - Cancel after partial payment, see what happens. - - Ensure a balance invoice cannot be cancelled or edited. - - Large invoices (many lines): test performance of rendering and summing. -- **Edge Case - Account with zero charges:** If for some reason an invoice is needed for a zero amount (maybe just to close out?), decide if allowed or skip since it’s pointless. Usually no invoice if nothing to bill. -- **Linking invoice to account balance:** Possibly update account’s notion of outstanding receivable. But since account balance can be derived from charges minus payments (not caring how many invoices), you may not need a separate field. The account could optionally track total invoiced vs not invoiced. -- **Open/Closed Accounting Periods:** In some hospital billing, once an account is discharged, they want all charges on one final bill. Late charges pose a problem. The system might allow generating another invoice for late charges or require managerial approval to add charges to a closed account. We touched on that. Implementation should allow invoicing any charges that appear later even if account was inactive (maybe temporarily reactivate or allow invoice generation even if account inactive but has unbilled charges). \ No newline at end of file +- **Invoice for Insurance vs Patient:** If insurance is involved, an initial invoice might be created to send to the insurer (or an electronic claim, depending on integration). After insurer pays or responds, a secondary invoice (often called patient statement) might be created for the patient for any remaining amount. In our HMIS, the Invoice module could handle both by marking who it’s addressed to. For instance, invoice #100 to Insurance (for full charges) and after insurance adjustments, an invoice #101 to patient for copay/deductible. +- **Invoice Adjustments/Credits:** If after issuing an invoice, one charge amount needs to be reduced (but not fully cancel the invoice), an approach is to add an adjustment line (negative line item) to the invoice.(How to do it?) From 18ed2551a3f4ded1dad01102066a29af820802f8 Mon Sep 17 00:00:00 2001 From: Bodhish Thomas Date: Wed, 30 Apr 2025 23:08:22 +0530 Subject: [PATCH 06/13] Update payments --- .../HMIS/Billing/PaymentReconciliation.md | 321 ++++++++---------- 1 file changed, 149 insertions(+), 172 deletions(-) diff --git a/docs/care/HMIS/Billing/PaymentReconciliation.md b/docs/care/HMIS/Billing/PaymentReconciliation.md index 41291ce..28d3287 100644 --- a/docs/care/HMIS/Billing/PaymentReconciliation.md +++ b/docs/care/HMIS/Billing/PaymentReconciliation.md @@ -1,66 +1,159 @@ # Payment Reconciliation -## Summary -The **Payment Reconciliation** module is responsible for recording payments (and adjustments) that the hospital receives and matching them to the corresponding invoices or accounts. In essence, it’s how the system knows an invoice has been paid, and by whom and when. Each Payment Reconciliation entry represents a payment transaction and how that payment is allocated to one or more invoices or other receivables ([PaymentReconciliation - FHIR v6.0.0-ballot2](https://build.fhir.org/paymentreconciliation.html#:~:text=The%20PaymentReconciliation%20resource%20provides%20the,or%20%2031%20for%20example)). This is aligned with the FHIR PaymentReconciliation resource, which “provides the details including amount of a payment and allocates the payment items being paid” ([PaymentReconciliation - FHIR v6.0.0-ballot2](https://build.fhir.org/paymentreconciliation.html#:~:text=This%20resource%20provides%20the%20details,the%20payment%20items%20being%20paid)). - -In a hospital billing context, payments can come from patients (cash, credit card, checks) or from insurance companies (bulk payments for multiple claims, often via electronic remittances or checks covering several patients). The Payment Reconciliation module must handle both scenarios: -- **Patient Payments:** e.g., a patient pays their bill at the cashier or online, which goes toward their invoice. -- **Insurance Payments:** e.g., an insurer sends a lump sum that covers multiple invoices (claims) for multiple patients, often with an explanation of benefits detailing how to split it. - -Key points: -- A Payment Reconciliation entry will have information about the payment (date, amount, method, identifier like check # or transaction ID). -- It will list one or more **allocations** – basically, references to the invoices (or accounts) that this money was applied to, along with how much of the payment went to each ([PaymentReconciliation - FHIR v6.0.0-ballot2](https://build.fhir.org/paymentreconciliation.html#:~:text=the%20individual%20payment%20amounts%20indicated,or%20%2031%20for%20example)). -- If the payment exactly matches an invoice, there will be one allocation for that invoice covering the full amount. If one payment is split, there are multiple allocations. -- Recording a payment will update the status of invoices (like marking them balanced if fully paid) and adjust account balances accordingly. -- The module should also handle reversals or cancellations of payments (for example, if a check bounces or a credit card charge is disputed, one must remove that payment). - -## Key Fields -**Key Fields:** -- **Payment Reference/Identifier:** An ID for the payment record, often the check number, transaction ID, or an internally generated receipt number. For example, “PMT-1001” or using bank ref like “CHK123456”. This helps trace the payment in case of queries. -- **Payment Date:** The date (and possibly time) when the payment was received. If a patient pays at the cashier, that’s the current date. If processing an insurance check received by mail, it might be the date on the check or the date it was processed. -- **Payment Amount:** The total amount of money received in this payment transaction. E.g., $250.00. -- **Payment Method:** How the payment was made. Common values: *Cash*, *Check*, *Credit Card*, *Bank Transfer*, *Mobile Payment*, etc. This is important for routing (e.g., checks need check numbers, credit cards have auth codes). The UI likely has a dropdown for method. -- **Payer (Source):** Who paid. If it’s a patient payment, the payer might be the patient or a family member (could have a name field). If it’s an insurance payment, the payer is the insurance company (and maybe a specific plan or reference). -- **Payee (Recipient):** Typically the hospital organization or department that received the money. Often implicit (the hospital’s name), but in multi-organization systems might be relevant (like which clinic’s bank account it went into). -- **Allocations (Applied To):** A breakdown of how the payment was applied: - - Each allocation entry might include: - - Reference to an **Invoice** (or possibly directly to an Account or Charge, but invoice is the usual granularity in our case) ([PaymentReconciliation - FHIR v6.0.0-ballot2](https://build.fhir.org/paymentreconciliation.html#:~:text=the%20individual%20payment%20amounts%20indicated,or%20%2031%20for%20example)). - - The amount of the payment applied to that invoice. - - (If integrated with insurance claims: possibly a reference to a Claim or ClaimResponse as well, but let’s assume invoice or account). - - A short note or code about the allocation, e.g., indicating if it was an adjustment or interest, etc. - - For example, a $100 insurance payment might be split: $80 to invoice 1001, $20 to invoice 1002. That means two allocation lines inside this Payment Reconciliation. - - If the payment exactly matches one invoice: one allocation of full amount to that invoice. - - If the payment is not tied to an invoice yet (like someone pre-pays before an invoice is generated), the allocation might just reference the Account (or be left unapplied temporarily, though ideally every payment ties to something). -- **Total Allocated vs Unallocated:** The sum of allocations ideally equals the payment amount. If not, then either there is an *unallocated remainder* (money received but not yet applied to any invoice) or *overallocation* (shouldn’t happen logically). For instance, insurance might send $100 but only 95 is for known invoices, 5 might be an overpayment or to be clarified. The system should track if any part of the payment isn’t allocated. -- **Status:** The status of the payment record. Likely values: **active/posted**, **cancelled**, **draft**, **entered-in-error** (following the FinancialResourceStatusCodes) ([Claim - FHIR Implementation Guide for ABDM v6.5.0 - NRCeS](https://www.nrces.in/preview/ndhm/fhir/r4/StructureDefinition-Claim.html#:~:text=Claim%20,state%20of%20the%20resource%20instance)). - - *Posted/Completed (Active):* Indicates the payment has been fully received and recorded (this is the normal state for a finalized payment). We can equate “active” to a completed payment record. - - *Draft:* If someone started entering a payment but didn’t finish (maybe awaiting confirmation), but in practice payments are usually recorded in one go, so draft might not be heavily used. - - *Cancelled/Reversed:* If the payment was voided (e.g., bounced check, or a credit card refund). Cancelled means the payment should no longer count. This typically would result in the corresponding invoices going back to unpaid. - - *Entered-in-error:* If the payment entry was a mistake (e.g., recorded twice by accident). That would also effectively remove it from balances. -- **Payment Details:** Additional info depending on method: - - If **Check**: check number, bank name. - - If **Credit Card**: maybe last 4 digits of card, transaction auth code. - - If **Transfer**: reference number, account number, etc. - - If **Cash**: maybe cashier name or location. - These might be captured in separate fields or a single notes field. -- **Notes/Comments:** Free text notes about the payment. E.g., “Patient paid $50 now, will pay rest next month” or “Insurance EOB 123456 dated 2025-04-01”. -- **Adjustment Type:** If this record also includes adjustments not actually money received (like a contractual adjustment from insurance), some systems include those as negative payment allocations or separate records. To keep it simpler, Payment Reconciliation entries should represent actual money transactions. Adjustments like write-offs can be recorded as zero-amount PaymentReconciliation with just allocations for adjustments, or as special allocation items. For now, assume payments only, but mention that insurance often comes with adjustments (insurance may pay less than billed, the difference is an adjustment that reduces invoice balance without payment). -- **Related Claim/EOB:** If tying to insurance, possibly reference to a Claim or ExplanationOfBenefit that this payment corresponds to. This helps in audit to know which claim the payment is for. Not needed in patient payments. - -**Business Logic:** +**Payment Reconciliation** records **payments** (and possibly adjustments) made toward one or more invoices or accounts. It answers: *“Who paid, how much, and which invoice(s) or account(s) does this money apply to?”* By storing a Payment Reconciliation entry each time a patient or insurer submits payment, the system can track how the invoice balances shift from unpaid to partially paid to fully settled. + +If a payment is reversed (e.g., check bounces), the Payment Reconciliation is canceled or marked in error, restoring the invoice’s outstanding amount. This ensures a complete audit trail of all financial transactions. + + +## Schema Definition +```json +{ + "id": "", // Internal Identifier + "type": "", // payment | adjustment | advance + "status": "", // active | cancelled | draft | entered-in-error + "kind": "", // e.g., "online", "online", "deposit" + "issuerType": "", // "patient" or "insurer" + "outcome": "", // queued | complete | error | partial + "facility": "", + "disposition": "", // Additional message or outcome detail + "method": "", // Payment method (cash, check, credit, etc.) + "datetime": "", // When payment was posted + "referenceNumber": "", // Check number or transaction reference + "authorization": "", // Auth code if card-based + "tenderedAmount": { "value": "", "currency": "" }, + "returnedAmount": { "value": "", "currency": "" }, + "amount": { "value": "", "currency": "" }, // Net amount posted + "target_invoice": "", // If a single-invoice payment + "account": "", // If no invoice, apply to Account + "note": "" +} +``` + +### Essential Fields + +| Field | Description | Technical Notes | +|-------|-------------|----------------| +| **id** | Internal system identifier | Primary key, auto-generated | +| **type** | Category of payment transaction | Distinguishes between payments, adjustments, and advances | +| **status** | Current state of the payment record | Controls visibility and effect on balances | +| **kind** | Payment workflow classification | Tracks channel or method of payment receipt | +| **issuerType** | Source of the payment | Distinguishes between patient payments and insurance payments | +| **outcome** | Processing result of the payment | Tracks whether payment was fully processed | +| **facility** | Reference to the healthcare facility | Location where payment was recorded | +| **method** | Payment method used | Cash, check, credit card, bank transfer, etc. | +| **datetime** | Date and time of payment | When payment was received | +| **referenceNumber** | External transaction identifier | Check number, transaction ID, etc. | +| **amount** | Payment amount | The actual amount received | +| **target_invoice** | Reference to the invoice | Invoice being paid (if applicable) | +| **account** | Reference to the billing account | Used when payment applies to account rather than specific invoice | + +### Status Values + +| Status Value | Description | System Behavior | +|--------------|-------------|----------------| +| **active** | Payment is complete and valid | Included in financial calculations | +| **cancelled** | Payment has been reversed | Excluded from balances; requires reversal processing | +| **draft** | Payment is being processed | Not yet included in financial calculations | +| **entered-in-error** | Payment recorded incorrectly | Excluded from all calculations | + +### Payment Types + +| Type | Description | Usage | +|------|-------------|-------| +| **payment** | Standard monetary transaction | Normal payments from patients or insurance | +| **adjustment** | Non-monetary balance change | Contractual adjustments, write-offs, etc. | +| **advance** | Payment before services | Pre-payments or deposits | + +### Payment Outcomes + +| Outcome | Description | Next Steps | +|---------|-------------|-----------| +| **queued** | Payment is pending processing | Requires follow-up to complete | +| **complete** | Payment fully processed | No additional action needed | +| **error** | Payment processing failed | Requires investigation and correction | +| **partial** | Payment partially processed | Remaining processing needed | + + +### Payment Kinds + +| Kind Value | Description | Usage | +|------------|-------------|--------| +| **deposit** | One-time payment deposit | Used for upfront payments or security deposits | +| **preriodic_payment** | Recurring scheduled payment | For payment plans or installments | +| **online** | Payment made through web portal | Self-service online payments | +| **kiosk** | Payment made at payment kiosk | Self-service kiosk payments | + + +### Payment Issuer Types + +| Issuer Type | Description | Usage | +|-------------|-------------|--------| +| **patient** | Payment from patient | Direct payments from patients or their representatives | +| **insurance** | Payment from insurance | Payments from insurance companies or third-party payers | + +### Payment Methods + +| Method Code | Description | Usage | +|------------|-------------|--------| +| **cash** | Cash payment | Physical currency payments | +| **ccca** | Credit card payment | Payment via credit card | +| **cchk** | Credit check | Payment via credit check | +| **cdac** | Credit/debit account | Payment via linked bank account | +| **chck** | Check payment | Payment via paper check | +| **ddpo** | Direct deposit | Payment via bank deposit | +| **debc** | Debit card | Payment via debit card | + + +## Flow +```mermaid +flowchart TD + A[Record Payment] --> B[Select Payment Type] + B --> C[Enter Payment Details] + C --> D[Select Target Invoice/Account] + + D --> E{Full or Partial Payment?} + E -->|Full Payment| F[Amount Equals Invoice Total] + E -->|Partial Payment| G[Enter Payment Amount] + F --> H[Validate Payment Details] + G --> H + + H --> I{Valid Payment?} + I -->|No| J[Fix Issues] + J --> H + I -->|Yes| K[Process Payment] + + K --> L[Create Payment Record] + L --> M[Update Invoice Status if Fully Paid] + M --> N[Update Account Balance] + + O[Reverse Payment] --> P[Locate Payment Record] + P --> Q[Enter Reversal Reason] + Q --> R[Process Reversal] + R --> S[Restore Invoice and Account Balances] + + classDef process fill:#f9f,stroke:#333,stroke-width:2px + classDef decision fill:#bbf,stroke:#333,stroke-width:2px + classDef state fill:#6f6,stroke:#333,stroke-width:2px + + class A,B,C,D,F,G,H,J,K,L,M,N,P,Q,R,S process + class E,I decision + class O state +``` + + +## Business Logic + - When a payment is recorded, the amount gets distributed to invoices: - If the user is recording a payment for a single invoice (like patient pays their bill), the system will auto-allocate full amount to that invoice (and check if it matches the invoice amount, if not, treat as partial payment). - If the payment is meant for multiple invoices (like an insurance bulk payment or patient paying multiple bills at once), the UI should allow selecting multiple target invoices and specifying amounts for each. The sum of allocations should equal the payment. - The account’s balance and each invoice’s balance need to update accordingly: subtract the paid amounts. -- If a payment fully covers an invoice, mark the invoice **balanced** (paid in full) ([OPENIMIS.FHIR.R4\Status (Invoice) - FHIR v4.0.1](https://fhir.openimis.org/ValueSet-invoice-status.html#:~:text=status%20hl7,cancelledCancelled%20the%20invoice%20was%20cancelled)). If partially, invoice remains **issued** with remaining balance. +- If a payment fully covers an invoice, mark the invoice **balanced** (paid in full). If partially, invoice remains **issued** with remaining balance. - If a payment exceeds what was due (overpayment), the system might either hold the extra as a credit on the account (unallocated) or ask the user to adjust the allocation (maybe the patient intended to pay only what was due). - Payment records can also represent **refunds or chargebacks** if negative amounts are allowed or by using cancellation: - - e.g., if a refund is given, one might record a payment with a negative amount or a separate process for refunds (some systems would record a negative payment). - We'll keep it simpler by saying to cancel or reverse the payment rather than negative entries. -- The Payment Reconciliation acts as a receipt internally. It might also produce a receipt for the patient at point of sale: e.g., printing a “Payment Receipt” acknowledging their payment and listing what it was for. -- For insurance, one Payment Reconciliation might cover many accounts, so it’s not tied to one account like invoices are. This module must be able to cross-reference multiple accounts/invoices in one go. -- The module also likely handles **adjustments** from insurance (like contractual adjustments where the hospital agrees not to charge the difference). These might be recorded as a special kind of allocation (with no actual payment but reduces invoice balance). Some systems treat that as part of the insurance payment posting process. We can consider that an “allocation” that doesn’t correspond to received money but an adjustment amount. -- Ensuring that after posting all payments, any remaining balance on an invoice is correctly represented (which might then be billed to patient or written off). +- The Payment Reconciliation acts as a receipt internally. +- The module also handles **adjustments** from insurance. These might be recorded as a special kind of allocation (with no actual payment but reduces invoice balance). +- Ensuring that after posting all payments, any remaining balance on an invoice is correctly represented. - Payments should update the **Account** as well: since account balance is charges minus payments, adding a payment will reduce the account’s balance. - If a Payment Reconciliation is cancelled (like a bounced check), the system should re-open those invoice balances: - The invoice status goes back from balanced to issued if it was fully paid by that payment. @@ -69,61 +162,7 @@ Key points: - There should be integrity: you shouldn’t be able to apply more money to an invoice than its amount (except if intentionally overpay, which then needs handling like credit). - Payment Reconciliation records also help in reconciling with bank deposits (each day’s cash, check, credit totals). So you might have reports grouping payments by date/method for bank reconciliation. -## Step-by-Step User Workflows (Payment Posting) - -**Recording a Patient Payment (Single Invoice, typical scenario):** -1. **Access Payment Screen:** The billing staff (or cashier) goes to record a payment. They might do this either from: - - The **Invoice** view: e.g., viewing an issued invoice and clicking a “Record Payment” button on that screen (which will start a payment entry form linked to that invoice). - - Or from a general **Payments** module: e.g., a “New Payment” function where they then search for the patient or invoice to apply it to. - In either case, assume we have an invoice reference or at least an account/patient context. -2. **Enter Payment Details:** A form appears to input payment data: - - ****Recording a Patient Payment (Single Invoice, typical scenario continued):** -2. **Enter Payment Details:** A form appears to input the payment data: - - **Invoice/Account Selection:** If not already pre-filled, the user selects which **Invoice** or **Account** the payment is for. (If they started from an invoice, this will be locked to that invoice). - - **Amount:** Enter the payment amount (e.g., the patient is paying $200). - - **Method:** Select the payment method (e.g., Cash, Credit Card, Check). Depending on choice, additional fields may appear (for check: check number; for card: transaction ID or last 4 digits). - - **Date:** Defaults to today. They can adjust if recording a payment that was received on a different date. - - **Payer Name:** By default the patient’s name might fill in. The staff can adjust if, say, a family member is paying on the patient’s behalf or if an insurance payment is being entered here (then would be the insurance name). - - **Reference/Notes:** Enter any reference number or note. For example, for a check: input the check # and bank name; for credit card: an authorization code or receipt number. Notes could include “Partial payment, patient will pay rest later” or any relevant remark. - - If the payment is less than the full invoice amount, some systems allow indicating if it’s an installment vs full settlement. Usually, just recording the amount is enough; the remaining balance will be tracked on the invoice. -3. **Apply Payment (Allocation):** Since this scenario is a single invoice, the system will allocate the entire amount to that invoice by default. The user should see something like “Apply $200 to Invoice #1234 (Total due $500).” They could adjust the allocation if they intend to split between multiple invoices (see multi-invoice scenario). Here, assume it’s just this one invoice. - - The form might show the invoice’s outstanding amount as a reference, e.g., “Invoice #1234 – Outstanding $500. Payment $200 will leave $300 remaining.” This helps the cashier confirm the amount. - - If the user accidentally entered more than outstanding (e.g., $600 on a $500 bill), the system should warn or require confirmation that this will result in an overpayment/credit. -4. **Save/Post Payment:** The user submits the payment. The system validates: - - Amount > 0 (for a payment). - - Required fields (method, etc.) are provided. - - Allocations sum to total amount (here trivial single allocation). - - If method is check or card, ensure reference info is entered. - - If all good, the system creates a **Payment Reconciliation** record representing this payment. - - It also updates the relevant invoice’s records: adds this payment allocation under that invoice. -5. **System Response:** After saving: - - The invoice’s status/fields update. If the invoice is now partially paid (not fully covered), it remains **Issued** but might show “Paid $200, Remaining $300”. If the payment covered the invoice fully (say the patient paid $500 on a $500 invoice), the system would mark that invoice as **Balanced (Paid in Full)** automatically ([OPENIMIS.FHIR.R4\Status (Invoice) - FHIR v4.0.1](https://fhir.openimis.org/ValueSet-invoice-status.html#:~:text=status%20hl7,cancelledCancelled%20the%20invoice%20was%20cancelled)). - - The account’s overall balance is reduced by $200 as well (since a payment was applied). - - The Payment record is now stored and can be viewed in the Payments module or under that account’s payment history. - - The UI likely displays a confirmation message “Payment of $200 recorded.” Often, it will also prompt to **print a receipt** for the patient. -6. **Receipt Printing:** The staff can print a **Payment Receipt** which typically includes: Hospital name, receipt number, date, patient name, amount paid, method, reference (check # etc.), invoice number it was applied to, and remaining balance if any. This is given to the patient as proof of payment. -7. **Ending Transaction:** The user’s workflow for that payment is done. If the patient only paid part, they might schedule another payment later. The invoice will remain open with the remaining balance. If paid in full, the invoice is closed out. - -**Recording a Bulk/Insurance Payment (Multiple invoices scenario):** -This is more complex, typically done by billing staff when reconciling an insurance remittance or when a patient pays multiple bills in one go. -1. **Initiate Bulk Payment:** In the Payments module, user chooses **“New Payment – Multiple Invoices”** (could be the same form but allows multiple allocations). If it’s an insurance payment, the user might input the insurance company name as the payer. -2. **Enter Total Amount and Method:** For example, an insurance sends a check of $1000 that covers 3 patients. The staff enters $1000, method “Check”, check #, date, payer “ABC Insurance Co.”. -3. **Select Invoices and Allocate:** The user then adds allocation lines for each portion: - - They might have a list or search to add invoices by number or patient name. For each invoice they add, they enter how much of the $1000 goes to that invoice. - - E.g., Invoice #1001: $400, Invoice #1005: $500, Invoice #1010: $100 (these sum to $1000). - - The system could help by showing each invoice’s outstanding amount and not allowing allocation more than due. If an invoice is due $500 and user tries $600, give error or highlight. - - If the insurance short-paid an invoice (allowed by contract), the allocation could be less than full amount, leaving some balance. Possibly the staff would then immediately record an adjustment for the remainder (maybe as another allocation line of type adjustment or they will handle that by marking that portion as insurance write-off separately). - - The UI ensures the sum of allocations equals the total payment before allowing save. -4. **Save Payment:** Once allocations are entered, the user saves. The system creates one Payment Reconciliation record of $1000, and within it, stores the details of $400 to inv #1001, $500 to #1005, $100 to #1010. -5. **System Updates:** Each invoice referenced is updated: - - Invoice #1001, #1005, #1010 get their paid amounts increased accordingly. If any hit full payment, mark them Balanced. Others remain issued with reduced balances. - - All three patients’ account balances are reduced as well. - - The Payment Reconciliation record can be retrieved later to see which invoices it covered. - - If there was a remainder not allocated (shouldn’t be if done correctly), the system might either keep the remainder as unallocated credit or not allow it in the first place. -6. **Insurance Adjustments:** If the insurance didn’t pay an invoice in full due to contract adjustments, typically the staff would also record those adjustments. This might be done by adding an allocation line of type "adjustment" for the remaining amount on that invoice (which doesn’t tie to a payment but indicates the invoice is settled). Some systems handle this by posting a separate transaction or as part of the claim response processing. For documentation: staff could, for example, mark the remaining $50 on invoice #1001 as an adjustment which zeroes out the invoice. This could be recorded as a zero-dollar Payment Reconciliation entry or a special flag on the invoice. Implementation may vary (but the result is invoice becomes balanced with $400 paid + $50 adjusted off on a $450 bill). -7. **Confirmation:** The system confirms the bulk payment entry. The staff may then move on to next payment. They often reconcile these entries with the insurance explanation of benefits to ensure correctness. - - The flowchart above outlines the payment reconciliation process. It starts when a payment is received, followed by selecting the target invoice(s) or account and entering the payment details. The payment is then allocated to the respective invoice(s). If an invoice is fully covered by the payment, it is marked as paid (balanced); if not, it remains open with an outstanding balance. Finally, a PaymentReconciliation record is saved and the payment is reflected in the system. *Figure: Workflow for recording a payment and reconciling it with invoices.* +## Payment Posting **Handling a Payment Reversal (Bounced check or error):** 1. Locate the Payment record (e.g., search by check number or patient). @@ -138,66 +177,4 @@ This is more complex, typically done by billing staff when reconciling an insura **Viewing Payment History:** - On a patient account or invoice screen, staff can see a list of payments applied. For each payment: date, amount, method, reference. If one payment covered multiple invoices, that payment might show up in each relevant account’s history (with the portion that applied). - There may also be a standalone Payment Reconciliation list (for all payments) where staff (like finance) can search by date range, method, etc., to do end-of-day reconciliation (e.g., total cash collected today). -- Reports can be generated, like “Daily Cash Collection Report” summing all payments by type, which should match actual cash in hand or bank deposits. - - -## Developer Notes (Payment Processing & Validation) -- **Data Model:** A PaymentReconciliation (PR) can be modeled with a main table (payment header) and a related table for allocations (line items): - - Payment table: id, date, amount, method, payer, status, etc. - - Payment allocation table: id, payment_id, invoice_id (or account_id), amount, type (payment or adjustment), note. - - This is a one-to-many relationship (one payment, many allocations). -- **Status Handling:** Use **FinancialResourceStatusCodes** for the payment record: *active* for completed, *cancelled* for reversed, *draft* if you allow saving incomplete, *entered-in-error* for deletion mistakes ([Claim - FHIR Implementation Guide for ABDM v6.5.0 - NRCeS](https://www.nrces.in/preview/ndhm/fhir/r4/StructureDefinition-Claim.html#:~:text=Claim%20,state%20of%20the%20resource%20instance)). -- **Atomic Allocation:** Ensure that when saving a payment with multiple allocations, the entire operation is atomic. Use transactions – if any part of applying it fails (e.g., invoice not found, or amount mismatch), roll back everything, so you don’t end up with half-applied payments. -- **Validation Rules:** - - The sum of allocation amounts must equal the payment amount (unless you allow partial allocation with remainder, but that complicates things; better to force full allocation). - - None of the allocations should allocate more than the current outstanding on that invoice. If an invoice has $300 due and user tries to allocate $350, block or auto-trim it to $300 and maybe warn about $50 remainder. - - Payment amount should generally not be 0 (except if using it to record pure adjustments, but those could be separate records or flagged). - - If method is check, ensure check number is provided; if credit card, maybe gather a transaction ID. - - The date should not be in the future (and perhaps not too far past if you want to warn, though you might back-date to when check was received). -- **Linking to Invoices/Accounts:** Ideally allocate to invoices. If a payment comes that is not specific to an invoice (say a patient gives an advance deposit), you could allow allocation to the Account without invoice. This would credit the account as a whole (like a prepayment). Later when an invoice is generated, that prepayment could be applied. Implementation: either treat it as an unallocated payment and then implement a way to apply credit to invoice, or encourage they hold money in a pseudo-invoice (some create a credit invoice). Possibly beyond current scope, but keep in mind. -- **Updating Invoice Records:** When a payment is posted: - - Update a field on Invoice for amountPaid or outstanding balance. This avoids calculating every time. Alternatively, one can compute outstanding by invoice.total - sum(payments allocated), but storing it can improve performance for lists. - - If `invoice.amountPaid >= invoice.total`, set `invoice.status = balanced`. Use `>=` to account for any slight overpayment scenario or float rounding. - - If `invoice.status` was balanced and a payment is cancelled, recalc or store the new paid amount and adjust status back if needed. -- **Updating Account Balance:** Account balance is typically computed from charges - payments. If you are not storing account balance, no update needed (just compute on the fly). If you keep a running balance, then on payment posting subtract the payment amount from the account’s balance field. -- **Receipt Generation:** Similar to invoices, provide a standardized receipt template. Could reuse invoice number or generate a separate receipt number sequence for payments. -- **Audit Trail:** Log the user who recorded each payment (and who cancels any payment). Financial transactions must be audit-logged for security. -- **Concurrent Payments:** If two payments are being applied to the same invoice concurrently (rare but possible in online systems), you must avoid race conditions. E.g., both try to pay remaining $100 at same time: - - Solutions: lock the invoice during payment allocation, or after each payment commit, check if invoice balance went negative (which indicates double payment) and handle accordingly (maybe refund one or notify staff). - - Also ensure invoice status check is up-to-date when posting. Possibly requery the invoice's latest outstanding just before saving each allocation. -- **Partial vs Full Payment Flows:** If a payment doesn’t fully pay an invoice, consider if you need to prompt the user for next steps (like scheduling or reminding about remaining). That’s more a business workflow; technically just keep invoice open with remaining amount. -- **Insurance Payment Adjustments:** Decide how to capture adjustments: - - Could allow an allocation line with no invoice but with an account reference and mark it as an adjustment (like -$X) to indicate a write-off. However, a better approach: treat adjustments as separate records (like a special Adjustment resource or use PaymentReconciliation with a different type code). - - FHIR PaymentReconciliation has a concept of detail with a `type` (payment, adjustment, advance, etc.) ([Class PaymentReconciliation - HAPI FHIR](https://hapifhir.io/hapi-fhir/apidocs/hapi-fhir-structures-r5/org/hl7/fhir/r5/model/PaymentReconciliation.html#:~:text=Code%20to%20indicate%20the%20nature,contained%2C)). You could incorporate a `type` field in allocation: e.g., type = payment or adjustment. If adjustment, maybe you allow linking to an invoice and amount that reduces its balance without actual cash. - - For simplicity, if insurer short-pays, you can directly reduce invoice total or mark something on invoice. But it's cleaner to explicitly record adjustments for transparency (so financial reports show that difference). - - Possibly implement: Payment Reconciliation entry with amount 0 and one detail of type adjustment for invoice #X of $50. But probably easier: after posting insurance payment, user records adjustments by another interface. We won't fully detail that here. -- **Unallocated Payments:** If the system allows accepting money without applying it (like patient deposits), have a way to hold that. Maybe create a PaymentReconciliation with no invoice allocation yet (store it with a flag or temp account). Later, when an invoice is available, allow applying that credit. This is advanced; many HMIS simply apply to an invoice or create an invoice for deposit. -- **Balance Forward / Credits:** If a patient overpays and has a credit, you might either keep the credit on account or refund it. If keeping on account, you could leave a PaymentReconciliation with an unallocated portion or apply it to a special "credit invoice". Alternatively, track a negative balance on account. This area can be complex; a straightforward approach is to avoid overpayments (or treat them as prepayments for next bill). -- **Search and Reports:** Provide ability to search payments by: - - Date range (for daily closeouts). - - Method (for reconciling with bank statements, e.g., sum of all check payments vs sum of bank deposits). - - Payer (find all payments by a certain insurance or patient). - - Invoice or account (show all payments that hit a specific bill). -- **Security:** Payments involve money, so ensure only authorized roles can record or cancel payments. Possibly require dual approval for cancellations above a threshold. -- **Notifications:** Optionally, trigger notifications. E.g., when a big payment is recorded or when an invoice gets fully paid, perhaps notify relevant staff or thank patient via email, etc. -- **Integration with Accounting:** Payment records might be exported to a general ledger. For example, daily totals for cash, etc., might flow to finance. If required, categorize transactions by type for GL mapping. -- **Integration with External Systems:** If using an online payment portal, those could feed into Payment Reconciliation entries automatically. The design should accommodate creation of payments via API or automated process in addition to manual UI entry. -- **FHIR Consideration:** A PaymentReconciliation in FHIR often corresponds to an insurer’s bulk payment with allocations to claims ([PaymentReconciliation - FHIR v6.0.0-ballot2](https://build.fhir.org/paymentreconciliation.html#:~:text=The%20PaymentReconciliation%20resource%20provides%20the,or%20%2031%20for%20example)). Our usage extends it to patient payments as well. If mapping to FHIR: - - Use `PaymentReconciliation.detail` for allocations with reference to `Invoice` (FHIR allows Invoice reference here since R5). - - Status mapping: posted vs cancelled as discussed. - - The payer could map to PaymentReconciliation.organization or request/response references, though FHIR might not have a direct field for payer name (in FHIR they often assume PaymentReconciliation from insurer implies the insurer is payer). - - Might also consider using `PaymentNotice` resource in cases where needed, but for internal HMIS, PaymentReconciliation is enough. -- **Testing:** - - Test single invoice payment, check invoice status and balance. - - Test underpayment, ensure remainder is correct. - - Test overpayment scenario, see how system behaves (should ideally flag). - - Test multi-invoice allocation: totals match, each invoice updated. - - Test cancellation: invoice balances restored. - - Test concurrency: two payments at once on same invoice (simulate if possible). - - Edge: Payment amount = 0 or negative (shouldn’t be allowed except perhaps negative for refunds, which we handle via cancellation instead). -- **User Feedback:** If a user tries to record a payment and the invoice is already balanced, block it (“Invoice already paid”) to prevent confusion. -- **Linking to Patient Account:** After a payment, you might update some summary on patient account like “Last Payment: $X on [date]”. Not essential but user-friendly. -- **Partial Refunds:** If a patient requests a refund for an overpayment, one way is to record a negative payment (which many systems avoid) or simply cancel part of the payment. Possibly simpler: have a “Refund” function that creates a new PaymentReconciliation with negative amount. But implementing negative amounts can complicate sum calculations. Alternatively, treat refunds as separate processes outside PaymentReconciliation. This depends on requirements; mention for completeness. - -By implementing the above, the Payment Reconciliation module will robustly handle the flow of funds in the HMIS, ensuring invoices are properly marked as paid or unpaid, and giving both staff and developers a clear view of the financial state of each account. - +- Reports can be generated, like “Daily Cash Collection Report” summing all payments by type, which should match actual cash in hand or bank deposits. \ No newline at end of file From 92a1b0b5bfb129a9a2e1404c9139756c27b53137 Mon Sep 17 00:00:00 2001 From: Bodhish Thomas Date: Wed, 30 Apr 2025 23:24:08 +0530 Subject: [PATCH 07/13] Update overview for billing --- docs/care/HMIS/Billing/Billing.md | 91 +++++++++++++++++-------------- 1 file changed, 49 insertions(+), 42 deletions(-) diff --git a/docs/care/HMIS/Billing/Billing.md b/docs/care/HMIS/Billing/Billing.md index 97a35ee..5a22a14 100644 --- a/docs/care/HMIS/Billing/Billing.md +++ b/docs/care/HMIS/Billing/Billing.md @@ -1,42 +1,49 @@ -# Billing Module - -This folder contains documentation for the **Billing** section of the HMIS (Hospital Management Information System) built with FHIR-inspired design principles. - -The goal of these documents is to help both **developers** (for integration and validation logic) and **hospital billing staff** (for understanding workflows) navigate and use the billing system effectively. - ---- - -## 📁 Documentation Structure - -| File | Description | -|------|-------------| -| `Account.md` | Explains how patient accounts are managed — including statuses, coverage, and linkage with charges and payments. | -| `ChargeItem.md` | Covers how billable services/items are posted to accounts, their status transitions, and validation rules. | -| `ChargeItemDefinition.md` | The source-of-truth catalog of all billable services and goods, with pricing, constraints, and usage rules. | -| `Invoice.md` | Workflow for generating, issuing, and managing invoices from charge items, including partial billing and cancellations. | -| `PaymentReconciliation.md` | Documentation on recording and applying payments to invoices/accounts, including bulk insurance payments. | -| `Notes.md` | Additional guidelines, clarifications, or decisions around the billing logic and implementation. | -| `Readme.md` | You are here — overview of this documentation folder. | - ---- - -## 📌 Guidelines for Use - -- **For Developers**: - - Use this to implement frontend validations, enforce backend rules, and understand field relationships and status transitions. - - Refer to flowcharts and step-by-step sections to implement the UI in sync with billing logic. - -- **For Staff and Admins**: - - Refer to individual module docs to understand workflows such as creating invoices, posting charges, reconciling payments, etc. - - Use this as a training/reference tool for new billing operators. - ---- - -## 🧭 Entry Points - -1. Start with `Account.md` — it is the anchor for billing operations. -2. Move to `ChargeItem.md` and `ChargeItemDefinition.md` to understand how charges work. -3. Review `Invoice.md` for generating bills. -4. Go through `PaymentReconciliation.md` to handle payments. - - +# Billing + +This overview provides a **big-picture** look at how billing data and workflows are organized, from recording healthcare services to collecting payments. The subsequent pages detail each component and its usage. + +## Key Billing Concepts + +1. **Charge Item Definition** + - **What it is:** The “catalog” or “tariff” of billable services and goods. Each definition includes a billing code, base price, optional surcharges/discounts/taxes, and applicability rules. + - **Why it matters:** Ensures consistent and accurate pricing logic for all services. + - **Where to learn more:** [Charge Item Definition Documentation](./ChargeItemDefinition.md) + +2. **Charge Item** + - **What it is:** A single, **actual** billable line for a specific service/product given to a patient (e.g., a lab test, medication, X-ray). + - **Why it matters:** Records each instance of care or resource usage, along with quantity, date, and final cost. + - **Where to learn more:** [Charge Item Documentation](./ChargeItem.md) + +3. **Account** + - **What it is:** A ledger or “billing bucket” that accumulates all charges and payments for a patient or purpose (e.g., an inpatient stay). + - **Why it matters:** Centralizes the financial tracking, letting you see what the patient (or insurance) owes in total. + - **Where to learn more:** [Account Documentation](./Account.md) + +4. **Invoice** + - **What it is:** A formal bill grouping multiple **Charge Items** from an **Account**. Once **issued**, the system expects payment against it. + - **Why it matters:** Creates an official statement for patients or insurers, facilitating payment collection. + - **Where to learn more:** [Invoice Documentation](./Invoice.md) + +5. **Payment Reconciliation** + - **What it is:** A record of payments received (and how they’re allocated to invoices). Also handles reversals (e.g., bounced checks). + - **Why it matters:** Keeps a detailed audit trail of all money flows, from partial payments to full settlements. + - **Where to learn more:** [Payment Reconciliation Documentation](./PaymentReconciliation.md) + +## High-Level Billing Flow + +Below is a simplified look at how these pieces fit together: + +```mermaid +flowchart LR + A[Charge Item Definition
Price Catalog] --> B[Charge Item
Specific Billable Service] + B --> C[Account
Ledger for Charges/Payments] + C --> D[Invoice
Formal Bill Summarizing Charges] + D --> E[Payment Reconciliation
Payments Applied to Invoice] + E --> F[Account Updated
Balance Reduced ] +``` + +1. **Charge Item Definition**: Administrators configure pricing rules and codes. +2. **Charge Item**: When a service is provided, a charge is created for the patient’s **Account**, with cost details derived from the definition. +3. **Account**: Aggregates all patient charges and payments. +4. **Invoice**: Groups outstanding charges into a final bill. Once issued, the charges become billed. +5. **Payment Reconciliation**: Records any incoming payment, updating the invoice and account balances accordingly. From 8234a3ab2ad1e916bbbdc2d0e5dab1992143e087 Mon Sep 17 00:00:00 2001 From: Bodhish Thomas Date: Wed, 30 Apr 2025 23:31:20 +0530 Subject: [PATCH 08/13] Remove .md from links --- docs/care/HMIS/Billing/Billing.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/care/HMIS/Billing/Billing.md b/docs/care/HMIS/Billing/Billing.md index 5a22a14..1e5449c 100644 --- a/docs/care/HMIS/Billing/Billing.md +++ b/docs/care/HMIS/Billing/Billing.md @@ -7,27 +7,27 @@ This overview provides a **big-picture** look at how billing data and workflows 1. **Charge Item Definition** - **What it is:** The “catalog” or “tariff” of billable services and goods. Each definition includes a billing code, base price, optional surcharges/discounts/taxes, and applicability rules. - **Why it matters:** Ensures consistent and accurate pricing logic for all services. - - **Where to learn more:** [Charge Item Definition Documentation](./ChargeItemDefinition.md) + - **Where to learn more:** [Charge Item Definition Documentation](./ChargeItemDefinition) 2. **Charge Item** - **What it is:** A single, **actual** billable line for a specific service/product given to a patient (e.g., a lab test, medication, X-ray). - **Why it matters:** Records each instance of care or resource usage, along with quantity, date, and final cost. - - **Where to learn more:** [Charge Item Documentation](./ChargeItem.md) + - **Where to learn more:** [Charge Item Documentation](./ChargeItem) 3. **Account** - **What it is:** A ledger or “billing bucket” that accumulates all charges and payments for a patient or purpose (e.g., an inpatient stay). - **Why it matters:** Centralizes the financial tracking, letting you see what the patient (or insurance) owes in total. - - **Where to learn more:** [Account Documentation](./Account.md) + - **Where to learn more:** [Account Documentation](./Account) 4. **Invoice** - **What it is:** A formal bill grouping multiple **Charge Items** from an **Account**. Once **issued**, the system expects payment against it. - **Why it matters:** Creates an official statement for patients or insurers, facilitating payment collection. - - **Where to learn more:** [Invoice Documentation](./Invoice.md) + - **Where to learn more:** [Invoice Documentation](./Invoice) 5. **Payment Reconciliation** - **What it is:** A record of payments received (and how they’re allocated to invoices). Also handles reversals (e.g., bounced checks). - **Why it matters:** Keeps a detailed audit trail of all money flows, from partial payments to full settlements. - - **Where to learn more:** [Payment Reconciliation Documentation](./PaymentReconciliation.md) + - **Where to learn more:** [Payment Reconciliation Documentation](./PaymentReconciliation) ## High-Level Billing Flow From 374e2d37f5d3a56aec8bf57ab8be041e33f47d89 Mon Sep 17 00:00:00 2001 From: Bodhish Thomas Date: Thu, 22 May 2025 10:47:17 +0530 Subject: [PATCH 09/13] Added Labs, Schedule, Pharmacy docs --- docs/care/HMIS/Billing/Account.md | 128 +++++++++--------- docs/care/HMIS/Billing/Billing.md | 46 ++++--- docs/care/HMIS/Labs/ActivityDefinition.md | 81 +++++++++++ docs/care/HMIS/Labs/ChargeItemDefinition.md | 101 ++++++++++++++ docs/care/HMIS/Labs/DiagnosticReport.md | 48 +++++++ docs/care/HMIS/Labs/ObservationDefinition.md | 71 ++++++++++ docs/care/HMIS/Labs/README.md | 38 ++++++ docs/care/HMIS/Labs/ServiceRequest.md | 56 ++++++++ docs/care/HMIS/Labs/Specimen.md | 30 ++++ docs/care/HMIS/Labs/SpecimenDefinition.md | 88 ++++++++++++ docs/care/HMIS/Pharmacy/ChargeItem.md | 72 ++++++++++ .../HMIS/Pharmacy/ChargeItemDefinition.md | 66 +++++++++ docs/care/HMIS/Pharmacy/InventoryItem.md | 67 +++++++++ docs/care/HMIS/Pharmacy/MedicationDispense.md | 109 +++++++++++++++ docs/care/HMIS/Pharmacy/MedicationRequest.md | 77 +++++++++++ docs/care/HMIS/Pharmacy/Product.md | 68 ++++++++++ docs/care/HMIS/Pharmacy/ProductKnowledge.md | 90 ++++++++++++ docs/care/HMIS/Pharmacy/README.md | 41 ++++++ docs/care/HMIS/Pharmacy/SupplyDelivery.md | 74 ++++++++++ docs/care/HMIS/Pharmacy/SupplyRequest.md | 75 ++++++++++ .../HMIS/Scheduling/AvailabilityException.md | 8 ++ docs/care/HMIS/Scheduling/Encounter.md | 59 ++++++++ docs/care/HMIS/Scheduling/README.md | 47 +++++++ .../Scheduling/SchedulableUserResource.md | 32 +++++ docs/care/HMIS/Scheduling/Schedule.md | 11 ++ docs/care/HMIS/Scheduling/TokenBooking.md | 17 +++ docs/care/HMIS/Scheduling/TokenSlot.md | 3 + .../HMIS/Billing/Billing Concept Diagram.svg | 1 + .../care/HMIS/Labs/Labs Concept Diagram.svg | 1 + .../Pharmacy/Pharmacy Concept Diagram.svg | 1 + .../Scheduling/Scheduling Concept Diagram.svg | 1 + 31 files changed, 1526 insertions(+), 81 deletions(-) create mode 100644 docs/care/HMIS/Labs/ActivityDefinition.md create mode 100644 docs/care/HMIS/Labs/ChargeItemDefinition.md create mode 100644 docs/care/HMIS/Labs/DiagnosticReport.md create mode 100644 docs/care/HMIS/Labs/ObservationDefinition.md create mode 100644 docs/care/HMIS/Labs/README.md create mode 100644 docs/care/HMIS/Labs/ServiceRequest.md create mode 100644 docs/care/HMIS/Labs/Specimen.md create mode 100644 docs/care/HMIS/Labs/SpecimenDefinition.md create mode 100644 docs/care/HMIS/Pharmacy/ChargeItem.md create mode 100644 docs/care/HMIS/Pharmacy/ChargeItemDefinition.md create mode 100644 docs/care/HMIS/Pharmacy/InventoryItem.md create mode 100644 docs/care/HMIS/Pharmacy/MedicationDispense.md create mode 100644 docs/care/HMIS/Pharmacy/MedicationRequest.md create mode 100644 docs/care/HMIS/Pharmacy/Product.md create mode 100644 docs/care/HMIS/Pharmacy/ProductKnowledge.md create mode 100644 docs/care/HMIS/Pharmacy/README.md create mode 100644 docs/care/HMIS/Pharmacy/SupplyDelivery.md create mode 100644 docs/care/HMIS/Pharmacy/SupplyRequest.md create mode 100644 docs/care/HMIS/Scheduling/AvailabilityException.md create mode 100644 docs/care/HMIS/Scheduling/Encounter.md create mode 100644 docs/care/HMIS/Scheduling/SchedulableUserResource.md create mode 100644 docs/care/HMIS/Scheduling/Schedule.md create mode 100644 docs/care/HMIS/Scheduling/TokenBooking.md create mode 100644 docs/care/HMIS/Scheduling/TokenSlot.md create mode 100644 static/img/care/HMIS/Billing/Billing Concept Diagram.svg create mode 100644 static/img/care/HMIS/Labs/Labs Concept Diagram.svg create mode 100644 static/img/care/HMIS/Pharmacy/Pharmacy Concept Diagram.svg create mode 100644 static/img/care/HMIS/Scheduling/Scheduling Concept Diagram.svg diff --git a/docs/care/HMIS/Billing/Account.md b/docs/care/HMIS/Billing/Account.md index e00c6b5..4b3fec4 100644 --- a/docs/care/HMIS/Billing/Account.md +++ b/docs/care/HMIS/Billing/Account.md @@ -1,7 +1,8 @@ # Account -## Summary -The **Account** module manages financial accounts that accumulate charges and payments for a patient or specific purpose (e.g. an inpatient stay or service request cost). An Account serves as a “billing bucket” or ledger for tracking healthcare costs over time. Charges (for services or items) are applied to an Account, and payments or adjustments credit the Account. In essence, it is a central record against which charges, payments, and adjustments are recorded. This allows the system to keep a running total of what a patient (or their insurance) owes. Accounts contain information about who the account is for (the patient or entity) and who is responsible for paying the balance (such as insurance or a guarantor). *For example, when a patient is admitted, an Account is opened to track all charges during that hospitalization, and later, an invoice will be generated from this account.* +## Summary + +The **Account** module manages financial accounts that accumulate charges and payments for a patient or specific purpose (e.g. an inpatient stay or service request cost). An Account serves as a “billing bucket” or ledger for tracking healthcare costs over time. Charges (for services or items) are applied to an Account, and payments or adjustments credit the Account. In essence, it is a central record against which charges, payments, and adjustments are recorded. This allows the system to keep a running total of what a patient (or their insurance) owes. Accounts contain information about who the account is for (the patient or entity) and who is responsible for paying the balance (such as insurance or a guarantor). _For example, when a patient is admitted, an Account is opened to track all charges during that hospitalization, and later, an invoice will be generated from this account._ :::info Note for Developers The Account concept aligns with the FHIR **Account** resource, providing a tool to track values accrued for a particular purpose in healthcare billing. While an account will have a running balance conceptually, it typically does **not** store a live balance field. Instead, the current balance is computed from all associated charges and payments and cached. The system will provide a function to calculate the balance on demand by summing charges minus payments, you can use the `calculated_at` field to track when the balance was last computed and ensure data consistency. @@ -11,24 +12,24 @@ The Account concept aligns with the FHIR **Account** resource, providing a tool ```json { - "id": "", // Internal Identifier - "status": "", // active | inactive | entered-in-error | on-hold | unknown + "id": "", // Internal Identifier + "status": "", // active | inactive | entered-in-error | on-hold | unknown "billing_status": "", // Bound to https://build.fhir.org/valueset-account-billing-status.html - "name": "", // Human-readable label - "patient": "", // The entity that caused the expenses - "facility" : "", // Facility where this Account is created - "service_period": "Period", // Transaction window - "description": "", // Explanation of purpose/use + "name": "", // Human-readable label + "patient": "", // The entity that caused the expenses + "facility": "", // Facility where this Account is created + "service_period": "Period", // Transaction window + "description": "", // Explanation of purpose/use "balance": [ { - "aggregate": "", // Patient or Insurer - Bound to https://build.fhir.org/valueset-account-aggregate.html + "aggregate": "", // Patient or Insurer - Bound to https://build.fhir.org/valueset-account-aggregate.html "amount": { - "value": "", // Numerical value (with implicit precision) - "currency": "" // ISO 4217 Currency Code - } // Calculated amount + "value": "", // Numerical value (with implicit precision) + "currency": "" // ISO 4217 Currency Code + } // Calculated amount } ], - "calculated_at": "" // Time the balance amount was calculated + "calculated_at": "" // Time the balance amount was calculated } ``` @@ -36,103 +37,102 @@ The Account concept aligns with the FHIR **Account** resource, providing a tool ### Essential Fields -| Field | Description | Technical Notes | -|-------|-------------|----------------| -| **id** | Internal system identifier for the Account | Primary key, auto-generated | -| **name** | Human-readable label (e.g., "John Doe – 2025 Inpatient Stay") | Helpful for staff identification | -| **patient** | Foreign key reference to the patient | Only charges for this patient should be applied to this Account | -| **facility** | Reference to the healthcare facility | Used for organizational tracking and reporting | -| **status** | Current lifecycle state of the Account | Controls available operations (see Status section) | -| **billing_status** | FHIR-compliant billing status code | Provides additional context beyond basic status | -| **service_period** | Date range covered by the Account | Typically maps to admission/discharge dates or specific billing cycle | -| **description** | Markdown-formatted explanation of purpose | Provides additional context for staff | -| **balance** | Array of calculated balances by payer type | Segmented by responsible party (patient vs. insurer) | -| **calculated_at** | Timestamp of last balance calculation | Ensures data freshness awareness | +| Field | Description | Technical Notes | +| ------------------ | ------------------------------------------------------------- | --------------------------------------------------------------------- | +| **id** | Internal system identifier for the Account | Primary key, auto-generated | +| **name** | Human-readable label (e.g., "John Doe – 2025 Inpatient Stay") | Helpful for staff identification | +| **patient** | Foreign key reference to the patient | Only charges for this patient should be applied to this Account | +| **facility** | Reference to the healthcare facility | Used for organizational tracking and reporting | +| **status** | Current lifecycle state of the Account | Controls available operations (see Status section) | +| **billing_status** | FHIR-compliant billing status code | Provides additional context beyond basic status | +| **service_period** | Date range covered by the Account | Typically maps to admission/discharge dates or specific billing cycle | +| **description** | Markdown-formatted explanation of purpose | Provides additional context for staff | +| **balance** | Array of calculated balances by payer type | Segmented by responsible party (patient vs. insurer) | +| **calculated_at** | Timestamp of last balance calculation | Ensures data freshness awareness | ### Account Status Lifecycle -| Status Value | Description | System Behavior | -|--------|-------------|----------------| -| **active** | Account is open and operational | Allows new charges, payments, and invoice generation | -| **on_hold** | Account is temporarily suspended | Blocks new charges and invoices; requires resolution | -| **inactive** | Account is permanently closed | Prevents all new transactions; read-only mode | -| **entered_in_error** | Account was created by mistake | Excluded from billing processes and reporting | - +| Status Value | Description | System Behavior | +| -------------------- | -------------------------------- | ---------------------------------------------------- | +| **active** | Account is open and operational | Allows new charges, payments, and invoice generation | +| **on_hold** | Account is temporarily suspended | Blocks new charges and invoices; requires resolution | +| **inactive** | Account is permanently closed | Prevents all new transactions; read-only mode | +| **entered_in_error** | Account was created by mistake | Excluded from billing processes and reporting | ### Billing Status Values -| Billing Status | Description | Typical Usage | -|----------------|-------------|--------------| -| **open** | Account is actively receiving charges | Default for new accounts | +| Billing Status | Description | Typical Usage | +| -------------------------- | --------------------------------------------------- | ---------------------------------- | +| **open** | Account is actively receiving charges | Default for new accounts | | **carecomplete_notbilled** | Care is complete but billing process hasn't started | Transitional state after discharge | -| **billing** | Invoicing and payment collection in progress | Active billing cycle | -| **closed_baddebt** | Account closed due to uncollectible debt | After collection attempts failed | -| **closed_voided** | Account canceled/voided | For erroneously created accounts | -| **closed_completed** | Account fully settled and closed | After full payment received | -| **closed_combined** | Account merged with another account | After account consolidation | +| **billing** | Invoicing and payment collection in progress | Active billing cycle | +| **closed_baddebt** | Account closed due to uncollectible debt | After collection attempts failed | +| **closed_voided** | Account canceled/voided | For erroneously created accounts | +| **closed_completed** | Account fully settled and closed | After full payment received | +| **closed_combined** | Account merged with another account | After account consolidation | ### Balance Aggregate Types -| Aggregate Type | Description | Purpose | -|----------------|-------------|---------| -| **patient** | Portion of balance patient is responsible for | Track patient's direct financial responsibility | -| **insurance** | Portion of balance expected from insurance | Track expected insurance payments | -| **total** | Combined total balance | Overall account balance | - +| Aggregate Type | Description | Purpose | +| -------------- | --------------------------------------------- | ----------------------------------------------- | +| **patient** | Portion of balance patient is responsible for | Track patient's direct financial responsibility | +| **insurance** | Portion of balance expected from insurance | Track expected insurance payments | +| **total** | Combined total balance | Overall account balance | ## Business Logic Highlights + - An account can accumulate many **Charge Items** (individual billed services) over time. Each Charge Item references the Account it belongs to. The Account itself does not list every charge internally; instead, charges “point” to the account. The system can retrieve all charges linked to a given account to compute the balance or prepare an invoice. - **Adding Charges:** Only allowed on active accounts. If a user tries to add a charge to an inactive/on-hold account, the system should prevent it and alert the user. -- **Account Closure:** Typically done when the patient’s episode of care is complete and billing is finalized. The staff will mark the account as **inactive** (closed) after all invoices are issued and the balance is zero. The system might enforce that an account with outstanding balance cannot be closed. If closure is forced, it can only be done at managerial level. *(Developer note: implement a check that blocks closing an account if any unpaid invoices or unbilled charges exist.)* +- **Account Closure:** Typically done when the patient’s episode of care is complete and billing is finalized. The staff will mark the account as **inactive** (closed) after all invoices are issued and the balance is zero. The system might enforce that an account with outstanding balance cannot be closed. If closure is forced, it can only be done at managerial level. _(Developer note: implement a check that blocks closing an account if any unpaid invoices or unbilled charges exist.)_ - **On-hold Behavior:** Placing an account on hold might be used if, for example, insurance eligibility is in question or a billing dispute arises. In this state, new charges can be collected in the background but not officially billed until hold is released. The UI should visibly flag held accounts, and possibly require a note or reason for hold. ```mermaid flowchart TD A[Account Creation] --> B{Set Initial Status} B -->|Default| C[Active] - + C --> D{Account Management Options} D -->|Add Charge| E[Validate Charge] D -->|Record Payment| F[Process Payment] D -->|Generate Invoice| G[Create Invoice] D -->|Change Status| H{New Status} - + E --> E1{Is Account Active?} E1 -->|Yes| E2[Create Charge Record] E1 -->|No| E3[Error: Cannot add charge] E2 --> E4[Update Account Balance] - + F --> F1[Create Payment Record] F1 --> F2[Update Account Balance] - + G --> G1{Is Account Active?} G1 -->|Yes| G2[Generate Invoice from Charges] G1 -->|No| G3[Error: Cannot invoice] - + H -->|On-Hold| I[Verify Permission] H -->|Inactive| J[Validate for Closure] H -->|Entered-in-Error| K[Verify Admin Permission] - + I --> I1[Require Reason Note] I1 --> I2[Update Status to On-Hold] I2 --> I3[Disable Billing Actions] - + J --> J1{Is Balance Zero?} J1 -->|Yes| J2[Update Status to Inactive] J1 -->|No| J3{Manager Override?} J3 -->|Yes| J4[Update with Override Note] J3 -->|No| J5[Error: Cannot close with balance] - + K --> K1[Mark as Error] K1 --> K2[Remove from Billing] - + J2 --> L[Account Closed] J4 --> L - + classDef status fill:#f9f,stroke:#333,stroke-width:2px classDef error fill:#f66,stroke:#333,stroke-width:2px classDef success fill:#6f6,stroke:#333,stroke-width:2px - + class C,I2,J2,J4,K1 status class E3,G3,J5 error class E4,F2,G2,L success @@ -141,27 +141,31 @@ flowchart TD **Creating a New Account** Accounts can be created in two ways: + 1. Manual Creation from Patient Page 2. Automatic Creation on First Charge In both cases, the account becomes immediately available for billing operations once created. - **Handling Account Holds:** + - If an account is on hold, the UI should prominently indicate this (e.g., a banner “On Hold”). While on hold, typical billing actions might be disabled or require override: - The “Add Charge” button might be hidden or greyed out with a tooltip “Account is on hold – cannot add charges.” - The “Generate Invoice” action might be disabled as well. - To remove a hold, a staff user (often with appropriate permission) would edit the account and change status back to **active**. The system might log who removed the hold and when. **Closing an Account (End of Cycle):** + - When all charges have been billed and paid, or the patient’s treatment cycle is over, the account should be closed. To do this, staff edits the account and sets **Status = Inactive**. - The system will prompt “Are you sure you want to close this account? This action will mark the account as closed and no further charges can be added.” If confirmed, and validation passes (balance is zero, etc.), the status updates to inactive. - Once inactive, the account is essentially archived for that episode. The UI might label it as **Closed**. Staff can still view details and history, but cannot add new entries. If somehow a late charge comes in after closure, typically a new account is needed. -**Account Balance Inquiry:** +**Account Balance Inquiry:** + - At any point, staff might need to inform a patient of their current balance. The account screen’s balance is calculated from charges and payments. If the patient or billing staff want a detailed statement, they can generate an **Account Statement** (which is essentially an on-demand invoice or report of all transactions). This is usually separate from the official Invoice process, but it gives a breakdown of charges, payments, and remaining due. -**Status Transitions:** +**Status Transitions:** + - Enforce rules when updating account status: - Only allow **inactive** if balance is 0 and no pending charges. If there is a balance, return a clear error to the UI. - Only allow **on-hold** or **active** transitions for appropriate user roles. Possibly log these changes for audit. diff --git a/docs/care/HMIS/Billing/Billing.md b/docs/care/HMIS/Billing/Billing.md index 1e5449c..9aa722a 100644 --- a/docs/care/HMIS/Billing/Billing.md +++ b/docs/care/HMIS/Billing/Billing.md @@ -4,29 +4,33 @@ This overview provides a **big-picture** look at how billing data and workflows ## Key Billing Concepts -1. **Charge Item Definition** - - **What it is:** The “catalog” or “tariff” of billable services and goods. Each definition includes a billing code, base price, optional surcharges/discounts/taxes, and applicability rules. - - **Why it matters:** Ensures consistent and accurate pricing logic for all services. +1. **Charge Item Definition** + + - **What it is:** The "catalog" or "tariff" of billable services and goods. Each definition includes a billing code, base price, optional surcharges/discounts/taxes, and applicability rules. + - **Why it matters:** Ensures consistent and accurate pricing logic for all services. - **Where to learn more:** [Charge Item Definition Documentation](./ChargeItemDefinition) -2. **Charge Item** - - **What it is:** A single, **actual** billable line for a specific service/product given to a patient (e.g., a lab test, medication, X-ray). - - **Why it matters:** Records each instance of care or resource usage, along with quantity, date, and final cost. +2. **Charge Item** + + - **What it is:** A single, **actual** billable line for a specific service/product given to a patient (e.g., a lab test, medication, X-ray). + - **Why it matters:** Records each instance of care or resource usage, along with quantity, date, and final cost. - **Where to learn more:** [Charge Item Documentation](./ChargeItem) -3. **Account** - - **What it is:** A ledger or “billing bucket” that accumulates all charges and payments for a patient or purpose (e.g., an inpatient stay). - - **Why it matters:** Centralizes the financial tracking, letting you see what the patient (or insurance) owes in total. +3. **Account** + + - **What it is:** A ledger or "billing bucket" that accumulates all charges and payments for a patient or purpose (e.g., an inpatient stay). + - **Why it matters:** Centralizes the financial tracking, letting you see what the patient (or insurance) owes in total. - **Where to learn more:** [Account Documentation](./Account) -4. **Invoice** - - **What it is:** A formal bill grouping multiple **Charge Items** from an **Account**. Once **issued**, the system expects payment against it. - - **Why it matters:** Creates an official statement for patients or insurers, facilitating payment collection. +4. **Invoice** + + - **What it is:** A formal bill grouping multiple **Charge Items** from an **Account**. Once **issued**, the system expects payment against it. + - **Why it matters:** Creates an official statement for patients or insurers, facilitating payment collection. - **Where to learn more:** [Invoice Documentation](./Invoice) -5. **Payment Reconciliation** - - **What it is:** A record of payments received (and how they’re allocated to invoices). Also handles reversals (e.g., bounced checks). - - **Why it matters:** Keeps a detailed audit trail of all money flows, from partial payments to full settlements. +5. **Payment Reconciliation** + - **What it is:** A record of payments received (and how they're allocated to invoices). Also handles reversals (e.g., bounced checks). + - **Why it matters:** Keeps a detailed audit trail of all money flows, from partial payments to full settlements. - **Where to learn more:** [Payment Reconciliation Documentation](./PaymentReconciliation) ## High-Level Billing Flow @@ -42,8 +46,12 @@ flowchart LR E --> F[Account Updated
Balance Reduced ] ``` -1. **Charge Item Definition**: Administrators configure pricing rules and codes. -2. **Charge Item**: When a service is provided, a charge is created for the patient’s **Account**, with cost details derived from the definition. -3. **Account**: Aggregates all patient charges and payments. -4. **Invoice**: Groups outstanding charges into a final bill. Once issued, the charges become billed. +1. **Charge Item Definition**: Administrators configure pricing rules and codes. +2. **Charge Item**: When a service is provided, a charge is created for the patient's **Account**, with cost details derived from the definition. +3. **Account**: Aggregates all patient charges and payments. +4. **Invoice**: Groups outstanding charges into a final bill. Once issued, the charges become billed. 5. **Payment Reconciliation**: Records any incoming payment, updating the invoice and account balances accordingly. + +### Concept Diagram + +![Billing Concept Diagram](../../../../static/img/care/HMIS/Billing/Billing%20Concept%20Diagram.svg) diff --git a/docs/care/HMIS/Labs/ActivityDefinition.md b/docs/care/HMIS/Labs/ActivityDefinition.md new file mode 100644 index 0000000..b93c746 --- /dev/null +++ b/docs/care/HMIS/Labs/ActivityDefinition.md @@ -0,0 +1,81 @@ +### Summary + +In CARE, `ActivityDefinition` is used to define reusable **templates for clinical actions**, such as lab tests or medication requests. Each definition standardizes how a particular diagnostic activity should be instantiated at runtime — enabling consistent behavior across service requests and automated billing. + +Although based on the FHIR `ActivityDefinition` resource, CARE tailors it to fit real-world facility workflows, especially for diagnostic and lab use cases. In the current scope, these templates primarily support `ServiceRequest` and `MedicationRequest`. Future versions may include orchestration through `PlanDefinition` and `RequestOrchestration`. + +### Core Relationships + +| Related Resource | Purpose | +| ----------------------- | ------------------------------------------------- | +| `ServiceRequest` | Primary output when ActivityDefinition is applied | +| `ChargeItemDefinition` | Linked to define billing behavior | +| `SpecimenDefinition` | Defines required specimens for lab tests | +| `ObservationDefinition` | Specifies expected observation outcomes | + +### Supported Fields + +| Field Name | Description | Example | +| -------------------------------- | ---------------------------------------------------------------------------- | ------------------------------ | +| `id` | Internal identifier | `AD-001` | +| `version` | Versioning control for updates | `1` | +| `slug` | Unique name within a facility | `cbc-test` | +| `derived_from_url` | Source or canonical reference | `https://fhir.care/ad/cbc` | +| `title` | Human-readable name | `Complete Blood Count` | +| `subtitle` | Optional secondary title | `CBC (Routine)` | +| `status` | Draft, active, retired | `active` | +| `category` | Clinical category (from FHIR extensible valueset) | `laboratory` | +| `description` | Long-form description | `"Standard CBC test"` | +| `purpose` | Rationale for defining the activity | `"Baseline health evaluation"` | +| `usage` | Description of clinical usage | `"Used for anemia screening"` | +| `facility` | Facility where the definition is used | `Facility/Medicity` | +| `kind` | Type of FHIR resource created by this template (e.g., `ServiceRequest`) | `ServiceRequest` | +| `code` | Clinical code (e.g., SNOMED or internal code for the action) | `718-7` | +| `body_site` | Applicable body site, if relevant | `left arm` | +| `locations[]` | List of locations where this test can be performed | `[LabA, LabB]` | +| `specimenRequirement[]` | Linked `SpecimenDefinition` entries required for the test | `Specimen/Blood` | +| `observationResultRequirement[]` | Linked `ObservationDefinition` entries that define expected result structure | `[Hemoglobin, WBC, RBC]` | + +### Functional Workflow + +- **Define Activity** + + Admin defines a test (e.g., CBC) using `ActivityDefinition`, linking to specimens, observations, and charge items. + +- **Apply ActivityDefinition** + + When a `ServiceRequest` is created (via UI/API), the system references the relevant `ActivityDefinition` and uses it to instantiate the required resource. + +- **Auto-Generate ChargeItems** + + If charges are linked to the `ActivityDefinition`, they are also instantiated. + +### **Schema Definition?** + +```jsx +{ + "id" : "", // Internal Identifier + "version" : "", // Version of the Activity Definition + "slug" : "", // Unique name per facility + "derived_from_url" : "", // URL this object was derived from + "title" : "", // Name for this activity definition (human friendly) + "subtitle" : "", // Subordinate title of the activity definition + "status" : "", // R! draft | active | retired | unknown + "category" : "" // Bound to https://build.fhir.org/valueset-servicerequest-category.html Extensible + // "contact" : [{ ContactDetail }], // Contact details for the publisher + "description" : "", // Natural language description of the activity definition + "purpose" : "", // Why this activity definition is defined + "usage" : "", // Describes the clinical usage of the activity definition + "facility" : "", // Facility where this Account is created + // topic" : "", // No Valid use for this right now + "kind" : "", // FHIR Resource Type that is created by this Definition, Options will be internally identified by the system + "code" : "", // Bound to Snomed, controls what kind of Def this is, Example Procedure Codes + //"intent" : "", // proposal | plan | directive | order | original-order | reflex-order | filler-order | instance-order | option + //"priority" : "", // routine | urgent | asap | stat + "body_site" : "" // Bound to the Body site Valueset + "locations" : [""], // Foreign key to location + "specimenRequirement" : [""], // Points to SpecimentDefinition + //"observationRequirement" : [""], //Points to Observation Requirement + "observationResultRequirement" : [""], // What observations must be produced by this action +} +``` diff --git a/docs/care/HMIS/Labs/ChargeItemDefinition.md b/docs/care/HMIS/Labs/ChargeItemDefinition.md new file mode 100644 index 0000000..f8cfb87 --- /dev/null +++ b/docs/care/HMIS/Labs/ChargeItemDefinition.md @@ -0,0 +1,101 @@ +### Summary + +The `ChargeItemDefinition` in CARE specifies **how clinical activities (like lab tests or medications) are priced**. It allows each `ActivityDefinition`, `Medication`, or other healthcare service to be tied to a dynamic billing rule that governs how much a service costs under specific conditions. + +CARE’s billing model works behind the scenes: **as practitioners record data (ServiceRequests, MedicationRequests, etc.), billing objects are automatically created** using the relevant `ChargeItemDefinition`. + +### Core Relationships + +| Related Resource | Purpose | +| ---------------------- | -------------------------------------------------- | +| `ActivityDefinition` | Resource whose execution will generate this charge | +| `Medication` | Medication product that incurs a cost | +| `Encounter`, `Patient` | Used in condition evaluation for dynamic pricing | + +### Supported Fields + +| Field Name | Description | Example | +| ----------------- | --------------------------------------------------------- | -------------------------------------- | +| `id` | Internal identifier | `charge-cbc` | +| `version` | Version number | `"1"` | +| `title` | Name for human readability | `"CBC Test Standard Rate"` | +| `slug` | Unique internal reference | `"cbc-charge"` | +| `derivedFromUri` | Canonical URL reference if derived from standard | `"http://example.org/rates/cbc"` | +| `status` | Lifecycle status (`draft`, `active`, etc.) | `"active"` | +| `facility` | The facility where this pricing applies | `Facility/medicity` | +| `description` | Free-text description of the charge definition | `"Pricing for CBC including lab work"` | +| `purpose` | Rationale for the charge | `"Used to generate automated bills"` | +| `code` | Internal or external billing/product code | `"CBC01"` | +| `instance[]` | List of linked resources (ActivityDefinition, Medication) | `[ActivityDefinition/cbc]` | +| `propertyGroup[]` | Array of pricing conditions and breakdowns | See below | + +### Property Groups & Dynamic Pricing + +Each `propertyGroup` contains: + +- **Applicability conditions**: Expressions that evaluate whether a price component should apply (e.g., “patient is above 60 years”). +- **Price components**: The base price, surcharges, discounts, or taxes applicable under those conditions. + +### Example Fields (within `propertyGroup`) + +| Field | Description | Example | +| ------------------------- | ------------------------------------------------------- | -------------------- | +| `applicability.condition` | Boolean expression for pricing applicability | `"patient.age > 60"` | +| `priceComponent[]` | Breakdown of charge (see below for `MonetaryComponent`) | See next section | + +### MonetaryComponent Specification + +```json +json +CopyEdit +{ + "type": "base", // base | surcharge | discount | tax | informational + "code": "CBC01-BASIC", + "factor": 1.0, + "amount": { + "value": 200.00, + "currency": "INR" + } +} + +``` + +| Field | Description | Example | +| ----------------- | ----------------------------------------------------------- | --------------- | +| `type` | Type of price item (`base`, `surcharge`, `discount`, `tax`) | `"base"` | +| `code` | Identifier for pricing rule or sub-component | `"CBC01-BASIC"` | +| `factor` | Multiplier applied to the amount | `1.0` | +| `amount.value` | Monetary value (final after applying factor) | `200.00` | +| `amount.currency` | ISO 4217 code | `"INR"` | + +### Billing Workflow in CARE + +1. Practitioner creates a `ServiceRequest` for CBC. +2. The system checks the associated `ActivityDefinition` and its linked `ChargeItemDefinition`. +3. Based on patient and encounter details (age, location, tags), applicable pricing rules are evaluated. +4. A **charge item is instantiated** and added to the patient’s bill automatically. +5. Taxes and discounts are computed, total is stored with a detailed breakdown. + +### Schema Definition? + +```jsx +{ + "id" : "", // Internal Identifier + "version" : "", // Version + "title" : "", // Name for this charge item definition + "slug" : "" // + "derivedFromUri" : "", // Was this from a URL + "status" : "", // Bound to draft | active | retired | unknown + "facility" : "", // Facility where this Charge Item Definition is created + "description" : "", // Natural language description of the charge item definition + "purpose" : "", // Why this charge item definition is defined + "code" : "", // Billing code or product type this definition applies to, No valueset for now + "instance" : [{ ActivityDefinition|Medication }], // Through some M2M Table, needs to be indexed. + "propertyGroup" : [{ // Group of properties which are applicable under the same conditions + "applicability" : [{ // Whether or not the billing code is applicable + "condition" : { Expression }, // Boolean-valued expression + }], // Conditions under which the priceComponent is applicable + "priceComponent" : [{ MonetaryComponent }] // Components of total line item price + }] +} +``` diff --git a/docs/care/HMIS/Labs/DiagnosticReport.md b/docs/care/HMIS/Labs/DiagnosticReport.md new file mode 100644 index 0000000..1b0b454 --- /dev/null +++ b/docs/care/HMIS/Labs/DiagnosticReport.md @@ -0,0 +1,48 @@ +### Summary + +A `DiagnosticReport` in CARE provides a structured summary of the findings, interpretations, and outcomes derived from diagnostic activities such as lab tests. While the **clinical measurements themselves are stored as `Observation` resources**, the `DiagnosticReport` acts as a **wrapper** or **summary document**, linking together those observations in a meaningful context. + +In the CARE MVP, diagnostic reports are generated **only from `ServiceRequest` resources**, but the system is designed to support reports generated from other clinical contexts in future. + +### Core Relationships + +| Related Resource | Purpose | +| ---------------- | ----------------------------------------------------- | +| `ServiceRequest` | Origin of the diagnostic request | +| `Observation[]` | Measured values linked to this report | +| `Patient` | Patient for whom the report was generated | +| `Encounter` | Visit or session in which the test was performed | +| `Specimen[]` | Specimens used for testing (currently ignored in MVP) | + +### Supported Fields + +| Field Name | Description | Example | +| ----------------- | --------------------------------------------------- | ---------------------------------------------- | +| `id` | Internal identifier | `drpt-00123` | +| `service_request` | Reference to the original `ServiceRequest` | `ServiceRequest/1002` | +| `status` | Current lifecycle status of the report | `final` | +| `category` | Type of diagnostic service (e.g., lab, pathology) | `laboratory` | +| `code` | Test/report type (same as SR code) | `CBC Report` | +| `patient` | Patient associated with the report | `Patient/1234` | +| `encounter` | Encounter during which the diagnostic was ordered | `Encounter/5678` | +| `specimen[]` | Specimen IDs referenced (not used functionally yet) | `["Specimen/blood-2025-01"]` | +| `result[]` | IDs of associated `Observation` resources | `["Observation/100", "Observation/101"]` | +| `note` | Additional commentary on the report | `"Repeat testing advised if symptoms persist"` | +| `conclusion` | Summary interpretation of results | `"All parameters within normal range"` | + +### File Uploads & DICOM Support + +- CARE supports **uploading attachments** to diagnostic reports (PDF, images). +- **DICOM imaging support** is planned as a plugin integration with external PACS (Picture Archiving and Communication Systems) for radiology or cardiology use cases. + +### Status Lifecycle + +| Status Code | Meaning | +| ------------------ | -------------------------------------------- | +| `registered` | Report is created but not yet populated | +| `partial` | Some results available | +| `preliminary` | Early results shared before verification | +| `final` | Completed and verified report | +| `amended` | Updates applied to a previously final report | +| `cancelled` | Report was voided | +| `entered-in-error` | Report was created in error | diff --git a/docs/care/HMIS/Labs/ObservationDefinition.md b/docs/care/HMIS/Labs/ObservationDefinition.md new file mode 100644 index 0000000..f7eefda --- /dev/null +++ b/docs/care/HMIS/Labs/ObservationDefinition.md @@ -0,0 +1,71 @@ +### Summary + +`ObservationDefinition` is used to define the structure and expectations of a **clinical observation or lab result**, such as "Hemoglobin level" or "Blood glucose." These definitions describe the unit, valid value range, data type, and measurement method — forming a **template** for the actual `Observation` instances recorded during diagnostics. + +In CARE, this ensures consistency across lab results and helps maintain standards for how observations are displayed, interpreted, and validated. + +### Core Relationships + +| Related Resource | Purpose | +| -------------------- | ---------------------------------------------------------- | +| `ActivityDefinition` | Links expected observations for a test | +| `Observation` | Actual instance of a result captured using this definition | +| `SpecimenDefinition` | May define specimen type required for this observation | + +### Supported Fields + +| Field Name | Description | Example | +| --------------------------- | ---------------------------------------------------------- | ------------------------------------- | +| `id` | Internal identifier | `obsdef-hb` | +| `version` | Versioning control | `1` | +| `title` | Human-readable name of the observation | `Hemoglobin` | +| `slug` | Unique internal reference name | `hb-level` | +| `status` | Lifecycle status (`draft`, `active`, etc.) | `active` | +| `facility` | Facility where the definition is applicable | `Facility/medicity` | +| `description` | Clinical context or explanation | `"Hemoglobin concentration in blood"` | +| `code` | LOINC/SNOMED or internal code | `"718-7"` | +| `method` | Measurement technique (e.g., Spectrophotometry) | `"Spectrophotometry"` | +| `preferred_report_name` | Label to be used in reports and UIs | `"Hemoglobin"` | +| `permitted_data_type[]` | Allowed result types (`Quantity`, `CodeableConcept`, etc.) | `["Quantity"]` | +| `unit` | Measurement unit | `"g/dL"` | +| `normal_range_low` | Lower limit of reference range | `12.0` | +| `normal_range_high` | Upper limit of reference range | `17.5` | +| `category` | Clinical category | `laboratory` | +| `abnormal_interpretation[]` | Qualitative meanings (e.g., `L`, `H`, `A`) | `["L", "H"]` | +| `critical_range_low` | Critical alert thresholds (optional) | `7.0` | +| `critical_range_high` | | `22.0` | + +### Functional Workflow + +1. Admin defines the **observation format** for a test (e.g., Hemoglobin). +2. Links this definition to the appropriate **ActivityDefinition**. +3. When test results are recorded, the system: + - Enforces data type (e.g., Quantity) + - Validates result range + - Uses the `preferred_report_name` for display + +### Schema Definition? + +```jsx +{ + "id" : "", // Internal identifier + "facility" : "" // Reference to facility if present, if not present, defenition is instance wide + "version" : "", // Automatically assigned version number + "slug" : "" // To maintain uniqueness in a given facility + "title" : "", // Name for this ObservationDefinition (human friendly) + "status" : "", // Options draft | active | retired | unknown + "description" : "", // Natural language description of the ObservationDefinition + "derivedFromUri" : "", // Is this observation defenition created based on an external URI + "category" : "", // Code for observation type + "code" : "", // Code for observation, ie what is being observed + "permittedDataType" : "", // From Questionnaire + "bodySite" : "", // Body part to be observed + "method" : "", // Method used to produce the observation + "permittedUnit" : "", // Unit for quantitative results + "component" : [{ // Component results + "code" : "", // What is being observed + "permittedDataType" : "", // From Questionnaire + "permittedUnit" : "", // I Unit for quantitative results + }] +} +``` diff --git a/docs/care/HMIS/Labs/README.md b/docs/care/HMIS/Labs/README.md new file mode 100644 index 0000000..9184144 --- /dev/null +++ b/docs/care/HMIS/Labs/README.md @@ -0,0 +1,38 @@ +# Labs + +Labs & Diagnostics Module +This overview provides a high-level understanding of how diagnostic workflows are structured in CARE — from test orders to sample collection, result entry, and billing. The subsequent pages detail each resource and its role in the system. + +## Key Concepts + +| Resource | Description | +| --------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| ServiceRequest | A record of a request for service such as diagnostic investigations, treatments, or operations to be performed. | +| ActivityDefinition | A template that defines a standard lab or imaging procedure | +| SpecimenDefinition | A record of a sample to be used for analysis. | +| ObservationDefinition | A template that defines lab test results or imaging findings — defining expected units, value types, and coded terminologies. | +| ChargeItemDefinition | A template that provides the properties that apply to the (billing) codes necessary to calculate costs and prices. | +| DiagnosticReport | The findings and interpretations of diagnostic tests performed on a patient. | + +## High-Level Labs Flow + +Below is a simplified look at how these pieces fit together: + +```mermaid +%%{init: {'theme':'redux'}}%% +flowchart LR + A[" Patient"] --> B[" Encounter"] + B --> C[" Lab Test Ordered"] + C --> D{" Sample Collected?"} + D -- Yes --> E[" Sample Sent to Lab"] + D -- No --> F[" Notify Nurse/Phlebotomist"] + E --> G[" Lab Processing"] + G --> H{" Result Ready?"} + H -- Yes --> I[" Result Uploaded to EMR"] + H -- No --> J[" Wait/Repeat Test"] + I --> K[" Doctor Reviews Results"] +``` + +### Concept Diagram + +![Labs Concept Diagram](../../../../static/img/care/HMIS/Labs/Labs%20Concept%20Diagram.svg) diff --git a/docs/care/HMIS/Labs/ServiceRequest.md b/docs/care/HMIS/Labs/ServiceRequest.md new file mode 100644 index 0000000..fae44e1 --- /dev/null +++ b/docs/care/HMIS/Labs/ServiceRequest.md @@ -0,0 +1,56 @@ +### Summary + +In FHIR, a `ServiceRequest` represents an order or proposal to perform a clinical or non-clinical action for a patient. It can lead to the creation of related resources like `Procedure`, `Observation`, `Specimen`, or `DiagnosticReport`, though these are optional and context-dependent. + +CARE supports a minimal subset of FHIR’s ServiceRequest features to keep implementation simple. As complexity and demand grow, additional features may be added. + +While FHIR allows multi-organization coordination, CARE currently restricts `ServiceRequest` handling within a single facility — cross-facility dispatch must be managed manually. + +Access control is managed via roles and permissions assigned at the organization level, with each ServiceRequest linked to one or more organizations. An audit trail is required to track user actions on each request. + +### **Schema Definition?** + +```jsx +{ +"id" : "", // Internal Identifier +"status" : "", // R! draft | active | on-hold | entered-in-error | ended | completed | revoked | unknown +"intent" : "", // R! proposal | plan | directive | order + +"category" : "", // Bound to https://build.fhir.org/valueset-servicerequest-category.html +"priority" : "", // routine | urgent | asap | stat +"do_not_perform" : "", // True if service/procedure should not be performed +"activity_definition" : "", // Points to Activity Definition if created from one +"patient" : "id|fk" , // Reference to patient +"encounter" : "id|fk", // Encounter in which the request was created +"locations" : [""], // Fk to location +"specimens" : ["id|fk"], // FK to Specimen +"bodySite" : "", // Coded location on Body +"note" : "", // Comments +"occurance" : "" // Time at which this SR should take place +"patient_instruction" : "" // Instructions to the patient +} +``` + +### **Core Data Structure** + +**Essential Fields** + +| Field | Type | Required | Description | Example | +| ------------ | ----------------- | -------- | --------------------------------------------- | ---------------------------- | +| `id` | `string` | Yes | Unique identifier for the ServiceRequest | `SR-2025-0001` | +| `status` | `code` | Yes | Request state: `draft`, `active`, `completed` | `active` | +| `intent` | `code` | Yes | Always set to `order` in CARE | `order` | +| `code` | `CodeableConcept` | Yes | Reference to test via `ActivityDefinition` | `CBC - Complete Blood Count` | +| `subject` | `Reference` | Yes | The patient for whom the request is made | `Patient/1234` | +| `encounter` | `Reference` | Yes | Clinical context | `Encounter/5678` | +| `authoredOn` | `dateTime` | Yes | When the request was created | `2025-05-21T10:00:00+05:30` | +| `requester` | `Reference` | Yes | Practitioner making the request | `Practitioner/DrAnjali` | +| `note` | `Annotation[]` | Optional | Any additional notes | `"Fasting sample preferred"` | + +### Supported Status Values + +| Status | Meaning | +| ----------- | ----------------------------------------- | +| `draft` | Incomplete and not actionable | +| `active` | Ready for specimen collection and testing | +| `completed` | Results recorded and linked | +| `cancelled` | Cancelled before lab action | diff --git a/docs/care/HMIS/Labs/Specimen.md b/docs/care/HMIS/Labs/Specimen.md new file mode 100644 index 0000000..88b3a9c --- /dev/null +++ b/docs/care/HMIS/Labs/Specimen.md @@ -0,0 +1,30 @@ +### Summary + +In CARE, a `Specimen` represents a **physical sample collected from a patient** for diagnostic analysis. This includes blood, urine, swabs, or tissue samples collected as part of a diagnostic process. Each specimen is associated with a patient, collected during an encounter, and typically originates from a `ServiceRequest`. + +Specimens can optionally be **instantiated from a `SpecimenDefinition`**, inheriting baseline properties such as type, preparation, and container. However, all real-world specifics — collection details, condition, and processing — are captured in the `Specimen` resource itself. + +### Core Relationships + +| Related Resource | Purpose | +| -------------------- | ------------------------------------------------------------ | +| `Patient` | The subject from whom the specimen was collected | +| `Encounter` | The clinical context of collection | +| `ServiceRequest` | The reason the specimen was collected | +| `SpecimenDefinition` | (Optional) Template from which the specimen was instantiated | +| `Procedure` | Procedure during which the specimen was collected | +| `Observation` | Diagnostic data produced based on this specimen | + +### Supported Fields + +| Field | Description | Example | +| ----------------------- | ------------------------------------- | -------------------------------------------------------- | +| `id` | Internal system ID | `spec-2025-001` | +| `accessionIdentifier[]` | External barcodes/IDs for tracking | `["LAB-BLOOD-34567"]` | +| `status` | Status of the specimen | `available` | +| `type` | Type of material (e.g., venous blood) | `"venous blood"` | +| `subject` | Links to patient and encounter | `{ patient: "Patient/123", encounter: "Encounter/456" }` | +| `receivedTime` | When the lab received the specimen | `"2025-05-21T10:15:00+05:30"` | +| `request` | Reference to the `ServiceRequest` | `"ServiceRequest/789"` | +| `note` | Free-text comment | `"Slight hemolysis observed"` | +| `condition[]` | Physical condition of the specimen | `["room temperature", "unclotted"]` | diff --git a/docs/care/HMIS/Labs/SpecimenDefinition.md b/docs/care/HMIS/Labs/SpecimenDefinition.md new file mode 100644 index 0000000..6b5af71 --- /dev/null +++ b/docs/care/HMIS/Labs/SpecimenDefinition.md @@ -0,0 +1,88 @@ +### Summary + +`SpecimenDefinition` defines the **template or blueprint for specimen types** used in the laboratory. Instead of repeatedly defining the properties of commonly collected specimens (like blood, urine, or sputum), CARE uses `SpecimenDefinition` to maintain a central, reusable registry of specimen kinds that can be instantiated when needed. + +When a specimen is collected during a diagnostic workflow, it is linked to its `SpecimenDefinition`. The instance retains a **snapshot** of the original definition to ensure **data integrity** and **historical traceability**, even if the definition changes later. + +This resource enables structured specimen management aligned with the FHIR specification and supports integration with `ActivityDefinition` for test planning. + +### Core Relationships + +| Related Resource | Purpose | +| -------------------- | ------------------------------------------------- | +| `ActivityDefinition` | Specifies which specimens are required for a test | +| `Specimen` | Concrete instance created from this definition | +| `Facility` | Scope of usage for definition | + +### Supported Fields + +| Field | Description | Example | +| ----------------------- | ------------------------------------------- | ------------------------------ | +| `id` | Internal identifier | `spec-blood-001` | +| `version` | Version number of the definition | `"1"` | +| `title` | Human-readable label | `"Venous Blood"` | +| `slug` | Unique internal name | `"venous-blood"` | +| `derived_from_uri` | Reference to external source or standard | `"http://hl7.org/specs/blood"` | +| `status` | Lifecycle status (`draft`, `active`, etc.) | `"active"` | +| `facility` | Facility where this definition applies | `Facility/medicity` | +| `description` | Narrative explanation of this specimen type | `"Standard blood draw"` | +| `type_collected` | Type of specimen (bound to HL7 valuesets) | `"venous blood"` | +| `patient_preparation[]` | Pre-collection instructions (e.g., fasting) | `["SNOMED/20430005"]` | +| `collection` | Collection procedure (e.g., venipuncture) | `"SNOMED/73761001"` | + +### Substructure (Container Info) + +| Subfield | Description | Example | +| ----------------------------------- | --------------------------------------------------------- | -------------------------------- | +| `is_derived` | Whether specimen is primary or derived | `false` | +| `preference` | Preferred or alternate | `"preferred"` | +| `container.description` | Label for the container | `"Vacutainer with EDTA"` | +| `container.capacity.value` | Capacity amount | `5` | +| `container.capacity.unit` | Unit of measure | `"mL"` | +| `container.minimum_volume_quantity` | Minimum acceptable volume | `{ "value": 2, "unit": "mL" }` | +| `container.cap` | Container cap type (bound to FHIR container-cap valueset) | `"red"` | +| `container.preparation` | Special handling for the container | `"Sterile, vacuum sealed"` | +| `requirement` | Transport/handling requirements | `"Keep at 4–8°C"` | +| `retention_time` | How long specimen should be retained | `{ "value": 3, "unit": "days" }` | +| `single_use` | Whether container is single-use | `true` | + +### Functional Workflow + +1. **Admin defines a SpecimenDefinition** for common sample types (e.g., venous blood). +2. **Linked via ActivityDefinition** to relevant lab tests. +3. When a lab test is initiated, **specimen instances are created** from these definitions via a dedicated API. +4. Specimen instances store a **snapshot** of definition fields to preserve traceability. + +### Schema Definition? + +```jsx +{ + "id" : "", // Internal Identifier + "version" : "", // Version of the SpecimenDefinition + "title" : "", // Name for this SpecimenDefinition (Human friendly) + "slug" : "", // Some internal Name + "derived_from_uri" : "", // Based on external definition + "status" : "", // R! draft | active | retired | unknown + "facility" : "", // Facility where this Account is created + "description" : "", // Natural language description of the SpecimenDefinition + "type_collected" : "", // Bound to Hl7 Valueset ( Unbounded ) + "patient_preparation" : ["" , ""], // Patient preparation for collection, Bound to Snomed + "collection" : "", // Specimen collection procedure, Bound to Snomed + "type_tested" : { // Specimen in container intended for testing by lab + "is_derived" : "", // Primary or secondary specimen + "preference" : "", // preferred | alternate + "container" : { // The specimen's container + "description" : "", // The description of the kind of container + "capacity" : { "value" : "" , "unit" : "" }, // The capacity of this kind of container + // minimumVolume[x]: Minimum volume. One of these 2: + "minimum_volume_quantity" : { "value" : "" , "unit" : "" }, + "minimum_volume_string" : "", + "cap" : "" // Maps to https://build.fhir.org/valueset-container-cap.html + "preparation" : "" // Special processing applied to the container for this specimen type + }, + "requirement" : "", // Requirements for specimen delivery and special handling + "retention_time" : { DurationSpec }, // The usual time for retaining this kind of specimen + "single_use" : "", // Specimen for single use only + } +} +``` diff --git a/docs/care/HMIS/Pharmacy/ChargeItem.md b/docs/care/HMIS/Pharmacy/ChargeItem.md new file mode 100644 index 0000000..ade201d --- /dev/null +++ b/docs/care/HMIS/Pharmacy/ChargeItem.md @@ -0,0 +1,72 @@ +### 📋 Summary + +The **Charge Item** resource in the CARE system captures financial details associated with services rendered or products supplied to a patient. It serves as a self-contained record, detailing the origin of the charge, the amount, applied discounts, taxes, and other relevant financial information. + +Charge Items are intrinsically linked to both an **Account** and an **Encounter**, ensuring accurate tracking and billing within the patient's financial records. + +This resource aligns with FHIR's [ChargeItem](https://build.fhir.org/chargeitem.html) resource, facilitating interoperability and standardized billing practices.[FHIR Build](https://build.fhir.org/chargeitem.html?utm_source=chatgpt.com) + +--- + +### 🎯 Key Purpose + +- Document financial charges for services or products provided to patients. +- Enable automated billing processes by linking clinical activities to financial records. +- Support detailed breakdowns of charges, including taxes, discounts, and surcharges. +- Facilitate auditing and financial analysis within the healthcare facility. + +--- + +### 🧱 Core Data Structure – Essential Fields + +- **`id`**: Internal identifier for the charge item. +- **`definition`**: Reference to the associated Charge Item Definition. +- **`status`**: Current state of the charge item (e.g., planned, billable, billed). +- **`code`**: Billing code identifying the charge. +- **`patient`**: Reference to the patient associated with the charge. +- **`encounter`**: Reference to the encounter during which the charge was incurred. +- **`facility`**: Reference to the facility where the charge item was created. +- **`quantity`**: Quantity of the service or product provided. +- **`unitPriceComponent`**: Breakdown of the unit price, including base price, taxes, and discounts. +- **`totalPriceComponent`**: Breakdown of the total price, considering quantity and other factors. +- **`total_price`**: Total monetary amount charged. +- **`overrideReason`**: Reason for any manual override of the standard pricing. +- **`service`**: Reference to the service or product that prompted the charge. +- **`account`**: Reference to the patient's account for billing purposes. +- **`note`**: Additional comments or annotations about the charge item. +- **`supportingInformation`**: Additional references supporting the charge (e.g., prescriptions, orders).[FHIR Build+13FHIR Build+13NRCeS+13](https://build.fhir.org/chargeitem.html?utm_source=chatgpt.com) + +--- + +### 🔗 Core Relationships + +| Field | Reference Resource | Description | +| ------------ | ------------------------------------- | -------------------------------------------------------- | +| `definition` | ChargeItemDefinition | Defines the pricing rules and applicability. | +| `patient` | Patient | Patient associated with the charge. | +| `encounter` | Encounter | Clinical encounter during which the charge was incurred. | +| `facility` | Organization | Facility where the charge item was created. | +| `service` | Various (e.g., Medication, Procedure) | Service or product that prompted the charge. | +| `account` | Account | Patient's account for billing purposes. | + +--- + +### 📄 Supported Fields + +**Monetary Component:** + +- **`type`**: Type of price component (e.g., base, surcharge, discount, tax, informational). +- **`code`**: Code differentiating kinds of taxes, surcharges, discounts, etc. +- **`factor`**: Factor used for calculating this component. +- **`amount`**: Monetary amount associated with this component, including value and currency. + +--- + +### 🔁 Functional Workflow + +1. **Charge Item Creation**: When a service is rendered or a product is supplied, a Charge Item is automatically generated, capturing all relevant financial details. +2. **Association with Encounter and Account**: The Charge Item is linked to the specific patient encounter and their billing account, ensuring accurate financial tracking. +3. **Pricing Calculation**: Using the associated Charge Item Definition, the system calculates the unit and total prices, factoring in any applicable taxes, discounts, or surcharges. +4. **Manual Overrides**: If necessary, authorized personnel can override standard pricing, with the reason documented in the `overrideReason` field. +5. **Billing and Invoicing**: Charge Items feed into the billing system, facilitating invoice generation and payment processing. +6. **Audit and Reporting**: Detailed records of Charge Items support financial audits and reporting requirements. diff --git a/docs/care/HMIS/Pharmacy/ChargeItemDefinition.md b/docs/care/HMIS/Pharmacy/ChargeItemDefinition.md new file mode 100644 index 0000000..a675822 --- /dev/null +++ b/docs/care/HMIS/Pharmacy/ChargeItemDefinition.md @@ -0,0 +1,66 @@ +### Summary + +The **Charge Item Definition** resource in the CARE system outlines the billing rules and pricing details associated with healthcare services and products. It serves as a blueprint for how charges are calculated, considering various factors such as patient demographics, service context, and applicable taxes. + +This resource aligns with FHIR's [ChargeItemDefinition](https://build.fhir.org/chargeitemdefinition.html) resource, providing a standardized framework for representing billing information.[FHIR Build](https://build.fhir.org/chargeitemdefinition.html?utm_source=chatgpt.com) + +--- + +### Key Purpose + +- Define billing rules and pricing structures for healthcare services and products. +- Enable automated charge item creation based on clinical data entry. +- Support conditional pricing based on patient attributes and service context. +- Facilitate tax calculations and regional billing configurations.[imagineteam.com+7HL7 Confluence+7RCM Matter+7](https://confluence.hl7.org/spaces/FHIR/pages/66929138/Chargeitemdefinition%2BFhir%2BResource%2BProposal?utm_source=chatgpt.com)[Medical Billing Star](https://www.medicalbillingstar.com/medgen-ehr/work-flow.html?utm_source=chatgpt.com) + +--- + +### Core Data Structure – Essential Fields + +- **`id`**: Internal identifier for the charge item definition. +- **`version`**: Version of the charge item definition. +- **`title`**: Human-readable name for the charge item definition. +- **`slug`**: URL-friendly identifier. +- **`derivedFromUri`**: URI from which this definition is derived. +- **`status`**: Current status (e.g., draft, active, retired, unknown). +- **`facility`**: Reference to the facility where this definition is applicable. +- **`description`**: Detailed description of the charge item definition. +- **`purpose`**: Explanation of the purpose behind this definition. +- **`code`**: Billing code or product type this definition applies to. +- **`instance`**: References to specific resources (e.g., ActivityDefinition, Medication) this definition applies to. +- **`propertyGroup`**: Groups of properties applicable under certain conditions.[FHIR Build+19Medplum+19RubyDoc+19](https://www.medplum.com/docs/api/fhir/resources/chargeitemdefinition?utm_source=chatgpt.com) + +--- + +### Core Relationships + +| Field | Reference Resource | Description | +| ---------- | -------------------------- | -------------------------------------------------------- | +| `facility` | Organization | Facility where the charge item definition is applicable. | +| `instance` | Various (e.g., Medication) | Resources this charge item definition applies to. | + +--- + +### Supported Fields + +**Property Group:** + +- **`applicability`**: Conditions under which the price component is applicable, defined using expressions. +- **`priceComponent`**: Components that make up the total price, such as base price, surcharges, discounts, and taxes. + +**Monetary Component:** + +- **`type`**: Type of price component (e.g., base, surcharge, discount, tax, informational). +- **`code`**: Code differentiating kinds of taxes, surcharges, discounts, etc. +- **`factor`**: Factor used for calculating this component. +- **`amount`**: Monetary amount associated with this component, including value and currency.[InterSystems Documentation](https://docs.intersystems.com/irisforhealthlatest/csp/documatic/%25CSP.Documatic.cls?CLASSNAME=HS.FHIR.DTL.vR4.Model.Element.ChargeItemDefinition.propertyGroup.priceComponent&LIBRARY=HSSYS&utm_source=chatgpt.com) + +--- + +### Functional Workflow + +1. **Definition Creation**: A Charge Item Definition is created, detailing the billing rules and pricing structures for specific services or products. +2. **Automated Charge Generation**: When clinical data is entered (e.g., medication requests), the system automatically generates corresponding charge items based on the definitions. +3. **Conditional Pricing**: The system evaluates patient and encounter data against the applicability conditions to determine the appropriate pricing. +4. **Tax Calculation**: Applicable taxes are calculated based on configured tax codes and added to the total charge. +5. **Billing Integration**: The final charge, including all components, is integrated into the billing system for invoicing and payment processing. diff --git a/docs/care/HMIS/Pharmacy/InventoryItem.md b/docs/care/HMIS/Pharmacy/InventoryItem.md new file mode 100644 index 0000000..b5c02d3 --- /dev/null +++ b/docs/care/HMIS/Pharmacy/InventoryItem.md @@ -0,0 +1,67 @@ +### Summary + +The **InventoryItem** resource represents the availability of a specific product at a given location. It is primarily used for inventory management within healthcare facilities, ensuring accurate tracking of stock levels for medications and other products. + +Inventory items are automatically created and updated, typically when a supply delivery is marked as completed. + +An inventory item can be marked as inactive to indicate that it is no longer actively dispensed by the pharmacy, possibly due to damage or other concerns. + +--- + +### Key Purpose + +- Track the availability and quantity of products at specific locations. +- Facilitate inventory management and auditing processes. +- Support automated updates based on supply deliveries. +- Indicate the active or inactive status of inventory items. + +--- + +### Core Data Structure – Essential Fields + +- **`product`**: Reference to the product being tracked. +- **`status`**: Current status of the inventory item (e.g., active, inactive). +- **`location`**: Location where the product is stored. +- **`net_content`**: Quantity of the product available at the specified location. + +--- + +### Supported Status Values + +The `status` field can have the following values: + +- **`active`**: The item is active and can be referenced. +- **`inactive`**: The item is presently inactive; there may be references to it, but it is not expected to be used. +- **`entered-in-error`**: The item record was entered in error. +- **`unknown`**: The item status has not been determined.[FHIR Build+1HL7 Terminology+1](https://build.fhir.org/codesystem-inventoryitem-status.html?utm_source=chatgpt.com) + +_Source: FHIR InventoryItem Status Codes_ + +--- + +### Core Relationships + +| Field | Reference Resource | Description | +| ---------- | ------------------ | ------------------------------------------- | +| `product` | Product | The product being tracked in the inventory. | +| `location` | Location | The location where the product is stored. | + +--- + +### Supported Fields + +| Field Name | Type | Description | +| ------------- | --------- | -------------------------------------------------- | +| `product` | Reference | Reference to the product being tracked. | +| `status` | code | Current status of the inventory item. | +| `location` | Reference | Location where the product is stored. | +| `net_content` | Quantity | Quantity of the product available at the location. | + +--- + +### Functional Workflow + +1. **Supply Delivery Completion**: When a supply delivery is marked as completed, corresponding inventory items are automatically created or updated to reflect the new stock levels. +2. **Inventory Updates**: Any changes in stock levels, such as dispensing or receiving products, result in automatic updates to the inventory items. +3. **Status Management**: Inventory items can be marked as inactive to indicate that they are no longer actively dispensed, possibly due to damage or other concerns. +4. **Inventory Auditing**: Regular audits can be conducted by reviewing the inventory items, their statuses, and quantities to ensure accurate stock management. diff --git a/docs/care/HMIS/Pharmacy/MedicationDispense.md b/docs/care/HMIS/Pharmacy/MedicationDispense.md new file mode 100644 index 0000000..dacee3c --- /dev/null +++ b/docs/care/HMIS/Pharmacy/MedicationDispense.md @@ -0,0 +1,109 @@ +### Summary + +The **MedicationDispense** resource in FHIR records the details of medications that have been dispensed to a patient. It serves as both a completion to the workflow initiated by a MedicationRequest and as a tool for inventory management within a healthcare setting. + +In inpatient (IP) settings, items may be dispensed and maintained in the patient's room and refilled as needed. In outpatient (OP) settings, dispensing typically occurs after an encounter has been completed. + +A **ChargeItem** can be associated with each dispense. By default, the **ChargeItemDefinition** is used to create this ChargeItem. + +--- + +### Key Purpose + +- Document the supply of medications to patients. +- Complete the medication workflow initiated by a MedicationRequest. +- Support inventory management within healthcare facilities. +- Facilitate billing through associated ChargeItems. + +--- + +### Core Data Structure – Essential Fields + +- **`product`**: Reference to the product being dispensed. +- **`status`**: Current status of the dispense (e.g., preparation, in-progress, completed). +- **`not_performed_reason`**: Reason why the dispense was not performed. +- **`status_history`**: History of status changes for auditing purposes. +- **`category`**: Type of medication dispense (e.g., IP, OP, Home). +- **`patient`**: Reference to the patient receiving the medication. +- **`encounter`**: Reference to the encounter during which the dispense occurred. +- **`location`**: Location where the dispense took place. +- **`authorizing_prescription`**: Reference to the MedicationRequest that authorized the dispense. +- **`dispense_type`**: Type of dispensing event performed. +- **`quantity`**: Amount of medication dispensed. +- **`days_supply`**: Number of days the supply is intended to last. +- **`when_prepared`**: Time when the medication was prepared. +- **`when_handed_over`**: Time when the medication was handed over to the patient. +- **`note`**: Additional information about the dispense. +- **`dosage_instruction`**: Instructions on how the medication should be used. +- **`substitution`**: Details about any substitution made during dispensing. +- **`charge_item`**: Reference to the associated charge item. + +--- + +### Supported Status Values + +The `status` field can have the following values: + +- **`preparation`**: The core event has not started yet, but some staging activities have begun (e.g., initial compounding or packaging of medication). +- **`in-progress`**: The dispensed product is ready for pickup. +- **`cancelled`**: The dispensed product was not and will never be picked up by the patient. +- **`on-hold`**: The dispense process is paused while waiting for an external event to reactivate the dispense. +- **`completed`**: The dispensed product has been picked up. +- **`entered-in-error`**: The dispense was entered in error and therefore nullified. +- **`stopped`**: Actions implied by the dispense have been permanently halted, before all of them occurred. +- **`declined`**: The dispense was declined and not performed. +- **`unknown`**: The authoring system does not know which of the status values applies for this medication dispense. + +--- + +### Core Relationships + +| Field | Reference Resource | Description | +| -------------------------- | ------------------ | ------------------------------------------------- | +| `product` | Product | The product being dispensed. | +| `patient` | Patient | The individual receiving the medication. | +| `encounter` | Encounter | The encounter during which the dispense was made. | +| `location` | Location | The location where the dispense occurred. | +| `authorizing_prescription` | MedicationRequest | The prescription that authorized the dispense. | +| `charge_item` | ChargeItem | The associated charge for the dispensed item. | + +--- + +### Supported Fields + +| Field Name | Type | Description | +| -------------------------- | --------------- | -------------------------------------------------------- | +| `product` | Reference | Reference to the product being dispensed. | +| `status` | code | The current status of the dispense. | +| `not_performed_reason` | CodeableConcept | Reason why the dispense was not performed. | +| `status_history` | List | History of status changes for auditing purposes. | +| `category` | CodeableConcept | Type of medication dispense (e.g., IP, OP, Home). | +| `patient` | Reference | The patient receiving the medication. | +| `encounter` | Reference | The encounter associated with the dispense. | +| `location` | Reference | The location where the dispense occurred. | +| `authorizing_prescription` | Reference | The prescription that authorized the dispense. | +| `dispense_type` | CodeableConcept | Type of dispensing event performed. | +| `quantity` | Quantity | Amount of medication dispensed. | +| `days_supply` | Quantity | Number of days the supply is intended to last. | +| `when_prepared` | dateTime | Time when the medication was prepared. | +| `when_handed_over` | dateTime | Time when the medication was handed over to the patient. | +| `note` | Annotation | Additional information about the dispense. | +| `dosage_instruction` | Dosage | Instructions on how the medication should be used. | +| `substitution` | BackboneElement | Details about any substitution made during dispensing. | +| `charge_item` | Reference | Reference to the associated charge item. | + +--- + +### Functional Workflow + +1. **Initiation**: A MedicationRequest is created for a patient. +2. **Dispensing**: Based on the request, a MedicationDispense is recorded when the medication is prepared and handed over. +3. **Status Tracking**: The status of the dispense is updated throughout the process (e.g., from `preparation` to `completed`). +4. **Inventory Management**: The dispense record aids in managing inventory levels within the healthcare facility. +5. **Billing**: A ChargeItem is associated with the dispense for billing purposes. + +--- + +### Substructure (Container Info) + +- **`substitution`**: Indicates whether a substitution was made during dispensing, the type of substitution, and the reason for it. diff --git a/docs/care/HMIS/Pharmacy/MedicationRequest.md b/docs/care/HMIS/Pharmacy/MedicationRequest.md new file mode 100644 index 0000000..5179ecf --- /dev/null +++ b/docs/care/HMIS/Pharmacy/MedicationRequest.md @@ -0,0 +1,77 @@ +### Summary + +A [**MedicationRequest**](https://hl7.org/fhir/medicationrequest.html) is an order or request for both the supply of medication and instructions for its administration to a patient. It represents the prescriber's intent for a medication to be supplied and/or administered. + +--- + +### Key Purpose + +- Create and track medication orders/prescriptions +- Document medication instructions and dosage requirements +- Facilitate regular and PRN (as needed) medications[Wikipedia+7Flexpa+7ExecuteCommands+7](https://www.flexpa.com/docs/fhir/medication-request?utm_source=chatgpt.com) + +--- + +### Core Components + +- Medication details (drug, form, strength) +- Dosage instructions +- Timing and frequency +- Route of administration +- Quantity/duration +- Patient and prescriber information + +--- + +### Supported Status Values + +- **active**: The prescription is active and should be fulfilled. +- **on-hold**: The prescription is temporarily suspended. +- **ended**: The prescription is no longer active, and the medication should not be taken. +- **stopped**: The prescription was stopped before completion. +- **completed**: The prescription has been fully completed. +- **cancelled**: The prescription was cancelled before any administration. +- **entered-in-error**: The prescription was entered in error. +- **draft**: The prescription is in draft status and not yet active. +- **unknown**: The status of the prescription is unknown. + +--- + +### Core Relationships + +| Field | Reference Resource | Description | +| ------------ | ------------------ | -------------------------------------------------------- | +| `subject` | Patient | The patient for whom the medication is prescribed. | +| `encounter` | Encounter | The encounter during which the prescription was created. | +| `medication` | Medication | The medication being prescribed. | +| `requester` | Practitioner | The individual who initiated the prescription. | + +--- + +### Supported Fields + +| Field Name | Type | Description | +| ------------------- | --------------- | -------------------------------------------------------- | +| `identifier` | Identifier | Unique identifier for the prescription. | +| `status` | code | The current status of the prescription. | +| `statusReason` | string | Reason for the current status. | +| `intent` | code | The intent of the prescription (e.g., order). | +| `priority` | code | Priority of the prescription. | +| `doNotPerform` | boolean | Indicates if the medication should not be given. | +| `category` | code | Category of the prescription (e.g., outpatient). | +| `medication` | CodeableConcept | The medication being prescribed. | +| `subject` | Reference | The patient for whom the medication is prescribed. | +| `encounter` | Reference | The encounter during which the prescription was created. | +| `authoredOn` | dateTime | When the prescription was authored. | +| `dosageInstruction` | Dosage | Instructions on how the medication should be taken. | +| `note` | string | Additional notes about the prescription. | + +--- + +### Functional Workflow + +1. **Prescription Creation**: A healthcare provider creates a MedicationRequest during a patient encounter. +2. **Review and Approval**: The prescription is reviewed and approved as per facility protocols. +3. **Dispensing**: The pharmacy dispenses the medication as per the prescription details. +4. **Administration and Monitoring**: The patient administers the medication, and adherence is monitored. +5. **Status Updates**: The status of the MedicationRequest is updated based on the medication's lifecycle (e.g., completed, stopped). diff --git a/docs/care/HMIS/Pharmacy/Product.md b/docs/care/HMIS/Pharmacy/Product.md new file mode 100644 index 0000000..5f76ac7 --- /dev/null +++ b/docs/care/HMIS/Pharmacy/Product.md @@ -0,0 +1,68 @@ +### Summary + +In the CARE system, a **Product** refers to any item that can be purchased from the facility. This encompasses: + +- [Medications](https://build.fhir.org/medication.html) +- [Nutritional Products](https://build.fhir.org/nutritionproduct.html) +- Consumables + +These items can be requested for a patient through a Medication Request. Although the terminology might seem counterintuitive, this design choice was made to streamline the ordering process. + +Requested products are dispensed via the Medication Dispense process. + +The **Product** resource in CARE is a culmination of multiple FHIR resource references. While it deviates from FHIR's standard structure, it maintains the capability to create individual FHIR resources when necessary. + +A **Product** is an instantiation of **Product Knowledge**. All pertinent details are housed within the Product Knowledge resource, whereas the Product resource captures data unique to a specific batch, such as batch number and expiry date. + +Additionally, a Product is linked to a Charge Item Definition, facilitating the creation of Charge Items whenever the product is billed. + +--- + +### Key Purpose + +- Represent purchasable items within the facility. +- Differentiate between general product information (Product Knowledge) and batch-specific details. +- Integrate with billing systems through Charge Item Definitions. +- Ensure compatibility with FHIR resources for interoperability. + +--- + +### Core Data Structure – Essential Fields + +- **`product_knowledge`**: Reference to the Product Knowledge resource containing general information about the product. +- **`batch_number`**: The specific batch number of the product. +- **`expiry_date`**: The expiration date of the product batch. +- **`charge_item_definition`**: Reference to the Charge Item Definition associated with the product. +- **`status`**: Current status of the product (e.g., active, inactive). + +--- + +### Core Relationships + +| Field | Reference Resource | Description | +| ------------------------ | -------------------- | -------------------------------------------- | +| `product_knowledge` | ProductKnowledge | General information about the product. | +| `charge_item_definition` | ChargeItemDefinition | Billing details associated with the product. | + +--- + +### Supported Fields + +| Field Name | Type | Description | +| ------------------------ | --------- | ------------------------------------------------------- | +| `product_knowledge` | Reference | Link to the general product information. | +| `batch_number` | string | Unique identifier for the product batch. | +| `expiry_date` | date | Expiration date of the product batch. | +| `charge_item_definition` | Reference | Link to the billing definition for the product. | +| `status` | code | Current status of the product (e.g., active, inactive). | + +--- + +### Functional Workflow + +1. **Product Knowledge Creation**: General information about a product is entered into the Product Knowledge resource. +2. **Product Instantiation**: For each batch received, a Product resource is created, referencing the Product Knowledge and including batch-specific details. +3. **Billing Integration**: The Product resource links to a Charge Item Definition, ensuring accurate billing when the product is dispensed. +4. **Dispensing Process**: Products are dispensed to patients through the Medication Dispense process, with all relevant information captured. + +--- diff --git a/docs/care/HMIS/Pharmacy/ProductKnowledge.md b/docs/care/HMIS/Pharmacy/ProductKnowledge.md new file mode 100644 index 0000000..507dfaf --- /dev/null +++ b/docs/care/HMIS/Pharmacy/ProductKnowledge.md @@ -0,0 +1,90 @@ +### Summary + +The **Product Knowledge** resource in the CARE system serves as the foundational reference for all products available within a healthcare facility. It encompasses comprehensive, context-independent information about a product, such as its classification, composition, storage guidelines, and intended use. + +This resource aligns with FHIR's [MedicationKnowledge](https://build.fhir.org/medicationknowledge.html) and [NutritionProduct](https://build.fhir.org/nutritionproduct.html) resources, providing a standardized framework for representing detailed product information. + +Each **Product** instance refers to a **Product Knowledge** entry, inheriting its general attributes while specifying batch-specific details like batch number and expiry date. + +--- + +### Key Purpose + +- Define comprehensive, facility-wide information about products. +- Standardize product data across different batches and instances. +- Facilitate integration with FHIR resources for interoperability. +- Support inventory management, prescribing, and dispensing processes. + +--- + +### Core Data Structure – Essential Fields + +- **`facility`**: Reference to the facility where the product is available (nullable). +- **`slug`**: A URL-friendly identifier for the product. +- **`status`**: Current status of the product knowledge entry (e.g., draft, active, retired, unknown). +- **`product_type`**: Type of product (e.g., Medication, NutritionProduct, Consumable). +- **`code`**: A code representing the product, with the value set depending on the product type. +- **`name`**: The primary name of the product. +- **`base_unit`**: The unit in which the product is measured or dispensed. +- **`names`**: A list of alternative names for the product, each with a specified name type. +- **`storage_guidelines`**: Instructions for storing the product, including notes, stability duration, and environmental settings. +- **`definition`**: Detailed information about the product's form, intended route(s) of administration, ingredients, nutrients, and drug characteristics. + +--- + +### Core Relationships + +| Field | Reference Resource | Description | +| ------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `facility` | Organization | The facility where the product is available. | +| `code` | CodeSystem | The coding system used to identify the product. | +| `names.name_type` | ValueSet | The type of name, bound to [InventoryItem Name Type](https://build.fhir.org/valueset-inventoryitem-nametype.html). | +| `definition.dose_form` | ValueSet | The form of the medication, bound to [Medication Form Codes](https://build.fhir.org/valueset-medication-form-codes.html). | +| `definition.intended_route` | ValueSet | The intended route(s) of administration, bound to [Route Codes](https://build.fhir.org/valueset-route-codes.html). | +| `definition.ingredients.substance` | Substance | The substance(s) that make up the product. | +| `definition.drug_characteristic.type` | ValueSet | The type of drug characteristic, bound to [Medication Knowledge Characteristic](https://build.fhir.org/valueset-medicationknowledge-characteristic.html). | + +--- + +### Supported Fields + +| Field Name | Type | Description | +| --------------------------------------------------- | --------------- | ----------------------------------------------------------------- | +| `facility` | Reference | Reference to the facility (nullable). | +| `slug` | string | URL-friendly identifier for the product. | +| `status` | code | Status of the product knowledge entry. | +| `product_type` | code | Type of product (e.g., Medication, NutritionProduct, Consumable). | +| `code` | CodeableConcept | Code representing the product. | +| `name` | string | Primary name of the product. | +| `base_unit` | CodeableConcept | Unit in which the product is measured or dispensed. | +| `names` | List | Alternative names for the product. | +| `names.name_type` | code | Type of name (e.g., trade name, brand name). | +| `names.name` | string | The alternative name. | +| `storage_guidelines` | List | Storage instructions for the product. | +| `storage_guidelines.note` | string | Additional notes on storage. | +| `storage_guidelines.stability_duration` | Duration | Duration for which the product remains stable. | +| `storage_guidelines.environmental_setting` | List | Environmental conditions for storage. | +| `storage_guidelines.environmental_setting.type` | code | Type of environmental condition. | +| `storage_guidelines.environmental_setting.value` | string | Value of the environmental condition. | +| `definition` | BackboneElement | Detailed definition of the product. | +| `definition.dose_form` | CodeableConcept | Form of the medication. | +| `definition.intended_route` | List | Intended route(s) of administration. | +| `definition.ingredients` | List | Ingredients of the product. | +| `definition.ingredients.is_active` | boolean | Indicates if the ingredient is active. | +| `definition.ingredients.substance` | CodeableConcept | Substance that makes up the ingredient. | +| `definition.ingredients.strength` | BackboneElement | Strength information of the ingredient. | +| `definition.ingredients.strength.strength_ratio` | Ratio | Strength ratio of the ingredient. | +| `definition.ingredients.strength.strength_quantity` | Quantity | Strength quantity of the ingredient. | +| `definition.nutrients` | List | Nutritional components of the product. | +| `definition.drug_characteristic` | List | Characteristics of the drug. | +| `definition.drug_characteristic.type` | CodeableConcept | Type of drug characteristic. | +| `definition.drug_characteristic.value` | string | Value of the drug characteristic. | + +--- + +### Functional Workflow + +1. **Creation**: A Product Knowledge entry is created with comprehensive details about a product, including its classification, composition, and storage guidelines. +2. **Reference**: Individual Product instances reference the Product Knowledge entry, inheriting its general attributes while specifying batch-specific details. +3. **Integration**: The Product Knowledge resource integrates with FHIR resources like MedicationKnowledge and NutritionProduct, facilitating interoperability across systems. +4. **Maintenance**: Updates to product information, such as changes in composition or storage guidelines, are made within the Product Knowledge resource, ensuring consistency across all related Product instances. diff --git a/docs/care/HMIS/Pharmacy/README.md b/docs/care/HMIS/Pharmacy/README.md new file mode 100644 index 0000000..a7421dc --- /dev/null +++ b/docs/care/HMIS/Pharmacy/README.md @@ -0,0 +1,41 @@ +# Pharmacy + +## Key Concepts + +This table outlines the primary components of the CARE Pharmacy Module, detailing their roles and associated FHIR resources. +| **Concept** | **FHIR Resource** | **Description** | +| --- | --- | --- | +| **Patient** | `Patient` | Represents an individual receiving healthcare services. | +| **Encounter** | `Encounter` | An interaction between a patient and healthcare provider(s) for the purpose of providing healthcare service(s). | +| **Medication Request** | `MedicationRequest` | An order or request for both the supply of the medication and the instructions for administration. | +| **Medication Dispense** | `MedicationDispense` | Indicates that a medication product is to be or has been dispensed for a named person/patient. | +| **Inventory Item** | `InventoryItem` | Represents a product in the inventory, including details like quantity, location, and status. | +| **Product** | `Medication` | The specific medication product, including its identification and definition. | +| **Product Knowledge** | `MedicationKnowledge` | Provides detailed information about a medication, including its composition, indications, and contraindications. | +| **Charge Item Definition** | `ChargeItemDefinition` | Defines the prices, factors, and conditions that apply to a billing code. | +| **Charge Item** | `ChargeItem` | Represents the provision of healthcare provider products for a patient, including billing details. | +| **Supply Request** | `SupplyRequest` | A record of a request to deliver a medication, substance, or device used in the healthcare setting. | +| **Supply Delivery** | `SupplyDelivery` | Records the delivery of a supply item. | +| **Location** | `Location` | Details and position information for a physical place where services are provided and resources are stored. | + +## High-Level Pharmacy Flow + +Below is a simplified look at how these pieces fit together: + +```mermaid +%%{init: {'theme':'redux'}}%% +flowchart LR + A[" Patient"] --> B[" Encounter"] + B --> C[" Medication Request"] + C --> D{" Drug Available in Pharmacy?"} + D -- Yes --> E[" Pharmacy Dispense Approval"] + D -- No --> F[" Notify for Substitution"] + E --> G[" Initiate Billing"] + G --> H{" Payment Completed?"} + H -- Yes --> I[" Medicine Dispensed"] + H -- No --> J[" Hold Dispensation"] +``` + +### Concept Diagram + +![Pharmacy Concept Diagram](../../../../static/img/care/HMIS/Pharmacy/Pharmacy%20Concept%20Diagram.svg) diff --git a/docs/care/HMIS/Pharmacy/SupplyDelivery.md b/docs/care/HMIS/Pharmacy/SupplyDelivery.md new file mode 100644 index 0000000..53ab39c --- /dev/null +++ b/docs/care/HMIS/Pharmacy/SupplyDelivery.md @@ -0,0 +1,74 @@ +### 📋 Summary + +The **Supply Delivery** resource in the CARE system records the delivery of healthcare-related items, such as medications, devices, or other supplies, to a specified location. It serves as a critical component in inventory management, ensuring accurate tracking of stock levels within healthcare facilities. + +This resource aligns with FHIR's [SupplyDelivery](https://build.fhir.org/supplydelivery.html) resource, facilitating standardized communication and interoperability in supply chain processes. + +--- + +### 🎯 Key Purpose + +- Document the delivery of healthcare items to specific locations. +- Facilitate inventory management by updating stock levels upon delivery. +- Support auditing and tracking of supply movements within the facility. +- Enable integration with supply requests and inventory systems for seamless operations.[MyDiagram](https://mydiagram.online/process-flow-diagram-healthcare/?utm_source=chatgpt.com)[HL7 Terminology+2OntoServer+2FHIR Build+2](https://tx.ontoserver.csiro.au/fhir/CodeSystem/supplydelivery-status?utm_source=chatgpt.com) + +--- + +### 🧱 Core Data Structure – Essential Fields + +- **`supply_request`**: Reference to the associated Supply Request. +- **`status`**: Current status of the delivery (e.g., in-progress, completed, abandoned, entered-in-error). +- **`status_history`**: Audit trail of status changes for the delivery. +- **`delivery_type`**: Type of supply being delivered (e.g., medication, device). +- **`stage`**: Stage of the delivery process (e.g., dispatched, received). +- **`supplied_item_quantity`**: Quantity of the item delivered. +- **`supplied_item_condition`**: Condition of the item upon delivery (e.g., intact, damaged). +- **`supplied_item`**: Reference to the specific product delivered. +- **`origin`**: Location from which the item was dispatched. +- **`destination`**: Location to which the item was delivered.[MyDiagram](https://mydiagram.online/process-flow-diagram-healthcare/?utm_source=chatgpt.com)[InterSystems Documentation](https://docs.intersystems.com/irisforhealthlatest/csp/documatic/%25CSP.Documatic.cls?CLASSNAME=HS.FHIR.DTL.vDSTU2.Model.Resource.SupplyDelivery&LIBRARY=HSCUSTOM&utm_source=chatgpt.com) + +--- + +### 🔗 Core Relationships + +| Field | Reference Resource | Description | +| ---------------- | ------------------ | -------------------------------------------- | +| `supply_request` | SupplyRequest | The original request prompting the delivery. | +| `supplied_item` | Product | The specific item being delivered. | +| `origin` | Location | The source location of the delivery. | +| `destination` | Location | The target location for the delivery. | + +--- + +### 📄 Supported Fields + +**Status Codes:** + +- `in-progress`: Delivery is currently underway. +- `completed`: Delivery has been successfully completed. +- `abandoned`: Delivery was not completed. +- `entered-in-error`: Delivery record was created in error.[IdentiMedical](https://identimedical.com/the-importance-of-hospital-inventory-management/?utm_source=chatgpt.com)[FHIR Build](https://build.fhir.org/codesystem-supplydelivery-status.html?utm_source=chatgpt.com) + +**Delivery Types:** + +- `medication`: Delivery of medication items. +- `device`: Delivery of medical devices. +- `biologically-derived-product`: Delivery of biologically derived products.[Zus Health+2FHIR Build+2FHIR Build+2](https://build.fhir.org/supplydelivery-definitions.html?utm_source=chatgpt.com) + +**Item Conditions:** + +- `intact`: Item delivered in good condition. +- `damaged`: Item delivered with damage. +- `expired`: Item delivered past its expiration date.[Medplum+3CData Software+3Karexpert+3](https://cdn.cdata.com/help/KIJ/jdbc/pg_table-supplydelivery.htm?utm_source=chatgpt.com) + +--- + +### 🔁 Functional Workflow + +1. **Initiation**: A Supply Request is finalized, prompting the creation of a corresponding Supply Delivery with the stage set to "dispatched." +2. **Dispatch**: Items are deducted from the inventory of the origin location upon dispatch. +3. **Receipt**: Upon arrival, the destination location verifies the quantity and condition of the items. +4. **Inventory Update**: If accepted, items are added to the destination's inventory. +5. **Discrepancy Handling**: If discrepancies or damages are noted, the delivery may be rejected, prompting a return to the origin and the creation of a new Supply Delivery. +6. **Audit Trail**: All status changes and actions are recorded in the status history for auditing purposes. diff --git a/docs/care/HMIS/Pharmacy/SupplyRequest.md b/docs/care/HMIS/Pharmacy/SupplyRequest.md new file mode 100644 index 0000000..1fb892f --- /dev/null +++ b/docs/care/HMIS/Pharmacy/SupplyRequest.md @@ -0,0 +1,75 @@ +### 📋 Summary + +The **Supply Request** resource in the CARE system represents a formal request for the provision of healthcare-related items such as medications, devices, or other supplies. It serves as the initial step in the supply chain workflow, capturing the intent to procure or transfer items within or between facilities. + +This resource aligns with FHIR's [SupplyRequest](https://build.fhir.org/supplyrequest.html) resource, facilitating standardized communication and interoperability in supply management processes.[FHIR Build](https://build.fhir.org/supplyrequest.html?utm_source=chatgpt.com) + +--- + +### 🎯 Key Purpose + +- Initiate requests for the supply of healthcare items. +- Facilitate inventory management by tracking requested items. +- Support logistics and procurement workflows within healthcare facilities. +- Enable integration with downstream processes such as supply delivery and inventory updates. + +--- + +### 🧱 Core Data Structure – Essential Fields + +- **`id`**: Unique identifier for the supply request. +- **`status`**: Current status of the request (e.g., draft, active, suspended, completed, entered-in-error, cancelled). +- **`category`**: Classification of the supply request (e.g., central, non-stock). +- **`priority`**: Indicates the urgency of the request (e.g., routine, urgent, asap, stat). +- **`item`**: The item being requested, represented as a reference to a resource (e.g., Medication, Device) or a code. +- **`quantity`**: The amount of the item requested. +- **`occurrence`**: The timeframe when the request should be fulfilled. +- **`authoredOn`**: Date when the request was created. +- **`requester`**: Individual or organization making the request. +- **`supplier`**: Potential suppliers who can fulfill the request. +- **`reasonCode`**: Reason for the request. +- **`deliverFrom`**: Origin location for the supply. +- **`deliverTo`**: Destination location for the supply.[FHIR Build+2Medplum+2HAPI FHIR+2](https://www.medplum.com/docs/api/fhir/resources/supplyrequest?utm_source=chatgpt.com)[InterSystems Documentation+1FHIR Build+1](https://docs.intersystems.com/irisforhealthlatest/csp/documatic/%25CSP.Documatic.cls?CLASSNAME=HS.FHIR.DTL.vSTU3.Model.Resource.SupplyDelivery&LIBRARY=HSLIB&utm_source=chatgpt.com)[FHIR Build](https://build.fhir.org/supplydelivery-definitions.html?utm_source=chatgpt.com)[Medical Packaging Inc., LLC+2FHIR Build+2IdentiMedical+2](https://build.fhir.org/resourcelist.html?utm_source=chatgpt.com) + +--- + +### 🔗 Core Relationships + +| Field | Reference Resource | Description | +| ------------- | -------------------------- | ------------------------------------------ | +| `item` | Medication, Device | The specific item being requested. | +| `requester` | Practitioner, Organization | Entity initiating the supply request. | +| `supplier` | Organization | Potential supplier to fulfill the request. | +| `deliverFrom` | Location | Origin location for the supply. | +| `deliverTo` | Location | Destination location for the supply. | + +--- + +### 📄 Supported Fields + +**Status Codes:** + +- `draft`: The request has been created but is not yet active. +- `active`: The request is currently active and awaiting fulfillment. +- `suspended`: The request has been temporarily suspended. +- `completed`: The request has been fulfilled. +- `entered-in-error`: The request was entered in error and is not valid. +- `cancelled`: The request has been cancelled. + +**Priority Levels:** + +- `routine`: Standard priority. +- `urgent`: High priority. +- `asap`: As soon as possible. +- `stat`: Immediate action required. + +--- + +### 🔁 Functional Workflow + +1. **Request Initiation**: A supply request is created by a practitioner or organization, specifying the item, quantity, and delivery details. +2. **Review and Approval**: The request is reviewed and approved by the appropriate authority within the facility. +3. **Fulfillment Planning**: Upon approval, the request is forwarded to potential suppliers or internal departments for fulfillment planning. +4. **Supply Delivery**: Once the supply is prepared, a corresponding Supply Delivery is initiated to track the movement of items. +5. **Inventory Update**: Upon receipt, the inventory at the destination location is updated to reflect the new stock levels. +6. **Request Completion**: The supply request status is updated to 'completed' to indicate fulfillment. diff --git a/docs/care/HMIS/Scheduling/AvailabilityException.md b/docs/care/HMIS/Scheduling/AvailabilityException.md new file mode 100644 index 0000000..d0d8dd1 --- /dev/null +++ b/docs/care/HMIS/Scheduling/AvailabilityException.md @@ -0,0 +1,8 @@ +### Summary + +In CARE, an **Availability Exception** represents periods when a schedulable user (e.g., a healthcare provider) is unavailable for appointments, such as during vacations, training sessions, or unforeseen absences. This concept aligns with FHIR's approach to managing non-availability through the `Schedule` and `Slot` resources. + +### Design Philosophy + +- **Explicit Non-Availability**: Clearly define periods when a provider is not available to prevent scheduling conflicts. +- **Integration with Scheduling**: Ensure that availability exceptions are considered when generating available slots for appointments. diff --git a/docs/care/HMIS/Scheduling/Encounter.md b/docs/care/HMIS/Scheduling/Encounter.md new file mode 100644 index 0000000..1c7ad92 --- /dev/null +++ b/docs/care/HMIS/Scheduling/Encounter.md @@ -0,0 +1,59 @@ +### Summary + +In CARE, an **Encounter** represents a specific interaction between a patient and healthcare provider(s) for the purpose of providing healthcare services or assessing the patient's health status. This concept aligns with FHIR's Encounter resource, which is used to record information about the actual activities that occur during a healthcare event. + +### Design Philosophy + +- **FHIR Alignment**: Utilize FHIR's `Encounter` resource to represent actual patient-provider interactions. +- **Integration with Appointments**: Link encounters to `Appointment` resources to trace the scheduling and fulfillment process. +- **Comprehensive Documentation**: Capture detailed information about the encounter, including participants, locations, reasons, and diagnoses. +- **Lifecycle Management**: Track the status of encounters through various stages, such as planned, in-progress, and completed. + +### Core Relationships + +| CARE Concept | FHIR Resource | Purpose | +| ----------------------- | ------------------ | ----------------------------------------------------------- | +| Patient | `Patient` | Represents the individual receiving care | +| Healthcare Provider | `Practitioner` | Represents the individual providing care | +| Provider Role | `PractitionerRole` | Defines the provider's role and association with a facility | +| Appointment Reservation | `Appointment` | Represents the booked appointment leading to the encounter | +| Encounter Record | `Encounter` | Captures the details of the patient-provider interaction | +| Location | `Location` | Specifies where the encounter took place | +| Service Request | `ServiceRequest` | Indicates the request that initiated the encounter | +| Diagnostic Report | `DiagnosticReport` | Contains findings resulting from the encounter | + +### Supported Fields (Encounter) + +| Field Name | Description | Example | +| ----------------- | ------------------------------------------------------------- | ------------------------------------------------ | +| `id` | Unique identifier for the encounter | `encounter-001` | +| `status` | The current status of the encounter | `in-progress` | +| `class` | Classification of the encounter (e.g., inpatient, outpatient) | `outpatient` | +| `type` | Specific type of encounter | `Consultation` | +| `serviceType` | Specific type of service provided | `General Practice` | +| `subject` | Reference to the patient involved in the encounter | `Patient/patient-001` | +| `participant` | List of participants involved in the encounter | See participant details below | +| `appointment` | Reference to the associated appointment | `Appointment/appointment-001` | +| `period` | The start and end time of the encounter | `2025-06-15T09:00:00Z` to `2025-06-15T09:30:00Z` | +| `reasonCode` | Reason for the encounter | `Routine check-up` | +| `diagnosis` | List of diagnoses relevant to the encounter | `Hypertension` | +| `location` | List of locations where the patient has been | `Clinic Room 1` | +| `serviceProvider` | The organization responsible for the encounter | `Organization/clinic-001` | + +**Participant Details:** + +Each participant includes: + +- `type`: Role of the participant (e.g., primary performer) +- `individual`: Reference to the participant (e.g., Practitioner) +- `period`: Time period during which the participant was involved +- `status`: Participation status (e.g., accepted) + +--- + +### Functional Workflow + +1. **Initiate Encounter**: When a patient arrives for a scheduled appointment, an `Encounter` resource is created to document the interaction. +2. **Record Details**: Capture information such as participants, reasons, diagnoses, and locations associated with the encounter. +3. **Update Status**: As the encounter progresses, update the `status` field to reflect its current state (e.g., in-progress, completed). +4. **Link to Outcomes**: Associate the encounter with resulting resources like `DiagnosticReport` or `Observation` to maintain a comprehensive record. diff --git a/docs/care/HMIS/Scheduling/README.md b/docs/care/HMIS/Scheduling/README.md index 1dab3b6..2d12213 100644 --- a/docs/care/HMIS/Scheduling/README.md +++ b/docs/care/HMIS/Scheduling/README.md @@ -1 +1,48 @@ # Scheduling + +## Key Concepts + +1. **Schedulable User Resource** + + – A healthcare worker (e.g., doctor, nurse) whose time can be scheduled on a facility. + +2. **Availability Exception** + + – Custom constraints or blocks (e.g., leave, holidays) applied to a Schedulable User. + +3. **Schedule** + + – Represents recurring availability patterns (e.g., daily 9 AM – 5 PM) of a Schedulable User. + +4. **Availability** + + – Specific dates/times (within a schedule) where bookings can be made. Links to **Slots**. + +5. **Token Slot** + + – A concrete, bookable time unit that can be reserved by a patient (analogous to `Slot` in FHIR). + +6. **Token Booking** + + – Represents an appointment, tied to a `Patient` and results in an `Encounter`. + +## High-Level Scheduling Flow + +Below is a simplified look at how these pieces fit together: + +```mermaid +%%{init: {'theme':'redux'}}%% +flowchart LR + A[" Facility"] --> B[" User (Doctor/Staff)"] + B --> C[" Schedule Created"] + C --> D{" Availability"} + D -- Yes --> E[" Token Slot"] + D -- No --> F[" No Slots (Holiday/Blocked)"] + E --> G[" Token Booked"] + G --> I[" Patient"] + I --> J[" Encounter Started"] +``` + +### Concept Diagram + + ![Scheduling Concept Diagram](../../../../static/img/care/HMIS/Scheduling/Scheduling%20Concept%20Diagram.svg) diff --git a/docs/care/HMIS/Scheduling/SchedulableUserResource.md b/docs/care/HMIS/Scheduling/SchedulableUserResource.md new file mode 100644 index 0000000..709dc64 --- /dev/null +++ b/docs/care/HMIS/Scheduling/SchedulableUserResource.md @@ -0,0 +1,32 @@ +### Summary + +In CARE, a **Schedulable User Resource** represents a healthcare provider (e.g., doctor, nurse) whose availability can be scheduled for patient appointments. + +This resource sits at the top of the scheduling hierarchy and governs the **availability**, **exceptions**, and **schedules** for each user. It acts as the anchor point from which **available slots** are derived and **token bookings** are made. + +### Design Philosophy + +- **Explicitly Declared Availability**: Not all users are schedulable by default — only those marked as such. +- **Facility-Scoped**: A user is schedulable within the context of a healthcare facility. +- **Encapsulates Multiple Scheduling Layers**: Availability, exceptions, and schedule patterns are defined here. + +### Core Relationships + +| Related Resource | Purpose | +| ----------------------- | ----------------------------------------------------------- | +| `Facility` | The organization within which the user operates | +| `Availability` | Repeating time blocks when this user is generally available | +| `AvailabilityException` | Overrides or cancels availability (e.g., leave, holiday) | +| `TokenSlot` | Actual bookable slots derived from the user's availability | +| `TokenBooking` | A confirmed reservation of a slot for a patient | +| `Encounter` | Generated upon successful booking? | + +### Functional Workflow + +1. A user is flagged as "schedulable" during onboarding or profile setup. +2. Admin assigns this user to a facility and defines: + - **Schedule** (recurring patterns) + - **Availability Exceptions** (leaves, conferences, holidays) +3. CARE dynamically calculates token slots based**Availability** ?and generates **Token Slots**. +4. Patients or staff can book available slots against this user. +5. Each successful booking leads to a **TokenBooking** and an **Encounter**. diff --git a/docs/care/HMIS/Scheduling/Schedule.md b/docs/care/HMIS/Scheduling/Schedule.md new file mode 100644 index 0000000..221831b --- /dev/null +++ b/docs/care/HMIS/Scheduling/Schedule.md @@ -0,0 +1,11 @@ +### Summary + +In CARE, the **Schedule** resource represents the availability of a healthcare provider (e.g., doctor, nurse) for appointments. It defines the time periods during which the provider is available to provide services. ~~This concept aligns with FHIR's `Schedule` resource~~, which serves as a container for time slots that can be booked using an appointment + +--- + +### Functional Workflow + +1. **Define Schedule**: Create a `Schedule` resource for each provider, specifying the time periods during which they are available. +2. **Generate Slots**: Within the schedule, create `Slot` resources representing specific time intervals available for booking.? +3. diff --git a/docs/care/HMIS/Scheduling/TokenBooking.md b/docs/care/HMIS/Scheduling/TokenBooking.md new file mode 100644 index 0000000..92b41ae --- /dev/null +++ b/docs/care/HMIS/Scheduling/TokenBooking.md @@ -0,0 +1,17 @@ +### Summary + +In CARE, a **Token Booking** represents the reservation of a specific time slot by a patient for a healthcare service. T~~his concept aligns with FHIR's Appointment resource~~, which describes the details of a scheduled meeting between a patient and a healthcare provider. + +### Design Philosophy + +- **Integration with Slots**: Each appointment is linked to a `Slot` resource that defines the specific time interval. +- **Status Tracking**: Monitor the status of appointments to manage workflows effectively. + +--- + +### Functional Workflow + +1. **Select Available Slot**: Patient selects an available `Slot` for the desired service. +2. **Create Appointment**: System creates an `Appointment` resource linking the patient, provider, and selected slot. +3. s. +4. **Manage Appointment**: Appointment status is updated as needed (e.g., checked-in, completed). diff --git a/docs/care/HMIS/Scheduling/TokenSlot.md b/docs/care/HMIS/Scheduling/TokenSlot.md new file mode 100644 index 0000000..536de55 --- /dev/null +++ b/docs/care/HMIS/Scheduling/TokenSlot.md @@ -0,0 +1,3 @@ +### Summary + +In CARE, a **TokenSlot** represents a specific time interval during which a healthcare provider is available for appointments. This concept aligns with FHIR's Slot resource, which defines a slot of time on a schedule that may be available for booking appointments. diff --git a/static/img/care/HMIS/Billing/Billing Concept Diagram.svg b/static/img/care/HMIS/Billing/Billing Concept Diagram.svg new file mode 100644 index 0000000..5eab60d --- /dev/null +++ b/static/img/care/HMIS/Billing/Billing Concept Diagram.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/static/img/care/HMIS/Labs/Labs Concept Diagram.svg b/static/img/care/HMIS/Labs/Labs Concept Diagram.svg new file mode 100644 index 0000000..47e8c43 --- /dev/null +++ b/static/img/care/HMIS/Labs/Labs Concept Diagram.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/static/img/care/HMIS/Pharmacy/Pharmacy Concept Diagram.svg b/static/img/care/HMIS/Pharmacy/Pharmacy Concept Diagram.svg new file mode 100644 index 0000000..205b0e0 --- /dev/null +++ b/static/img/care/HMIS/Pharmacy/Pharmacy Concept Diagram.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/static/img/care/HMIS/Scheduling/Scheduling Concept Diagram.svg b/static/img/care/HMIS/Scheduling/Scheduling Concept Diagram.svg new file mode 100644 index 0000000..8f57188 --- /dev/null +++ b/static/img/care/HMIS/Scheduling/Scheduling Concept Diagram.svg @@ -0,0 +1 @@ + \ No newline at end of file From bdba007e34d39fcc3982d3fda26be1290f2f1147 Mon Sep 17 00:00:00 2001 From: Bodhish Thomas Date: Thu, 22 May 2025 13:56:25 +0530 Subject: [PATCH 10/13] Removed outdated sections and improved field descriptions for better clarity and consistency. --- docs/care/HMIS/Labs/ActivityDefinition.md | 2 - docs/care/HMIS/Labs/ChargeItemDefinition.md | 63 +------------- docs/care/HMIS/Labs/DiagnosticReport.md | 33 -------- docs/care/HMIS/Labs/ObservationDefinition.md | 59 +++---------- docs/care/HMIS/Labs/README.md | 5 +- docs/care/HMIS/Labs/ServiceRequest.md | 53 ------------ docs/care/HMIS/Labs/Specimen.md | 14 ---- docs/care/HMIS/Labs/SpecimenDefinition.md | 84 +++++-------------- docs/care/HMIS/Pharmacy/ChargeItem.md | 56 ++++--------- .../HMIS/Pharmacy/ChargeItemDefinition.md | 56 +++++-------- docs/care/HMIS/Pharmacy/InventoryItem.md | 44 ++-------- docs/care/HMIS/Pharmacy/MedicationDispense.md | 74 +++------------- docs/care/HMIS/Pharmacy/MedicationRequest.md | 42 +++------- docs/care/HMIS/Pharmacy/Product.md | 16 +--- docs/care/HMIS/Pharmacy/ProductKnowledge.md | 8 +- 15 files changed, 117 insertions(+), 492 deletions(-) diff --git a/docs/care/HMIS/Labs/ActivityDefinition.md b/docs/care/HMIS/Labs/ActivityDefinition.md index b93c746..6e4cc78 100644 --- a/docs/care/HMIS/Labs/ActivityDefinition.md +++ b/docs/care/HMIS/Labs/ActivityDefinition.md @@ -2,8 +2,6 @@ In CARE, `ActivityDefinition` is used to define reusable **templates for clinical actions**, such as lab tests or medication requests. Each definition standardizes how a particular diagnostic activity should be instantiated at runtime — enabling consistent behavior across service requests and automated billing. -Although based on the FHIR `ActivityDefinition` resource, CARE tailors it to fit real-world facility workflows, especially for diagnostic and lab use cases. In the current scope, these templates primarily support `ServiceRequest` and `MedicationRequest`. Future versions may include orchestration through `PlanDefinition` and `RequestOrchestration`. - ### Core Relationships | Related Resource | Purpose | diff --git a/docs/care/HMIS/Labs/ChargeItemDefinition.md b/docs/care/HMIS/Labs/ChargeItemDefinition.md index f8cfb87..737ec80 100644 --- a/docs/care/HMIS/Labs/ChargeItemDefinition.md +++ b/docs/care/HMIS/Labs/ChargeItemDefinition.md @@ -16,8 +16,6 @@ CARE’s billing model works behind the scenes: **as practitioners record data ( | Field Name | Description | Example | | ----------------- | --------------------------------------------------------- | -------------------------------------- | -| `id` | Internal identifier | `charge-cbc` | -| `version` | Version number | `"1"` | | `title` | Name for human readability | `"CBC Test Standard Rate"` | | `slug` | Unique internal reference | `"cbc-charge"` | | `derivedFromUri` | Canonical URL reference if derived from standard | `"http://example.org/rates/cbc"` | @@ -28,46 +26,12 @@ CARE’s billing model works behind the scenes: **as practitioners record data ( | `code` | Internal or external billing/product code | `"CBC01"` | | `instance[]` | List of linked resources (ActivityDefinition, Medication) | `[ActivityDefinition/cbc]` | | `propertyGroup[]` | Array of pricing conditions and breakdowns | See below | - -### Property Groups & Dynamic Pricing - -Each `propertyGroup` contains: - -- **Applicability conditions**: Expressions that evaluate whether a price component should apply (e.g., “patient is above 60 years”). -- **Price components**: The base price, surcharges, discounts, or taxes applicable under those conditions. - -### Example Fields (within `propertyGroup`) - -| Field | Description | Example | -| ------------------------- | ------------------------------------------------------- | -------------------- | -| `applicability.condition` | Boolean expression for pricing applicability | `"patient.age > 60"` | -| `priceComponent[]` | Breakdown of charge (see below for `MonetaryComponent`) | See next section | - -### MonetaryComponent Specification - -```json -json -CopyEdit -{ - "type": "base", // base | surcharge | discount | tax | informational - "code": "CBC01-BASIC", - "factor": 1.0, - "amount": { - "value": 200.00, - "currency": "INR" - } -} +| `baseprice[]` | Base Charge for a lab test | See below | +| `discounts[]` | Price reduction applied to the base amount before tax | See below | +| `taxes[]` | Applicable government taxes | See below | ``` -| Field | Description | Example | -| ----------------- | ----------------------------------------------------------- | --------------- | -| `type` | Type of price item (`base`, `surcharge`, `discount`, `tax`) | `"base"` | -| `code` | Identifier for pricing rule or sub-component | `"CBC01-BASIC"` | -| `factor` | Multiplier applied to the amount | `1.0` | -| `amount.value` | Monetary value (final after applying factor) | `200.00` | -| `amount.currency` | ISO 4217 code | `"INR"` | - ### Billing Workflow in CARE 1. Practitioner creates a `ServiceRequest` for CBC. @@ -76,26 +40,5 @@ CopyEdit 4. A **charge item is instantiated** and added to the patient’s bill automatically. 5. Taxes and discounts are computed, total is stored with a detailed breakdown. -### Schema Definition? -```jsx -{ - "id" : "", // Internal Identifier - "version" : "", // Version - "title" : "", // Name for this charge item definition - "slug" : "" // - "derivedFromUri" : "", // Was this from a URL - "status" : "", // Bound to draft | active | retired | unknown - "facility" : "", // Facility where this Charge Item Definition is created - "description" : "", // Natural language description of the charge item definition - "purpose" : "", // Why this charge item definition is defined - "code" : "", // Billing code or product type this definition applies to, No valueset for now - "instance" : [{ ActivityDefinition|Medication }], // Through some M2M Table, needs to be indexed. - "propertyGroup" : [{ // Group of properties which are applicable under the same conditions - "applicability" : [{ // Whether or not the billing code is applicable - "condition" : { Expression }, // Boolean-valued expression - }], // Conditions under which the priceComponent is applicable - "priceComponent" : [{ MonetaryComponent }] // Components of total line item price - }] -} ``` diff --git a/docs/care/HMIS/Labs/DiagnosticReport.md b/docs/care/HMIS/Labs/DiagnosticReport.md index 1b0b454..dc7faf0 100644 --- a/docs/care/HMIS/Labs/DiagnosticReport.md +++ b/docs/care/HMIS/Labs/DiagnosticReport.md @@ -13,36 +13,3 @@ In the CARE MVP, diagnostic reports are generated **only from `ServiceRequest` r | `Patient` | Patient for whom the report was generated | | `Encounter` | Visit or session in which the test was performed | | `Specimen[]` | Specimens used for testing (currently ignored in MVP) | - -### Supported Fields - -| Field Name | Description | Example | -| ----------------- | --------------------------------------------------- | ---------------------------------------------- | -| `id` | Internal identifier | `drpt-00123` | -| `service_request` | Reference to the original `ServiceRequest` | `ServiceRequest/1002` | -| `status` | Current lifecycle status of the report | `final` | -| `category` | Type of diagnostic service (e.g., lab, pathology) | `laboratory` | -| `code` | Test/report type (same as SR code) | `CBC Report` | -| `patient` | Patient associated with the report | `Patient/1234` | -| `encounter` | Encounter during which the diagnostic was ordered | `Encounter/5678` | -| `specimen[]` | Specimen IDs referenced (not used functionally yet) | `["Specimen/blood-2025-01"]` | -| `result[]` | IDs of associated `Observation` resources | `["Observation/100", "Observation/101"]` | -| `note` | Additional commentary on the report | `"Repeat testing advised if symptoms persist"` | -| `conclusion` | Summary interpretation of results | `"All parameters within normal range"` | - -### File Uploads & DICOM Support - -- CARE supports **uploading attachments** to diagnostic reports (PDF, images). -- **DICOM imaging support** is planned as a plugin integration with external PACS (Picture Archiving and Communication Systems) for radiology or cardiology use cases. - -### Status Lifecycle - -| Status Code | Meaning | -| ------------------ | -------------------------------------------- | -| `registered` | Report is created but not yet populated | -| `partial` | Some results available | -| `preliminary` | Early results shared before verification | -| `final` | Completed and verified report | -| `amended` | Updates applied to a previously final report | -| `cancelled` | Report was voided | -| `entered-in-error` | Report was created in error | diff --git a/docs/care/HMIS/Labs/ObservationDefinition.md b/docs/care/HMIS/Labs/ObservationDefinition.md index f7eefda..5d58180 100644 --- a/docs/care/HMIS/Labs/ObservationDefinition.md +++ b/docs/care/HMIS/Labs/ObservationDefinition.md @@ -14,26 +14,19 @@ In CARE, this ensures consistency across lab results and helps maintain standard ### Supported Fields -| Field Name | Description | Example | -| --------------------------- | ---------------------------------------------------------- | ------------------------------------- | -| `id` | Internal identifier | `obsdef-hb` | -| `version` | Versioning control | `1` | -| `title` | Human-readable name of the observation | `Hemoglobin` | -| `slug` | Unique internal reference name | `hb-level` | -| `status` | Lifecycle status (`draft`, `active`, etc.) | `active` | -| `facility` | Facility where the definition is applicable | `Facility/medicity` | -| `description` | Clinical context or explanation | `"Hemoglobin concentration in blood"` | -| `code` | LOINC/SNOMED or internal code | `"718-7"` | -| `method` | Measurement technique (e.g., Spectrophotometry) | `"Spectrophotometry"` | -| `preferred_report_name` | Label to be used in reports and UIs | `"Hemoglobin"` | -| `permitted_data_type[]` | Allowed result types (`Quantity`, `CodeableConcept`, etc.) | `["Quantity"]` | -| `unit` | Measurement unit | `"g/dL"` | -| `normal_range_low` | Lower limit of reference range | `12.0` | -| `normal_range_high` | Upper limit of reference range | `17.5` | -| `category` | Clinical category | `laboratory` | -| `abnormal_interpretation[]` | Qualitative meanings (e.g., `L`, `H`, `A`) | `["L", "H"]` | -| `critical_range_low` | Critical alert thresholds (optional) | `7.0` | -| `critical_range_high` | | `22.0` | +| Field Name | Description | Example | +| ------------- | ----------------------------------------------- | ------------------------------------- | +| `title` | Human-readable name of the observation | `Hemoglobin` | +| `slug` | Unique internal reference name | `hb-level` | +| `description` | Clinical context or explanation | `"Hemoglobin concentration in blood"` | +| `status` | Lifecycle status (`draft`, `active`, etc.) | `active` | +| `category` | Clinical category | `laboratory` | +| `data_type` | Type of result value | `string` | +| `Loinc_Code` | LOINC or internal code | `"LOINCCode"` | +| `Body Site` | Location on the body for sample collection | `"Right Arm"` | +| `Method` | Measurement technique (e.g., Spectrophotometry) | `"Automatic"` | +| `unit` | Measurement unit | `"mmHg"` | +| `Components` | To record multiple related values | `CBC` | ### Functional Workflow @@ -43,29 +36,3 @@ In CARE, this ensures consistency across lab results and helps maintain standard - Enforces data type (e.g., Quantity) - Validates result range - Uses the `preferred_report_name` for display - -### Schema Definition? - -```jsx -{ - "id" : "", // Internal identifier - "facility" : "" // Reference to facility if present, if not present, defenition is instance wide - "version" : "", // Automatically assigned version number - "slug" : "" // To maintain uniqueness in a given facility - "title" : "", // Name for this ObservationDefinition (human friendly) - "status" : "", // Options draft | active | retired | unknown - "description" : "", // Natural language description of the ObservationDefinition - "derivedFromUri" : "", // Is this observation defenition created based on an external URI - "category" : "", // Code for observation type - "code" : "", // Code for observation, ie what is being observed - "permittedDataType" : "", // From Questionnaire - "bodySite" : "", // Body part to be observed - "method" : "", // Method used to produce the observation - "permittedUnit" : "", // Unit for quantitative results - "component" : [{ // Component results - "code" : "", // What is being observed - "permittedDataType" : "", // From Questionnaire - "permittedUnit" : "", // I Unit for quantitative results - }] -} -``` diff --git a/docs/care/HMIS/Labs/README.md b/docs/care/HMIS/Labs/README.md index 9184144..b25d1b6 100644 --- a/docs/care/HMIS/Labs/README.md +++ b/docs/care/HMIS/Labs/README.md @@ -1,7 +1,6 @@ -# Labs +# Labs & Diagnostics Module -Labs & Diagnostics Module -This overview provides a high-level understanding of how diagnostic workflows are structured in CARE — from test orders to sample collection, result entry, and billing. The subsequent pages detail each resource and its role in the system. +This overview provides a high-level understanding of how diagnostic workflows are structured in CARE — from test orders to sample collection, report generation and recording observations. The subsequent pages detail each resource and its role in the system. ## Key Concepts diff --git a/docs/care/HMIS/Labs/ServiceRequest.md b/docs/care/HMIS/Labs/ServiceRequest.md index fae44e1..458f308 100644 --- a/docs/care/HMIS/Labs/ServiceRequest.md +++ b/docs/care/HMIS/Labs/ServiceRequest.md @@ -1,56 +1,3 @@ ### Summary In FHIR, a `ServiceRequest` represents an order or proposal to perform a clinical or non-clinical action for a patient. It can lead to the creation of related resources like `Procedure`, `Observation`, `Specimen`, or `DiagnosticReport`, though these are optional and context-dependent. - -CARE supports a minimal subset of FHIR’s ServiceRequest features to keep implementation simple. As complexity and demand grow, additional features may be added. - -While FHIR allows multi-organization coordination, CARE currently restricts `ServiceRequest` handling within a single facility — cross-facility dispatch must be managed manually. - -Access control is managed via roles and permissions assigned at the organization level, with each ServiceRequest linked to one or more organizations. An audit trail is required to track user actions on each request. - -### **Schema Definition?** - -```jsx -{ -"id" : "", // Internal Identifier -"status" : "", // R! draft | active | on-hold | entered-in-error | ended | completed | revoked | unknown -"intent" : "", // R! proposal | plan | directive | order + -"category" : "", // Bound to https://build.fhir.org/valueset-servicerequest-category.html -"priority" : "", // routine | urgent | asap | stat -"do_not_perform" : "", // True if service/procedure should not be performed -"activity_definition" : "", // Points to Activity Definition if created from one -"patient" : "id|fk" , // Reference to patient -"encounter" : "id|fk", // Encounter in which the request was created -"locations" : [""], // Fk to location -"specimens" : ["id|fk"], // FK to Specimen -"bodySite" : "", // Coded location on Body -"note" : "", // Comments -"occurance" : "" // Time at which this SR should take place -"patient_instruction" : "" // Instructions to the patient -} -``` - -### **Core Data Structure** - -**Essential Fields** - -| Field | Type | Required | Description | Example | -| ------------ | ----------------- | -------- | --------------------------------------------- | ---------------------------- | -| `id` | `string` | Yes | Unique identifier for the ServiceRequest | `SR-2025-0001` | -| `status` | `code` | Yes | Request state: `draft`, `active`, `completed` | `active` | -| `intent` | `code` | Yes | Always set to `order` in CARE | `order` | -| `code` | `CodeableConcept` | Yes | Reference to test via `ActivityDefinition` | `CBC - Complete Blood Count` | -| `subject` | `Reference` | Yes | The patient for whom the request is made | `Patient/1234` | -| `encounter` | `Reference` | Yes | Clinical context | `Encounter/5678` | -| `authoredOn` | `dateTime` | Yes | When the request was created | `2025-05-21T10:00:00+05:30` | -| `requester` | `Reference` | Yes | Practitioner making the request | `Practitioner/DrAnjali` | -| `note` | `Annotation[]` | Optional | Any additional notes | `"Fasting sample preferred"` | - -### Supported Status Values - -| Status | Meaning | -| ----------- | ----------------------------------------- | -| `draft` | Incomplete and not actionable | -| `active` | Ready for specimen collection and testing | -| `completed` | Results recorded and linked | -| `cancelled` | Cancelled before lab action | diff --git a/docs/care/HMIS/Labs/Specimen.md b/docs/care/HMIS/Labs/Specimen.md index 88b3a9c..e9cc964 100644 --- a/docs/care/HMIS/Labs/Specimen.md +++ b/docs/care/HMIS/Labs/Specimen.md @@ -14,17 +14,3 @@ Specimens can optionally be **instantiated from a `SpecimenDefinition`**, inheri | `SpecimenDefinition` | (Optional) Template from which the specimen was instantiated | | `Procedure` | Procedure during which the specimen was collected | | `Observation` | Diagnostic data produced based on this specimen | - -### Supported Fields - -| Field | Description | Example | -| ----------------------- | ------------------------------------- | -------------------------------------------------------- | -| `id` | Internal system ID | `spec-2025-001` | -| `accessionIdentifier[]` | External barcodes/IDs for tracking | `["LAB-BLOOD-34567"]` | -| `status` | Status of the specimen | `available` | -| `type` | Type of material (e.g., venous blood) | `"venous blood"` | -| `subject` | Links to patient and encounter | `{ patient: "Patient/123", encounter: "Encounter/456" }` | -| `receivedTime` | When the lab received the specimen | `"2025-05-21T10:15:00+05:30"` | -| `request` | Reference to the `ServiceRequest` | `"ServiceRequest/789"` | -| `note` | Free-text comment | `"Slight hemolysis observed"` | -| `condition[]` | Physical condition of the specimen | `["room temperature", "unclotted"]` | diff --git a/docs/care/HMIS/Labs/SpecimenDefinition.md b/docs/care/HMIS/Labs/SpecimenDefinition.md index 6b5af71..ed0da97 100644 --- a/docs/care/HMIS/Labs/SpecimenDefinition.md +++ b/docs/care/HMIS/Labs/SpecimenDefinition.md @@ -16,35 +16,27 @@ This resource enables structured specimen management aligned with the FHIR speci ### Supported Fields -| Field | Description | Example | -| ----------------------- | ------------------------------------------- | ------------------------------ | -| `id` | Internal identifier | `spec-blood-001` | -| `version` | Version number of the definition | `"1"` | -| `title` | Human-readable label | `"Venous Blood"` | -| `slug` | Unique internal name | `"venous-blood"` | -| `derived_from_uri` | Reference to external source or standard | `"http://hl7.org/specs/blood"` | -| `status` | Lifecycle status (`draft`, `active`, etc.) | `"active"` | -| `facility` | Facility where this definition applies | `Facility/medicity` | -| `description` | Narrative explanation of this specimen type | `"Standard blood draw"` | -| `type_collected` | Type of specimen (bound to HL7 valuesets) | `"venous blood"` | -| `patient_preparation[]` | Pre-collection instructions (e.g., fasting) | `["SNOMED/20430005"]` | -| `collection` | Collection procedure (e.g., venipuncture) | `"SNOMED/73761001"` | - -### Substructure (Container Info) - -| Subfield | Description | Example | -| ----------------------------------- | --------------------------------------------------------- | -------------------------------- | -| `is_derived` | Whether specimen is primary or derived | `false` | -| `preference` | Preferred or alternate | `"preferred"` | -| `container.description` | Label for the container | `"Vacutainer with EDTA"` | -| `container.capacity.value` | Capacity amount | `5` | -| `container.capacity.unit` | Unit of measure | `"mL"` | -| `container.minimum_volume_quantity` | Minimum acceptable volume | `{ "value": 2, "unit": "mL" }` | -| `container.cap` | Container cap type (bound to FHIR container-cap valueset) | `"red"` | -| `container.preparation` | Special handling for the container | `"Sterile, vacuum sealed"` | -| `requirement` | Transport/handling requirements | `"Keep at 4–8°C"` | -| `retention_time` | How long specimen should be retained | `{ "value": 3, "unit": "days" }` | -| `single_use` | Whether container is single-use | `true` | +| Field | Description | Example | +| ------------------------- | ------------------------------------------- | ------------------------------ | +| `title` | Human-readable label | `"Venous Blood"` | +| `slug` | Unique internal name | `"venous-blood"` | +| `status` | Lifecycle status (`draft`, `active`, etc.) | `"active"` | +| `derived_from_uri` | Reference to external source or standard | `"http://hl7.org/specs/blood"` | +| `description` | Narrative explanation of this specimen type | `"Standard blood draw"` | +| `type_collected` | Type of specimen (bound to HL7 valuesets) | `"venous blood"` | +| `collection` | Collection procedure (e.g., venipuncture) | `"SNOMED/73761001"` | +| `patient_preparation[]` | Pre-collection instructions (e.g., fasting) | `["SNOMED/20430005"]` | +| `Is derived[]` | Whether specimen is derived or not | `[""]` | +| `Single Use[]` | Whether it is meant for a single use or not | `[""]` | +| `Specimen Type[]` | Type of specimen collected | `[""]` | +| `Preference[]` | Preferred or alternate | `[""]` | +| `Retention Time[]` | Amount of time specimen can be retained | `[""]` | +| `Requirement[]` | To add any additional requirements | `[""]` | +| `Container Description[]` | Description of container | `[""]` | +| `Cap[]` | Color of the container cap | `[""]` | +| `Capacity[]` | Capacity of container | `[""]` | +| `Minimum Quantity[]` | Minimum quantity of specimen required | `[""]` | +| `Preparation[]` | To record preparation details | `[""]` | ### Functional Workflow @@ -52,37 +44,3 @@ This resource enables structured specimen management aligned with the FHIR speci 2. **Linked via ActivityDefinition** to relevant lab tests. 3. When a lab test is initiated, **specimen instances are created** from these definitions via a dedicated API. 4. Specimen instances store a **snapshot** of definition fields to preserve traceability. - -### Schema Definition? - -```jsx -{ - "id" : "", // Internal Identifier - "version" : "", // Version of the SpecimenDefinition - "title" : "", // Name for this SpecimenDefinition (Human friendly) - "slug" : "", // Some internal Name - "derived_from_uri" : "", // Based on external definition - "status" : "", // R! draft | active | retired | unknown - "facility" : "", // Facility where this Account is created - "description" : "", // Natural language description of the SpecimenDefinition - "type_collected" : "", // Bound to Hl7 Valueset ( Unbounded ) - "patient_preparation" : ["" , ""], // Patient preparation for collection, Bound to Snomed - "collection" : "", // Specimen collection procedure, Bound to Snomed - "type_tested" : { // Specimen in container intended for testing by lab - "is_derived" : "", // Primary or secondary specimen - "preference" : "", // preferred | alternate - "container" : { // The specimen's container - "description" : "", // The description of the kind of container - "capacity" : { "value" : "" , "unit" : "" }, // The capacity of this kind of container - // minimumVolume[x]: Minimum volume. One of these 2: - "minimum_volume_quantity" : { "value" : "" , "unit" : "" }, - "minimum_volume_string" : "", - "cap" : "" // Maps to https://build.fhir.org/valueset-container-cap.html - "preparation" : "" // Special processing applied to the container for this specimen type - }, - "requirement" : "", // Requirements for specimen delivery and special handling - "retention_time" : { DurationSpec }, // The usual time for retaining this kind of specimen - "single_use" : "", // Specimen for single use only - } -} -``` diff --git a/docs/care/HMIS/Pharmacy/ChargeItem.md b/docs/care/HMIS/Pharmacy/ChargeItem.md index ade201d..9196542 100644 --- a/docs/care/HMIS/Pharmacy/ChargeItem.md +++ b/docs/care/HMIS/Pharmacy/ChargeItem.md @@ -2,10 +2,6 @@ The **Charge Item** resource in the CARE system captures financial details associated with services rendered or products supplied to a patient. It serves as a self-contained record, detailing the origin of the charge, the amount, applied discounts, taxes, and other relevant financial information. -Charge Items are intrinsically linked to both an **Account** and an **Encounter**, ensuring accurate tracking and billing within the patient's financial records. - -This resource aligns with FHIR's [ChargeItem](https://build.fhir.org/chargeitem.html) resource, facilitating interoperability and standardized billing practices.[FHIR Build](https://build.fhir.org/chargeitem.html?utm_source=chatgpt.com) - --- ### 🎯 Key Purpose @@ -13,43 +9,27 @@ This resource aligns with FHIR's [ChargeItem](https://build.fhir.org/chargeitem. - Document financial charges for services or products provided to patients. - Enable automated billing processes by linking clinical activities to financial records. - Support detailed breakdowns of charges, including taxes, discounts, and surcharges. -- Facilitate auditing and financial analysis within the healthcare facility. --- -### 🧱 Core Data Structure – Essential Fields - -- **`id`**: Internal identifier for the charge item. -- **`definition`**: Reference to the associated Charge Item Definition. -- **`status`**: Current state of the charge item (e.g., planned, billable, billed). -- **`code`**: Billing code identifying the charge. -- **`patient`**: Reference to the patient associated with the charge. -- **`encounter`**: Reference to the encounter during which the charge was incurred. -- **`facility`**: Reference to the facility where the charge item was created. -- **`quantity`**: Quantity of the service or product provided. -- **`unitPriceComponent`**: Breakdown of the unit price, including base price, taxes, and discounts. -- **`totalPriceComponent`**: Breakdown of the total price, considering quantity and other factors. -- **`total_price`**: Total monetary amount charged. -- **`overrideReason`**: Reason for any manual override of the standard pricing. -- **`service`**: Reference to the service or product that prompted the charge. -- **`account`**: Reference to the patient's account for billing purposes. -- **`note`**: Additional comments or annotations about the charge item. -- **`supportingInformation`**: Additional references supporting the charge (e.g., prescriptions, orders).[FHIR Build+13FHIR Build+13NRCeS+13](https://build.fhir.org/chargeitem.html?utm_source=chatgpt.com) - ---- - -### 🔗 Core Relationships - -| Field | Reference Resource | Description | -| ------------ | ------------------------------------- | -------------------------------------------------------- | -| `definition` | ChargeItemDefinition | Defines the pricing rules and applicability. | -| `patient` | Patient | Patient associated with the charge. | -| `encounter` | Encounter | Clinical encounter during which the charge was incurred. | -| `facility` | Organization | Facility where the charge item was created. | -| `service` | Various (e.g., Medication, Procedure) | Service or product that prompted the charge. | -| `account` | Account | Patient's account for billing purposes. | - ---- +## Core Data Structure + +### Essential Fields + +| Field | Description | Technical Notes | +| ----------------------- | --------------------------------------- | ------------------------------------------------ | +| **id** | Internal system identifier | Primary key, auto-generated | +| **definition** | Reference to the Charge Item Definition | Links to the catalog entry for this service/item | +| **status** | Current state in the billing lifecycle | Controls whether the item can be invoiced | +| **code** | Billing code for the service | Often derived from the definition | +| **patient** | Reference to the patient | Person receiving the service | +| **encounter** | Reference to the healthcare encounter | Links to the clinical context | +| **facility** | Reference to the healthcare facility | Location where service was provided | +| **quantity** | Number of units provided | Default is 1 for most services | +| **unitPriceComponent** | Price breakdown per unit | Includes base, surcharges, discounts, taxes | +| **totalPriceComponent** | Price breakdown for all units | Unit price × quantity with all components | +| **total_price** | Final calculated amount | Sum of all price components | +| **account** | Reference to the billing account | Where this charge accumulates | ### 📄 Supported Fields diff --git a/docs/care/HMIS/Pharmacy/ChargeItemDefinition.md b/docs/care/HMIS/Pharmacy/ChargeItemDefinition.md index a675822..ea5e4ef 100644 --- a/docs/care/HMIS/Pharmacy/ChargeItemDefinition.md +++ b/docs/care/HMIS/Pharmacy/ChargeItemDefinition.md @@ -15,45 +15,33 @@ This resource aligns with FHIR's [ChargeItemDefinition](https://build.fhir.org/c --- -### Core Data Structure – Essential Fields - -- **`id`**: Internal identifier for the charge item definition. -- **`version`**: Version of the charge item definition. -- **`title`**: Human-readable name for the charge item definition. -- **`slug`**: URL-friendly identifier. -- **`derivedFromUri`**: URI from which this definition is derived. -- **`status`**: Current status (e.g., draft, active, retired, unknown). -- **`facility`**: Reference to the facility where this definition is applicable. -- **`description`**: Detailed description of the charge item definition. -- **`purpose`**: Explanation of the purpose behind this definition. -- **`code`**: Billing code or product type this definition applies to. -- **`instance`**: References to specific resources (e.g., ActivityDefinition, Medication) this definition applies to. -- **`propertyGroup`**: Groups of properties applicable under certain conditions.[FHIR Build+19Medplum+19RubyDoc+19](https://www.medplum.com/docs/api/fhir/resources/chargeitemdefinition?utm_source=chatgpt.com) - ---- - ### Core Relationships -| Field | Reference Resource | Description | -| ---------- | -------------------------- | -------------------------------------------------------- | -| `facility` | Organization | Facility where the charge item definition is applicable. | -| `instance` | Various (e.g., Medication) | Resources this charge item definition applies to. | - ---- +| Related Resource | Purpose | +| ---------------------- | -------------------------------------------------- | +| `ActivityDefinition` | Resource whose execution will generate this charge | +| `Medication` | Medication product that incurs a cost | +| `Encounter`, `Patient` | Used in condition evaluation for dynamic pricing | ### Supported Fields -**Property Group:** - -- **`applicability`**: Conditions under which the price component is applicable, defined using expressions. -- **`priceComponent`**: Components that make up the total price, such as base price, surcharges, discounts, and taxes. - -**Monetary Component:** - -- **`type`**: Type of price component (e.g., base, surcharge, discount, tax, informational). -- **`code`**: Code differentiating kinds of taxes, surcharges, discounts, etc. -- **`factor`**: Factor used for calculating this component. -- **`amount`**: Monetary amount associated with this component, including value and currency.[InterSystems Documentation](https://docs.intersystems.com/irisforhealthlatest/csp/documatic/%25CSP.Documatic.cls?CLASSNAME=HS.FHIR.DTL.vR4.Model.Element.ChargeItemDefinition.propertyGroup.priceComponent&LIBRARY=HSSYS&utm_source=chatgpt.com) +| Field Name | Description | Example | +| ----------------- | --------------------------------------------------------- | -------------------------------------- | +| `title` | Name for human readability | `"CBC Test Standard Rate"` | +| `slug` | Unique internal reference | `"cbc-charge"` | +| `derivedFromUri` | Canonical URL reference if derived from standard | `"http://example.org/rates/cbc"` | +| `status` | Lifecycle status (`draft`, `active`, etc.) | `"active"` | +| `facility` | The facility where this pricing applies | `Facility/medicity` | +| `description` | Free-text description of the charge definition | `"Pricing for CBC including lab work"` | +| `purpose` | Rationale for the charge | `"Used to generate automated bills"` | +| `code` | Internal or external billing/product code | `"CBC01"` | +| `instance[]` | List of linked resources (ActivityDefinition, Medication) | `[ActivityDefinition/cbc]` | +| `propertyGroup[]` | Array of pricing conditions and breakdowns | See below | +| `baseprice[]` | Base Charge for a lab test | See below | +| `discounts[]` | Price reduction applied to the base amount before tax | See below | +| `taxes[]` | Applicable government taxes | See below | + +``` --- diff --git a/docs/care/HMIS/Pharmacy/InventoryItem.md b/docs/care/HMIS/Pharmacy/InventoryItem.md index b5c02d3..93fc98d 100644 --- a/docs/care/HMIS/Pharmacy/InventoryItem.md +++ b/docs/care/HMIS/Pharmacy/InventoryItem.md @@ -4,8 +4,6 @@ The **InventoryItem** resource represents the availability of a specific product Inventory items are automatically created and updated, typically when a supply delivery is marked as completed. -An inventory item can be marked as inactive to indicate that it is no longer actively dispensed by the pharmacy, possibly due to damage or other concerns. - --- ### Key Purpose @@ -17,45 +15,17 @@ An inventory item can be marked as inactive to indicate that it is no longer act --- -### Core Data Structure – Essential Fields - -- **`product`**: Reference to the product being tracked. -- **`status`**: Current status of the inventory item (e.g., active, inactive). -- **`location`**: Location where the product is stored. -- **`net_content`**: Quantity of the product available at the specified location. - ---- - -### Supported Status Values - -The `status` field can have the following values: - -- **`active`**: The item is active and can be referenced. -- **`inactive`**: The item is presently inactive; there may be references to it, but it is not expected to be used. -- **`entered-in-error`**: The item record was entered in error. -- **`unknown`**: The item status has not been determined.[FHIR Build+1HL7 Terminology+1](https://build.fhir.org/codesystem-inventoryitem-status.html?utm_source=chatgpt.com) - -_Source: FHIR InventoryItem Status Codes_ - ---- - -### Core Relationships - -| Field | Reference Resource | Description | -| ---------- | ------------------ | ------------------------------------------- | -| `product` | Product | The product being tracked in the inventory. | -| `location` | Location | The location where the product is stored. | - --- ### Supported Fields -| Field Name | Type | Description | -| ------------- | --------- | -------------------------------------------------- | -| `product` | Reference | Reference to the product being tracked. | -| `status` | code | Current status of the inventory item. | -| `location` | Reference | Location where the product is stored. | -| `net_content` | Quantity | Quantity of the product available at the location. | +| Field Name | Type | Description | +| ----------------- | --------- | -------------------------------------------------- | +| `product` | Reference | Reference to the product being tracked. | +| `net_content` | Quantity | Quantity of the product available at the location. | +| `status` | code | Current status of the inventory item. | +| `expiration_date` | date | date of expiry | +| `Batch` | string | Batch Number | --- diff --git a/docs/care/HMIS/Pharmacy/MedicationDispense.md b/docs/care/HMIS/Pharmacy/MedicationDispense.md index dacee3c..971b2c1 100644 --- a/docs/care/HMIS/Pharmacy/MedicationDispense.md +++ b/docs/care/HMIS/Pharmacy/MedicationDispense.md @@ -17,45 +17,6 @@ A **ChargeItem** can be associated with each dispense. By default, the **ChargeI --- -### Core Data Structure – Essential Fields - -- **`product`**: Reference to the product being dispensed. -- **`status`**: Current status of the dispense (e.g., preparation, in-progress, completed). -- **`not_performed_reason`**: Reason why the dispense was not performed. -- **`status_history`**: History of status changes for auditing purposes. -- **`category`**: Type of medication dispense (e.g., IP, OP, Home). -- **`patient`**: Reference to the patient receiving the medication. -- **`encounter`**: Reference to the encounter during which the dispense occurred. -- **`location`**: Location where the dispense took place. -- **`authorizing_prescription`**: Reference to the MedicationRequest that authorized the dispense. -- **`dispense_type`**: Type of dispensing event performed. -- **`quantity`**: Amount of medication dispensed. -- **`days_supply`**: Number of days the supply is intended to last. -- **`when_prepared`**: Time when the medication was prepared. -- **`when_handed_over`**: Time when the medication was handed over to the patient. -- **`note`**: Additional information about the dispense. -- **`dosage_instruction`**: Instructions on how the medication should be used. -- **`substitution`**: Details about any substitution made during dispensing. -- **`charge_item`**: Reference to the associated charge item. - ---- - -### Supported Status Values - -The `status` field can have the following values: - -- **`preparation`**: The core event has not started yet, but some staging activities have begun (e.g., initial compounding or packaging of medication). -- **`in-progress`**: The dispensed product is ready for pickup. -- **`cancelled`**: The dispensed product was not and will never be picked up by the patient. -- **`on-hold`**: The dispense process is paused while waiting for an external event to reactivate the dispense. -- **`completed`**: The dispensed product has been picked up. -- **`entered-in-error`**: The dispense was entered in error and therefore nullified. -- **`stopped`**: Actions implied by the dispense have been permanently halted, before all of them occurred. -- **`declined`**: The dispense was declined and not performed. -- **`unknown`**: The authoring system does not know which of the status values applies for this medication dispense. - ---- - ### Core Relationships | Field | Reference Resource | Description | @@ -71,26 +32,17 @@ The `status` field can have the following values: ### Supported Fields -| Field Name | Type | Description | -| -------------------------- | --------------- | -------------------------------------------------------- | -| `product` | Reference | Reference to the product being dispensed. | -| `status` | code | The current status of the dispense. | -| `not_performed_reason` | CodeableConcept | Reason why the dispense was not performed. | -| `status_history` | List | History of status changes for auditing purposes. | -| `category` | CodeableConcept | Type of medication dispense (e.g., IP, OP, Home). | -| `patient` | Reference | The patient receiving the medication. | -| `encounter` | Reference | The encounter associated with the dispense. | -| `location` | Reference | The location where the dispense occurred. | -| `authorizing_prescription` | Reference | The prescription that authorized the dispense. | -| `dispense_type` | CodeableConcept | Type of dispensing event performed. | -| `quantity` | Quantity | Amount of medication dispensed. | -| `days_supply` | Quantity | Number of days the supply is intended to last. | -| `when_prepared` | dateTime | Time when the medication was prepared. | -| `when_handed_over` | dateTime | Time when the medication was handed over to the patient. | -| `note` | Annotation | Additional information about the dispense. | -| `dosage_instruction` | Dosage | Instructions on how the medication should be used. | -| `substitution` | BackboneElement | Details about any substitution made during dispensing. | -| `charge_item` | Reference | Reference to the associated charge item. | +| Field Name | Type | Description | +| --------------------- | ---------- | -------------------------------------------------- | +| `medicine` | Reference | Reference to the product being dispensed. | +| `dosage_instructions` | Dosage | Instructions on how the medication should be used. | +| `select_lot` | Lot | Lot number | +| `expiry` | string | Expiry Date | +| `quantity` | Quantity | Amount of medication dispensed. | +| `days_supply` | Quantity | Number of days the supply is intended to last. | +| `price` | Amount | Price of the item | +| `discount` | Percentage | Applicable discount | +| `is_fully_dispensed` | Checkbox | Full or partial dispensed | --- @@ -103,7 +55,3 @@ The `status` field can have the following values: 5. **Billing**: A ChargeItem is associated with the dispense for billing purposes. --- - -### Substructure (Container Info) - -- **`substitution`**: Indicates whether a substitution was made during dispensing, the type of substitution, and the reason for it. diff --git a/docs/care/HMIS/Pharmacy/MedicationRequest.md b/docs/care/HMIS/Pharmacy/MedicationRequest.md index 5179ecf..fc83cf9 100644 --- a/docs/care/HMIS/Pharmacy/MedicationRequest.md +++ b/docs/care/HMIS/Pharmacy/MedicationRequest.md @@ -23,20 +23,6 @@ A [**MedicationRequest**](https://hl7.org/fhir/medicationrequest.html) is an ord --- -### Supported Status Values - -- **active**: The prescription is active and should be fulfilled. -- **on-hold**: The prescription is temporarily suspended. -- **ended**: The prescription is no longer active, and the medication should not be taken. -- **stopped**: The prescription was stopped before completion. -- **completed**: The prescription has been fully completed. -- **cancelled**: The prescription was cancelled before any administration. -- **entered-in-error**: The prescription was entered in error. -- **draft**: The prescription is in draft status and not yet active. -- **unknown**: The status of the prescription is unknown. - ---- - ### Core Relationships | Field | Reference Resource | Description | @@ -50,21 +36,19 @@ A [**MedicationRequest**](https://hl7.org/fhir/medicationrequest.html) is an ord ### Supported Fields -| Field Name | Type | Description | -| ------------------- | --------------- | -------------------------------------------------------- | -| `identifier` | Identifier | Unique identifier for the prescription. | -| `status` | code | The current status of the prescription. | -| `statusReason` | string | Reason for the current status. | -| `intent` | code | The intent of the prescription (e.g., order). | -| `priority` | code | Priority of the prescription. | -| `doNotPerform` | boolean | Indicates if the medication should not be given. | -| `category` | code | Category of the prescription (e.g., outpatient). | -| `medication` | CodeableConcept | The medication being prescribed. | -| `subject` | Reference | The patient for whom the medication is prescribed. | -| `encounter` | Reference | The encounter during which the prescription was created. | -| `authoredOn` | dateTime | When the prescription was authored. | -| `dosageInstruction` | Dosage | Instructions on how the medication should be taken. | -| `note` | string | Additional notes about the prescription. | +| Field Name | Type | Description | +| -------------- | ------------- | ---------------------------------------- | +| `Medicine` | string | Medicine name | +| `Dosage` | string | Dosage suggested | +| `Frequency` | string | Frequency of medication | +| `Duration` | string | Duration of medicine administration | +| `Instructions` | text | Additional instructions | +| `Route` | text | Administration route | +| `Site` | text | Body site | +| `Method` | text | Administration method | +| `Intent` | text | Medicine intent | +| `Authored_on` | date and time | Prescribed on | +| `Note` | text | Additional notes about the prescription. | --- diff --git a/docs/care/HMIS/Pharmacy/Product.md b/docs/care/HMIS/Pharmacy/Product.md index 5f76ac7..82d04c7 100644 --- a/docs/care/HMIS/Pharmacy/Product.md +++ b/docs/care/HMIS/Pharmacy/Product.md @@ -1,20 +1,12 @@ ### Summary -In the CARE system, a **Product** refers to any item that can be purchased from the facility. This encompasses: +A product in Care refers to anything that can be purchasable from the facility, this could be [medication](https://build.fhir.org/medication.html), [nutritional product](https://build.fhir.org/nutritionproduct.html) or consumables. All of these items can be requested through Medication request for a patient ( The terminology is confusion, but it made sense at the time ), requested products are dispensed through Medication Dispense. -- [Medications](https://build.fhir.org/medication.html) -- [Nutritional Products](https://build.fhir.org/nutritionproduct.html) -- Consumables +Since product is a culmination of multiple resources references maintained by FHIR, It should be possible to create resources of theses types when creating integrations with FHIR, the spec for the Product resource will deviate from FHIR significantly while still being able to create the individual resourse when needed. -These items can be requested for a patient through a Medication Request. Although the terminology might seem counterintuitive, this design choice was made to streamline the ordering process. +Product is an instantiation of Product Knowledge, All relevant details will always be present in Product Knowledge, the Product resource will only capture data that is unique to the particular batch in question, like batch no, expiry etc.. -Requested products are dispensed via the Medication Dispense process. - -The **Product** resource in CARE is a culmination of multiple FHIR resource references. While it deviates from FHIR's standard structure, it maintains the capability to create individual FHIR resources when necessary. - -A **Product** is an instantiation of **Product Knowledge**. All pertinent details are housed within the Product Knowledge resource, whereas the Product resource captures data unique to a specific batch, such as batch number and expiry date. - -Additionally, a Product is linked to a Charge Item Definition, facilitating the creation of Charge Items whenever the product is billed. +A Product will have a link to a charge item definition as well, this can help create charge items whenever this particular medication is billed. --- diff --git a/docs/care/HMIS/Pharmacy/ProductKnowledge.md b/docs/care/HMIS/Pharmacy/ProductKnowledge.md index 507dfaf..34b42fc 100644 --- a/docs/care/HMIS/Pharmacy/ProductKnowledge.md +++ b/docs/care/HMIS/Pharmacy/ProductKnowledge.md @@ -1,12 +1,10 @@ ### Summary -The **Product Knowledge** resource in the CARE system serves as the foundational reference for all products available within a healthcare facility. It encompasses comprehensive, context-independent information about a product, such as its classification, composition, storage guidelines, and intended use. +This resource stores all foundational information about a given product, foundational information is anything need not be duplicated across different individual products, ie ingredient lists, possible allergens, nutritional information and so on.. -This resource aligns with FHIR's [MedicationKnowledge](https://build.fhir.org/medicationknowledge.html) and [NutritionProduct](https://build.fhir.org/nutritionproduct.html) resources, providing a standardized framework for representing detailed product information. +All Products will have a Product Knowledge item in Care. -Each **Product** instance refers to a **Product Knowledge** entry, inheriting its general attributes while specifying batch-specific details like batch number and expiry date. - ---- +## Production Knowledge can be instance or facility level. ### Key Purpose From ed12265caa0f9cd7d0f1195081c67cfc7d808ff6 Mon Sep 17 00:00:00 2001 From: Bodhish Thomas Date: Thu, 22 May 2025 13:57:13 +0530 Subject: [PATCH 11/13] Refactor key concepts sections in Billing, Labs, Pharmacy, and Scheduling documentation for improved clarity and consistency. Update diagrams and enhance descriptions for better understanding of workflows. --- docs/care/HMIS/Billing/Billing.md | 37 +++++------------------ docs/care/HMIS/Labs/README.md | 4 +-- docs/care/HMIS/Pharmacy/README.md | 4 +-- docs/care/HMIS/Scheduling/Encounter.md | 15 +++++---- docs/care/HMIS/Scheduling/README.md | 35 ++++++--------------- docs/care/HMIS/Scheduling/Schedule.md | 1 - docs/care/HMIS/Scheduling/TokenBooking.md | 5 ++- 7 files changed, 33 insertions(+), 68 deletions(-) diff --git a/docs/care/HMIS/Billing/Billing.md b/docs/care/HMIS/Billing/Billing.md index 9aa722a..83a34cb 100644 --- a/docs/care/HMIS/Billing/Billing.md +++ b/docs/care/HMIS/Billing/Billing.md @@ -4,34 +4,13 @@ This overview provides a **big-picture** look at how billing data and workflows ## Key Billing Concepts -1. **Charge Item Definition** - - - **What it is:** The "catalog" or "tariff" of billable services and goods. Each definition includes a billing code, base price, optional surcharges/discounts/taxes, and applicability rules. - - **Why it matters:** Ensures consistent and accurate pricing logic for all services. - - **Where to learn more:** [Charge Item Definition Documentation](./ChargeItemDefinition) - -2. **Charge Item** - - - **What it is:** A single, **actual** billable line for a specific service/product given to a patient (e.g., a lab test, medication, X-ray). - - **Why it matters:** Records each instance of care or resource usage, along with quantity, date, and final cost. - - **Where to learn more:** [Charge Item Documentation](./ChargeItem) - -3. **Account** - - - **What it is:** A ledger or "billing bucket" that accumulates all charges and payments for a patient or purpose (e.g., an inpatient stay). - - **Why it matters:** Centralizes the financial tracking, letting you see what the patient (or insurance) owes in total. - - **Where to learn more:** [Account Documentation](./Account) - -4. **Invoice** - - - **What it is:** A formal bill grouping multiple **Charge Items** from an **Account**. Once **issued**, the system expects payment against it. - - **Why it matters:** Creates an official statement for patients or insurers, facilitating payment collection. - - **Where to learn more:** [Invoice Documentation](./Invoice) - -5. **Payment Reconciliation** - - **What it is:** A record of payments received (and how they're allocated to invoices). Also handles reversals (e.g., bounced checks). - - **Why it matters:** Keeps a detailed audit trail of all money flows, from partial payments to full settlements. - - **Where to learn more:** [Payment Reconciliation Documentation](./PaymentReconciliation) +| **Concept** | **Description** | +| -------------------------- | ------------------------------------------------------------------------------------ | +| **Charge Item Definition** | Specifies billing rules and pricing for services or products. | +| **Charge Item** | Represents a specific billable service or product provided to a patient. | +| **Account** | Aggregates all financial transactions for a patient, including charges and payments. | +| **Invoice** | Formal document summarizing charges and payments, issued to request payment. | +| **Payment Reconciliation** | Process of matching received payments with billed charges to ensure accuracy. | ## High-Level Billing Flow @@ -52,6 +31,6 @@ flowchart LR 4. **Invoice**: Groups outstanding charges into a final bill. Once issued, the charges become billed. 5. **Payment Reconciliation**: Records any incoming payment, updating the invoice and account balances accordingly. -### Concept Diagram +## Concept Diagram ![Billing Concept Diagram](../../../../static/img/care/HMIS/Billing/Billing%20Concept%20Diagram.svg) diff --git a/docs/care/HMIS/Labs/README.md b/docs/care/HMIS/Labs/README.md index b25d1b6..10cebca 100644 --- a/docs/care/HMIS/Labs/README.md +++ b/docs/care/HMIS/Labs/README.md @@ -2,7 +2,7 @@ This overview provides a high-level understanding of how diagnostic workflows are structured in CARE — from test orders to sample collection, report generation and recording observations. The subsequent pages detail each resource and its role in the system. -## Key Concepts +## Key Labs Concepts | Resource | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------- | @@ -32,6 +32,6 @@ flowchart LR I --> K[" Doctor Reviews Results"] ``` -### Concept Diagram +## Concept Diagram ![Labs Concept Diagram](../../../../static/img/care/HMIS/Labs/Labs%20Concept%20Diagram.svg) diff --git a/docs/care/HMIS/Pharmacy/README.md b/docs/care/HMIS/Pharmacy/README.md index a7421dc..8703029 100644 --- a/docs/care/HMIS/Pharmacy/README.md +++ b/docs/care/HMIS/Pharmacy/README.md @@ -1,6 +1,6 @@ # Pharmacy -## Key Concepts +## Key Pharmacy Concepts This table outlines the primary components of the CARE Pharmacy Module, detailing their roles and associated FHIR resources. | **Concept** | **FHIR Resource** | **Description** | @@ -36,6 +36,6 @@ flowchart LR H -- No --> J[" Hold Dispensation"] ``` -### Concept Diagram +## Concept Diagram ![Pharmacy Concept Diagram](../../../../static/img/care/HMIS/Pharmacy/Pharmacy%20Concept%20Diagram.svg) diff --git a/docs/care/HMIS/Scheduling/Encounter.md b/docs/care/HMIS/Scheduling/Encounter.md index 1c7ad92..9a267a4 100644 --- a/docs/care/HMIS/Scheduling/Encounter.md +++ b/docs/care/HMIS/Scheduling/Encounter.md @@ -1,13 +1,16 @@ ### Summary -In CARE, an **Encounter** represents a specific interaction between a patient and healthcare provider(s) for the purpose of providing healthcare services or assessing the patient's health status. This concept aligns with FHIR's Encounter resource, which is used to record information about the actual activities that occur during a healthcare event. +Encounters represent interactions between a patient and a healthcare provider. -### Design Philosophy +At its core, it represents a documented contact between a patient and healthcare provider, serving as a container for clinical events and activities. -- **FHIR Alignment**: Utilize FHIR's `Encounter` resource to represent actual patient-provider interactions. -- **Integration with Appointments**: Link encounters to `Appointment` resources to trace the scheduling and fulfillment process. -- **Comprehensive Documentation**: Capture detailed information about the encounter, including participants, locations, reasons, and diagnoses. -- **Lifecycle Management**: Track the status of encounters through various stages, such as planned, in-progress, and completed. +## Key Purpose + +- Document and track patient-provider interactions +- Establish context for clinical activities and observations +- Support billing and administrative workflows +- Enable care coordination across different settings +- Maintain chronological record of patient care events ### Core Relationships diff --git a/docs/care/HMIS/Scheduling/README.md b/docs/care/HMIS/Scheduling/README.md index 2d12213..6ef6a55 100644 --- a/docs/care/HMIS/Scheduling/README.md +++ b/docs/care/HMIS/Scheduling/README.md @@ -1,30 +1,15 @@ # Scheduling -## Key Concepts +## Key Scheduling Concepts -1. **Schedulable User Resource** - - – A healthcare worker (e.g., doctor, nurse) whose time can be scheduled on a facility. - -2. **Availability Exception** - - – Custom constraints or blocks (e.g., leave, holidays) applied to a Schedulable User. - -3. **Schedule** - - – Represents recurring availability patterns (e.g., daily 9 AM – 5 PM) of a Schedulable User. - -4. **Availability** - - – Specific dates/times (within a schedule) where bookings can be made. Links to **Slots**. - -5. **Token Slot** - - – A concrete, bookable time unit that can be reserved by a patient (analogous to `Slot` in FHIR). - -6. **Token Booking** - - – Represents an appointment, tied to a `Patient` and results in an `Encounter`. +| **Concept** | **Description** | +| --------------------------- | ------------------------------------------------------------------------------------------ | +| **SchedulableUserResource** | A healthcare provider (e.g., doctor, nurse) whose time can be scheduled within a facility. | +| **AvailabilityException** | Specific time periods when a provider is unavailable (e.g., leave, holidays). | +| **Schedule** | Defines recurring availability patterns (e.g., daily 9 AM – 5 PM) for a provider. | +| **Availability** | Specific dates/times within a schedule when appointments can be booked. | +| **TokenSlot** | A concrete, bookable time unit available for patient appointments. | +| **TokenBooking** | Represents a confirmed appointment, linking a patient to a specific time slot. | ## High-Level Scheduling Flow @@ -43,6 +28,6 @@ flowchart LR I --> J[" Encounter Started"] ``` -### Concept Diagram +## Concept Diagram ![Scheduling Concept Diagram](../../../../static/img/care/HMIS/Scheduling/Scheduling%20Concept%20Diagram.svg) diff --git a/docs/care/HMIS/Scheduling/Schedule.md b/docs/care/HMIS/Scheduling/Schedule.md index 221831b..1b75835 100644 --- a/docs/care/HMIS/Scheduling/Schedule.md +++ b/docs/care/HMIS/Scheduling/Schedule.md @@ -8,4 +8,3 @@ In CARE, the **Schedule** resource represents the availability of a healthcare p 1. **Define Schedule**: Create a `Schedule` resource for each provider, specifying the time periods during which they are available. 2. **Generate Slots**: Within the schedule, create `Slot` resources representing specific time intervals available for booking.? -3. diff --git a/docs/care/HMIS/Scheduling/TokenBooking.md b/docs/care/HMIS/Scheduling/TokenBooking.md index 92b41ae..e0e380c 100644 --- a/docs/care/HMIS/Scheduling/TokenBooking.md +++ b/docs/care/HMIS/Scheduling/TokenBooking.md @@ -1,6 +1,6 @@ ### Summary -In CARE, a **Token Booking** represents the reservation of a specific time slot by a patient for a healthcare service. T~~his concept aligns with FHIR's Appointment resource~~, which describes the details of a scheduled meeting between a patient and a healthcare provider. +In CARE, a **Token Booking** represents the reservation of a specific time slot by a patient for a healthcare service. It describes the details of a scheduled meeting between a patient and a healthcare provider. ### Design Philosophy @@ -13,5 +13,4 @@ In CARE, a **Token Booking** represents the reservation of a specific time slot 1. **Select Available Slot**: Patient selects an available `Slot` for the desired service. 2. **Create Appointment**: System creates an `Appointment` resource linking the patient, provider, and selected slot. -3. s. -4. **Manage Appointment**: Appointment status is updated as needed (e.g., checked-in, completed). +3. **Manage Appointment**: Appointment status is updated as needed (e.g., checked-in, completed). From 50c2b7766e261ad94d1ea346da2094911672e8df Mon Sep 17 00:00:00 2001 From: Bodhish Thomas Date: Thu, 22 May 2025 14:21:56 +0530 Subject: [PATCH 12/13] Add headers for key concepts in Labs, Pharmacy, and Scheduling documentation to enhance organization and clarity. --- docs/care/HMIS/Labs/ActivityDefinition.md | 2 ++ docs/care/HMIS/Labs/ChargeItemDefinition.md | 2 ++ docs/care/HMIS/Labs/DiagnosticReport.md | 2 ++ docs/care/HMIS/Labs/ObservationDefinition.md | 2 ++ docs/care/HMIS/Labs/ServiceRequest.md | 2 ++ docs/care/HMIS/Labs/Specimen.md | 2 ++ docs/care/HMIS/Labs/SpecimenDefinition.md | 2 ++ docs/care/HMIS/Pharmacy/ChargeItem.md | 2 ++ docs/care/HMIS/Pharmacy/ChargeItemDefinition.md | 3 +++ docs/care/HMIS/Pharmacy/InventoryItem.md | 2 ++ docs/care/HMIS/Pharmacy/MedicationDispense.md | 2 ++ docs/care/HMIS/Pharmacy/MedicationRequest.md | 2 ++ docs/care/HMIS/Pharmacy/Product.md | 2 ++ docs/care/HMIS/Pharmacy/ProductKnowledge.md | 2 ++ docs/care/HMIS/Pharmacy/SupplyDelivery.md | 2 ++ docs/care/HMIS/Pharmacy/SupplyRequest.md | 2 ++ docs/care/HMIS/Scheduling/AvailabilityException.md | 2 ++ docs/care/HMIS/Scheduling/Encounter.md | 2 ++ docs/care/HMIS/Scheduling/SchedulableUserResource.md | 2 ++ docs/care/HMIS/Scheduling/Schedule.md | 2 ++ docs/care/HMIS/Scheduling/TokenBooking.md | 2 ++ docs/care/HMIS/Scheduling/TokenSlot.md | 2 ++ 22 files changed, 45 insertions(+) diff --git a/docs/care/HMIS/Labs/ActivityDefinition.md b/docs/care/HMIS/Labs/ActivityDefinition.md index 6e4cc78..1017d1e 100644 --- a/docs/care/HMIS/Labs/ActivityDefinition.md +++ b/docs/care/HMIS/Labs/ActivityDefinition.md @@ -1,3 +1,5 @@ +# Activity Definition + ### Summary In CARE, `ActivityDefinition` is used to define reusable **templates for clinical actions**, such as lab tests or medication requests. Each definition standardizes how a particular diagnostic activity should be instantiated at runtime — enabling consistent behavior across service requests and automated billing. diff --git a/docs/care/HMIS/Labs/ChargeItemDefinition.md b/docs/care/HMIS/Labs/ChargeItemDefinition.md index 737ec80..fa5000e 100644 --- a/docs/care/HMIS/Labs/ChargeItemDefinition.md +++ b/docs/care/HMIS/Labs/ChargeItemDefinition.md @@ -1,3 +1,5 @@ +# Charge Item Definition + ### Summary The `ChargeItemDefinition` in CARE specifies **how clinical activities (like lab tests or medications) are priced**. It allows each `ActivityDefinition`, `Medication`, or other healthcare service to be tied to a dynamic billing rule that governs how much a service costs under specific conditions. diff --git a/docs/care/HMIS/Labs/DiagnosticReport.md b/docs/care/HMIS/Labs/DiagnosticReport.md index dc7faf0..c157d52 100644 --- a/docs/care/HMIS/Labs/DiagnosticReport.md +++ b/docs/care/HMIS/Labs/DiagnosticReport.md @@ -1,3 +1,5 @@ +# Diagnostic Report + ### Summary A `DiagnosticReport` in CARE provides a structured summary of the findings, interpretations, and outcomes derived from diagnostic activities such as lab tests. While the **clinical measurements themselves are stored as `Observation` resources**, the `DiagnosticReport` acts as a **wrapper** or **summary document**, linking together those observations in a meaningful context. diff --git a/docs/care/HMIS/Labs/ObservationDefinition.md b/docs/care/HMIS/Labs/ObservationDefinition.md index 5d58180..474448b 100644 --- a/docs/care/HMIS/Labs/ObservationDefinition.md +++ b/docs/care/HMIS/Labs/ObservationDefinition.md @@ -1,3 +1,5 @@ +# Observation Definition + ### Summary `ObservationDefinition` is used to define the structure and expectations of a **clinical observation or lab result**, such as "Hemoglobin level" or "Blood glucose." These definitions describe the unit, valid value range, data type, and measurement method — forming a **template** for the actual `Observation` instances recorded during diagnostics. diff --git a/docs/care/HMIS/Labs/ServiceRequest.md b/docs/care/HMIS/Labs/ServiceRequest.md index 458f308..668115f 100644 --- a/docs/care/HMIS/Labs/ServiceRequest.md +++ b/docs/care/HMIS/Labs/ServiceRequest.md @@ -1,3 +1,5 @@ +# Service Request + ### Summary In FHIR, a `ServiceRequest` represents an order or proposal to perform a clinical or non-clinical action for a patient. It can lead to the creation of related resources like `Procedure`, `Observation`, `Specimen`, or `DiagnosticReport`, though these are optional and context-dependent. diff --git a/docs/care/HMIS/Labs/Specimen.md b/docs/care/HMIS/Labs/Specimen.md index e9cc964..1a3f964 100644 --- a/docs/care/HMIS/Labs/Specimen.md +++ b/docs/care/HMIS/Labs/Specimen.md @@ -1,3 +1,5 @@ +# Specimen + ### Summary In CARE, a `Specimen` represents a **physical sample collected from a patient** for diagnostic analysis. This includes blood, urine, swabs, or tissue samples collected as part of a diagnostic process. Each specimen is associated with a patient, collected during an encounter, and typically originates from a `ServiceRequest`. diff --git a/docs/care/HMIS/Labs/SpecimenDefinition.md b/docs/care/HMIS/Labs/SpecimenDefinition.md index ed0da97..b97fb80 100644 --- a/docs/care/HMIS/Labs/SpecimenDefinition.md +++ b/docs/care/HMIS/Labs/SpecimenDefinition.md @@ -1,3 +1,5 @@ +# Specimen Definition + ### Summary `SpecimenDefinition` defines the **template or blueprint for specimen types** used in the laboratory. Instead of repeatedly defining the properties of commonly collected specimens (like blood, urine, or sputum), CARE uses `SpecimenDefinition` to maintain a central, reusable registry of specimen kinds that can be instantiated when needed. diff --git a/docs/care/HMIS/Pharmacy/ChargeItem.md b/docs/care/HMIS/Pharmacy/ChargeItem.md index 9196542..dfd4b81 100644 --- a/docs/care/HMIS/Pharmacy/ChargeItem.md +++ b/docs/care/HMIS/Pharmacy/ChargeItem.md @@ -1,3 +1,5 @@ +# Charge Item + ### 📋 Summary The **Charge Item** resource in the CARE system captures financial details associated with services rendered or products supplied to a patient. It serves as a self-contained record, detailing the origin of the charge, the amount, applied discounts, taxes, and other relevant financial information. diff --git a/docs/care/HMIS/Pharmacy/ChargeItemDefinition.md b/docs/care/HMIS/Pharmacy/ChargeItemDefinition.md index ea5e4ef..34c3d82 100644 --- a/docs/care/HMIS/Pharmacy/ChargeItemDefinition.md +++ b/docs/care/HMIS/Pharmacy/ChargeItemDefinition.md @@ -1,3 +1,5 @@ +# Charge Item Definition + ### Summary The **Charge Item Definition** resource in the CARE system outlines the billing rules and pricing details associated with healthcare services and products. It serves as a blueprint for how charges are calculated, considering various factors such as patient demographics, service context, and applicable taxes. @@ -52,3 +54,4 @@ This resource aligns with FHIR's [ChargeItemDefinition](https://build.fhir.org/c 3. **Conditional Pricing**: The system evaluates patient and encounter data against the applicability conditions to determine the appropriate pricing. 4. **Tax Calculation**: Applicable taxes are calculated based on configured tax codes and added to the total charge. 5. **Billing Integration**: The final charge, including all components, is integrated into the billing system for invoicing and payment processing. +``` diff --git a/docs/care/HMIS/Pharmacy/InventoryItem.md b/docs/care/HMIS/Pharmacy/InventoryItem.md index 93fc98d..162cde5 100644 --- a/docs/care/HMIS/Pharmacy/InventoryItem.md +++ b/docs/care/HMIS/Pharmacy/InventoryItem.md @@ -1,3 +1,5 @@ +# Inventory Item + ### Summary The **InventoryItem** resource represents the availability of a specific product at a given location. It is primarily used for inventory management within healthcare facilities, ensuring accurate tracking of stock levels for medications and other products. diff --git a/docs/care/HMIS/Pharmacy/MedicationDispense.md b/docs/care/HMIS/Pharmacy/MedicationDispense.md index 971b2c1..9c10285 100644 --- a/docs/care/HMIS/Pharmacy/MedicationDispense.md +++ b/docs/care/HMIS/Pharmacy/MedicationDispense.md @@ -1,3 +1,5 @@ +# Medication Dispense + ### Summary The **MedicationDispense** resource in FHIR records the details of medications that have been dispensed to a patient. It serves as both a completion to the workflow initiated by a MedicationRequest and as a tool for inventory management within a healthcare setting. diff --git a/docs/care/HMIS/Pharmacy/MedicationRequest.md b/docs/care/HMIS/Pharmacy/MedicationRequest.md index fc83cf9..ee4f263 100644 --- a/docs/care/HMIS/Pharmacy/MedicationRequest.md +++ b/docs/care/HMIS/Pharmacy/MedicationRequest.md @@ -1,3 +1,5 @@ +# Medication Request + ### Summary A [**MedicationRequest**](https://hl7.org/fhir/medicationrequest.html) is an order or request for both the supply of medication and instructions for its administration to a patient. It represents the prescriber's intent for a medication to be supplied and/or administered. diff --git a/docs/care/HMIS/Pharmacy/Product.md b/docs/care/HMIS/Pharmacy/Product.md index 82d04c7..b245247 100644 --- a/docs/care/HMIS/Pharmacy/Product.md +++ b/docs/care/HMIS/Pharmacy/Product.md @@ -1,3 +1,5 @@ +# Product + ### Summary A product in Care refers to anything that can be purchasable from the facility, this could be [medication](https://build.fhir.org/medication.html), [nutritional product](https://build.fhir.org/nutritionproduct.html) or consumables. All of these items can be requested through Medication request for a patient ( The terminology is confusion, but it made sense at the time ), requested products are dispensed through Medication Dispense. diff --git a/docs/care/HMIS/Pharmacy/ProductKnowledge.md b/docs/care/HMIS/Pharmacy/ProductKnowledge.md index 34b42fc..c77919a 100644 --- a/docs/care/HMIS/Pharmacy/ProductKnowledge.md +++ b/docs/care/HMIS/Pharmacy/ProductKnowledge.md @@ -1,3 +1,5 @@ +# Product Knowledge + ### Summary This resource stores all foundational information about a given product, foundational information is anything need not be duplicated across different individual products, ie ingredient lists, possible allergens, nutritional information and so on.. diff --git a/docs/care/HMIS/Pharmacy/SupplyDelivery.md b/docs/care/HMIS/Pharmacy/SupplyDelivery.md index 53ab39c..c73a276 100644 --- a/docs/care/HMIS/Pharmacy/SupplyDelivery.md +++ b/docs/care/HMIS/Pharmacy/SupplyDelivery.md @@ -1,3 +1,5 @@ +# Supply Delivery + ### 📋 Summary The **Supply Delivery** resource in the CARE system records the delivery of healthcare-related items, such as medications, devices, or other supplies, to a specified location. It serves as a critical component in inventory management, ensuring accurate tracking of stock levels within healthcare facilities. diff --git a/docs/care/HMIS/Pharmacy/SupplyRequest.md b/docs/care/HMIS/Pharmacy/SupplyRequest.md index 1fb892f..b3ff4ec 100644 --- a/docs/care/HMIS/Pharmacy/SupplyRequest.md +++ b/docs/care/HMIS/Pharmacy/SupplyRequest.md @@ -1,3 +1,5 @@ +# Supply Request + ### 📋 Summary The **Supply Request** resource in the CARE system represents a formal request for the provision of healthcare-related items such as medications, devices, or other supplies. It serves as the initial step in the supply chain workflow, capturing the intent to procure or transfer items within or between facilities. diff --git a/docs/care/HMIS/Scheduling/AvailabilityException.md b/docs/care/HMIS/Scheduling/AvailabilityException.md index d0d8dd1..13b0f09 100644 --- a/docs/care/HMIS/Scheduling/AvailabilityException.md +++ b/docs/care/HMIS/Scheduling/AvailabilityException.md @@ -1,3 +1,5 @@ +# Availability Exception + ### Summary In CARE, an **Availability Exception** represents periods when a schedulable user (e.g., a healthcare provider) is unavailable for appointments, such as during vacations, training sessions, or unforeseen absences. This concept aligns with FHIR's approach to managing non-availability through the `Schedule` and `Slot` resources. diff --git a/docs/care/HMIS/Scheduling/Encounter.md b/docs/care/HMIS/Scheduling/Encounter.md index 9a267a4..466224d 100644 --- a/docs/care/HMIS/Scheduling/Encounter.md +++ b/docs/care/HMIS/Scheduling/Encounter.md @@ -1,3 +1,5 @@ +# Encounter + ### Summary Encounters represent interactions between a patient and a healthcare provider. diff --git a/docs/care/HMIS/Scheduling/SchedulableUserResource.md b/docs/care/HMIS/Scheduling/SchedulableUserResource.md index 709dc64..e2cad05 100644 --- a/docs/care/HMIS/Scheduling/SchedulableUserResource.md +++ b/docs/care/HMIS/Scheduling/SchedulableUserResource.md @@ -1,3 +1,5 @@ +# Schedulable User Resource + ### Summary In CARE, a **Schedulable User Resource** represents a healthcare provider (e.g., doctor, nurse) whose availability can be scheduled for patient appointments. diff --git a/docs/care/HMIS/Scheduling/Schedule.md b/docs/care/HMIS/Scheduling/Schedule.md index 1b75835..f0c33cb 100644 --- a/docs/care/HMIS/Scheduling/Schedule.md +++ b/docs/care/HMIS/Scheduling/Schedule.md @@ -1,3 +1,5 @@ +# Schedule + ### Summary In CARE, the **Schedule** resource represents the availability of a healthcare provider (e.g., doctor, nurse) for appointments. It defines the time periods during which the provider is available to provide services. ~~This concept aligns with FHIR's `Schedule` resource~~, which serves as a container for time slots that can be booked using an appointment diff --git a/docs/care/HMIS/Scheduling/TokenBooking.md b/docs/care/HMIS/Scheduling/TokenBooking.md index e0e380c..118d7bc 100644 --- a/docs/care/HMIS/Scheduling/TokenBooking.md +++ b/docs/care/HMIS/Scheduling/TokenBooking.md @@ -1,3 +1,5 @@ +# Token Booking + ### Summary In CARE, a **Token Booking** represents the reservation of a specific time slot by a patient for a healthcare service. It describes the details of a scheduled meeting between a patient and a healthcare provider. diff --git a/docs/care/HMIS/Scheduling/TokenSlot.md b/docs/care/HMIS/Scheduling/TokenSlot.md index 536de55..3c875ea 100644 --- a/docs/care/HMIS/Scheduling/TokenSlot.md +++ b/docs/care/HMIS/Scheduling/TokenSlot.md @@ -1,3 +1,5 @@ +# Token Slot + ### Summary In CARE, a **TokenSlot** represents a specific time interval during which a healthcare provider is available for appointments. This concept aligns with FHIR's Slot resource, which defines a slot of time on a schedule that may be available for booking appointments. From ef277f897b3d3ada93ba9ba670006e721490200e Mon Sep 17 00:00:00 2001 From: Bodhish Thomas Date: Thu, 22 May 2025 14:28:37 +0530 Subject: [PATCH 13/13] Standardize section headers in ChargeItem, SupplyDelivery, and SupplyRequest documentation for improved readability and consistency. --- docs/care/HMIS/Pharmacy/ChargeItem.md | 8 ++++---- docs/care/HMIS/Pharmacy/SupplyDelivery.md | 12 ++++++------ docs/care/HMIS/Pharmacy/SupplyRequest.md | 12 ++++++------ 3 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/care/HMIS/Pharmacy/ChargeItem.md b/docs/care/HMIS/Pharmacy/ChargeItem.md index dfd4b81..ff647bf 100644 --- a/docs/care/HMIS/Pharmacy/ChargeItem.md +++ b/docs/care/HMIS/Pharmacy/ChargeItem.md @@ -1,12 +1,12 @@ # Charge Item -### 📋 Summary +### Summary The **Charge Item** resource in the CARE system captures financial details associated with services rendered or products supplied to a patient. It serves as a self-contained record, detailing the origin of the charge, the amount, applied discounts, taxes, and other relevant financial information. --- -### 🎯 Key Purpose +### Key Purpose - Document financial charges for services or products provided to patients. - Enable automated billing processes by linking clinical activities to financial records. @@ -33,7 +33,7 @@ The **Charge Item** resource in the CARE system captures financial details assoc | **total_price** | Final calculated amount | Sum of all price components | | **account** | Reference to the billing account | Where this charge accumulates | -### 📄 Supported Fields +### Supported Fields **Monetary Component:** @@ -44,7 +44,7 @@ The **Charge Item** resource in the CARE system captures financial details assoc --- -### 🔁 Functional Workflow +### Functional Workflow 1. **Charge Item Creation**: When a service is rendered or a product is supplied, a Charge Item is automatically generated, capturing all relevant financial details. 2. **Association with Encounter and Account**: The Charge Item is linked to the specific patient encounter and their billing account, ensuring accurate financial tracking. diff --git a/docs/care/HMIS/Pharmacy/SupplyDelivery.md b/docs/care/HMIS/Pharmacy/SupplyDelivery.md index c73a276..b1e9c4a 100644 --- a/docs/care/HMIS/Pharmacy/SupplyDelivery.md +++ b/docs/care/HMIS/Pharmacy/SupplyDelivery.md @@ -1,6 +1,6 @@ # Supply Delivery -### 📋 Summary +### Summary The **Supply Delivery** resource in the CARE system records the delivery of healthcare-related items, such as medications, devices, or other supplies, to a specified location. It serves as a critical component in inventory management, ensuring accurate tracking of stock levels within healthcare facilities. @@ -8,7 +8,7 @@ This resource aligns with FHIR's [SupplyDelivery](https://build.fhir.org/supplyd --- -### 🎯 Key Purpose +### Key Purpose - Document the delivery of healthcare items to specific locations. - Facilitate inventory management by updating stock levels upon delivery. @@ -17,7 +17,7 @@ This resource aligns with FHIR's [SupplyDelivery](https://build.fhir.org/supplyd --- -### 🧱 Core Data Structure – Essential Fields +### Core Data Structure – Essential Fields - **`supply_request`**: Reference to the associated Supply Request. - **`status`**: Current status of the delivery (e.g., in-progress, completed, abandoned, entered-in-error). @@ -32,7 +32,7 @@ This resource aligns with FHIR's [SupplyDelivery](https://build.fhir.org/supplyd --- -### 🔗 Core Relationships +### Core Relationships | Field | Reference Resource | Description | | ---------------- | ------------------ | -------------------------------------------- | @@ -43,7 +43,7 @@ This resource aligns with FHIR's [SupplyDelivery](https://build.fhir.org/supplyd --- -### 📄 Supported Fields +### Supported Fields **Status Codes:** @@ -66,7 +66,7 @@ This resource aligns with FHIR's [SupplyDelivery](https://build.fhir.org/supplyd --- -### 🔁 Functional Workflow +### Functional Workflow 1. **Initiation**: A Supply Request is finalized, prompting the creation of a corresponding Supply Delivery with the stage set to "dispatched." 2. **Dispatch**: Items are deducted from the inventory of the origin location upon dispatch. diff --git a/docs/care/HMIS/Pharmacy/SupplyRequest.md b/docs/care/HMIS/Pharmacy/SupplyRequest.md index b3ff4ec..57312ac 100644 --- a/docs/care/HMIS/Pharmacy/SupplyRequest.md +++ b/docs/care/HMIS/Pharmacy/SupplyRequest.md @@ -1,6 +1,6 @@ # Supply Request -### 📋 Summary +### Summary The **Supply Request** resource in the CARE system represents a formal request for the provision of healthcare-related items such as medications, devices, or other supplies. It serves as the initial step in the supply chain workflow, capturing the intent to procure or transfer items within or between facilities. @@ -8,7 +8,7 @@ This resource aligns with FHIR's [SupplyRequest](https://build.fhir.org/supplyre --- -### 🎯 Key Purpose +### Key Purpose - Initiate requests for the supply of healthcare items. - Facilitate inventory management by tracking requested items. @@ -17,7 +17,7 @@ This resource aligns with FHIR's [SupplyRequest](https://build.fhir.org/supplyre --- -### 🧱 Core Data Structure – Essential Fields +### Core Data Structure – Essential Fields - **`id`**: Unique identifier for the supply request. - **`status`**: Current status of the request (e.g., draft, active, suspended, completed, entered-in-error, cancelled). @@ -35,7 +35,7 @@ This resource aligns with FHIR's [SupplyRequest](https://build.fhir.org/supplyre --- -### 🔗 Core Relationships +### Core Relationships | Field | Reference Resource | Description | | ------------- | -------------------------- | ------------------------------------------ | @@ -47,7 +47,7 @@ This resource aligns with FHIR's [SupplyRequest](https://build.fhir.org/supplyre --- -### 📄 Supported Fields +### Supported Fields **Status Codes:** @@ -67,7 +67,7 @@ This resource aligns with FHIR's [SupplyRequest](https://build.fhir.org/supplyre --- -### 🔁 Functional Workflow +### Functional Workflow 1. **Request Initiation**: A supply request is created by a practitioner or organization, specifying the item, quantity, and delivery details. 2. **Review and Approval**: The request is reviewed and approved by the appropriate authority within the facility.