fix(backchecks): join backcheck dates on the backcheck KEY

[iabaako]

Pull Request Summary 🚀

What does this PR do? 📝

Fills in backcheck dates, and with them the "Avg Days" statistics, when the survey and backcheck datasets have different KEYs. It also fixes backchecker statistics, which were always empty when the survey KEY is also the merge ID. Closes #300.

 _add_date_columns
-  bc_dates = backcheck_data[survey_key, backcheck_date]
-  join on survey_key                 # survey KEY ≠ backcheck KEY → no match
+  if backcheck_data has survey_key:
+    backcheck_key = f"{survey_key}__BCCL"   # backcheck KEY carried in the analysis
+    if backcheck_key not in analysis:        # survey_key is also the merge ID
+      backcheck_key = survey_key
+    bc_dates = backcheck_data[survey_key AS backcheck_key, backcheck_date]
+    join on backcheck_key

Why is this change needed? 🤔

Survey and backcheck submissions normally have different KEYs. Joining the backcheck date on the survey KEY matched nothing, so backcheck_date_col was empty. "Avg Days" in the enumerator and backchecker statistics then showed 0.

How was this implemented? 🛠️

• Join backcheck dates on {survey_key}__BCCL, as the backchecker staff join (_join_staff_information) already does.
• When survey_key is also the merge ID, the merge adds no __BCCL column, so the join falls back to survey_key, which then matches both datasets.
• Skip the backcheck date when the backcheck data has no survey_key column. That path raised ColumnNotFoundError before this PR; the spec review found it.
• Backchecker statistics when survey_key is also the merge ID (from Copilot review): compute_enumerator_backchecker_stats returned empty unless the analysis had a {survey_key}__BCCL column, which the merge never adds in that case. That pre-join check is gone; the function now returns empty only if the join could not add the staff column (backcheck data without survey_key). _get_staff_configuration no longer returns a join key.

Tidy-up (from review):

• BACKCHECK_SUFFIX and merged_backcheck_name(col) in models.py replace every hard-coded "__BCCL" in compute.py and report_ui.py.
• _join_backcheck_columns is the one place that joins backcheck columns by backcheck KEY. It falls back to survey_key when that is the merge ID and skips missing columns. Both the backchecker staff join and the backcheck date join use it, so they now behave the same. _join_staff_information no longer takes a join_key.

Left alone: the "Backchecks" stats column counts survey KEYs. #318 redefines that column.

How to test or reproduce ? 🧪

uv run python -m pytest tests/checks/backchecks/test_compute.py
just test

New tests in tests/checks/backchecks/test_compute.py, all using distinct survey and backcheck KEYs:

Test	Before	After
test_add_date_columns_distinct_survey_and_backcheck_keys	❌ [None, None] dates	✅ dates populated, avg 5.5 days
test_stats_avg_days_with_distinct_survey_and_backcheck_keys[enumerator]	❌ Avg Days 0.0	✅ 3.0
test_stats_avg_days_with_distinct_survey_and_backcheck_keys[backchecker]	❌ Avg Days 0.0	✅ 3.0
test_add_date_columns_backcheck_data_without_key	❌ ColumnNotFoundError	✅ backcheck date skipped
test_backchecker_stats_when_survey_key_is_merge_id (survey_key = merge ID)	❌ empty stats	✅ stats, 1 mismatch, Avg Days 3.0
test_backchecker_stats_empty_when_backcheck_data_has_no_survey_key	✅ empty	✅ empty (no crash)

test_compute_enumerator_backchecker_stats_backchecker had expected empty stats in the merge-ID case, which locked in the bug; it now requires stats.

Full suite: 3518 passed, 6 skipped. test_join_backcheck_columns_survey_key_is_merge_id covers the fallback, and test_join_staff_information_backchecker_path now uses distinct KEYs.

Manual: open a backchecks page whose survey and backcheck data have distinct KEYs and a configured backcheck date. "Avg Days" in the Enumerator/Backchecker statistics is now non-zero.

Merge risk: low and easy to undo (revert the commits). It affects only the backcheck date join and backchecker statistics: "Avg Days" changes from 0 to its real value, and backchecker statistics appear where they were empty.

Screenshots (if applicable) 📷

N/A. There is no layout change, only values.

Checklist ✅

• I have run and tested my changes locally
• I have limit this PR to less than 1000 lines of code change (if not, explain why)
• I have updated/added tests to cover my changes (if applicable)
• I have updated/added requirements to cover my changes (if applicable): N/A, no new dependencies
• I have run linting and formatting on any code changes (if applicable)
• I have updated the documentation (README, etc.) accordingly: CHANGELOG entry under Fixed
• I have reviewed and resolved any merge conflict

Reviewer Emoji Legend

	:code:	Meaning
😃👍💯	:smiley: :+1: :100:	I like this... ...and I want the author to know it! This is a way to highlight positive parts of a code review.
⭐⭐⭐	:star: :star: :star:	Important to fix before PR can be approved... And I am providing reasons why it needs to be addressed as well as suggested improvements.
⭐⭐	:star: :star:	Important to fix but non-blocking for PR approval... And I am providing suggestions where it could be improved either in this PR or later.
⭐	:star:	Give this some thought but non-blocking for PR approval... ...and consider this a suggestion, not a requirement.
❓	:question:	I have a question. This should be a fully formed question with sufficient information and context that requires a response.
📝	:memo:	This is an explanatory note, fun fact, or relevant commentary that does not require any action.
⛏	:pick:	This is a nitpick. This does not require any changes and is often better left unsaid. This may include stylistic, formatting, or organization suggestions and should likely be prevented/enforced by linting if they really matter
♻️	:recycle:	Suggestion for refactoring. Should include enough context to be actionable and not be considered a nitpick.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

Backchecker statistics still return empty when the survey KEY is also the merge ID.

Review effort: Balanced
Findings: 1

Open (1)

• Accept unsuffixed merge key for identical survey key and ID · New

What changed in this PR

Fixes backcheck date joins when survey and backcheck KEYs differ, restoring accurate “Avg Days” statistics.

Changes:

• Joins backcheck metadata using the backcheck KEY.
• Centralizes the __BCCL suffix.
• Adds regression tests and changelog documentation.

File	Description
src/​datasure/​checks/​backchecks/​compute.py	Adds shared backcheck-column join logic.
src/​datasure/​checks/​backchecks/​models.py	Defines the suffix constant and naming helper.
src/​datasure/​checks/​backchecks/​report_ui.py	Uses the centralized naming helper.
tests/​checks/​backchecks/​test_compute.py	Tests distinct KEYs and missing columns.
CHANGELOG.md	Documents the corrected date join.

---

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

[Copilot]

Copilot review overview

🔵 Needs a closer look

The shared-key fallback remains blocked for backchecker statistics by the preceding join-key guard.

Review effort: Balanced
Findings: 1

Open (1)

• Accept unsuffixed merge key for identical survey key and ID

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud