devsofttech_hms_ci4/.agents/rules/hms_billing_standards.md

HMS Billing & Revenue Standards

This document defines the architectural and database rules for all OPD, IPD, Diagnostics, and Pharmacy billing in the E-Atria HMS.

---

1. Core Billing Table Schema & Roles

Table Name	Primary Role	Key Columns
invoice_master	Master bill/invoice record for OPD, IPD, and Lab visits	id, invoice_no, patient_id, doctor_id, total_amount, discount_amount, tax_amount, net_amount, paid_amount, balance_amount, status, payment_mode, created_date
invoice_item	Line items for services, doctor visits, procedures, lab investigations	id, invoice_id, item_type, item_id, item_name, item_rate, qty, amount, discount, net_amount, doctor_id, created_at
payment_history	Multi-tender transaction log (Cash, UPI, Card, NetBanking, Cheque)	id, invoice_id, patient_id, amount, payment_mode, transaction_ref, bank_source_id, received_by, payment_date
ipd_invoice_item	Dynamic daily IPD charges (room rent, nursing, doctor rounds, procedures)	id, ipd_id, item_type, item_id, item_name, item_rate, item_qty, item_amount, doc_id, doc_name, date_item
doc_opd_fee	OPD consultation fee slab configured per doctor	id, doc_id, doc_fee_type, doc_fee_desc, amount
doc_ipd_fee	IPD visit fee slab configured per doctor	id, doc_id, doc_fee_type, doc_fee_desc, amount, isdelete
sales_master	Pharmacy sales invoice master	id, bill_no, patient_id, opd_id, ipd_id, total, discount, net_amount, paid_amount, created_at

---

2. Inviolable Financial Integrity Rules

1. Balance Equation Strictness: For every invoice in invoice_master:

   \text{net\_amount} = \text{total\_amount} - \text{discount\_amount} + \text{tax\_amount}

   \text{balance\_amount} = \text{net\_amount} - \text{paid\_amount}

   • Any transaction modifying line items or applying discounts MUST atomically update invoice_master.net_amount and invoice_master.balance_amount.

2. Every Receipt Must Have a Ledger Entry:

   • Whenever money is collected (cash, UPI, card, bank transfer, advance), an entry MUST be inserted into payment_history.
   • Never update invoice_master.paid_amount without inserting a corresponding row in payment_history.
   • The sum of payments in payment_history for an invoice_id must always equal invoice_master.paid_amount.

3. Status Transitions:

   • UNPAID: \text{paid\_amount} = 0
   • PARTIAL: 0 < \text{paid\_amount} < \text{net\_amount}
   • PAID: \text{paid\_amount} \ge \text{net\_amount}
   • CANCELLED: Only permitted when reversed with reason log and audit user ID.

4. IPD Running Charges to Final Invoice:

   • IPD patients accumulate daily charges in ipd_invoice_item (room tariff, daily doctor rounds, medication, nursing care).
   • Upon discharge billing, all unbilled items from ipd_invoice_item and approved advances from payment_history are aggregated into the final settlement invoice in invoice_master.
   • Once finalized, items in ipd_invoice_item must be marked as billed/settled to prevent double billing.

5. Discount Governance:

   • Any discount greater than zero requires discount_reason and must be authorized by an authorized user (discount_approved_by).
   • Doctors or cashiers cannot grant unauthorized ad-hoc discounts without an audit trail.

6. Patient Full Name Standard:

   • In invoices and receipts, the patient's name MUST be fetched from patient_master.p_fname.
   • Never query or write to patient_master.p_lname (permanently dropped).