Lakshy Yarlagadda requested to merge feat/vitals_waiting into develop Apr 04, 2026

Merge Request

Overview

This MR aligns the frontend volunteer queue workflow with the current patient journey by comparing the complete branch against develop.

The branch introduces a new Vitals Waiting Queue, expands the medicine pickup and verification flow, improves patient journey tracking, and updates shared queue-aware components and tests to reflect the revised workflow.

This solves the issue where several volunteer pages, shared components, and tests had drifted from the actual queue model.

The main workflow now explicitly supports:

vitals_waiting → vitals → know_your_patient → medicine_prescribing → medicine_pickup_waiting → medicine_pickedup → medicine_verification → medicine_verified → counselling

This change is needed to:

show the correct queue at each stage
render valid action buttons for volunteers
improve flow clarity for medicine pickup and verification
align dashboard navigation and patient status tracking
ensure tests reflect actual workflow behavior

What does this MR do and why?

Motivation

The frontend workflow had multiple inconsistencies compared to the current branch state:

older queue assumptions still existed in some pages
patient journey tracking was incomplete
medicine flow lacked clear stage separation
vitals flow was not split into waiting vs active stages
tests were outdated compared to actual UI behavior

This reduced trust in the queue flow and made volunteer actions harder to validate.

Approach Taken

The branch introduces explicit UI flow steps instead of overloading existing pages.

The main approach was:

add missing route/page for vitals_waiting
enhance queue-state interpretation in shared utilities
improve PatientCard and status rendering logic
expand medicine pickup into guided dialog flow
update patient journey steps and badges
align all related tests

Trade-offs

existing backend queue naming is preserved
no full state-machine refactor was introduced
some naming inconsistencies still remain:
- medicine_verification
- medicine_verified
- counselling
- counselling_done

This MR prioritizes correctness and workflow alignment.

Changes Made

Files Added

src/pages/volunteer/VitalsWaitingQueuePage.tsx

Files Modified

CHANGELOG.md
src/App.tsx
src/components/AppLayout.tsx
src/components/PatientCard.tsx
src/components/PatientStatusTracker.tsx
src/components/QueueDisplay.tsx
src/hooks/usePatientStatus.ts
src/locales/en/translations.json
src/locales/hi/translations.json
src/locales/te/translations.json
src/pages/DashboardPage.tsx
src/pages/coordinator/QueueManagementPage.tsx
src/pages/doctor/DoctorPage.tsx
src/pages/volunteer/ConsultationCompletedPage.tsx
src/pages/volunteer/ConsultationQueuePage.tsx
src/pages/volunteer/CounselingQueuePage.tsx
src/pages/volunteer/MedicinePickupQueuePage.tsx
src/pages/volunteer/PatientHistoryPage.tsx
src/pages/volunteer/PatientStatus.tsx
src/pages/volunteer/PrescriptionsQueuePage.tsx
src/pages/volunteer/RecordVitalsPage.tsx
src/pages/volunteer/UpdatePrescriptionPage.tsx
src/pages/volunteer/VerifyMedicinesPage.tsx
src/pages/volunteer/VerifyMedicinesQueuePage.tsx
src/pages/volunteer/VitalsQueuePage.tsx
src/types/api.ts
src/utils/patientUtils.tsx

Tests Updated

tests/PatientCard.test.tsx
tests/pages/PublicQueuePage.test.tsx
tests/unit/components/ConsultationCompletedPage.test.tsx
tests/unit/components/ConsultationQueuePage.test.tsx
tests/unit/components/QueueManagementPage.test.tsx
tests/unit/pages/coordinator/QueueManagementPage.test.tsx
tests/unit/pages/volunteer/UpdatePrescriptionPage.test.tsx
tests/usePatientStatus.test.ts
tests/usePatientStatus.test.tsx
tests/utils/patientUtils.test.tsx
tests/volunteers/MedicinePickupQueuePage.test.tsx
tests/volunteers/PatientStatus.test.tsx
tests/volunteers/RecordVitalsPage.test.tsx
tests/volunteers/UpdatePrescriptionPage.test.tsx

New Components / Hooks / Utilities

VitalsWaitingQueuePage
enhanced usePatientStatus
improved patientUtils
queue-aware PatientCard actions

API Endpoint Changes

No new endpoints introduced.

Existing API statuses are now consumed more comprehensively in:

src/types/api.ts
queue-aware UI pages
patient journey components

Configuration Changes

No configuration or environment changes.

Technical Details

Root Cause

The workflow logic was fragmented across:

volunteer pages
patient status tracker
shared utilities
tests

Older transitions and assumptions still existed.

How this Fix Addresses It

This MR introduces:

Vitals flow split

vitals_waiting
vitals

This makes queue progression explicit.

Medicine flow enhancement

Expanded guided flow:

assign volunteer
inspect prescriptions
confirm pickup
move to verification
route to counseling

Shared state normalization

Improved:

usePatientStatus
patientUtils
PatientCard
PatientStatusTracker

to interpret queue states consistently.

State Management Approach

TanStack Query for server state
page-local state for dialogs and selected patients
shared queue normalization via hook/util helpers

Component Structure and Data Flow

volunteer pages fetch queue data
QueueDisplay renders list view
PatientCard renders status-aware actions
journey tracker uses normalized queue state

Type of Change

🐛 Bug fix
- ✨ New feature
- 💥 Breaking change
- 📝 Documentation update
- 🎨 UI/UX improvement
- ♻️ Refactor
- ⚡ Performance improvement
- 🧪 Test update
- 🔧 Configuration change
- 🚨 Security fix

Related Issues / References

Related to volunteer queue workflow alignment
Related to medicine pickup and verification flow

Screenshots or Screen Recordings

Required UI Screenshots

Please include:

Screen	Before	After
Vitals Waiting Queue	Old direct flow	New explicit waiting queue
Medicine Pickup Queue	Basic queue	Dialog-guided pickup
Verify Medicines	Old verification	Updated counseling route
Patient Status	Old steps	Updated journey tracker

How to Set Up and Validate Locally

Setup

bun install

bun dev

Validate Flow

Login as volunteer
Open dashboard
Open vitals-waiting-queue
Start vitals
Record vitals
Add prescription
Open medicine pickup queue
Assign volunteer
Confirm pickup
Verify medicines
Confirm counseling route
Validate patient journey page

Expected Behavior

queue stages split correctly
valid action buttons shown
patient journey steps accurate
full suite passes

Testing Done

Manual testing completed
- Unit tests added/updated

Test Cases Covered

Scenario	Expected Result	Status
vitals waiting queue	moves patient to active vitals	✅
active vitals queue	record flow works	✅
medicine pickup	volunteer assign + confirm	✅
verify medicines	routes to counseling	✅
patient card actions	correct status buttons	✅
journey tracker	normalized steps	✅
full suite	passes	✅

Code Quality Checklist

follows conventions
- no console/debugger
- no unused code
- reusable components used
- TypeScript types correct
- TanStack Query preserved
- errors handled
- CHANGELOG updated

Known Limitations / Technical Debt

queue naming still inconsistent across some statuses
warnings still exist in tests:
- act(...)
- dialog accessibility
- asChild
queue logic still spread across pages/helpers

Additional Notes

This MR is based on:

git diff develop...HEAD

and reflects the full branch changes, not just recent fixes.

Main functional highlights:

split vitals into two stages
explicit medicine pickup flow
improved patient journey rendering
test alignment

MR Acceptance Checklist

compared against develop
- routes updated
- shared components aligned
- journey tracker updated
- tests aligned
- bun run test passes

Feat/frontend volunteer queue workflow