docs: add session handover for unified OPD consult bundle and care context
This commit is contained in:
parent
04eff5e5ba
commit
8d00536d3b
124
ABDM_UNIFIED_CONSULT_BUNDLE_SESSION.md
Normal file
124
ABDM_UNIFIED_CONSULT_BUNDLE_SESSION.md
Normal file
|
|
@ -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`
|
||||||
Loading…
Reference in New Issue
Block a user