feat: add funnel analytics routes for camp analytics dashboard
name: Feature Request
about: Suggest a new feature or enhancement for the Corpus Collector Backend.
title: "[Feature]: feat(analytics): add funnel stage data for patient journey tracking"
labels: "feature"
assignees: ''title: "feat(backend): add funnel analytics data to existing analytics endpoint"
🚀 Feature Request
Is your feature request related to a problem? Please describe.
The current endpoint /api/v1/analytics only returns basic aggregated data such as:
- Total patients
- Completed vitals
- Completed consultations
This is not sufficient to build the Patient Journey Funnel Chart in the admin dashboard.
Because of this limitation:
- Frontend cannot visualize patient progression across stages
- No visibility into drop-offs between stages
- Funnel chart remains incomplete
Describe the solution you'd like
Enhance the existing /api/v1/analytics endpoint to include stage-wise funnel data.
Add the following fields:
doctor_assignmentvitals_collectionconsultationprescriptionmedicine_verificationcounseling
Logic:
| Stage | Condition |
|---|---|
| Registration | Total patients |
| Doctor Assignment | doctor_id != null |
| Vitals | vitals_done = true |
| Consultation | consultation_done = true |
| Prescription | prescription_given = true |
| Medicine Verification | medicine_verified = true |
| Counseling | counseling_done = true |
Describe alternatives you've considered
-
New endpoint (
/analytics/funnel)-
❌ Duplicate logic -
❌ Extra maintenance
-
-
Frontend computation
-
❌ Inefficient -
❌ Requires full dataset -
❌ Risk of inconsistency
-
Additional context
🧪 Test Cases
✅ Functional Test Cases
| TC ID | Scenario | Input | Expected Output |
|---|---|---|---|
| TC_01 | Fetch analytics with valid camp ID | medical_camp_id = valid | API returns 200 with funnel data |
| TC_02 | Patient registration count | Patients exist |
patients matches DB count |
| TC_03 | Doctor assignment | doctor_id != null |
doctor_assignment correct |
| TC_04 | Vitals stage | vitals_done = true |
vitals_collection correct |
| TC_05 | Consultation stage | consultation_done = true |
consultation correct |
| TC_06 | Prescription stage | prescription_given = true |
prescription correct |
| TC_07 | Medicine verification | medicine_verified = true |
medicine_verification correct |
| TC_08 | Counseling stage | counseling_done = true |
counseling correct |
| TC_09 | Full funnel | All stages completed | Proper funnel progression |
| TC_10 | Partial funnel | Some incomplete | Drop-offs visible correctly |
⚠ ️ Edge Test Cases
| TC ID | Scenario | Input | Expected Output |
|---|---|---|---|
| TC_11 | No patients | Empty dataset | All counts = 0 |
| TC_12 | Invalid camp ID | Invalid ID | Empty/error response |
| TC_13 | Missing param | No medical_camp_id | 400 validation error |
| TC_14 | Null values | Some fields null | No crash, safe handling |
| TC_15 | Large dataset | 1000+ patients | Performance maintained |
🔁 Regression Test Cases
| TC ID | Scenario | Expected Output |
|---|---|---|
| TC_16 | Existing fields |
patients, vitals, consultations unchanged |
| TC_17 | API structure | No breaking changes |
| TC_18 | Frontend compatibility | UI works without changes |
🔐 Validation Logic
| Stage | Condition |
|---|---|
| Registration | Total patients |
| Doctor Assignment | doctor_id != null |
| Vitals | vitals_done = true |
| Consultation | consultation_done = true |
| Prescription | prescription_given = true |
| Medicine Verification | medicine_verified = true |
| Counseling | counseling_done = true |
🔍 How to Validate
# Start backend
docker compose up --build -d
# Test API
curl "http://localhost:8000/api/v1/analytics?medical_camp_id=1"
# Invalid case
curl "http://localhost:8000/api/v1/analytics?medical_camp_id=9999"