diff --git a/ABDM_UNIFIED_CONSULT_BUNDLE_SESSION.md b/ABDM_UNIFIED_CONSULT_BUNDLE_SESSION.md new file mode 100644 index 0000000..277c0df --- /dev/null +++ b/ABDM_UNIFIED_CONSULT_BUNDLE_SESSION.md @@ -0,0 +1,124 @@ +# Session Handover: Unified OPD Consultation Bundle & Single Care Context Integration + +**Date:** October 6, 2026 +**Status:** ✅ Complete, Deployed & Verified on Live Environment +**Target Repository:** `HMS_CI4_OLD` (`origin/main`) & `HMS-ABDM-Gateway` (`origin/AG_version`) +**Live Server:** `hms-live` (`root@hms-live`) + +--- + +## 1. Problem Statement & User Requests + +1. **Default OTP Customization**: + - The user requested updating the default sandbox OTP for ABDM care context linking to `654321` while preserving backward compatibility. +2. **Duplicate Records in PHR App (Image 5)**: + - Previously, a single OPD consultation visit generated 3 distinct records/care contexts: + - `OPD-15353-S33727-20261006` + - `PRESC-15353-S33727-20261006` + - `WELLNESS-33727-20261006` + - In the PHR application (e.g. ABHA App), this caused duplicate entries where `OPConsultation` and `WellnessRecord` appeared separately for the exact same visit. +3. **Mislabeled Invoice Records (Images 2 & 3)**: + - Older records for OPD invoices showed both `Prescription` and `Invoice` because historical rows had `hi_type = 'OPConsultRecord'` or lacked strict HI-type separation. +4. **Unified NRCES Bundle**: + - The user requested consolidating into a **single unified bundle & care context** for the OPD visit. + - The care context display must dynamically reflect the clinical contents: + `OPD Consult, Wellness, Prescription, HealthDocument` (including vitals, prescribed medicines, and scanned/uploaded files). +5. **Auto-Generate / Update on Print**: + - Automatically compile or update the FHIR record whenever the consultation form is saved or printed in HMS. + +--- + +## 2. Technical Implementation Details + +### A. NRCES FHIR R4 Specification Conformance +- **Profile**: `https://nrces.in/ndhm/fhir/r4/StructureDefinition/OPConsultRecord` +- Following the ABDM standard, an `OPConsultRecord` Document Bundle natively contains all clinical sections: + 1. **Chief Complaints**: `Condition` / complaint entries. + 2. **Physical Examination / Vitals**: `Observation` resources for Blood Pressure, Pulse, Temperature, $\text{SpO}_2$, Weight, and Height. + 3. **Problems & Diagnoses**: `Condition` resources with SNOMED CT and ICD-10 codings. + 4. **Medications / Prescriptions**: `MedicationRequest` resources with dose, frequency, and instructions. + 5. **Investigation Advice**: `ServiceRequest` for recommended tests/imaging. + 6. **Follow-Up Appointment**: `Appointment` resource for next visit date. + 7. **Document References**: `Binary` / `DocumentReference` for uploaded scans and generated prescription PDFs. +- **Bundle Meta Hardening**: + - Added required `'versionId' => '1'` and `'lastUpdated' => $issuedAt` across all builder methods in `app/Libraries/FhirR4Builder.php`. + - Validated using NRCES FHIR validator (`validate_fhir` tool): 0 structural errors. + +### B. Single Care Context & Cleanup of Redundant Records +- **File**: `app/Controllers/Opd_prescription.php` + - In `storePrescriptionFhirBundle()`, unified generation to compile only the single `OPConsultRecord`. + - Removed generation of separate `PRESC-...` and `WELLNESS-...` records. + - Automatically cleans up redundant standalone entries (`PRESC-...`, `WELLNESS-...`, and old alias patterns) from `health_records` and `opd_fhir_documents`. + - In `resolveRecentFhirPushStatus()`, relaxed session reference search to `'-S' . $sessionId . '-'`. + +### C. Clinical Component Labeling & Alias Deduplication +- **File**: `app/Controllers/AbdmGateway.php` + - In `findCareContextsForPatient()`: + - Automatically builds dynamic component labels: `OPD Consult, Wellness, Prescription - Dr. Name - Date` (dynamically appends `, HealthDocument` if external reports or scans exist). + - Length guarded to 85 characters to ensure clean display across all PHR apps. + - Registers all aliases in `$seenRefs` (`OPD-{patientId}-S{sessionId}-{cleanDate}`, `OPD-{opdId}-S{sessionId}-{visitDate}`, etc.). + - Tracks `$seenOpdSessions`: step 6c fallback suppresses any orphaned or legacy alias references matching an already processed OPD session. + +### D. ABDM Bridge Gateway HI-Type Resolution Fix +- **File**: `/var/www/html/abdm-bridge-gateway/app/Controllers/AbdmGateway.php` on `hms-live` + - Modified `resolveAbdmHiTypeFromContext()` to apply **strict prefix checking** (`INVOICE-` $\rightarrow$ `Invoice`, `OPD-` $\rightarrow$ `OPConsultation`, `WELLNESS-` $\rightarrow$ `WellnessRecord`, etc.) before loose keyword searching on the display string. + - This prevents composite titles like `"OPD Consult, Wellness"` from being misclassified into `WellnessRecord`. + +### E. Task Board Synchronization Hardening +- **File**: `app/Libraries/Abdm/Sync/AbdmTaskBoardSyncService.php` + - In `queryEligibleOpdVisits()`: sorted `opd_fhir_documents` to prioritize `OPConsultRecord` over legacy `PrescriptionRecord`. + - Standardized care context reference derivation to canonical `OPD-{patientId}-S{sessionId}-{cleanDate}`. + - In `linkAndPushOpdRecord()`: checks existing record by `care_context_reference` before inserting to prevent duplicate queued rows. + - In `syncSingleWorkTask()`: applies canonical OPD reference format and `OPConsultRecord` prioritization. + +### F. Auto-Generation on Consultation Print & PDF +- **File**: `app/Controllers/Opd.php` + - Added auto-generation / updating hook inside `opd_lettre_print()` and `opd_lettre_pdf()`. + - When the consultation letter is printed or downloaded, `storePrescriptionFhirBundle()` is invoked in the background, updating `opd_fhir_documents` and `health_records`. + +--- + +## 3. Live Verification & Database Status + +### Target Test Patient: +- **Patient ID**: `15353` (`P26081015353`) +- **ABHA Address**: `91310013085603@sbx` +- **OPD ID**: `33793` +- **Session ID**: `33727` + +### Care Context Output: +```text +V3 Care Contexts Count: 2 + [0] ref=OPD-15353-S33727-20261006 + display=OPD Consult, Wellness, Prescription - Dr. Jayashri Joshi - 06 Oct 2026 + hiType=OPConsultation + [1] ref=INVOICE-OPD-33793-2026-10-06 + display=Invoice D26100033793 (OPD - Rs 1,000.00) + hiType=Invoice +``` + +### Database `health_records` State on `hms-live`: +| id | patient_id | hi_type | care_context_reference | push_status | +|---|---|---|---|---| +| 243 | 15353 | `InvoiceRecord` | `INVOICE-OPD-33793-2026-10-06` | `linked` | +| 244 | 15353 | `OPConsultRecord` | `OPD-15353-S33727-20261006` | `local_discovery_ready` | + +*(Legacy duplicate queued rows 247, 248, 249 and stale PrescriptionRecord document 123 were deleted).* + +### Print Hook Verification: +- Executing `opd_lettre_print(33727)` completes cleanly and updates `health_records` row `244` with latest timestamp. + +--- + +## 4. Git Commits & Push Summary + +### `HMS_CI4_OLD` (`main` branch): +- `04eff5e`: Standardize OPD care context formatting and prevent duplicate session aliases +- `b0a0811`: fix(fhir): add versionId and lastUpdated to DocumentBundle meta for full NRCES conformance +- `e2bb0b1`: fix(abdm): enrich OPD and INVOICE care contexts with clinical components and bill summary +- `f367603`: fix(abdm): unify consult visit into single OPConsultRecord bundle and auto-sync on print +- `d46f222`: fix(abdm): set default sandbox linking OTP to 654321 and accept both 654321 and 123456 + +### `abdm-bridge-gateway` (`AG_version` branch on `hms-live`): +- `eff0fe6`: fix(abdm): strict prefix precedence for hiType resolution to prevent multi-component display hijacking +- Pushed to `https://github.com/infodevsofttech-admin/HMS-ABDM-Gateway.git`