test+docs(spp_metric_service): assert applies_to CASE wrapping; document expansion semantics

Addresses the review's two verify-items and its test gap:
- two tests assert the CASE WHEN is_group = FALSE/TRUE wrapping for
  individuals-/groups-scoped dimensions (previously unexercised);
- compute_breakdown docstring and HISTORY state the endorsed semantics:
  all-or-nothing expansion when any individuals dimension is present, and
  member-counted totals that need not reconcile with group-level scope counts.

Author: gonzalesedwin1123

spp_metric_service/models/breakdown_service.py

@@ -24,6 +24,15 @@ def compute_breakdown(self, registrant_ids, group_by, statistics=None, context=N
 
         Uses dimension cache for 5-10x performance improvement.
 
+        Expansion semantics (deliberate): if ANY requested dimension has
+        ``applies_to == "individuals"``, the ENTIRE registrant set is expanded
+        from groups to their active individual members before evaluation —
+        including for any non-individual dimensions mixed into the same
+        request (mixing scopes in one breakdown is inherently ambiguous; the
+        expansion is all-or-nothing by design). Consequently breakdown totals
+        count members and intentionally need not reconcile with a group-level
+        scope count.
+
         :param registrant_ids: List of partner IDs
         :param group_by: List of dimension names
         :param statistics: List of statistic names (optional)

spp_metric_service/readme/HISTORY.md

@@ -1,6 +1,6 @@
 ### 19.0.2.1.0
 
-- feat: demographic breakdown expansion and SQL column support for metric disaggregation (re-land from #76; uses the spp_cel_domain SQL CASE compiler).
+- feat: demographic breakdown expansion and SQL column support for metric disaggregation (re-land from #76; uses the spp_cel_domain SQL CASE compiler). Expansion is all-or-nothing: any individuals-scoped dimension expands the whole registrant set to active members, so breakdown totals count members and need not reconcile with a group-level scope count.
 
 ### 19.0.2.0.0
 

spp_metric_service/tests/test_sql_column.py

@@ -153,3 +153,42 @@ def test_cross_module_cel_call(self):
         # Should reference the correct alias
         self.assertIn("t", sql_str)
         self.assertIn("birthdate", sql_str)
+
+    def test_applies_to_individuals_wraps_in_is_group_false_case(self):
+        """An individuals-scoped dimension wraps its SQL in CASE WHEN is_group = FALSE."""
+        dim = self.env["spp.demographic.dimension"].create(
+            {
+                "name": "test_individuals_scope",
+                "label": "Individuals Scope",
+                "dimension_type": "field",
+                "field_path": "is_group",
+                "default_value": "unknown",
+                "applies_to": "individuals",
+            }
+        )
+        result = dim.to_sql_column("p", 0)
+        self.assertIsNotNone(result)
+        sql_str = str(result.expression)
+        self.assertIn("CASE WHEN", sql_str)
+        self.assertIn("is_group", sql_str)
+        self.assertIn("= FALSE", sql_str)
+        # Non-matching registrants fall through to the dimension default
+        self.assertIn("unknown", str(result.expression.params))
+
+    def test_applies_to_groups_wraps_in_is_group_true_case(self):
+        """A groups-scoped dimension wraps its SQL in CASE WHEN is_group = TRUE."""
+        dim = self.env["spp.demographic.dimension"].create(
+            {
+                "name": "test_groups_scope",
+                "label": "Groups Scope",
+                "dimension_type": "field",
+                "field_path": "is_group",
+                "default_value": "unknown",
+                "applies_to": "groups",
+            }
+        )
+        result = dim.to_sql_column("p", 0)
+        self.assertIsNotNone(result)
+        sql_str = str(result.expression)
+        self.assertIn("CASE WHEN", sql_str)
+        self.assertIn("= TRUE", sql_str)