179 adding date filter to volunteer activity (trend and location dashboards)

[KTB2110]

Summary

Adds independent date filter support to the two volunteer analytics widgets on the Super Admin dashboard.

New Helper Functions

• build_date_filter() — single shared helper (confirmed with team lead Sana Desai as preferred over two separate helper functions) that accepts time_range, start_date, and end_date; returns a SQL WHERE condition string and a params tuple (using %s placeholders to prevent SQL injection). Handles 7D, 30D, 1Y, All, and Custom ranges against vd.created_at.
• get_grouping() — accepts time_range and returns the DATE_TRUNC unit and format string for dynamic grouping. Short ranges (7D, 30D, Custom) group daily (YYYY-MM-DD); long ranges (1Y, All) group monthly (YYYY-MM).

Updated Functions

• get_volunteer_activity_trend() — now accepts time_range, start_date, end_date; applies dynamic date filtering and grouping across all three sub-queries (new_volunteers, active_volunteers, total_volunteers). Response key updated from month to period per API spec.
• get_volunteers_by_location() — now accepts time_range, start_date, end_date; applies date filtering only. No grouping logic added. Country aggregation logic unchanged.
• merge_periodic_data() — renamed from merge_monthly_data() to reflect the new period key in responses.
• lambda_handler() — reads two independent filter sets from the event payload: time_range/start_date/end_date for trend, and time_range_location/location_start_date/location_end_date for location.

Independent Filters

Trend and location widgets use separate filter keys so each chart can be filtered independently:

{
  "time_range": "30D",
  "time_range_location": "7D"
}

Testing

Tested locally against a PostgreSQL copy of the Virginia tables for all five time ranges on both widgets. Verified daily grouping for 7D, 30D, Custom and monthly grouping for 1Y, All. Verified volunteers_by_location applies date filtering without grouping dates, only groups countries.

---

Update — Response Restructure (per updated requirements)

Following updated requirements, the response now returns all preset ranges in a single call, keyed by time range, instead of a single flat trend/location pair.

New Response Shape

{
  "7D":  { "volunteer_activity_trend": {...}, "volunteers_by_location": [...] },
  "30D": { "volunteer_activity_trend": {...}, "volunteers_by_location": [...] },
  "1Y":  { "volunteer_activity_trend": {...}, "volunteers_by_location": [...] },
  "All": { "volunteer_activity_trend": {...}, "volunteers_by_location": [...] },
  "Custom": { "volunteer_activity_trend": {...}, "volunteers_by_location": [...] }
}

• 7D, 30D, 1Y, All are always computed and populated for both widgets, even when a custom range is supplied.
• Custom is always present with both keys.

Custom Range — Independent Per-Widget Dates

The two widgets inside Custom have fully independent date ranges:

Supplied	Result
start_date + end_date	Custom.volunteer_activity_trend populated (grouped daily)
location_start_date + location_end_date	Custom.volunteers_by_location populated
One pair missing	That widget defaults to its empty shape; the other still populates
Neither supplied	Both default to empty

Empty defaults differ by widget (pulled from one shared definition, not hand-retyped):

• trend → { "new_volunteers": [], "active_volunteers": [], "total_volunteers": [] }
• location → []

Safe Response

The error/fallback response was updated to mirror the new time-range-keyed shape, so error responses match the structure the frontend expects on success (previously it returned the old flat shape, which would have broken frontend code indexing by range).

Additional Testing

• Scenario 1 (trend custom dates only) → Custom.volunteers_by_location returns []
• Scenario 2 (location custom dates only) → Custom.volunteer_activity_trend returns the empty trend structure
• Scenario 3 (both supplied) → both populated
• new_volunteers counts cross-checked directly against the DB and matched exactly (2× raw, since Virginia and Ireland point at the same local DB in testing)

Closes #179