docs(abdm): add care context and FHIR standards documentation and agent rules

2026-10-23 09:53:56 +05:30 · 2026-10-23 09:53:56 +05:30 · 42241beceb
commit 42241beceb
parent 45f1888227
3 changed files with 188 additions and 0 deletions
--- a/.agents/rules/abdm_standards.md
+++ b/.agents/rules/abdm_standards.md
@ -0,0 +1,39 @@
+# ABDM Integration Rules & Standards
+
+## Rule 1: Care Context & Patient Reference Formatting in ABDM Linking Payloads
+
+### Background & PHR Table Display Behavior
+In the ABDM PHR app (`phrsbx.abdm.gov.in` and official PHR apps), the records table renders the payload's `patient[].referenceNumber` field directly under the column header:
+**`Patient reference` | `Health Document Type` | `Date`**
+
+### Strict Constraint
+1. **NEVER** set or overwrite `patient[].referenceNumber` with the internal hospital UHID or patient code (e.g. `P26081015350`).
+2. **ALWAYS** set `patient[].referenceNumber` to the exact Care Context Reference (e.g. `PRESC-15350-S33765-20261023`, `OPD-15350-S33765-20261023`).
+3. If linking multiple care contexts in a single request, provide each care context with its own item in the `patient[]` array so each record displays its unique reference number in the PHR app.
+
+### Canonical Care Context Reference Standard
+- **Prescription**: `PRESC-{patient_id}-S{session_id}-{YYYYMMDD}`
+- **OPD Consultation**: `OPD-{patient_id}-S{session_id}-{YYYYMMDD}`
+- **Discharge Summary**: `DISCHARGE-{ipd_id}-{YYYYMMDD}`
+- **Diagnostic Lab**: `LAB-{patient_id}-{test_id}-{YYYYMMDD}`
+- **Diagnostic Radiology**: `RAD-{patient_id}-{rad_id}-{YYYYMMDD}`
+- **Invoice**: `INVOICE-OPD-{opd_id}-{YYYY-MM-DD}` or `INVOICE-CHG-{charge_id}-{YYYY-MM-DD}`
+- **Wellness**: `WELLNESS-{patient_id}-{YYYYMMDD}`
+- **Immunization**: `IMM-{patient_id}-{vaccine_id}-{YYYYMMDD}`
+
+---
+
+## Rule 2: Never Overwrite Structured References in Code
+In `app/Controllers/AbdmGateway.php` and the bridge gateway:
+- Do NOT use regex to detect `OPD-`, `PRESC-`, etc., and replace them with `p_code`.
+- If a caller supplies a structured care context reference as `patient_ref`, keep it intact.
+- Only fall back to `p_code` or `P-{id}` if no care context reference is provided or available.
+
+---
+
+## Rule 3: FHIR Document Generation Standards
+- All clinical FHIR documents must conform to NRCeS FHIR R4 profiles.
+- Entry[0] must always be the `Composition` resource.
+- Use valid LOINC codes for composition type and section codes.
+- Use SNOMED CT for clinical diagnoses, findings, and conditions.
+- Refer to `docs/abdm/CARE_CONTEXT_AND_FHIR_STANDARDS.md` for full implementation specifications.
--- a/AGENTS.md
+++ b/AGENTS.md
@ -0,0 +1,12 @@
+# Developer & Agent Guidelines
+
+## ABDM Standards
+For all ABDM (Ayushman Bharat Digital Mission) development, linking, Care Context management, and FHIR generation:
+- Strictly follow the standards defined in [.agents/rules/abdm_standards.md](file:///d:/Workplace/HMS_CI4_OLD/.agents/rules/abdm_standards.md)
+- Full documentation and API contract explanations: [docs/abdm/CARE_CONTEXT_AND_FHIR_STANDARDS.md](file:///d:/Workplace/HMS_CI4_OLD/docs/abdm/CARE_CONTEXT_AND_FHIR_STANDARDS.md)
+
+### Key Rules at a Glance:
+1. **Never set `patient[].referenceNumber` to internal hospital UHID (e.g. `P26081015350`).**  
+   The ABDM PHR app displays this field under its "Patient reference" table column. It MUST always be set to the specific care context reference (`PRESC-{patient_id}-S{session_id}-{YYYYMMDD}`, `OPD-{patient_id}-S{session_id}-{YYYYMMDD}`, etc.).
+2. **Never overwrite structured references with `p_code` in `AbdmGateway.php`.**
+3. **All FHIR bundles must conform to NRCeS FHIR R4 document bundle specifications.**
--- a/docs/abdm/CARE_CONTEXT_AND_FHIR_STANDARDS.md
+++ b/docs/abdm/CARE_CONTEXT_AND_FHIR_STANDARDS.md
@ -0,0 +1,137 @@
+# ABDM Care Context Reference & FHIR Standards Guide
+
+> **CRITICAL STANDARD FOR DEVELOPERS & AI ASSISTANTS**  
+> This document defines the canonical reference formatting, payload structure, and FHIR standards for all ABDM integrations in this hospital management system (HMS) and the ABDM Bridge Gateway. Any code modifications touching care contexts, linking APIs (M1, M2, M3), or FHIR bundles **must** strictly adhere to this specification.
+
+---
+
+## 1. Executive Summary: The PHR UI Table Behavior
+
+In the official ABDM PHR App (`phrsbx.abdm.gov.in` and production ABHA apps), when a user opens their linked records from a facility, the records are displayed in a table with the following headers:
+
+| Patient reference | Health Document Type | Date |
+| :--- | :--- | :--- |
+| `PRESC-15350-S33765-20261023` | Prescription | 23-October-2026 |
+| `OPD-15350-S33765-20261023` | OPConsultation | 23-October-2026 |
+| `PRESC-15350-S33764-20261022` | Prescription | 22-October-2026 |
+
+### Why `Patient reference` Displays the Care Context Reference
+In ABDM's linking API specification (`/v3/hip/link/carecontext`, `/v0.5/links/link/add-contexts`, and user-initiated `/v3/hip/link/patient/care-context/confirm`):
+```json
+{
+  "patient": [
+    {
+      "referenceNumber": "PRESC-15350-S33765-20261023",
+      "display": "Devender Singh",
+      "careContexts": [
+        {
+          "referenceNumber": "PRESC-15350-S33765-20261023",
+          "display": "Prescription - 2026-10-23"
+        }
+      ],
+      "hiType": "Prescription",
+      "count": 1
+    }
+  ]
+}
+```
+
+> [!CAUTION]
+> **DO NOT SET `patient[].referenceNumber` TO INTERNAL HOSPITAL UHID (`P26081015350`)!**  
+> If `patient[].referenceNumber` is populated with the internal UHID/patient code (`P26081015350`), the PHR application will display `P26081015350` in the "Patient reference" column instead of the distinct record reference.
+>
+> **MANDATORY RULE:**  
+> In all ABDM linking payloads (both M1 HIP-initiated and M2 user-initiated confirm), `patient[].referenceNumber` **MUST** be set to the care context reference (`PRESC-...`, `OPD-...`, `INVOICE-...`, `DISCHARGE-...`). When linking multiple contexts, create an individual patient block per care context so each record renders its exact reference number in the PHR app.
+
+---
+
+## 2. Canonical Care Context Reference Formats
+
+All care context references must follow these deterministic formats:
+
+| HI Type | Prefix | Format Pattern | Example |
+| :--- | :--- | :--- | :--- |
+| **Prescription** | `PRESC-` | `PRESC-{patient_id}-S{session_id}-{YYYYMMDD}` | `PRESC-15350-S33765-20261023` |
+| **OPD Consultation** | `OPD-` | `OPD-{patient_id}-S{session_id}-{YYYYMMDD}` | `OPD-15350-S33765-20261023` |
+| **Discharge Summary** | `DISCHARGE-` | `DISCHARGE-{ipd_id}-{YYYYMMDD}` | `DISCHARGE-450-20261023` |
+| **Diagnostic Lab** | `LAB-` | `LAB-{patient_id}-{test_id}-{YYYYMMDD}` | `LAB-15350-1082-20261023` |
+| **Diagnostic Radiology**| `RAD-` | `RAD-{patient_id}-{rad_id}-{YYYYMMDD}` | `RAD-15350-402-20261023` |
+| **Invoice / Receipt** | `INVOICE-` | `INVOICE-OPD-{opd_id}-{YYYY-MM-DD}` | `INVOICE-OPD-9102-2026-10-23` |
+| **Wellness Record** | `WELLNESS-` | `WELLNESS-{patient_id}-{YYYYMMDD}` | `WELLNESS-15350-20261023` |
+| **Immunization** | `IMM-` | `IMM-{patient_id}-{vaccine_id}-{YYYYMMDD}` | `IMM-15350-12-20261023` |
+
+### Field Components
+- `{patient_id}`: Primary key integer from `patient_master.id` (e.g. `15350`).
+- `S{session_id}`: Primary key integer from `opd_session.id` or `opd_details.id` prefixed with `S` (e.g. `S33765`). If session is absent, use `S0`.
+- `{YYYYMMDD}`: Date of visit or service in compact 8-digit ISO format (e.g. `20261023`).
+
+---
+
+## 3. Implementation Rules in Code
+
+### A. HMS Backend (`app/Controllers/AbdmGateway.php`)
+1. **Never Overwrite in `hipLinkCareContext`**:
+   Do NOT inspect `patient_ref` with regex and strip `PRESC-` or `OPD-` to replace with `p_code`.
+   ```php
+   // CORRECT:
+   if (empty($body['patient_ref']) || $body['patient_ref'] === $body['abha_address']) {
+       $firstContextRef = (string) ($body['care_contexts'][0]['ref'] ?? $body['care_contexts'][0]['referenceNumber'] ?? '');
+       $body['patient_ref'] = $firstContextRef !== '' ? $firstContextRef : (!empty($patientRow['p_code']) ? $patientRow['p_code'] : 'P-' . $patientId);
+   }
+   ```
+2. **Preserve in `m2LinkConfirm`**:
+   The response patient block must use the care context reference:
+   ```php
+   $confirmedPatientRef = (! empty($confirmedContexts[0]['referenceNumber'])) ? (string) $confirmedContexts[0]['referenceNumber'] : $patientRef;
+   return $this->response->setJSON([
+       'ok' => 1,
+       'message' => 'Care contexts linked successfully',
+       'patient' => [
+           'referenceNumber' => $confirmedPatientRef,
+           'display' => $patientDisplay,
+           'careContexts' => $confirmedContexts,
+       ],
+   ]);
+   ```
+
+### B. Bridge Gateway (`dispatchCareContextLink` & `hipLinkCareContextSubmit`)
+In the bridge gateway (`/mnt/volume_blr1_1790148792836_eatria/www/abdm-bridge-gateway/app/Controllers/AbdmGateway.php`):
+1. In `dispatchCareContextLink()`, `$patientRefNumber` is resolved to `$record->care_context_reference`.
+2. In `hipLinkCareContextSubmit()`, each care context in `$careContexts` is mapped to its own `$patientList` item where:
+   `'referenceNumber' => $ref`
+   `'careContexts' => [['referenceNumber' => $ref, 'display' => $cleanDisp]]`
+
+---
+
+## 4. FHIR R4 Bundle Standards
+
+All health records pushed to the bridge and shared with ABDM HIU/PHR must conform to **NRCeS FHIR Release 4**:
+
+1. **Bundle Structure**:
+   - `resourceType`: `"Bundle"`
+   - `type`: `"document"`
+   - `identifier`: System `https://www.e-atria.in/bundle-id`, value matching `{hiType}-{recordId}-{timestamp}`.
+   - `timestamp`: ISO 8601 UTC / IST with timezone offset.
+   - First entry (`entry[0]`) **must** be the `Composition` resource.
+
+2. **Composition Resource**:
+   - `status`: `"final"`
+   - `type`: Appropriate LOINC code (e.g. `57833-6` for Prescription, `11488-4` for Consultation Note, `18842-5` for Discharge Summary).
+   - `subject`: Reference to `Patient` resource (`urn:uuid:patient-{id}`).
+   - `author`: Reference to `Practitioner` and/or `Organization`.
+   - `section`: Structured sections with LOINC narrative codes and entries referencing clinical resources (`MedicationRequest`, `Condition`, `Observation`, etc.).
+
+3. **Terminology Standards**:
+   - Diagnoses / Findings: **SNOMED CT** (`http://snomed.info/sct`).
+   - Lab / Radiology Tests: **LOINC** (`http://loinc.org`).
+   - Medications: Clean Indian Pharmacopoeia / brand / generic names with dosage instructions.
+
+---
+
+## 5. Verification Checklist
+
+Whenever modifying any linking, sync, or FHIR generation code:
+- [ ] Are care context references structured as `{PREFIX}-{PATIENT_ID}-S{SESSION_ID}-{YYYYMMDD}`?
+- [ ] Is `patient[].referenceNumber` set to the care context reference rather than the hospital UHID (`P26081015350`)?
+- [ ] Does the PHR App display `PRESC-...` or `OPD-...` under the "Patient reference" column?
+- [ ] Does `php -l` pass with zero syntax errors on both HMS and Bridge controllers?