Skip to content

feat : medicinepickupby and counsellingdoneby saving in db

Lakshy Yarlagadda requested to merge feat/recorduseratpickup into develop

Merge Request

Overview

This MR aligns the backend consultation workflow with the current queue model and introduces a dedicated medicine pickup claim stage.

It resolves the drift between:

  • queue enums
  • visit-status enums
  • API transitions
  • database state

This mismatch was causing:

  • invalid workflow transitions
  • skipped or disappearing patient queues
  • stale consultation lookups
  • volunteer pickup conflicts

This MR introduces a new backend-supported queue flow:

medicine_prescribing -> medicine_pickup_waiting -> medicine_pickedup -> medicine_verification

This change is required so that one volunteer can safely claim a patient for medicine pickup before the actual pickup is confirmed, while keeping the workflow consistent across models, services, APIs, websockets, and migrations.

What does this MR do and why?

The motivation behind this change was repeated workflow breakage caused by mismatched status names and incomplete backend workflow handling.

The system previously contained a mix of legacy and active statuses, and the post-consultation stages were not fully represented.

Approach Taken

  • normalized queue and visit workflow handling around the active status set
  • introduced a queue-only claim stage for medicine pickup
  • consolidated queue-related schema evolution into a single migration
  • updated service-layer transition validation and synchronization
  • fixed current-camp/current-visit resolution to target the correct active visit
  • extended test coverage for the updated flow

Trade-offs

  • some backward compatibility logic is retained for legacy status names
  • live databases with stale Alembic stamps may require migration stamp correction during rollout

Changes Made

Files Added / Modified

  • alembic/versions/d1e2f3a4b5c6_add_visit_pickup_counsel_attribution.py
  • app/models/consultation_queue.py
  • app/models/patient_visit_details.py
  • app/api/v1/routes/consultation_queue_routes.py
  • app/api/v1/routes/consultations_routes.py
  • app/api/v1/routes/patient_routes.py
  • app/services/consultation_queue_service.py
  • app/services/current_camp_service.py
  • app/services/doctor_service.py
  • app/services/medical_camp_service.py
  • app/services/medicine_service.py
  • app/services/patient_consultation_service.py
  • app/services/patient_service.py
  • app/services/analytics_service.py
  • app/websockets/consultation_queue_websocket_manager.py
  • app/websockets/socketio_queue_manager.py
  • related tests under:
    • tests/test_api
    • tests/test_models
    • tests/test_services

New Models / Services / Utilities

New queue status

  • QueueStatusEnum.medicine_pickup_waiting

Attribution fields

  • medicine_pickedup_by
  • counselling_done_by

Volunteer claim flow

  • uses assigned_by for volunteer ownership

API Endpoint Changes

Updated queue transitions:

  • in_consultation -> medicine_prescribing
  • medicine_prescribing -> medicine_pickup_waiting
  • medicine_pickup_waiting -> medicine_pickedup
  • medicine_pickedup -> medicine_verification
  • medicine_verification -> counselling
  • counselling -> completed

Configuration / Schema Changes

  • consolidated migration promoted as latest Alembic head
  • queue enum updated with medicine_pickup_waiting

Technical Details

Root Cause

The issue was caused by:

  • mixed legacy and current statuses across models and routes
  • no dedicated pickup-claim stage
  • stale current-camp/current-visit resolution
  • enum drift between database and backend code

Fix Implementation

This MR addresses the issue by:

  • centralizing transition rules in consultation_queue_service.py
  • introducing medicine_pickup_waiting
  • using volunteer ownership before actual pickup confirmation
  • recording actor attribution
  • aligning websocket broadcasts and patient status APIs
  • updating all related tests

Architecture Decisions

  • medicine_pickup_waiting is queue-only
  • it is not added to visit-status enum
  • transient claim states remain queue-scoped
  • completed workflow states sync to visit status

Database Schema Changes

  • latest migration: d1e2f3a4b5c6
  • queue enum includes medicine_pickup_waiting
  • visit details store attribution fields

Type of Change

  • 🐛 Bug fix
    • ✨ New feature
    • 💥 Breaking change
    • 📝 Documentation update
    • ♻️ Refactor
    • ⚡ Performance improvement
    • 🧪 Test update
    • 🔧 Configuration change
    • 🚨 Security fix
    • 🗑️ Deprecation

Related Issues / References

  • Closes #123
  • Fixes #456
  • Related to !789

Screenshots or Screen Recordings

For API validation, include:

  • /docs screenshots
  • test run output screenshots
  • curl / Postman examples for:
    • medicine_pickup_waiting
    • medicine_pickedup
    • medicine_verification

How to Validate Locally

Previous Behavior

  • patients skipped post-consultation queues
  • queue transitions failed due to enum drift
  • no volunteer claim stage existed

Validation Steps

docker compose up --build -d

.venv/bin/alembic heads

docker compose exec db psql -U postgres -d medical_camp -Atc "SELECT version_num FROM alembic_version;"

Workflow Validation

Move patient through:

waiting -> in_consultation -> medicine_prescribing -> medicine_pickup_waiting -> medicine_pickedup -> medicine_verification -> counselling -> completed

New Behavior

  • explicit queue progression
  • volunteer ownership before pickup
  • consistent patient status API ordering

Testing Done

Test Cases Covered

Scenario Expected Result Status
consultation → prescribing succeeds ✅
prescribing → pickup waiting enters queue ✅
pickup waiting → picked up volunteer claim works ✅
picked up → verification validation enforced ✅
patient status ordering correct sequence ✅
fresh migration succeeds ✅

Test Commands Run

.venv/bin/pytest tests/test_services/test_consultation_queue_service.py \ tests/test_services/test_patient_consultation_service.py \ tests/test_api/test_consultation_queue_routes.py \ tests/test_api/test_patient_routes.py \ tests/test_models/test_model_definitions.py -q

.venv/bin/pre-commit run --all-files

npm run build

Known Limitations / Technical Debt

  • stale Alembic stamps may require manual correction
  • legacy compatibility logic still retained
  • raw SQL remains in migration enum rebuild flow

Additional Notes

This MR intentionally combines:

  • workflow normalization
  • pickup-claim stage
  • migration cleanup

because these changes are tightly coupled.

MR Acceptance Checklist

Quality & Correctness

  • Works as intended
    • No regressions introduced
    • Edge cases handled

Maintainability

  • Readable and organized
    • Well tested
    • Follows project conventions

Acceptance Review

  • Reviewed by teammate
    • Reviewed by product owner
Edited by Lakshy Yarlagadda

Merge request reports