Skip to content

Multi-Doctor Consultation & Queue Synchronization Refactor

Vandana reddy Balannagari requested to merge fix/change-reassign into fix/develop

Merge Request: Multi-Doctor Consultation & Queue Synchronization Refactor

Overview

This MR refactors the patient consultation service and queue management to support visits involving multiple doctors. It resolves the "single-session lockout" issue and ensures that patient records in the queue are always synchronized with the correctly assigned doctor's specialization.

What does this MR do and why?

Motivation

In multi-specialty camps, patients often require consultations from multiple doctors (e.g., General → Dentist). The previous implementation enforced a cycle-based restriction, which prevented updates to earlier consultations and broke multi-doctor workflows.

Approach

  • Removed restrictive cycle-based validation from the consultation service.
  • Introduced dynamic specialization synchronization during doctor reassignment.
  • Enabled handling of multiple active consultations within a single visit.

Trade-offs

  • Implemented PostgreSQL-specific DISTINCT ON logic to ensure unique patient entries in queues.
  • Requires strict ORDER BY alignment for consistent results.

Changes Made

Services Modified

app/services/patient_consultation_service.py

  • Removed cycle_number restriction in validate_consultation_status_for_prescription_modification
  • Added automatic queue specialization synchronization in reassign_doctor_for_consultation

app/services/consultation_queue_service.py

  • Implemented distinct(ConsultationQueue.book_no) in get_all_active_queue

Technical Details

Bug Fix

Resolved a race condition where reassigning a doctor updated only the doctor ID but not the specialization in the queue. This caused patients to disappear from filtered queues. ✔ Now specialization is updated immediately during reassignment.

Architecture

  • Shifted to a multi-active consultation model
  • All consultations within a visit are treated as active
  • Volunteers/pharmacists can update or verify any consultation independently

Type of Change

  • ✨ New feature (non-breaking change)
  • 🐛 Bug fix (non-breaking fix)
  • ♻️ Refactor (internal improvement)

Related Issues / References

  • Closes: Backend Support for Referral Flow
  • Fixes: Queue Specialization Mismatch on Reassign

Screenshots / Recordings

image image image

Manual verification of /api/v1/queue/all confirms:

  • Unique Book Numbers
  • No duplicate entries after multiple referrals (e.g., Book #18 (closed))

How to Validate Locally

Scenario 1: Referral

  • Trigger doctor reassignment for an existing visit
  • Verify consultation_queue updates specialization correctly

Scenario 2: Multi-Prescription

  • Create two consultations under one visit
  • Update prescription for the first consultation ✔ Should succeed (previously failed with 400 error)

Scenario 3: Queue Deduplication

  • Run:
SELECT * FROM consultation_queue;
  • Then call:
GET /api/v1/queue/all

✔ Only one entry per patient should appear

Testing Done

  • ✔ Manual API validation using PostgreSQL queries
  • ✔ Unit/Integration tests for consultation service

Test Cases Covered

Scenario Expected Result Status
Reassign Doctor Queue specialization updates correctly ✅
Update Old Prescription No cycle restriction, update succeeds ✅
Get All Active Queue Unique Book Numbers returned ✅

Test Commands Run

pytest app/tests/services/test_patient_consultation_service.py

Code Quality Checklist

Code Standards

  • Code follows naming and structural conventions
  • No debug statements or commented-out code
  • Proper type hints implemented

Python & FastAPI Best Practices

  • Async/await used correctly
  • SQLAlchemy queries optimized
  • Clear and safe error handling (detail messages)

Database & Migrations

  • Data integrity maintained via visit-consultation relationships
  • Indexes on book_no and camp_visit_id verified

closes #104 (closed)

Merge request reports