Aditya feat: Add donutChartData with mutually exclusive volunteer categories

[Aditya-gam]

Description

This PR implements a new donutChartData object in the volunteer statistics API to provide three mutually exclusive volunteer categories for improved donut chart visualization and accurate reporting. Additionally, it includes critical bug fixes to prevent application crashes when no Blue Square data exists.

Implements: Volunteer Status Donut Chart with Mutually Exclusive Categories

Related PRs (if any):

• This PR builds upon PR #1768 Aditya-fix/volunteer-double-counting which fixed the volunteer double-counting issue
• Related frontend PR #4191

Main changes explained:

1. Added donutChartData Object (src/helpers/overviewReportHelper.js)

   • Introduced a new donutChartData object in the getVolunteerNumberStats function response
   • Contains three mutually exclusive volunteer categories:
     • existingActive: Active volunteers who are not new (calculated as activeVolunteers - newVolunteers)
     • newActive: New volunteers created within the date range
     • deactivated: All inactive volunteers
   • Each category includes:
     • count: The number of volunteers in that category
     • percentageOutOfTotal: Rounded percentage (2 decimal places) calculated against total volunteers
     • comparisonPercentage (optional): Growth/decline percentage when comparison dates are provided.

2. Added Comparison Data for Donut Chart (src/helpers/overviewReportHelper.js)

   • Implemented comparison percentage calculations for all three donut chart categories when comparisonStartDate and comparisonEndDate are provided
   • Uses the existing calculateGrowthPercentage helper function for consistency
   • Properly handles edge cases (division by zero, no comparison data)

3. Bug Fix: Added Optional Chaining for Blue Square Stats (src/helpers/overviewReportHelper.js)

   • Added optional chaining (?.) and default values (|| 0) to prevent crashes when no Blue Square infringement data exists
   • Ensures graceful handling of empty datasets without application errors

The implementation ensures:

• activeVolunteers.count = donutChartData.existingActive.count + donutChartData.newActive.count
• totalVolunteers.count = activeVolunteers.count + deactivatedVolunteers.count
• donutChartData.existingActive.count + donutChartData.newActive.count + donutChartData.deactivated.count = totalVolunteers.count
• All percentages sum to approximately 1.00 (allowing for rounding)
• No negative counts are possible

How to test:

Prerequisites:

1. Check out the current branch: Aditya-fix/volunteer-status-donut-chart-percentages
2. Reinstall dependencies using rm -rf node_modules package-lock.json && npm cache clean --force
3. Run npm install to install dependencies
4. Start the backend server: npm run dev
5. Ensure MongoDB is running with volunteer data

Test Cases:

API Testing Instructions:
Check

• Local server running on port 4500
• Valid authentication token
• API testing tool (Postman, curl, etc.)

---

Test 1: Basic Request (No Comparison)

Request:

• Method: GET
• URL: http://localhost:4500/api/reports/volunteerstats?startDate=2024-01-01&endDate=2024-12-31
• Headers: Authorization Bearer token, Content-Type: application/json

Verify:

1. Response contains donutChartData object with three categories: existingActive, newActive, deactivated
2. Each category has count and percentageOutOfTotal fields
3. No comparisonPercentage fields present
4. activeVolunteers.count equals existingActive.count + newActive.count

---

Test 2: With Comparison Dates

Request:

• URL: http://localhost:4500/api/reports/volunteerstats?startDate=2024-01-01&endDate=2024-12-31&comparisonStartDate=2023-01-01&comparisonEndDate=2023-12-31
• Same headers as Test 1

Verify:

1. All three donut chart categories include the comparisonPercentage field
2. Values show growth/decline or "No Comparison Data"

---

Test 3: Mathematical Consistency

Using any successful response, verify:

1. activeVolunteers.count === (existingActive.count + newActive.count)
2. totalVolunteers.count === (activeVolunteers.count + deactivatedVolunteers.count)
3. Sum of all donut chart counts equals totalVolunteers.count
4. Sum of donut chart percentages ≈ 1.00 (within 0.02)
5. All count values ≥ 0

---

Test 4: Missing Parameters

Request:

• URL: http://localhost:4500/api/reports/volunteerstats (no query params)

Verify:

• Status: 400
• Error: "Please provide a start and end date."

Screenshots or videos of changes:

TestingVideo.mov

Note:

• Search for donutChartData in the JSON response object to verify the data.

[RitzzzZ2021]

Test locally. Test 3 failed, and others work perfectly. Please look into the Error in Test 3.

Test 1: Basic Request (No Comparison) >> pass

• Response contains donutChartData object with three categories: existingActive, newActive, deactivated
• Each category has count and percentageOutOfTotal fields
• No comparisonPercentage fields present
• activeVolunteers.count equals existingActive.count + newActive.count

Test 2: With Comparison Dates >> pass

• All three donut chart categories include the comparisonPercentage field
• Values show growth/decline or "No Comparison Data"

Test 3: Edge Case - No Data (Blue Square Bug Fix) >> not pass

• Server returns message: Error occured while fetching data.
• TypeError: Cannot read properties of undefined (reading 'totalHours')

Test 4: Mathematical Consistency >> pass

All verified:

• activeVolunteers.count === (existingActive.count + newActive.count)
• totalVolunteers.count === (activeVolunteers.count + deactivatedVolunteers.count)
• Sum of all donut chart counts equals totalVolunteers.count
• Sum of donut chart percentages ≈ 1.00 (within 0.02)
• All count values ≥ 0

Test 5: Missing Parameters >> pass

• Status: 400
• Error: "Please provide a start and end date."

[Aswin20010]

Reviewed PR #4191+1794 update that introduces support for the new donutChartData structure in the Volunteer Status chart. Verified correct extraction of nested .count properties from existingActive, newActive, and deactivated categories, along with backward compatibility for the legacy data format. Confirmed updated chart labels (“Existing Active,” “New Active,” and “Deactivated”) accurately reflect volunteer status categories and display proper color coding. Tested hybrid data access logic with optional chaining and default values to ensure no rendering or NaN% errors occur. Validated that the metric cards continue to function using the original data structure without regression. Conducted end-to-end testing under Dashboard → Reports → Total Organization Summary after clearing cache and reinstalling dependencies. Checked percentage accuracy, total count display, and dynamic updates upon changing date ranges. No UI, data, or logic issues found — approved the PR.

[Aditya-gam]

Test locally. Test 3 failed, and others work perfectly. Please look into the Error in Test 3.

Test 1: Basic Request (No Comparison) >> pass

• Response contains donutChartData object with three categories: existingActive, newActive, deactivated
• Each category has count and percentageOutOfTotal fields
• No comparisonPercentage fields present
• activeVolunteers.count equals existingActive.count + newActive.count

**Test 2: With Comparison Dates** >> pass

• All three donut chart categories include the comparisonPercentage field
• Values show growth/decline or "No Comparison Data"

**Test 3: Edge Case - No Data (Blue Square Bug Fix)** >> not pass

• Server returns message: Error occured while fetching data.
• TypeError: Cannot read properties of undefined (reading 'totalHours')

**Test 4: Mathematical Consistency** >> pass

All verified:

• activeVolunteers.count === (existingActive.count + newActive.count)
• totalVolunteers.count === (activeVolunteers.count + deactivatedVolunteers.count)
• Sum of all donut chart counts equals totalVolunteers.count
• Sum of donut chart percentages ≈ 1.00 (within 0.02)
• All count values ≥ 0

Test 5: Missing Parameters >> pass

• Status: 400
• Error: "Please provide a start and end date."

The blue squares fix wasn't a part of this PR. I added that because backend won't work without that. It is not a permenant fix.

[deep3072]

All the testcases work as expected:

Testcase 1:

Testcase 2:

Testcase 3:

Testcase 4:

[one-community]

Thank you all, merging!