"""Build evidence-bound reports for agent answers and mixed historical evidence. Formal KPI values are rendered from the existing server summaries. This module does not calculate rates, totals, or deltas; it only selects verified frames, formats their values, and binds every fact to its evidence reference. """ from __future__ import annotations import json import re from decimal import Decimal, InvalidOperation from nao_period import PERIOD_KEYS, expected_months, normalize_period from nao_evidence_report import ( _filters, _scope_label, cell, period as format_period, shown, ) _FIELD_LABELS = { 'rate': ('合格率', True, ''), 'scrapRate': ('报废率', True, ''), 'totalWeight': ('投入重量', False, ' kg'), 'scrapWeight': ('报废重量', False, ' kg'), } _STAGES = (('black', '黑片'), ('bright', '亮片')) def _task(context): from nao_agent_task import task_from_context return task_from_context(context) def _period_key(value): if value is None: return None try: normalized = normalize_period(value) except ValueError: return None return tuple(normalized.get(key) for key in PERIOD_KEYS) def _context_filters(context, task): if task is not None and isinstance(task.get('filters'), dict): return _filters(task['filters']) if isinstance(context, dict) and isinstance(context.get('filters'), dict): return _filters(context['filters']) if isinstance(context, dict): return _filters(context) return {} def _history_all(task): return bool(task and task.get('kind') == 'report' and task.get('historyMode') == 'all') def _detail_cell(value): if value is None: return '未提供' if isinstance(value, bool): return 'true' if value else 'false' if isinstance(value, (dict, list)): return json.dumps(value, ensure_ascii=False, separators=(',', ':'), default=str) return str(value) def _private_detail_field(name): normalized = str(name).strip().casefold() return (normalized in {'file', 'filename', 'sourcefile', 'filepath', 'sourcepath', 'evidencepath', 'path'} or '文件路径' in normalized or '原表路径' in normalized or 'filepath' in normalized) def _render_detail_section(period_label, stage_label, rows): if not rows: return None title = f'### {period_label} · {stage_label}原表行明细' table = ('| 原表行号 / 证据 | 规格 | 原字段 | 原值 |\n' '| --- | --- | --- | --- |\n' + '\n'.join('| ' + ' | '.join(cell(value).replace('\\r', ' ') for value in row) + ' |' for row in rows)) return title + '\n\n' + table def _metric_documents(evidence, context): task = _task(context) history_all = _history_all(task) expected_release = context.get('releaseId') if isinstance(context, dict) else None expected_filters = _context_filters(context, task) expected_period = None if task is not None: expected_period = task.get('period') if expected_period is None and isinstance(context, dict): expected_period = context.get('period') or context.get('currentPeriod') if expected_period is None and any(key in context for key in PERIOD_KEYS): expected_period = {key: context[key] for key in PERIOD_KEYS if key in context} unique = {} for document in evidence: result = document.get('result') if isinstance(document, dict) else None if (not isinstance(result, dict) or result.get('kind') != 'quality_metrics' or document.get('mode') != 'query'): continue if expected_release is not None and result.get('releaseId') != expected_release: continue period_value = result.get('period') if _period_key(period_value) is None: continue filters = _filters(result.get('filters')) if not history_all: if filters != expected_filters: continue if expected_period is not None and _period_key(period_value) != _period_key(expected_period): continue if not isinstance(document.get('evidenceRef'), str): continue key = (result.get('releaseId'), _period_key(period_value), json.dumps(filters, ensure_ascii=False, sort_keys=True)) # Evidence is normally already sorted by creation time. Keep the latest # verified query for a repeated period/scope, while preserving distinct # periods and scopes in historical reports. unique[key] = document return list(unique.values()), task, expected_period, expected_filters def _snapshot(result): summary = result.get('summary') if not isinstance(summary, dict): return None return {**summary, 'period': result.get('period'), 'coverage': result.get('coverage')} def _metric_requests(task): fields = task.get('fields') if isinstance(task, dict) else None stages = task.get('stages') if isinstance(task, dict) else None if not isinstance(fields, list): fields = [] fields = [field for field in fields if field in _FIELD_LABELS] if not isinstance(stages, list): stages = [] stages = [stage for stage in stages if stage in ('black', 'bright')] # A report without a requested field set gives the user the official # composite rate and both stage snapshots, without inventing a combined # weight denominator. if not fields: selected_stages = stages or ['black', 'bright'] return [('overall', 'rate'), *((stage, field) for stage in selected_stages for field in ('rate', 'totalWeight', 'scrapWeight'))] if stages: return [(stage, field) for stage in stages for field in fields] # With no stage selected, only the server's official composite rate is a # valid aggregate. Formal scrap rates remain stage-specific; never invent # a combined scrap-rate denominator. requests = [('overall', field) for field in fields if field != 'scrapRate'] if 'scrapRate' in fields: requests.extend((stage, 'scrapRate') for stage in ('black', 'bright')) return requests def _coverage_reason(snapshot, stage): from nao_quality_tools import _valid_stage_period_coverage selected_period = snapshot.get('period') or {} ok, reason = _valid_stage_period_coverage(snapshot, selected_period, stage) return None if ok else reason or '阶段来源覆盖不足。' def _value(snapshot, stage, field): if stage == 'overall': if field != 'rate': return None, '未指定阶段,服务端未提供该聚合指标。' from nao_quality_tools import _valid_composite_rate_reference _, reason = _valid_composite_rate_reference(snapshot, snapshot.get('period') or {}) value = snapshot.get('compositeRate') else: stage_values = snapshot.get(stage) if isinstance(snapshot.get(stage), dict) else {} if field == 'rate': from nao_quality_tools import _valid_stage_rate_reference metric_snapshot = {**snapshot, 'summary': {stage: stage_values}} _, reason = _valid_stage_rate_reference(metric_snapshot, snapshot.get('period') or {}, stage) elif field == 'scrapRate': from nao_quality_tools import _valid_stage_scrap_rate_reference metric_snapshot = {**snapshot, 'summary': {stage: stage_values}} _, reason = _valid_stage_scrap_rate_reference(metric_snapshot, snapshot.get('period') or {}, stage) else: reason = _coverage_reason(snapshot, stage) value = stage_values.get(field) from nao_evidence_report import number if reason: return None, reason numeric = number(value) if numeric is None or field in ('scrapRate', 'scrapWeight') and numeric < 0: return None, '服务端未提供该正式指标。' return value, None def _build_trend_report(evidence, context, question): """Render only formal, frame-bound monthly observations; never recompute a KPI.""" documents, task, requested_period, requested_filters = _metric_documents(evidence, context) missing = [] report = {'headline': '按已取得的正式月度指标分析变化。', 'sections': [], 'facts': [], 'policy': '月度值直接引用正式指标;未提供的月份不补零,未计算年度平均值。', 'missingEvidence': missing, 'coverageSufficient': False, 'rawMetrics': []} expected_release = context.get('releaseId') if isinstance(context, dict) else None if not isinstance(expected_release, str) or not expected_release: missing.append('月度趋势缺少明确的数据版本。') return report try: requested_period = normalize_period(requested_period) valid_months = set(expected_months(requested_period)) except ValueError: missing.append('月度趋势缺少明确的年份或季度范围。') return report if requested_period is None or 'month' in requested_period: missing.append('月度趋势缺少明确的多月期间范围。') return report # Historical report assembly may otherwise intentionally collect several # frames. A single trend fact must never relabel another frame as this one. documents = [document for document in documents if document['result'].get('releaseId') == expected_release and document.get('releaseId') in (None, expected_release) and _filters(document['result'].get('filters')) == requested_filters and _period_key(document['result'].get('period')) == _period_key(requested_period)] if len(documents) != 1: missing.append('未取得与本轮版本、期间和范围一致的月度趋势依据。') return report document = documents[0] result = document['result'] reference = document['evidenceRef'] if result.get('view') != 'overall': missing.append('月度趋势依据不是本轮指定范围的正式指标。') return report trend = result.get('trend') count = result.get('trendCount') if (not isinstance(trend, list) or type(count) is not int or count != len(trend) or result.get('trendTruncated') is not False or len(trend) > 36): missing.append('正式月度趋势数据缺失或不完整,无法确认全部返回月份。') return report expected_year = requested_period['year'] rows = {} for row in trend: if not isinstance(row, dict) or not isinstance(row.get('period'), str): missing.append('正式月度趋势包含无法确认的期间。') return report match = re.fullmatch(r'(\d{4})-(0[1-9]|1[0-2])', row['period']) if not match or int(match.group(1)) != expected_year or int(match.group(2)) not in valid_months: missing.append('月度趋势包含本轮期间以外的数据,无法安全引用。') return report month = int(match.group(2)) if month in rows: missing.append('月度趋势存在重复期间,无法安全引用。') return report rows[month] = row scope_label = _scope_label(requested_filters) from nao_evidence_report import number parent_coverage = result.get('coverage') or {} source_months = parent_coverage.get('sourceMonths') if isinstance(parent_coverage, dict) else None source_by_month = {item.get('month'): item for item in source_months or [] if isinstance(item, dict) and item.get('year') == expected_year} for stage, field in _metric_requests(task): visual_minimum = 2 if task and task.get('visualType') == 'line' else 3 label, is_percent, suffix = _FIELD_LABELS[field] stage_label = '综合' if stage == 'overall' else dict(_STAGES)[stage] metric_label = stage_label + label if stage == 'overall' and field != 'rate': missing.append(f'{metric_label}没有正式的跨阶段月度指标。') continue observed = {} for month, row in rows.items(): row_coverage = row.get('coverage') or {} source = source_by_month.get(month) or {} def stage_missing(name): field_name = name + 'Rows' a, b = row_coverage.get(field_name), source.get(field_name) if ('monthStart' in requested_period and task and task.get('periodCoverage') == 'complete'): return (type(a) is not int or isinstance(a, bool) or a <= 0 or type(b) is not int or isinstance(b, bool) or b <= 0) return a == 0 or b == 0 def effective_source_row(): result_row = {'year': expected_year, 'month': month} for selected_stage in ('black', 'bright'): field_name = selected_stage + 'Rows' row_count = row_coverage.get(field_name) source_count = source.get(field_name) if isinstance(source, dict) else None if (type(row_count) is int and row_count >= 0 and type(source_count) is int and source_count >= 0): result_row[field_name] = min(row_count, source_count) elif type(row_count) is not int or row_count < 0: result_row[field_name] = row_count else: result_row[field_name] = source_count return result_row # The formal business rule defines a usable composite even when # just one stage has source rows. Keep the same availability test # as the chart; unknown coverage in older evidence stays unknown. if not isinstance(row_coverage, dict): continue month_period = {'year': expected_year, 'month': month} if stage == 'overall': metric_snapshot = { 'period': month_period, 'coverage': {'sourceMonths': [effective_source_row()]}, 'summary': {'compositeRate': row.get('compositeRate'), 'black': row.get('black'), 'bright': row.get('bright')}, } from nao_quality_tools import _valid_composite_rate_reference if not _valid_composite_rate_reference(metric_snapshot, month_period)[0]: continue if stage != 'overall' and stage_missing(stage): continue if stage != 'overall' and field == 'rate': field_name = stage + 'Rows' row_count = row_coverage.get(field_name) source_count = source.get(field_name) if isinstance(source, dict) else None if type(row_count) is not int or row_count <= 0 or type(source_count) is not int or source_count <= 0: continue from nao_quality_tools import _valid_stage_rate_reference metric_snapshot = {'period': month_period, 'coverage': {'sourceMonths': [source]}, 'summary': {stage: row.get(stage)}} if not _valid_stage_rate_reference(metric_snapshot, month_period, stage)[0]: continue if field == 'scrapRate' and stage != 'overall': field_name = stage + 'Rows' row_count = row_coverage.get(field_name) if isinstance(row_coverage, dict) else None source_count = source.get(field_name) if isinstance(source, dict) else None if (type(row_count) is not int or row_count <= 0 or type(source_count) is not int or source_count <= 0): continue from nao_quality_tools import _valid_stage_scrap_rate_reference metric_snapshot = {'period': month_period, 'coverage': {'sourceMonths': [effective_source_row()]}, 'summary': {stage: row.get(stage)}} if not _valid_stage_scrap_rate_reference(metric_snapshot, month_period, stage)[0]: continue if row.get('noData') is True or row.get('monthStatus') in ('future', 'unavailable'): continue raw = row.get('compositeRate') if stage == 'overall' else (row.get(stage) or {}).get(field) value = number(raw) signed_black_input = stage == 'black' and field == 'totalWeight' if (value is None or value < 0 and not signed_black_input or is_percent and field != 'scrapRate' and value > 1): continue observed[month] = raw if len(observed) < 2: missing.append(f'{metric_label}只有{len(observed)}个可用月度值,不足以判断趋势。') if task and task.get('visualPreference') == 'required' and len(observed) < visual_minimum: missing.append(f'{metric_label}只有{len(observed)}个有效月份,少于{visual_minimum}个月图表要求。') if not observed: continue first, last = min(observed), max(observed) display_months = valid_months if 'monthStart' in requested_period else range(first, last + 1) values = [f'{month}月{shown(observed[month], percent=is_percent)}{suffix}' if month in observed else f'{month}月未提供' for month in display_months] period_label = format_period(requested_period) if 'monthStart' in requested_period else f'{expected_year}年' trend_text = f'{period_label};{scope_label};{metric_label}月度趋势:' + '、'.join(values) + '。' if len(observed) >= 2: start, end = number(observed[first]), number(observed[last]) direction = '上升' if end > start else '下降' if end < start else '持平' trend_text += f'首末对比,{last}月较{first}月{direction};未提供月份不补零。' if len(observed) < visual_minimum and task and task.get('visualPreference') != 'none': trend_text += f'不足{visual_minimum}个有效月份,暂无法生成所选趋势图。' fact = {'id': 'F' + str(len(report['facts']) + 1), 'kind': 'trend', 'label': metric_label + '月度趋势', 'text': trend_text, 'evidenceRef': reference} report['facts'].append(fact) report['sections'].append('### ' + metric_label + '月度趋势\n\n' + trend_text + '[' + reference + ']') if task and task.get('periodCoverage') == 'complete' and any(month not in observed for month in valid_months): missing.append(f'{metric_label}未覆盖所要求期间的全部月份。') report['rawMetrics'].append({'evidenceRef': reference, 'releaseId': result.get('releaseId'), 'period': result.get('period'), 'filters': requested_filters, 'trend': trend, 'coverage': parent_coverage}) report['missingEvidence'] = list(dict.fromkeys(missing)) report['coverageSufficient'] = bool(report['facts']) and not report['missingEvidence'] return report def _build_metrics_report(evidence, context, question, *, required=False): documents, task, expected_period, expected_filters = _metric_documents(evidence, context) if not documents: if required: raise ValueError('缺少与本轮范围、期间一致的单期正式指标') return None selected_frames = {(doc['result'].get('releaseId'), _period_key(doc['result'].get('period')), json.dumps(_filters(doc['result'].get('filters')), ensure_ascii=False, sort_keys=True)) for doc in documents} missing = [] if not _history_all(task) and expected_period is None: unique_periods = {_period_key(doc['result'].get('period')) for doc in documents} if len(unique_periods) > 1: missing.append('本轮包含多个单期期间,需明确要回答的期间。') # Semantic metric coverage is the authoritative check for selected period, # fields, stages, and scope. The report still lists only the matching frame. if task is not None and task.get('kind') == 'metrics' and question: from nao_analysis_coverage import semantic_metric_gaps missing.extend(semantic_metric_gaps(evidence, question, context)) facts = [] sections = [] raw_metrics = [] requests = _metric_requests(task) for document in documents: result = document['result'] reference = document['evidenceRef'] snapshot = _snapshot(result) if snapshot is None or not isinstance(snapshot.get('period'), dict): missing.append('单期正式指标缺少可识别的业务期间或指标摘要。') continue label = format_period(snapshot['period']) scope_label = _scope_label(result.get('filters')) rows = [] for stage, field in requests: field_label, is_percent, suffix = _FIELD_LABELS[field] stage_label = '综合' if stage == 'overall' else dict(_STAGES)[stage] metric_label = stage_label + field_label value, reason = _value(snapshot, stage, field) shown_value = shown(value, percent=is_percent) + suffix if reason is None else '未提供' fact_text = f'{label};{scope_label};{metric_label}:{shown_value}。' if stage == 'overall' and field == 'rate' and reason is None: missing_stages = [dict(_STAGES)[selected] for selected, _ in _STAGES if _value(snapshot, selected, 'rate')[1]] if missing_stages: fact_text += ('缺少' + '、'.join(missing_stages) + '可用独立阶段指标;综合率沿用服务端正式值,缺失阶段不作为实测100%。') fact = {'id': 'F' + str(len(facts) + 1), 'kind': 'overall' if stage == 'overall' else 'stage', 'label': metric_label, 'text': fact_text, 'evidenceRef': reference} facts.append(fact) rows.append([metric_label, shown_value]) if reason: missing.append(f'{label}{scope_label}{metric_label}:{reason}') section = ('### ' + label + ' · ' + scope_label + '\n\n' + '| 指标 | 正式值 |\n| --- | --- |\n' + '\n'.join('| ' + cell(key) + ' | ' + cell(value) + ' |' for key, value in rows) + '\n\n[' + reference + ']') sections.append(section) raw_metrics.append({'evidenceRef': reference, 'releaseId': result.get('releaseId'), 'period': result.get('period'), 'filters': _filters(result.get('filters')), 'summary': result.get('summary'), 'coverage': result.get('coverage')}) if not facts: raise ValueError('单期指标没有可绑定的事实') distinct_frames = len(selected_frames) headline = ('已列示前述各期间与范围的正式单期指标。' if distinct_frames > 1 else '已列示本期正式质量指标。') return {'headline': headline, 'sections': sections, 'facts': facts, 'policy': '指标值直接引用服务端正式质量指标摘要;重量单位为 kg,合格率按正式值显示,不在此处重算。', 'missingEvidence': list(dict.fromkeys(missing)), 'coverageSufficient': not missing, 'rawMetrics': raw_metrics} def historical_leaf_report(evidence, context=None): """Reuse validated leaf results without requiring an unrelated parent KPI. Every frame keeps its own period, filters and stage. Only evidence already selected by the report's session/release provenance is eligible here. """ task = _task(context) if not task or task.get('kind') != 'report' or task.get('historyMode') not in ('all', 'last'): return None from nao_defect_report import build_single_defect_report from nao_weight_ranking import ranking_report, ranking_gaps frames = {} for document in evidence: result = document.get('result') or {} kind = result.get('kind') if (kind not in ('quality_fine_defects', 'quality_weight_ranking') or result.get('comparisonPeriod') is not None or result.get('releaseId') != (context or {}).get('releaseId')): continue if task['historyMode'] == 'last': if _filters(result.get('filters')) != _context_filters(context, task): continue if task.get('period') and _period_key(result.get('period')) != _period_key(task['period']): continue key = json.dumps([kind, result.get('period'), _filters(result.get('filters')), result.get('stage'), result.get('dimension'), result.get('metric'), result.get('category'), result.get('defect')], sort_keys=True) frames[key] = document if not frames: return None report = {'headline':'已整理前述查询保存的缺陷或重量排名依据。', 'facts':[], 'sections':[], 'missingEvidence':[], 'coverageSufficient':False, 'rawMetrics':[]} for document in frames.values(): result = document['result']; dimension = result.get('dimension'); stage = result.get('stage') frame = {**task, 'period':result.get('period'), 'comparisonPeriod':None, 'comparisonRequired':False, 'filters':_filters(result.get('filters')), 'dimensions':[dimension], 'stages':[stage], 'dimensionStages':{dimension:[stage]}, 'fields':['scrapWeight'], 'visualPreference':'auto', 'visualType':None, 'periodCoverage':'available'} part = None if result['kind'] == 'quality_fine_defects' and document.get('mode') == 'defects': part = build_single_defect_report([document], frame, context) elif (result['kind'] == 'quality_weight_ranking' and document.get('mode') == 'rank' and dimension in ('product','department','group') and stage in ('black','bright') and result.get('metric') in ('totalWeight','scrapWeight')): frame['fields'] = [result['metric']] if not ranking_gaps([document], frame, context): part = ranking_report([document], frame, context) if part is None: gap = format_period(result.get('period') or {})+';'+_scope_label(result.get('filters'))+';前述排名缺少完整有效依据。' report['missingEvidence'].append(gap) continue prefix = format_period(frame['period'])+';'+_scope_label(frame['filters'])+';' for fact in part['facts']: fact['text'] = prefix + fact['text'] part['sections'] = ['### '+prefix.rstrip(';')+'\n\n'+section for section in part['sections']] _append_part(report, part) report['coverageSufficient'] = bool(report['facts']) and not report['missingEvidence'] return report def build_noncomparison_report(evidence, context=None, question=None): """Render exact-period `quality_metrics` facts without requiring a comparison. Query-only evidence is eligible when it is an actual `quality_metrics` result. Generic `quality_query` documents are never treated as KPI values. """ from nao_weight_ranking import ranking_task,ranking_report task = _task(context) if ranking_task(task): report = ranking_report(evidence,task,context) if task.get('trendRequired'): _append_part(report, _build_trend_report(evidence, context, question)) return report if task and task.get('trendRequired'): return _build_trend_report(evidence, context, question) from nao_defect_report import build_single_defect_report from nao_agent_contract import primary_query_required if task and not primary_query_required(task): defect_report = build_single_defect_report(evidence, task, context) if defect_report is not None: return defect_report report = _build_metrics_report(evidence, context, question, required=False) if report is not None: return report defect_report = build_single_defect_report(evidence, task, context) if defect_report is not None: return defect_report leaf_report = historical_leaf_report(evidence, context) if leaf_report is not None and leaf_report['facts']: return leaf_report task = _task(context) source_only = bool(task and ((task.get('kind') == 'source_verify' and task.get('verifySource')) or (task.get('kind') == 'details' and task.get('fullDetails')) or (task.get('kind') == 'report' and task.get('historyMode') in ('all', 'last')))) if not source_only: raise ValueError('缺少与本轮范围、期间一致的单期正式指标') report = {'headline': '本轮原表核验与明细读取依据。', 'sections': [], 'facts': [], 'policy': '本节只汇报已保存依据中的核验状态和分页计数;不展示原始文件路径或原始记录内容。', 'missingEvidence': [], 'coverageSufficient': False, 'rawMetrics': []} _append_investigation_report(report, evidence, context) if not report['facts']: raise ValueError('缺少与本轮范围、期间、阶段一致的原表或明细依据') from nao_evidence_finalizer import coverage_sufficient report['coverageSufficient'] = coverage_sufficient(evidence, question or task.get('question', ''), context) if not report['coverageSufficient']: request_label = '原表核验' if task.get('verifySource') else '完整明细读取' report['missingEvidence'] = [f'本轮要求的{request_label}依据尚未覆盖所有指定阶段、期间或记录。'] return report def _comparison_frame_keys(evidence): frames = set() for document in evidence: result = document.get('result') if isinstance(document, dict) else None if not isinstance(result, dict) or result.get('kind') != 'quality_comparison': continue filters_key = json.dumps(_filters(result.get('filterBinding')), ensure_ascii=False, sort_keys=True) for side in ('current', 'comparison'): snapshot = result.get(side) or {} frames.add((result.get('releaseId'), _period_key(snapshot.get('period')), filters_key)) return frames def _append_part(report, part, *, include_raw=True): offset = len(report.setdefault('facts', [])) for index, fact in enumerate(part.get('facts', []), start=offset + 1): fact['id'] = 'F' + str(index) report['facts'].append(fact) report.setdefault('sections', []).extend(part.get('sections', [])) report['missingEvidence'] = list(dict.fromkeys([*report.get('missingEvidence', []), *part.get('missingEvidence', [])])) report['coverageSufficient'] = not report['missingEvidence'] if part.get('policy'): report['policy'] = (str(report.get('policy') or '').rstrip() + ' ' + str(part['policy'])).strip() if include_raw and part.get('rawMetrics'): existing = report.get('rawMetrics') if isinstance(existing, list): report['rawMetrics'] = [*existing, *part['rawMetrics']] elif existing is None: report['rawMetrics'] = list(part['rawMetrics']) else: report['rawMetrics'] = {'comparisons': existing, 'singlePeriod': list(part['rawMetrics'])} def _investigation_docs(evidence, context): task = _task(context) history_all = _history_all(task) expected_release = context.get('releaseId') if isinstance(context, dict) else None expected_filters = _context_filters(context, task) periods = set() stages = set() if task is not None: for key in ('period', 'comparisonPeriod'): if isinstance(task.get(key), dict): periods.add(_period_key(task[key])) stages.update(stage for stage in task.get('stages', []) if stage in ('black', 'bright')) if not stages: stages.update(('black', 'bright')) selected = [] for document in evidence: result = document.get('result') if isinstance(document, dict) else None if (not isinstance(result, dict) or result.get('kind') != 'quality_investigation' or result.get('action') not in ('source', 'rows') or document.get('mode') != 'investigate'): continue if expected_release is not None and result.get('releaseId') != expected_release: continue if not history_all: if result.get('stage') not in stages or _filters(result.get('filters')) != expected_filters: continue if result.get('category') is not None: continue selected.append(document) return selected, task, history_all, periods, stages, expected_filters def _source_coverage_complete(coverage, total_rows): if not isinstance(coverage, dict) or type(total_rows) is not int or total_rows <= 0: return False if coverage.get('rows') != total_rows or coverage.get('numericRows') != total_rows: return False return all(type(coverage.get(key)) is int and coverage.get(key) == 0 for key in ('keyAbsentRows', 'nullOrBlankRows', 'invalidNumericRows', 'negativeRows')) def _source_category_fields(category): rows = [] for item in category.get('fields') or []: if isinstance(item, dict) and isinstance(item.get('coverage'), dict): rows.append({'field': item.get('field'), **item['coverage']}) for item in category.get('fieldCoverageLimits') or []: if isinstance(item, dict): rows.append(dict(item)) columns, values = category.get('fieldCoverageColumns'), category.get('fieldCoverage') if isinstance(columns, list) and isinstance(values, list): for row in values: if isinstance(row, list) and len(row) == len(columns): rows.append(dict(zip(columns, row))) unique = {} for row in rows: field = row.get('field') if isinstance(field, str) and field: unique[field] = row return list(unique.values()) def _source_category_reconciliation(category, *, total_rows, selected_fields, source_proof, stage, period, filters, release_id): """Return a safe, scope-bound summary of formal/source category reconciliation.""" category_name = category.get('category') formal_coverage = category.get('formalCoverage') raw_coverage = category.get('rawTotalCoverage') fields = _source_category_fields(category) reasons = [] proof_complete = (isinstance(source_proof, dict) and source_proof.get('complete') is True and source_proof.get('allSelectedValuesMatchStored') is True and source_proof.get('expectedRows') == total_rows and source_proof.get('verifiedRows') == total_rows and source_proof.get('missingRows') == 0 and source_proof.get('mismatchRows') == 0) if not proof_complete: reasons.append('原表所选字段与已存储原始值尚未完整匹配') if not _source_coverage_complete(raw_coverage, total_rows): reasons.append('原表对应类别总量字段缺失或覆盖不完整') if not _source_coverage_complete(formal_coverage, total_rows): reasons.append('正式类别分量覆盖不完整') field_names = {row.get('field') for row in fields if isinstance(row.get('field'), str)} if category.get('noFineFields') is True or not fields: reasons.append('没有可用的来源细项,无法核对分项合计') else: if not field_names.issubset(selected_fields): reasons.append('本次原表核验未覆盖全部来源细项') if any(not _source_coverage_complete(row, total_rows) for row in fields): reasons.append('来源细项存在缺失或无效值,覆盖不完整') if type(category.get('rawFormalMismatchRows')) is not int: reasons.append('缺少原表类别总量与正式分量的逐行对账结果') elif category['rawFormalMismatchRows'] != 0: reasons.append('原表类别总量与正式分量存在逐行差异') comparable = category.get('comparableRows') missing_formal = category.get('missingOrInvalidFormalRows') if comparable != total_rows or missing_formal != 0: reasons.append('正式分量与来源细项未覆盖全部对应行') difference = category.get('differenceFormalMinusSubitems') try: delta = Decimal(str(difference)) if difference is not None else None except (InvalidOperation, TypeError, ValueError): delta = None if delta is None: reasons.append('正式分量与来源细项合计无法完整对账') elif abs(delta) > Decimal('0.000001'): reasons.append('正式分量与来源细项合计存在差异') if category.get('requiresFurtherInvestigation') is not False: reasons.append('服务端标记仍需进一步核查') reasons = list(dict.fromkeys(reasons)) reconciled = not reasons return { 'category': category_name, 'status': 'RECONCILED' if reconciled else 'UNRESOLVED', 'reconciled': reconciled, 'releaseId': release_id, 'stage': stage, 'period': dict(period) if isinstance(period, dict) else {}, 'filters': _filters(filters), 'reasons': reasons, } def _append_investigation_report(report, evidence, context): documents, task, history_all, expected_periods, expected_stages, expected_filters = _investigation_docs(evidence, context) if not documents: return rows, facts = [], [] detail_rows = {} for document in documents: result = document['result'] reference = document['evidenceRef'] action = result['action'] for side_name in ('current', 'comparison'): side = result.get(side_name) if not isinstance(side, dict): continue side_context = side.get('context') if isinstance(side.get('context'), dict) else {} selected_period = {key: side_context[key] for key in PERIOD_KEYS if side_context.get(key) is not None} stage = side_context.get('stage') or result.get('stage') if not selected_period: fallback_period = result.get('period') if side_name == 'current' else result.get('comparisonPeriod') selected_period = fallback_period if isinstance(fallback_period, dict) else {} if not history_all: if stage not in expected_stages: continue if expected_periods and _period_key(selected_period) not in expected_periods: continue if side_context: context_filters = {key: side_context[key] for key in ('department', 'group', 'product', 'projectGroup', 'extraFilters', 'exclusions', 'includeUnassigned') if key in side_context} if _filters(context_filters) != expected_filters: continue side_period = format_period(selected_period) if selected_period else '期间未标明' stage_label = dict(_STAGES).get(stage, '阶段未标明') if action == 'source': proof = side.get('sourceVerification') if isinstance(side.get('sourceVerification'), dict) else {} expected = proof.get('expectedRows') verified = proof.get('verifiedRows') total_rows = side.get('totalRows') complete = (proof.get('complete') is True and proof.get('allSelectedValuesMatchStored') is True and side.get('aggregateComplete') is True and type(total_rows) is int and total_rows > 0 and type(expected) is int and expected == total_rows and type(verified) is int and verified == total_rows and type(proof.get('missingRows')) is int and proof.get('missingRows') == 0 and type(proof.get('mismatchRows')) is int and proof.get('mismatchRows') == 0) status = '所选原表值与已存储原始值全部匹配且核验完整' if complete else '原表核验未完整通过' count_text = f'已核验{verified}行/应核验{expected}行' if type(verified) is int and type(expected) is int else '核验行数未提供' mismatch_text = ';'.join( f'{label}{proof[name]}条' if type(proof.get(name)) is int else f'{label}数量未提供' for name, label in (('missingRows', '未核验'), ('mismatchRows', '不一致'))) proof_boundary = '该核验只证明所选原表值与已存储原始值一致,不证明正式类别与来源细项已对账。' fact_text = f'{side_period};{stage_label};{status},{count_text};{mismatch_text};{proof_boundary}' source_count_values = [] for count, metric in ((verified, 'sourceVerifiedRows'), (expected, 'sourceExpectedRows'), (proof.get('missingRows'), 'sourceMissingRows'), (proof.get('mismatchRows'), 'sourceMismatchRows')): if type(count) is int and count >= 0: source_count_values.append({'rawValue': str(count), 'displayValue': str(count), 'unit': 'metadata_count', 'metricField': metric, 'stageHint': stage_label, 'period': selected_period, 'sourceVerificationCount': True}) rows.append([side_period, stage_label, '原表核验', status + ';' + count_text + ';' + mismatch_text, reference]) source_fact = {'kind': 'source', 'label': stage_label + '原表核验', 'text': fact_text, 'evidenceRef': reference, '_nativeSourceValues': source_count_values} facts.append(source_fact) # Surface only authorized aggregate coverage and official # category components. Raw rows, workbook values, filenames, # and mismatch examples never enter the narration facts. selected_fields = side.get('selectedFields') selected_fields = {value for value in selected_fields if isinstance(value, str) and value} if isinstance(selected_fields, list) else set() categories = side.get('categories') if isinstance(side.get('categories'), list) else [] category_names = [str(item.get('category')) for item in categories if isinstance(item, dict) and isinstance(item.get('category'), str)] category_relations = [] for category in categories: if not isinstance(category, dict) or not isinstance(category.get('category'), str): continue category_name = category['category'] relation = _source_category_reconciliation(category, total_rows=total_rows, selected_fields=selected_fields, source_proof=proof, stage=stage, period=selected_period, filters=result.get('filters'), release_id=result.get('releaseId')) category_relations.append(relation) if relation['reconciled']: reconciliation_text = (f'{side_period};{stage_label};{category_name}正式类别分量、原表类别总量与来源细项已完整对账一致。') else: reasons = ';'.join(relation['reasons']) reconciliation_text = (f'{side_period};{stage_label};{category_name}正式类别分量与原表类别总量/来源细项未完整对账;' f'当前卡点:{reasons}。') rows.append([side_period, stage_label, category_name + '类别对账', '已完整对账一致' if relation['reconciled'] else '未完整对账:' + reasons, reference]) facts.append({'kind': 'source_reconciliation', 'label': category_name + '类别对账', 'text': reconciliation_text, 'evidenceRef': reference, '_nativeSourceCategoryReconciliation': relation}) formal_weight = category.get('formalWeight') formal_coverage = category.get('formalCoverage') if isinstance(category.get('formalCoverage'), dict) else {} numeric_rows = formal_coverage.get('numericRows') coverage_rows = formal_coverage.get('rows') complete_component = (type(total_rows) is int and total_rows > 0 and coverage_rows == total_rows and type(numeric_rows) is int and numeric_rows == total_rows and all(type(formal_coverage.get(key)) is int and formal_coverage.get(key) == 0 for key in ('keyAbsentRows', 'nullOrBlankRows', 'invalidNumericRows', 'negativeRows'))) from nao_evidence_report import number formal_value = number(formal_weight) if complete_component and formal_value is not None and formal_value >= 0: facts.append({'kind': 'category', 'label': category_name, 'text': f'{side_period};{stage_label}正式大类分量:{category_name}为{shown(formal_value)} kg。', 'evidenceRef': reference, '_nativeSourceValues': [{'rawValue': str(formal_value), 'displayValue': shown(formal_value), 'unit': 'kg', 'metricField': 'categoryWeight', 'stageHint': stage_label, 'categoryHint': category_name, 'categoryNames': category_names, 'period': selected_period, 'releaseId': result.get('releaseId')}], '_nativeSourceCategoryReconciliation': relation}) # These field names are emitted only when the server says # they were selected for this source check. Missing or bad # values remain coverage gaps; they are never represented # as zero weight. field_rows = [] for item in category.get('fields') or []: if isinstance(item, dict) and isinstance(item.get('coverage'), dict): field_rows.append((item.get('field'), item['coverage'])) for item in category.get('fieldCoverageLimits') or []: if isinstance(item, dict): field_rows.append((item.get('field'), item)) columns, values = category.get('fieldCoverageColumns'), category.get('fieldCoverage') if isinstance(columns, list) and isinstance(values, list): for row in values: if isinstance(row, list) and len(row) == len(columns): mapped = dict(zip(columns, row)) field_rows.append((mapped.get('field'), mapped)) deduped = {} for field_name, coverage in field_rows: if isinstance(field_name, str) and field_name in selected_fields and isinstance(coverage, dict): deduped[field_name] = coverage for field_name, coverage in deduped.items(): issues = [] for key, label in (('keyAbsentRows', '缺列'), ('nullOrBlankRows', '空值'), ('invalidNumericRows', '非数值'), ('negativeRows', '负值')): count = coverage.get(key) if type(count) is int and count > 0: issues.append(label) rows_with_coverage = coverage.get('rows') numeric_count = coverage.get('numericRows') if (type(rows_with_coverage) is int and type(numeric_count) is int and numeric_count < rows_with_coverage and not issues): issues.append('有效数值覆盖不足') if issues: fact_text = (f'{side_period};{stage_label}来源字段“{field_name}”存在' + '、'.join(issues) + ';缺失或非法覆盖不能按零处理。') facts.append({'kind': 'source_coverage', 'label': field_name, 'text': fact_text, 'evidenceRef': reference}) source_fact['_nativeSourceCategoryReconciliations'] = category_relations else: matching = side.get('matchingRows') returned = side.get('returnedRows') offset = side.get('offset') more = side.get('hasMore') record_filter = cell(side.get('recordFilter') or result.get('recordFilter') or '未标明') selection = {'all': '全部记录', 'differences': '差异记录', 'unexpectedDifferences': '需核查的差异记录'}.get(record_filter, '已选记录') page_end = '已取到末页' if more is False else '还有记录待读取' count_text = f'{selection}共{matching}条,本页{returned}条;{page_end}' fact_text = f'{side_period};{stage_label};明细页:{count_text}。' rows.append([side_period, stage_label, '明细页', count_text, reference]) facts.append({'kind': 'rows', 'label': stage_label + '明细页', 'text': fact_text, 'evidenceRef': reference}) records = side.get('differenceRecords', side.get('rows')) if isinstance(records, list): destination = detail_rows.setdefault((side_period, stage_label), []) for record in records: if not isinstance(record, dict): continue row_number = _detail_cell(record.get('rowNumber')) product = record.get('product') or record.get('group') product = _detail_cell(product) values = record.get('values') visible_values = [(name, value) for name, value in values.items() if not _private_detail_field(name)] if isinstance(values, dict) else [] if not visible_values: destination.append([f'{row_number} [{reference}]', product, '原字段值', '未提供']) else: for field, value in visible_values: destination.append([f'{row_number} [{reference}]', product, str(field), _detail_cell(value)]) if not rows: return section = ('### 原表核验与明细读取\n\n' '| 期间 | 阶段 | 内容 | 状态或分页计数 | 证据 |\n' '| --- | --- | --- | --- | --- |\n' + '\n'.join('| ' + ' | '.join(cell(value) for value in row) + ' |' for row in rows)) sections = [section] for (period_label, stage_label), detail in sorted(detail_rows.items()): rendered = _render_detail_section(period_label, stage_label, detail) if rendered: sections.append(rendered) part = {'sections': sections, 'facts': facts, 'missingEvidence': [], 'coverageSufficient': True, 'policy': ('本节汇报已保存依据中的核验状态和分页计数;完整明细表逐项引用接口返回的原字段和值,' '空值标记为“未提供”,不展示原始文件路径。'), 'rawMetrics': []} _append_part(report, part, include_raw=False) def append_noncomparison_sections(report, evidence, context=None): """Append distinct single-period frames and source/rows evidence in place.""" frames = _comparison_frame_keys(evidence) if frames: part = _build_metrics_report(evidence, context, None, required=False) if part is not None: filtered = [] for document in part['rawMetrics']: key = (document.get('releaseId'), _period_key(document.get('period')), json.dumps(_filters(document.get('filters')), ensure_ascii=False, sort_keys=True)) # The report and query summaries share the same authenticated # release. Only period/scope distinguishes already-rendered # comparison sides from additional historical snapshots. duplicate = key in frames if not duplicate: filtered.append(document) if len(filtered) != len(part['rawMetrics']): allowed_refs = {item['evidenceRef'] for item in filtered} part['facts'] = [fact for fact in part['facts'] if fact['evidenceRef'] in allowed_refs] part['sections'] = [section for section in part['sections'] if any('[' + ref + ']' in section for ref in allowed_refs)] part['rawMetrics'] = filtered if part['facts']: _append_part(report, part) _append_investigation_report(report, evidence, context) report['missingEvidence'] = list(dict.fromkeys(report.get('missingEvidence', []))) report['coverageSufficient'] = not report['missingEvidence'] return report def build_agent_report(evidence, context=None, question=None): """Build a report from comparisons when available, otherwise KPI queries.""" has_comparison = any(isinstance(doc, dict) and isinstance(doc.get('result'), dict) and doc['result'].get('kind') == 'quality_comparison' for doc in evidence) if has_comparison: from nao_evidence_report import build_report report = build_report(evidence, context, question) report = append_noncomparison_sections(report, evidence, context) task = _task(context) if task and task.get('trendRequired'): _append_part(report, _build_trend_report(evidence, context, question)) else: report = build_noncomparison_report(evidence, context, question) leaves = historical_leaf_report(evidence, context) if leaves is not None: existing_refs = {fact.get('evidenceRef') for fact in report.get('facts', [])} new_refs = {fact.get('evidenceRef') for fact in leaves['facts']} - existing_refs leaves['facts'] = [fact for fact in leaves['facts'] if fact.get('evidenceRef') in new_refs] leaves['sections'] = [section for section in leaves['sections'] if any('['+ref+']' in section for ref in new_refs)] if leaves['facts'] or leaves['missingEvidence']: _append_part(report, leaves) task = _task(context) if task is not None and (task.get('verifySource') or task.get('fullDetails')): from nao_evidence_finalizer import coverage_sufficient complete = coverage_sufficient(evidence, question or task.get('question', ''), context) if not complete: request_label = '原表核验' if task.get('verifySource') else '完整明细读取' gap = f'本轮要求的{request_label}依据尚未覆盖所有指定阶段、期间或记录。' report['missingEvidence'] = list(dict.fromkeys([*report.get('missingEvidence', []), gap])) report['coverageSufficient'] = False return report def build_scoped_protocol_report(evidence, scopes, *, question, release_id, initial_gaps=()): """Build each queryPlan node report against its exact proof and child frame.""" from nao_query_plan import scope_context, scope_documents report = {'headline': '按服务器授权的节点范围分别核对正式证据。', 'sections': [], 'facts': [], 'policy': '', 'requiredFactIds': [], 'missingEvidence': list(dict.fromkeys(str(gap) for gap in initial_gaps if isinstance(gap, str) and gap)), 'coverageSufficient': False, 'rawMetrics': []} represented = set() focused = any(isinstance(scope,dict) and scope.get('purpose') == 'changes' for scope in scopes if isinstance(scopes,list)) for scope in scopes if isinstance(scopes, list) else []: if not isinstance(scope, dict) or not isinstance(scope.get('task'), dict): report['missingEvidence'].append('服务器queryPlan范围记录不完整。') continue pair = (scope.get('nodeId'), scope.get('scopeId')) if pair in represented: report['missingEvidence'].append('queryPlan范围重复,无法确认唯一覆盖。') continue represented.add(pair) child_task = scope['task'] child_question = child_task.get('question') if isinstance(child_task.get('question'), str) else question selected = scope_documents(evidence, scope, release_id=release_id) label = scope.get('label') if isinstance(scope.get('label'), str) and scope.get('label').strip() else str(pair[0]) if not selected: report['sections'].append('### ' + label + '\n\n未取得与该子范围精确匹配的正式证据。') scope_gap_prefix = label+':' if not any(gap.startswith(scope_gap_prefix) for gap in report['missingEvidence']): report['missingEvidence'].append('节点'+str(pair[0])+'范围'+label+ '没有同期间、同筛选且绑定node/scope的正式证据。') continue context = scope_context(scope, release_id=release_id, question=question) try: if scope.get('purpose') == 'changes': from nao_changes import changes_report part = changes_report(selected, child_task, release_id) elif scope.get('purpose') == 'defects': from nao_defect_report import protocol_defect_report part = protocol_defect_report(selected, child_task, release_id) else: part = build_agent_report(selected, context, child_question) if focused and scope.get('purpose') == 'metrics': # Keep complete tables in the appendix, but give the model the # overall movement and stage drivers instead of every category. part['facts'] = [fact for fact in part.get('facts', []) if fact.get('kind') in ('overall','stage')] for document in selected: result = document.get('result') or {} decomposition = result.get('stageDecomposition') or {} if decomposition.get('status') != 'available': continue values = [decomposition.get(key) for key in ('blackContributionToCompositePP','brightContributionToCompositePP')] if any(value is None for value in values): continue old, now = result.get('comparison') or {}, result.get('current') or {} primary_stage = min(zip(values,('黑片','亮片')),key=lambda item:item[0]) lead = '主要不利阶段为'+primary_stage[1]+'。' if primary_stage[0] < 0 else '' text = (lead+'黑片合格率'+shown((old.get('black') or {}).get('rate'),percent=True)+'→' +shown((now.get('black') or {}).get('rate'),percent=True)+',亮片合格率' +shown((old.get('bright') or {}).get('rate'),percent=True)+'→' +shown((now.get('bright') or {}).get('rate'),percent=True) +';阶段影响拆解:黑片对综合合格率变化影响'+shown(values[0],signed=True) +'个百分点,亮片影响'+shown(values[1],signed=True) +'个百分点;这是正式阶段率变化的拆解,不代表生产根因。') part['facts'] = [fact for fact in part['facts'] if fact.get('kind')=='overall'] part['facts'].append({'id':'F'+str(len(part['facts'])+1),'kind':'stage', 'label':'阶段影响拆解','text':text,'evidenceRef':document['evidenceRef']}) except (KeyError, ValueError, TypeError): missing = [] # Composite-rate comparison reports require a formally published # rate on both sides. If one period has no usable source, retain # that exact period as a validated coverage gap instead of # reducing the failure to a generic formatting error. if (scope.get('purpose') == 'metrics' and child_task.get('comparisonRequired') and 'rate' in (child_task.get('fields') or []) and not (child_task.get('stages') or [])): from nao_evidence_report import _display_rate for document in selected: result = document.get('result') if isinstance(document, dict) else None if not isinstance(result, dict) or result.get('kind') != 'quality_comparison': continue for side_key in ('comparison', 'current'): side = result.get(side_key) if not isinstance(side, dict) or _display_rate(side) is not None: continue try: period_label = format_period(side.get('period') or {}) except (KeyError, TypeError, ValueError): period_label = '所选'+('对照' if side_key == 'comparison' else '当前')+'期间' missing.append('节点'+str(pair[0])+'范围'+label+';'+period_label+ '没有可引用的正式综合合格率或有效阶段来源覆盖。') if not missing: missing = ['节点'+str(pair[0])+'范围'+label+'的正式统计无法按子任务规则完成整理。'] part = {'headline': label, 'sections': [], 'facts': [], 'missingEvidence': missing, 'coverageSufficient': False, 'policy': '', 'rawMetrics': []} local_to_merged = {} for fact in part.get('facts', []): if not isinstance(fact, dict): continue merged_fact = {**fact, 'id': 'F'+str(len(report['facts'])+1), 'text': ('' if label=='基础范围' or scope.get('purpose')=='changes' else label+';')+str(fact.get('text') or ''), 'nodeId': pair[0], 'scopeId': pair[1], 'scopeLabel': label, 'scopePurpose': scope.get('purpose')} report['facts'].append(merged_fact) if isinstance(fact.get('id'), str): local_to_merged[fact['id']] = merged_fact['id'] if scope.get('purpose') in ('metrics', 'trend'): report['requiredFactIds'].append(merged_fact['id']) elif scope.get('purpose') == 'ranking' and fact.get('kind') == 'overall': # Each requested rank frame needs its denominator/Top summary # in the synthesized answer even when the model prefers a # concise narrative over the attached table. report['requiredFactIds'].append(merged_fact['id']) if scope.get('purpose') in ('defects','changes'): for fact_id in part.get('requiredFactIds', []): merged_id = local_to_merged.get(fact_id) if merged_id is not None and (not focused or scope.get('purpose') == 'changes' or len([fid for fid in report['requiredFactIds'] if fid in local_to_merged.values()]) < 1): report['requiredFactIds'].append(merged_id) for section in part.get('sections', []): if isinstance(section, str) and section: report['sections'].append(('' if label=='基础范围' else '### '+label+'\n\n')+section) report['missingEvidence'].extend(part.get('missingEvidence', [])) if (scope.get('purpose') in ('metrics', 'trend') and not part.get('facts') and not part.get('missingEvidence')): report['missingEvidence'].append('节点'+str(pair[0])+'范围'+label+'缺少可引用的指标事实。') if part.get('policy'): report['policy'] = (report['policy']+' '+part['policy']).strip() if not represented: report['missingEvidence'].append('没有任何queryPlan节点取得服务器授权范围。') report['missingEvidence'] = list(dict.fromkeys(report['missingEvidence'])) report['coverageSufficient'] = bool(report['facts']) and not report['missingEvidence'] if focused: from nao_changes import diagnostic_intent report['policy']=('来源具体缺陷重量不等同于总体报废贡献,生产原因需结合现场记录核查。' if diagnostic_intent(question) or any(scope.get('purpose')=='defects' for scope in scopes) else '') return report