"""Month-range evidence stays bound to its exact selected calendar window.""" import sys import unittest from pathlib import Path sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'scripts')) from analysis_visuals import build_visuals from nao_agent_report import _build_trend_report from nao_evidence_finalizer import _coverage_period, coverage_sufficient from nao_evidence_report import _frame_key, _same_periods, period, select_comparison_frames from nao_period import expected_months, normalize_period QUESTION = '查看客户甲2026年3至5月的综合合格率趋势图' RELEASE = 'release-range' FILTERS = {'extraFilters': {'customerCode': ['客户甲']}} def selected_task(period_value, *, period_coverage='available'): return { 'version': 1, 'kind': 'metrics', 'question': QUESTION, 'goal': QUESTION, 'period': period_value, 'comparisonPeriod': None, 'comparisonRequired': False, 'filters': FILTERS, 'freshQuery': True, 'dimensions': [], 'dimensionStages': {}, 'stages': [], 'fields': ['rate'], 'historyMode': 'none', 'trendRequired': True, 'periodCoverage': period_coverage, 'visualPreference': 'auto', 'visualType': None, 'responseStyle': 'brief', 'verifySource': False, 'fullDetails': False, } def context(period_value, *, period_coverage='available'): task = selected_task(period_value, period_coverage=period_coverage) return {'releaseId': RELEASE, 'period': period_value, 'filters': FILTERS, '_agentTask': task} def metric_doc(selected_period, months, *, release=RELEASE, filters=None, ref='Q1234ABCD'): rates = {1: .71, 2: .72, 3: .73, 4: .74, 5: .75, 6: .76, 7: .77, 8: .78, 9: .79, 10: .80} trend = [ {'period': f"2026-{month:02d}", 'compositeRate': rates[month], 'black': {'rate': rates[month] - .01}, 'bright': {'rate': rates[month] + .01}, 'coverage': {'blackRows': 5, 'brightRows': 5}} for month in months ] return { 'evidenceRef': ref, 'mode': 'query', 'releaseId': release, 'result': { 'kind': 'quality_metrics', 'releaseId': release, 'view': 'overall', 'period': selected_period, 'filters': filters if filters is not None else FILTERS, 'summary': {'compositeRate': .74}, 'trend': trend, 'trendCount': len(trend), 'trendTruncated': False, 'coverage': {'sourceMonths': [ {'year': 2026, 'month': month, 'blackRows': 5, 'brightRows': 5} for month in months ]}, }, } class MonthRangeEvidenceTests(unittest.TestCase): def test_period_helper_supports_ranges_and_preserves_single_month_quarter_year(self): self.assertIsNone(normalize_period(None)) self.assertEqual(expected_months({'year': 2026, 'monthStart': 1, 'monthEnd': 9}), list(range(1, 10))) self.assertEqual(expected_months({'year': 2026, 'monthStart': 3, 'monthEnd': 5}), [3, 4, 5]) self.assertEqual(expected_months({'year': 2026}), list(range(1, 13))) self.assertEqual(expected_months({'year': 2026, 'quarter': 2}), [4, 5, 6]) self.assertEqual(expected_months({'year': 2026, 'month': 9}), [9]) def test_range_requires_paired_valid_ordered_endpoints(self): invalid = ( {'year': 2026, 'monthStart': 3}, {'year': 2026, 'monthEnd': 5}, {'year': 2026, 'monthStart': 5, 'monthEnd': 3}, {'year': 2026, 'monthStart': 0, 'monthEnd': 5}, {'year': 2026, 'monthStart': 3, 'monthEnd': 13}, {'year': 2026, 'monthStart': 3, 'monthEnd': 5, 'month': 4}, {'year': 2026, 'monthStart': 3, 'monthEnd': 5, 'quarter': 2}, ) for value in invalid: with self.subTest(period=value), self.assertRaises(ValueError): normalize_period(value) def test_report_renders_range_and_does_not_fill_an_absent_month_with_zero(self): selected = {'year': 2026, 'monthStart': 1, 'monthEnd': 9} item = metric_doc(selected, [1, 2, 3, 5, 6, 7, 8, 9]) report = _build_trend_report([item], context(selected), QUESTION) self.assertTrue(report['coverageSufficient']) text = report['facts'][0]['text'] self.assertIn('2026年1–9月', text) self.assertIn('1月71.00%', text) self.assertIn('4月未提供', text) self.assertIn('9月79.00%', text) self.assertNotIn('4月0.00%', text) def test_short_range_includes_only_selected_months_and_rejects_outer_data(self): selected = {'year': 2026, 'monthStart': 3, 'monthEnd': 5} item = metric_doc(selected, [3, 4, 5]) report = _build_trend_report([item], context(selected), QUESTION) self.assertTrue(report['coverageSufficient']) self.assertIn('3月73.00%', report['facts'][0]['text']) self.assertIn('5月75.00%', report['facts'][0]['text']) self.assertNotIn('2月', report['facts'][0]['text']) self.assertNotIn('6月', report['facts'][0]['text']) out_of_range = metric_doc(selected, [2, 3, 4, 5]) rejected = _build_trend_report([out_of_range], context(selected), QUESTION) self.assertFalse(rejected['coverageSufficient']) self.assertFalse(rejected['facts']) self.assertIn('期间以外', rejected['missingEvidence'][0]) def test_unknown_stage_rows_do_not_become_known_zero_in_a_composite_trend_point(self): selected = {'year': 2026, 'monthStart': 1, 'monthEnd': 5} item = metric_doc(selected, [1, 2, 3, 4, 5]) february = next(row for row in item['result']['trend'] if row['period'] == '2026-02') february['coverage']['brightRows'] = None parent_february = next(row for row in item['result']['coverage']['sourceMonths'] if row['month'] == 2) parent_february['brightRows'] = None report = _build_trend_report([item], context(selected), QUESTION) text = report['facts'][0]['text'] self.assertIn('2月未提供', text) self.assertNotIn('2月72.00%', text) def test_period_identity_and_release_scope_reject_other_range_evidence(self): large = {'year': 2026, 'monthStart': 1, 'monthEnd': 9} short = {'year': 2026, 'monthStart': 3, 'monthEnd': 5} self.assertNotEqual(_frame_key({'current': {'period': large}, 'comparison': {'period': {'year': 2025}}, 'filterBinding': FILTERS}), _frame_key({'current': {'period': short}, 'comparison': {'period': {'year': 2025}}, 'filterBinding': FILTERS})) self.assertEqual(period(short), '2026年3–5月') def comparison(ref, current_period): return { 'evidenceRef': ref, 'mode': 'compare', 'result': {'kind': 'quality_comparison', 'releaseId': RELEASE, 'filterBinding': FILTERS, 'current': {'period': current_period}, 'comparison': {'period': {'year': 2025}}, 'delta': {'available': True, 'percentagePoints': 1.0}}, } roots, limitations = select_comparison_frames( [comparison('Q11111111', large), comparison('Q22222222', short)], context(short)) self.assertEqual([root['evidenceRef'] for root in roots], ['Q22222222']) self.assertEqual(limitations, []) roots, limitations = select_comparison_frames([comparison('Q11111111', large)], context(short)) self.assertTrue(limitations) wrong = metric_doc(large, [3, 4, 5]) report = _build_trend_report([wrong], context(short), QUESTION) self.assertFalse(report['coverageSufficient']) self.assertFalse(report['facts']) self.assertFalse(coverage_sufficient([wrong], QUESTION, context(short))) expected = {'kind': 'quality_changes', 'currentPeriod': short, 'comparisonPeriod': {'year': 2026, 'monthStart': 1, 'monthEnd': 2}} wrong_frame = {'kind': 'quality_changes', 'currentPeriod': large, 'comparisonPeriod': {'year': 2026, 'monthStart': 1, 'monthEnd': 2}} self.assertTrue(_same_periods(expected, { 'kind': 'quality_comparison', 'current': {'period': short}, 'comparison': {'period': {'year': 2026, 'monthStart': 1, 'monthEnd': 2}}, 'filterBinding': FILTERS, })) self.assertFalse(_same_periods(wrong_frame, { 'kind': 'quality_comparison', 'current': {'period': short}, 'comparison': {'period': {'year': 2026, 'monthStart': 1, 'monthEnd': 2}}, 'filterBinding': FILTERS, })) def test_complete_range_requires_every_selected_month_and_source_coverage(self): selected = {'year': 2026, 'monthStart': 3, 'monthEnd': 5} item = metric_doc(selected, [3, 4, 5]) item['result']['coverage']['sourceMonths'].pop(1) report = _build_trend_report([item], context(selected, period_coverage='complete'), QUESTION) self.assertFalse(report['coverageSufficient']) self.assertIn('全部月份', ' '.join(report['missingEvidence'])) self.assertFalse(coverage_sufficient([item], QUESTION, context(selected, period_coverage='complete'))) missing_month = metric_doc(selected, [3, 5]) report = _build_trend_report([missing_month], context(selected, period_coverage='complete'), QUESTION) self.assertFalse(report['coverageSufficient']) self.assertIn('4月未提供', report['facts'][0]['text']) def test_visual_scope_and_points_stay_inside_selected_range(self): selected = {'year': 2026, 'monthStart': 1, 'monthEnd': 9} item = metric_doc(selected, [1, 2, 3, 5, 6, 7, 8, 9]) visual_context = { **context(selected), '_agentTask': { 'version': 1, 'kind': 'metrics', 'question': QUESTION, 'visualPreference': 'required', 'visualType': 'line', 'dimensions': [], 'stages': [], 'fields': ['rate'], }, } result = build_visuals([item], QUESTION, 'range-visual', context=visual_context) self.assertEqual(result['visualState'], 'ready') chart = next(chart for chart in result['visuals'] if chart.get('metric') == 'composite_rate') self.assertEqual(chart['scope']['year'], 2026) self.assertEqual(chart['scope']['monthStart'], 1) self.assertEqual(chart['scope']['monthEnd'], 9) self.assertEqual(chart['series'][0]['values'], [.71, .72, .73, None, .75, .76, .77, .78, .79]) outside = metric_doc(selected, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]) rejected = build_visuals([outside], QUESTION, 'range-visual-outside', context=visual_context) self.assertEqual(rejected['visuals'], []) def test_finalizer_period_identity_accepts_range_exactly(self): selected = {'year': 2026, 'monthStart': 3, 'monthEnd': 5} self.assertEqual(_coverage_period(selected), selected) self.assertIsNone(_coverage_period({'year': 2026, 'monthStart': 3})) self.assertIsNone(_coverage_period({'year': 2026, 'monthStart': 6, 'monthEnd': 5})) if __name__ == '__main__': unittest.main()