feat(b2b_dashboard): return per-status counts on the learner-progress envelope

[blarghmatey]

What are the relevant tickets?

Closes #67

Description (What does it do?)

MIT Learn's learner directory (mitodl/mit-learn#3958) renders four summary tiles (Enrollments, Not started, In progress, Completed) above the learner table. Until now the other three came from three extra /learner-progress requests with limit=1 and a completion_status filter, each paying for an org-manager existence check, a page query, and a COUNT(*) over mv_b2b_learner_enrollment that scans the full matching set regardless of limit. Five requests per page load against starrocks_pool_max_size=10 per pod.

• Adds completion_status_counts (not_started, in_progress, passed, certified) to LearnerProgressResponse, computed as conditional SUMs in the same count query alongside the existing outcomes_withheld_count SUM. No additional scan.
• not_started/in_progress/passed/certified come from the mutually exclusive branches of _COMPLETION_STATUS, so the buckets never overlap, and consent-withheld rows land in none of them: the four buckets plus outcomes_withheld_count sum to total_count.
• The counts share the response's own WHERE clause (search, status filter, include_inactive), the same tradeoff the issue flagged as open. Going with the cheaper, filter-following option, since it's free (the count query already builds the clause) and keeps the envelope internally consistent with total_count. A tile that must stay contract-wide regardless of the table's filters would need a second, unfiltered aggregate query, not implemented here since MIT Learn's tiles read from a limit=1 call with no filters applied today, so this changes nothing for the current caller.

How can this be tested?

uv run pytest tests/test_dashboard_learner_progress.py (19 tests, includes new coverage for the per-status counts, that they share the response's WHERE clause, and that CompletionStatusCounts field descriptions hold to the no-field-name-reference constraint) and uv run pytest for the full suite (278 tests) both pass. prek run (ruff, ruff format, mypy) is clean on the changed files.

Additional Context

Out of scope, filed separately: mitxonline_client._cache has no per-key lock (unlike refresh_metadata), so N concurrent cold-cache requests for one (sub, org) all issue the manager check. Once MIT Learn's directory drops its three extra /learner-progress calls in favor of this field, that only leaves one MITx Online call per page load instead of up to five, which should make that race much rarer in practice but doesn't eliminate it.

[Copilot]

Copilot review overview

🟡 Changes recommended

The manager-facing descriptions misstate exclusive bucket semantics, and the new test fixture violates the documented count invariant.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Fix fixture total_count mismatch and assert bucket sum invariant · New
• Clarify mutually exclusive CASE bucket precedence and exclusions · New

What changed in this PR

Adds filter-scoped completion-status aggregates to the learner-progress response, reducing clients’ need for repeated count requests.

Changes:

• Computes four status buckets in the existing count query.
• Exposes counts through a documented nested response model.
• Adds endpoint and schema tests.

File	Description
learner_queries.py	Adds conditional status aggregates.
learner_models.py	Defines the status-count response schema.
routers/​learners.py	Maps aggregate results into the response.
test_dashboard_learner_progress.py	Tests status counts, filtering, and descriptions.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[blarghmatey]

Addressed Copilot's review: fixed the test fixture's total_count/bucket-sum mismatch (149ee9f) and clarified the completion_status_counts field descriptions to state bucket precedence (certified beats passed beats in_progress beats not_started), since a certified enrollment can also carry a passing grade but counts only once. Both threads resolved; all checks green.

[github-actions]

OpenAPI Changes

Show/hide changes

## Changes for b2b_dashboard.yaml:
1 changes: 0 error, 0 warning, 1 info
info	[response-required-property-added] at head/openapi/specs/b2b_dashboard.yaml
	in API GET /api/v1/analytics/organizations/{organization_id}/contracts/{contract_id}/learner-progress
		added the required property `completion_status_counts` to the response with the `200` status



## Changes for b2b_learner_records.yaml:
No changes detected

Unexpected changes? Ensure your branch is up-to-date with main (consider rebasing).

[blarghmatey]

Addressed daniellefrappier18's review comment: added a docstring note (3bc81c6) on why completion_status_counts skips cohort suppression, plus the regenerated OpenAPI spec (fcbcf4f). Thread resolved, all checks green.