Fix doctor assignment & reassignment workflow with proper consultation state validation

Merge Request

Overview

This MR fixes the doctor assignment and reassignment workflow in the eHRS system by separating assign vs reassign logic, enforcing consultation state rules, and ensuring consistency between consultation and queue records.

---

What does this MR do and why?

Previously, the system had issues where:

• Doctor reassignment was attempted during active consultation stages
• /assign-doctor endpoint was used for both assign and reassign
• Multiple active consultations could be created for a single patient
• Queue and consultation doctor mappings could become inconsistent
• Backend startup configuration was incorrect

This MR introduces a clear separation between assignment and reassignment workflows, enforces strict consultation lifecycle validation, and ensures queue synchronization.

---

Changes Made

• Updated assign_patient_to_consultation:

  • Always creates a new consultation and queue record
  • Removed logic that updated existing active consultations

• Implemented reassign_doctor_for_consultation:

  • Updates doctor_id in both consultation and latest queue record

• Added queue lookup:

  • Fetch latest queue using book_no and camp_visit_id
  • Ensures doctor consistency between queue and consultation

Technical Details

Root Cause:

• Mixing assign and reassign logic caused inconsistent state transitions
• No validation for consultation status
• Lack of constraint on active consultations

Fix Approach:

• Separated responsibilities:

  • Assign → create new consultation
  • Reassign → update existing consultation

• Introduced state-based validation

• Synced queue and consultation records

---

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ♻️ Refactor (no functional changes)
• 🔧 Configuration change

---

Related Issues / References

• Fixes doctor reassignment issue in consultation queue
• Prevents duplicate active consultations
• Aligns queue and consultation mapping

---

Screenshots or Screen Recordings

Before:

After:

How to Validate Locally

1. Start backend:

   cd ehrs-fastapi
   uv run main.py

2. Start frontend:

   cd ehrs-frontend-vite
   npm run dev

3. Test scenarios:

   • Assign doctor → new consultation created
   • Attempt duplicate assign → blocked
   • Reassign doctor in WAITING → success
   • Reassign during consultation → blocked
   • Verify queue doctor_id updates correctly

---

Testing Done

• Unit tests updated
• API endpoint tested

Test Cases Covered:

Scenario	Expected Result	Status
Assign doctor	New consultation created	✅
Duplicate assign	Error returned	✅
Valid reassignment	Doctor updated	✅
Invalid reassignment	400 error	✅

Code Quality Checklist

Code Standards

• Code follows project conventions
• No unused imports or debug code
• No duplicate logic
• Type hints properly defined
• Ruff checks pass

Python & FastAPI Best Practices

• Functions follow single responsibility
• Proper validation implemented
• SQLAlchemy queries optimized
• Error handling added

API Design

• RESTful structure maintained
• Proper status codes used
• Input validation added

Database & Migrations

• No schema changes required
• Data consistency ensured

Security

• No sensitive data exposed
• ORM used (no raw SQL)

Error Handling

• Proper HTTP exceptions used
• User-friendly messages returned

---

Known Limitations / Technical Debt

• Audit logging for doctor reassignment not yet implemented
• State machine for consultation lifecycle can be further improved

---

Additional Notes

This MR ensures a clean and scalable consultation workflow by enforcing strict separation between assignment and reassignment logic while maintaining data integrity.

---

MR Acceptance Checklist

Quality & Correctness

• Code works as intended
• No regressions introduced
• Edge cases handled

Maintainability

• Code is clean and modular
• Easy to extend in future

Acceptance Review

• Reviewed by teammate
• Reviewed by product owner