"""Build small, deterministic chart snapshots from trusted quality evidence. The builder has no model, network, filesystem, or query dependencies. It accepts the complete evidence documents written by ``QualityTools._write_evidence`` and returns only bounded display facts; unsupported or unsafe candidates are skipped so callers can keep the existing written answer. """ from __future__ import annotations import hashlib import json import math import re from decimal import Decimal, InvalidOperation from typing import Any VISUAL_SCHEMA_VERSION = 1 MAX_VISUALS = 3 MAX_BODY_BYTES = 256 * 1024 MAX_RANK_ROWS = 10 MAX_TREND_POINTS = 36 MAX_TREND_SERIES = 4 MAX_LABEL_LENGTH = 160 _SAFE_ID = re.compile(r"^[A-Za-z0-9_.:-]{1,100}$") _SAFE_EVIDENCE_REF = re.compile(r"^(?:Q[A-F0-9]{8}|nao-quality-[a-f0-9]{32})$") _SAFE_KEY = re.compile(r"^[A-Za-z0-9_.:-]{1,120}$") _SCOPE_KEYS = {"year", "month", "quarter", "department", "group", "product", "projectGroup", "view", "includeUnassigned", "releaseId", "extraFilters", "category", "defect", "stage"} _DEFECT_FIELDS = { "black": { "责废": "black_responsibility_scrap", "料废": "black_material_scrap", "外废": "black_external_scrap", }, "bright": { "镀废": "bright_plating_scrap", "材料废": "bright_material_scrap", "加工废": "bright_processing_scrap", "扩散废": "bright_diffusion_scrap", }, } _SECRET_TEXT = re.compile( r"(?i)(?:bearer\s+\S+|(?:api[_-]?key|password|passwd|token|secret|authorization)\s*[=::]\s*\S+)" ) _URL = re.compile(r"(?i)\b(?:https?://|file://|ftp://)") _LOCAL_PATH = re.compile(r"(?:^|\s)/(?:Users|home|private|var|tmp|etc|opt)/") _CONTROL = re.compile(r"[\x00-\x1f\x7f]") _EXPLICIT_CHART = re.compile( r"图表|画图|绘图|可视化|趋势图|柱状图|柱形图|竖向柱|纵向柱|折线图|条形图|横条图|" r"横向柱|水平柱|面积图|面积趋势|热力图|热图|环状图|环形图|环状|环形|甜甜圈|饼图|" r"构成|占比|排名图|柏拉图|帕累托|pareto" ) _NO_CHART = re.compile(r"不画图|不要(?:绘图|图表?|可视化|配图)|不需要(?:绘图|图表?|可视化|配图)|无需(?:绘图|图表|配图)|只要(?:文字|文本)|仅需(?:文字|文本)") _HORIZONTAL_BAR = re.compile(r"横向条形图|横条图|横向柱|水平条形图|水平柱|horizontal\s+bar", re.IGNORECASE) _COLUMN_CHART = re.compile(r"柱状图|柱形图|竖向柱|纵向柱|column\s+chart", re.IGNORECASE) _AREA_CHART = re.compile(r"面积图|面积趋势|area\s+chart", re.IGNORECASE) _HEATMAP_CHART = re.compile(r"热力图|热图|heat\s*map", re.IGNORECASE) _DONUT_CHART = re.compile(r"环状图|环形图|环状|环形|甜甜圈|饼图|构成|占比|donut|doughnut|pie\s+chart", re.IGNORECASE) _PARETO_CHART = re.compile(r"柏拉图|帕累托|pareto", re.IGNORECASE) _LINE_CHART = re.compile(r"折线图|折线趋势|line\s+chart", re.IGNORECASE) _BAR_CHART = re.compile(r"条形图|bar\s+chart", re.IGNORECASE) _NEGATED_STYLE_PREFIX = re.compile(r"(?:不要|不用|无需|不需要|不画|不想要)\s*(?:使用|用|画)?\s*$") _ANALYSIS_INTENT = re.compile( r"对比|比较|变化|趋势|排名|排行|哪些|主要|恶化|改善|下降|上升|增量|增减|分析|分布|集中|top", re.IGNORECASE, ) _SIMPLE_SINGLE_METRIC = re.compile( r"^(?:请)?(?:查|看|告诉我|查询)?\s*(?:本期|当期|\d{4}年?\d{1,2}月?)?\s*" r"(?:综合合格率|合格率|报废重量|报废量|投入重量|黑片合格率|亮片合格率)" r"(?:是多少|多少|呢|\??\s*)$" ) def _result(document: Any) -> dict[str, Any] | None: if not isinstance(document, dict): return None value = document.get("result") return value if isinstance(value, dict) else None def _safe_text(value: Any, *, limit: int = MAX_LABEL_LENGTH) -> str | None: if not isinstance(value, str): return None text = value.strip() if not text or len(text) > limit or _CONTROL.search(text): return None if _SECRET_TEXT.search(text) or _URL.search(text) or _LOCAL_PATH.search(text): return None return text def _safe_id(value: Any) -> str | None: if not isinstance(value, str) or not _SAFE_ID.fullmatch(value): return None return value def _evidence_ref(document: dict[str, Any]) -> str | None: for key in ("evidenceRef", "evidenceId"): value = document.get(key) if isinstance(value, str) and _SAFE_EVIDENCE_REF.fullmatch(value): return value return None def _finite_number(value: Any) -> tuple[float | None, bool]: """Return (number, valid); ``None`` is a valid absent value, bool is not.""" if value is None: return None, True if isinstance(value, bool) or not isinstance(value, (int, float, Decimal)): return None, False if isinstance(value, int) and not isinstance(value, bool) and abs(value) > 9_007_199_254_740_991: return None, False try: number = float(value) except (TypeError, ValueError, OverflowError): return None, False if not math.isfinite(number): return None, False try: decimal = value if isinstance(value, Decimal) else Decimal(str(value)) exponent = decimal.as_tuple().exponent if not decimal.is_finite() or len(decimal.as_tuple().digits) > 64 or abs(exponent) > 64: return None, False except (InvalidOperation, ValueError, TypeError): return None, False return number, True def _safe_scope_value(value: Any, depth: int = 0) -> tuple[Any, bool]: if depth > 3: return None, False if value is None or isinstance(value, bool): return value, True if isinstance(value, str): text = _safe_text(value, limit=160) return text, text is not None if isinstance(value, int) and not isinstance(value, bool): return (value, abs(value) <= 9_007_199_254_740_991) if isinstance(value, float): return (value, math.isfinite(value)) if isinstance(value, dict): if len(value) > 40: return None, False clean: dict[str, Any] = {} for key, child in value.items(): safe_key = _safe_text(key, limit=80) if isinstance(key, str) else None if safe_key is None or re.search(r"(?i)api[_-]?key|password|passwd|token|secret|authorization", safe_key): return None, False safe_child, ok = _safe_scope_value(child, depth + 1) if not ok: return None, False clean[safe_key] = safe_child return clean, True if isinstance(value, (list, tuple)): if len(value) > 40: return None, False clean_list: list[Any] = [] for child in value: safe_child, ok = _safe_scope_value(child, depth + 1) if not ok: return None, False clean_list.append(safe_child) return clean_list, True return None, False def _scope(filters: Any) -> tuple[dict[str, Any] | None, str | None]: if not isinstance(filters, dict): return None, None clean, ok = _safe_scope_value(filters) if not ok or not isinstance(clean, dict): return None, None if any(key not in _SCOPE_KEYS for key in clean): return None, None extra = clean.get("extraFilters") if extra is not None: if not isinstance(extra, dict) or len(extra) > 20: return None, None if any(not isinstance(values, list) or len(values) > 50 or any(not isinstance(value, str) or len(value) > 256 for value in values) for values in extra.values()): return None, None try: encoded = json.dumps(clean, ensure_ascii=False, sort_keys=True, separators=(",", ":")) except (TypeError, ValueError): return None, None return clean, encoded def _chart_scope(filters: dict[str, Any], release_id: str, period: dict[str, Any] | None = None, view: str | None = None, stage: str | None = None, category: str | None = None, defect: str | None = None) -> dict[str, Any]: clean = dict(filters) clean["releaseId"] = release_id if period is not None and "start" not in period: for key in ("year", "month", "quarter"): if key in period: clean[key] = period[key] if view is not None: clean["view"] = view if stage in ("black", "bright"): clean["stage"] = stage if category is not None: clean["category"] = category if defect is not None: clean["defect"] = defect return clean def _period(value: Any) -> tuple[dict[str, int] | None, str | None, tuple[int, int, int] | None]: if not isinstance(value, dict): return None, None, None year = value.get("year") if isinstance(year, bool) or not isinstance(year, int) or not 2000 <= year <= 2100: return None, None, None month = value.get("month") quarter = value.get("quarter") if month is not None and quarter is not None: return None, None, None if isinstance(month, int) and not isinstance(month, bool) and 1 <= month <= 12: clean = {"year": year, "month": month} return clean, f"{year:04d}-{month:02d}", (year, month, 0) if isinstance(quarter, int) and not isinstance(quarter, bool) and 1 <= quarter <= 4: clean = {"year": year, "quarter": quarter} return clean, f"{year:04d}-Q{quarter}", (year, (quarter - 1) * 3 + 1, 1) if month is None and quarter is None: return {"year": year}, str(year), (year, 0, 2) return None, None, None def _trend_period(value: Any) -> tuple[str | None, tuple[int, int, int] | None]: if isinstance(value, dict): _, label, order = _period(value) return label, order if not isinstance(value, str): return None, None match = re.fullmatch(r"(\d{4})-(\d{2})", value) if match: year, month = int(match.group(1)), int(match.group(2)) if 2000 <= year <= 2100 and 1 <= month <= 12: return value, (year, month, 0) match = re.fullmatch(r"(\d{4})-Q([1-4])", value) if match: year, quarter = int(match.group(1)), int(match.group(2)) if 2000 <= year <= 2100: return value, (year, (quarter - 1) * 3 + 1, 1) if re.fullmatch(r"\d{4}", value): year = int(value) if 2000 <= year <= 2100: return value, (year, 0, 2) return None, None def _release_id(document: dict[str, Any], result: dict[str, Any]) -> str | None: value = result.get("releaseId") if not _safe_id(value): return None wrapped = document.get("releaseId") if wrapped is not None and wrapped != value: return None release = result.get("release") if release is not None: if not isinstance(release, dict) or release.get("id") != value: return None return value def _visual_id(turn_id: str, semantic: dict[str, Any]) -> str: material = json.dumps( {"turn": turn_id, "semantic": semantic}, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False, ).encode("utf-8") return "v1-" + hashlib.sha256(material).hexdigest()[:24] def _chart( *, turn_id: str, chart_type: str, title: str, subtitle: str, unit: str, categories: list[dict[str, str]], series: list[dict[str, Any]], evidence_refs: list[str], required_fields: list[str], scope: dict[str, Any], period: dict[str, Any] | None, comparison_period: dict[str, Any] | None = None, stage: str | None = None, metric: str, coverage: dict[str, Any], note: str | None = None, ) -> dict[str, Any]: chart: dict[str, Any] = { "type": chart_type, "title": title, "subtitle": subtitle, "unit": unit, "categories": categories, "series": series, "evidenceRefs": sorted(set(evidence_refs)), "requiredFields": required_fields, "scope": scope, "metric": metric, "coverage": coverage, "originTurnId": turn_id, } if period is not None: chart["period"] = period if comparison_period is not None: chart["comparisonPeriod"] = comparison_period if stage in ("black", "bright"): chart["stage"] = stage if note: chart["note"] = note[:240] identity = dict(chart) identity.pop("id", None) chart["id"] = _visual_id(turn_id, identity) return chart def _valid_rate(value: Any) -> tuple[float | None, bool]: number, valid = _finite_number(value) if not valid or (number is not None and not 0 <= number <= 1): return None, False return number, True def _valid_weight(value: Any) -> tuple[float | None, bool]: number, valid = _finite_number(value) if not valid or (number is not None and number < 0): return None, False return number, True def _optional_selector(result: dict[str, Any], key: str) -> tuple[str | None, bool]: value = result.get(key) if value is None or value == "": return None, True safe = _safe_text(value) return safe, safe is not None def _scope_compatible( scope: dict[str, Any], release_id: str, *, period: dict[str, Any] | None = None, stage: str | None = None, category: str | None = None, defect: str | None = None, ) -> bool: if scope.get("releaseId", release_id) != release_id: return False selected_stage = scope.get("stage") if selected_stage is not None and selected_stage != stage: return False for key, selected in (("category", category), ("defect", defect)): if selected is not None and scope.get(key, selected) != selected: return False if period is not None: for key in ("year", "month", "quarter"): if key in scope and period.get(key) != scope[key]: return False return True def _comparison_charts(document: dict[str, Any], result: dict[str, Any], turn_id: str, question: str) -> list[dict[str, Any]]: if result.get("kind") != "quality_comparison": return [] release_id = _release_id(document, result) scope, scope_key = _scope(result.get("filterBinding")) current, comparison = result.get("current"), result.get("comparison") if release_id is None or scope is None or scope_key is None or not isinstance(current, dict) or not isinstance(comparison, dict): return [] current_period, current_label, _ = _period(current.get("period")) comparison_period, comparison_label, _ = _period(comparison.get("period")) if current_period is None or comparison_period is None or current_period == comparison_period: return [] delta = result.get("delta") if not isinstance(delta, dict) or delta.get("available") is not True: return [] refs = [_evidence_ref(document)] if _evidence_ref(document) else [] categories = [ {"key": "comparison", "label": comparison_label}, {"key": "current", "label": current_label}, ] asked_black, asked_bright = "黑片" in question, "亮片" in question explicit_stage_only = (asked_black or asked_bright) and not re.search(r"综合|总体", question) metrics: list[tuple[str, str | None, str, Any, Any, str]] = [] if not explicit_stage_only: metrics.append(("composite_rate", None, "综合合格率", comparison.get("compositeRate"), current.get("compositeRate"), "composite_rate")) stage_changes = result.get("stageRateChangesPP") requested_stages = [] if asked_black: requested_stages.append(("black", "黑片合格率", "black_rate")) if asked_bright: requested_stages.append(("bright", "亮片合格率", "bright_rate")) for stage, label, metric in requested_stages: old_side, now_side = comparison.get(stage), current.get(stage) stage_change, stage_change_ok = _finite_number(stage_changes.get(stage) if isinstance(stage_changes, dict) else None) if not stage_change_ok or stage_change is None: continue metrics.append((metric, stage, label, old_side.get("rate") if isinstance(old_side, dict) else None, now_side.get("rate") if isinstance(now_side, dict) else None, metric)) charts: list[dict[str, Any]] = [] for metric, stage, label, old_raw, now_raw, required in metrics: if not _scope_compatible(scope, release_id, period=current_period, stage=stage): continue old_value, old_ok = _valid_rate(old_raw) now_value, now_ok = _valid_rate(now_raw) if not old_ok or not now_ok or (old_value is None and now_value is None): continue charts.append(_chart( turn_id=turn_id, chart_type="bar", title=f"正式{label}期间对比", subtitle=f"比较期 {comparison_label},本期 {current_label};使用正式指标服务结果。", unit="ratio", categories=categories, series=[{"key": metric, "label": label, "values": [old_value, now_value]}], evidence_refs=refs, required_fields=(["black_good_weight", "black_total_weight", "bright_good_weight", "bright_total_weight"] if metric == "composite_rate" else [f"{stage}_good_weight", f"{stage}_total_weight"]), scope=_chart_scope(scope, release_id, current_period, stage=stage), period=current_period, comparison_period=comparison_period, stage=stage, metric=metric, coverage={"totalRows": 2, "returnedRows": 2, "truncated": False}, )) return charts def _formal_donut_chart( document: dict[str, Any], result: dict[str, Any], turn_id: str, *, summary: dict[str, Any], filters: Any, period_value: Any, requested_stage: str, chart_type: str = "donut", ) -> dict[str, Any] | None: """Build composition/pareto only from a stage's formal categories.""" stage_summary = summary.get(requested_stage) if not isinstance(stage_summary, dict): return None raw_defects = stage_summary.get("defects") if not isinstance(raw_defects, list) or not 2 <= len(raw_defects) <= 4: return None scope, _ = _scope(filters) period, period_label, _ = _period(period_value) release_id = _release_id(document, result) if (scope is None or period is None or release_id is None or scope.get("category") not in (None, "") or scope.get("defect") not in (None, "") or not _scope_compatible(scope, release_id, period=period, stage=requested_stage)): return None labels_by_key = {label: key for label, key in _DEFECT_FIELDS[requested_stage].items()} categories: list[dict[str, str]] = [] values: list[float] = [] required_fields: list[str] = [] seen: set[str] = set() for item in raw_defects: if not isinstance(item, dict): return None label = _safe_text(item.get("name"), limit=80) key = labels_by_key.get(label) if label is not None else None weight, valid = _valid_weight(item.get("weight")) if key is None or key in seen or not valid or weight is None: return None seen.add(key) categories.append({"key": key, "label": label}) values.append(weight) required_fields.append(key) if len(categories) < 2 or sum(values) <= 0: return None if chart_type == "pareto": # Stable sorting preserves the authoritative category order for ties. ordered = sorted(zip(values, categories, required_fields), key=lambda item: -item[0]) values = [item[0] for item in ordered] categories = [item[1] for item in ordered] required_fields = [item[2] for item in ordered] stage_label = "黑片" if requested_stage == "black" else "亮片" count = len(categories) return _chart( turn_id=turn_id, chart_type=chart_type, title=(f"{stage_label}报废类别重量柏拉图" if chart_type == "pareto" else f"已列报废类别构成({stage_label})"), subtitle=f"{period_label};重量单位 kg。", unit="kg", categories=categories, series=[{"key": "source_defect_weight", "label": "正式类别重量", "values": values}], evidence_refs=[_evidence_ref(document)] if _evidence_ref(document) else [], required_fields=required_fields, scope=_chart_scope(scope, release_id, period, view="overall", stage=requested_stage), period=period, stage=requested_stage, metric="source_defect_weight", coverage={"totalRows": count, "returnedRows": count, "truncated": False, "shareBasis": "displayed_categories"}, note="占比按本图已列类别重量合计计算,不代表正式报废总量占比。", ) def _comparison_category_charts(document: dict[str, Any], result: dict[str, Any], turn_id: str, question: str) -> list[dict[str, Any]]: chart_type = _requested_chart_type(question) if chart_type not in ("donut", "pareto") or result.get("kind") != "quality_comparison": return [] current = result.get("current") if not isinstance(current, dict): return [] stages = _requested_stages(question) return [chart for stage in stages if (chart := _formal_donut_chart( document, result, turn_id, summary=current, filters=result.get("filterBinding"), period_value=current.get("period"), requested_stage=stage, chart_type=chart_type, )) is not None] def _metrics_category_charts(document: dict[str, Any], result: dict[str, Any], turn_id: str, question: str) -> list[dict[str, Any]]: chart_type = _requested_chart_type(question) if (chart_type not in ("donut", "pareto") or result.get("kind") != "quality_metrics" or result.get("view") != "overall"): return [] summary = result.get("summary") if not isinstance(summary, dict): return [] stages = _requested_stages(question) return [chart for stage in stages if (chart := _formal_donut_chart( document, result, turn_id, summary=summary, filters=result.get("filters"), period_value=result.get("period"), requested_stage=stage, chart_type=chart_type, )) is not None] def _share_chart_from_top_chart(chart: dict[str, Any], document: dict[str, Any], result: dict[str, Any], turn_id: str, chart_type: str) -> dict[str, Any] | None: if chart.get("metric") != "source_defect_weight" or chart.get("stage") not in ("black", "bright"): return None ranking = result.get("rankingCoverage") rows = result.get("rows") if not isinstance(rows, list) or chart.get("coverage", {}).get("truncated") is not False: return None categories = chart.get("categories") series = chart.get("series") if not isinstance(categories, list) or len(categories) < 2 or not isinstance(series, list) or len(series) != 1: return None scope = chart.get("scope") if not isinstance(scope, dict) or scope.get("category") not in (None, "") or scope.get("defect") not in (None, ""): return None values = series[0].get("values") if not isinstance(values, list) or len(values) != len(categories): return None checked: list[float] = [] for value in values: number, valid = _valid_weight(value) if not valid or number is None: return None checked.append(number) if sum(checked) <= 0: return None stage = chart["stage"] canonical_keys = set(_DEFECT_FIELDS[stage].values()) category_keys = {item.get("key") for item in categories if isinstance(item, dict)} ranking_complete = ( isinstance(ranking, dict) and ranking.get("complete") is True and not isinstance(ranking.get("groups"), bool) and isinstance(ranking.get("groups"), int) and ranking["groups"] == len(rows) and category_keys == canonical_keys and result.get("cumulativeThresholdApplied") is False ) source_complete = _category_top_source_complete(document, result) if not (ranking_complete or source_complete): return None if chart_type == "pareto": ordered = sorted(zip(checked, categories), key=lambda item: -item[0]) checked = [item[0] for item in ordered] categories = [item[1] for item in ordered] result_chart_values = checked else: result_chart_values = checked result_chart = dict(chart) result_chart["type"] = chart_type stage_label = "黑片" if chart["stage"] == "black" else "亮片" result_chart["title"] = (f"{stage_label}报废类别重量柏拉图" if chart_type == "pareto" else f"已列报废类别构成({stage_label})") result_chart["note"] = "占比按本图已列类别重量合计计算,不代表正式报废总量占比。" result_chart["categories"] = categories result_chart["series"] = [dict(series[0], values=result_chart_values)] result_chart["requiredFields"] = [category["key"] for category in categories] result_chart["coverage"] = {"totalRows": len(categories), "returnedRows": len(categories), "truncated": False, "shareBasis": "displayed_categories"} result_chart.pop("id", None) result_chart["id"] = _visual_id(turn_id, result_chart) return result_chart def _change_chart(document: dict[str, Any], result: dict[str, Any], turn_id: str) -> dict[str, Any] | None: if result.get("kind") != "quality_changes": return None if result.get("dimension") not in ("product", "group", "department"): return None release_id = _release_id(document, result) if release_id is None: return None scope, _ = _scope(result.get("filters")) if scope is None: return None current_period, current_label, _ = _period(result.get("currentPeriod")) comparison_period, comparison_label, _ = _period(result.get("comparisonPeriod")) if current_period is None or comparison_period is None or current_period == comparison_period: return None rows = result.get("rows") if not isinstance(rows, list) or not rows or len(rows) > 500: return None total_rows = result.get("totalRows") returned_rows = result.get("returnedRows") truncated = result.get("truncated") if (isinstance(total_rows, bool) or not isinstance(total_rows, int) or total_rows < len(rows) or returned_rows != len(rows) or not isinstance(truncated, bool)): return None order = result.get("sort") row_info: list[tuple[str, str, dict[str, Any]]] = [] for index, row in enumerate(rows): if not isinstance(row, dict): return None key, label = row.get("key"), row.get("label") if _safe_text(key) is None: return None label = _safe_text(label if label is not None else key) if label is None: return None rank = row.get("rank") if isinstance(rank, bool) or not isinstance(rank, int) or rank != index + 1: # This endpoint returns the complete ordered page from rank one. return None row_info.append((key, label, row)) stage = result.get("stage") if result.get("stage") in ("black", "bright") else None if stage is None and scope.get("stage") in ("black", "bright"): stage = scope["stage"] category_selector, category_ok = _optional_selector(result, "category") defect_selector, defect_ok = _optional_selector(result, "defect") if not category_ok or not defect_ok: return None if not _scope_compatible(scope, release_id, period=current_period, stage=stage, category=category_selector, defect=defect_selector): return None if order == "scrap_delta": title = "报废重量增减排名" if stage is None else "分组报废重量增减排名" metric, unit, label, field = "scrap_delta", "kg", "报废增减(kg)", "scrapDelta" required_fields = (["black_scrap_weight", "bright_scrap_weight"] if stage is None else [f"{stage}_scrap_weight"]) def value_for(row: dict[str, Any]) -> tuple[float | None, bool]: return _finite_number(row.get(field)) note = "保留接口排序和正负方向;该分组变化不作为总体率变化贡献。" if stage is None: note = "黑片与亮片两阶段报废重量之和仅作分组描述,不代表独立投入分母或总体变化贡献。" elif order == "rate_drop": title = "合格率变化排名" if stage is None else "分组合格率变化排名" metric, unit, label, field = "rate_drop_pp", "pp", "合格率下降(pp)", "rateDrop" required_fields = (["black_good_weight", "black_total_weight", "bright_good_weight", "bright_total_weight"] if stage is None else [f"{stage}_good_weight", f"{stage}_total_weight"]) def value_for(row: dict[str, Any]) -> tuple[float | None, bool]: raw, ok = _finite_number(row.get(field)) if not ok or (raw is not None and abs(raw) > 1): return None, False return (raw * 100 if raw is not None else None), True note = "正值表示合格率下降,负值表示改善;百分点取自正式分组率差。" if stage is None: note = "正值表示综合合格率下降,负值表示改善;按正式综合率比较,不作为生产根因。" elif order == "current_scrap": if stage is None: return None title = "分组本期报废重量排名" metric, unit, label, field = "current_scrap_weight", "kg", "本期报废重量(kg)", "scrapWeight" required_fields = [f"{stage}_scrap_weight"] def value_for(row: dict[str, Any]) -> tuple[float | None, bool]: current = row.get("current") raw = current.get(field) if isinstance(current, dict) else None return _valid_weight(raw) note = "" else: return None selected = row_info[:MAX_RANK_ROWS] values: list[float | None] = [] categories: list[dict[str, str]] = [] keys_seen: set[str] = set() for key, name, row in selected: if key in keys_seen: return None keys_seen.add(key) value, valid = value_for(row) if not valid: return None categories.append({"key": key, "label": name}) values.append(value) if not values or not any(value is not None for value in values): return None if result["dimension"] == "product": title = title.replace("分组", "产品") elif result["dimension"] == "group": title = title.replace("分组", "业务分组") else: title = title.replace("分组", "产业部") if stage: title = f"{stage == 'black' and '黑片' or '亮片'}{title}" coverage = { "totalRows": total_rows, "returnedRows": len(selected), "truncated": truncated or len(selected) < len(row_info), } return _chart( turn_id=turn_id, chart_type="bar", title=title, subtitle=f"{comparison_label} → {current_label};按接口返回排名,展示前 {len(selected)} 项。", unit=unit, categories=categories, series=[{"key": metric, "label": label, "values": values}], evidence_refs=[_evidence_ref(document)] if _evidence_ref(document) else [], required_fields=required_fields, scope=_chart_scope(scope, release_id, current_period, stage=stage, category=category_selector, defect=defect_selector), period=current_period, comparison_period=comparison_period, stage=stage, metric=metric, coverage=coverage, note=note, ) def _category_top_raw_values(result: dict[str, Any]) -> tuple[set[str], list[Decimal]] | None: stage = result.get("stage") if stage not in _DEFECT_FIELDS: return None rows = result.get("rows") expected = _DEFECT_FIELDS[stage] if not isinstance(rows, list) or not 2 <= len(rows) <= len(expected): return None keys: set[str] = set() weights: list[Decimal] = [] for index, row in enumerate(rows): if not isinstance(row, dict): return None label = _safe_text(row.get("label"), limit=MAX_LABEL_LENGTH) field = expected.get(label) if label is not None else None rank = row.get("rank") if (field is None or row.get("key") != label or isinstance(rank, bool) or not isinstance(rank, int) or rank != index + 1 or field in keys): return None raw_weight = row.get("weight") _, valid = _valid_weight(raw_weight) if not valid or raw_weight is None: return None try: weight = raw_weight if isinstance(raw_weight, Decimal) else Decimal(str(raw_weight)) except (InvalidOperation, ValueError, TypeError): return None if not weight.is_finite(): return None keys.add(field) weights.append(weight) return keys, weights def _close_decimal(left: Decimal, right: Decimal) -> bool: return abs(left - right) <= Decimal("0.00001") def _category_top_source_complete(document: dict[str, Any], result: dict[str, Any]) -> bool: """Verify the current TOP(category) wire shape without inventing ranking metadata.""" stage = result.get("stage") if (result.get("kind") != "quality_top" or result.get("dimension") != "category" or stage not in _DEFECT_FIELDS or result.get("cumulativeThresholdApplied") is not False or result.get("shareBasis") != "所选筛选条件下选中原报废分类的重量总和"): return False raw = _category_top_raw_values(result) if raw is None: return False _, weights = raw denominator_raw = result.get("denominator") _, denominator_valid = _valid_weight(denominator_raw) if not denominator_valid or denominator_raw is None: return False try: denominator = denominator_raw if isinstance(denominator_raw, Decimal) else Decimal(str(denominator_raw)) except (InvalidOperation, ValueError, TypeError): return False if not denominator.is_finite() or not _close_decimal(sum(weights, Decimal(0)), denominator): return False rows = result.get("rows") if not isinstance(rows, list): return False for row in rows: row_denominator = row.get("denominator") _, row_valid = _valid_weight(row_denominator) if not row_valid or row_denominator is None: return False try: row_denominator_decimal = row_denominator if isinstance(row_denominator, Decimal) else Decimal(str(row_denominator)) except (InvalidOperation, ValueError, TypeError): return False if not row_denominator_decimal.is_finite() or not _close_decimal(row_denominator_decimal, denominator): return False release_id = _release_id(document, result) period, _, _ = _period(result.get("period")) filters = result.get("filters") api_source = document.get("apiSource") calls = api_source.get("calls") if isinstance(api_source, dict) else None if (release_id is None or period is None or not isinstance(filters, dict) or not isinstance(calls, list) or len(calls) > 100): return False canonical_count = len(_DEFECT_FIELDS[stage]) control_params = {"releaseId", "stage", "dimension", "limit", "year", "month", "quarter"} expected_filter_keys: set[str] = set() for key, value in filters.items(): if key in ("category", "defect") and value not in (None, "", [], {}): return False if key in ("year", "month", "quarter", "releaseId"): continue if value not in (None, "", [], {}): expected_filter_keys.add(key) for call in calls: if not isinstance(call, dict) or call.get("method") != "GET" or call.get("path") != "/api/analytics/top": continue params = call.get("params") if not isinstance(params, dict): continue limit = params.get("limit") if (params.get("releaseId") != release_id or params.get("stage") != stage or params.get("dimension") != "category" or isinstance(limit, bool) or not isinstance(limit, int) or limit < canonical_count): continue if any(params.get(key) not in (None, "", [], {}) for key in ("category", "defect")): continue if params.get("cumulativeThreshold") not in (None, False, 0, 0.0, "0", "false"): continue if any(params.get(key) != value for key, value in period.items()): continue if any(key in params and key not in period for key in ("year", "month", "quarter")): continue actual_filter_keys = {key for key in params if key not in control_params} if actual_filter_keys != expected_filter_keys: continue if any(params.get(key) != value for key, value in filters.items() if key not in ("year", "month", "quarter", "releaseId") and key in expected_filter_keys): continue return True return False def _top_chart(document: dict[str, Any], result: dict[str, Any], turn_id: str) -> dict[str, Any] | None: if result.get("kind") != "quality_top" or result.get("stage") not in ("black", "bright"): return None if _release_id(document, result) is None: return None dimension = result.get("dimension") if dimension not in ("product", "group", "department", "projectGroup", "category"): return None scope, _ = _scope(result.get("filters")) period, period_label, _ = _period(result.get("period")) release_id = _release_id(document, result) if scope is None or period is None or release_id is None: return None if not _scope_compatible(scope, release_id, period=period, stage=result.get("stage")): return None category_selector, category_ok = _optional_selector(result, "category") defect_selector, defect_ok = _optional_selector(result, "defect") if not category_ok or not defect_ok: return None if not _scope_compatible(scope, release_id, period=period, stage=result["stage"], category=category_selector, defect=defect_selector): return None # Grouped rankings constrained to one category need a category-specific # permission proof. Until the schema can express per-row selector fields, # fail closed rather than reuse the whole-stage scrap metric. if dimension != "category" and (category_selector is not None or defect_selector is not None): return None rows = result.get("rows") ranking_coverage = result.get("rankingCoverage") groups = ranking_coverage.get("groups") if isinstance(ranking_coverage, dict) else None if not isinstance(rows, list) or not rows or len(rows) > 500: return None if dimension == "category" and (isinstance(groups, bool) or not isinstance(groups, int)): # Current TOP(category) evidence omits rankingCoverage. Accept this shape # only when the recorded endpoint call and returned denominator prove that # the unrestricted formal-category result is complete. if not _category_top_source_complete(document, result): return None groups = len(rows) if isinstance(groups, bool) or not isinstance(groups, int) or groups < len(rows): return None stage = result["stage"] metric = "source_defect_weight" if dimension == "category" else "current_scrap_weight" unit = "kg" keys_seen: set[str] = set() categories: list[dict[str, str]] = [] values: list[float | None] = [] required_fields: set[str] = set() for index, row in enumerate(rows): if not isinstance(row, dict): return None rank, raw_key = row.get("rank"), row.get("key") if isinstance(rank, bool) or not isinstance(rank, int) or rank != index + 1: return None if dimension == "category": label = _safe_text(row.get("label")) field = _DEFECT_FIELDS[stage].get(label) if label is not None else None # The endpoint only returns canonical official defect categories; # unknown labels could be aliases or totals, so do not guess. if field is None or raw_key != label: return None key = field required_fields.add(field) else: key = _safe_text(raw_key) label = _safe_text(row.get("label") if row.get("label") is not None else raw_key) if key is None or label is None: return None if key in keys_seen or label is None: return None value, valid = _valid_weight(row.get("weight")) if not valid: return None keys_seen.add(key) categories.append({"key": key, "label": label}) values.append(value) if len(categories) < 2 or not any(value is not None for value in values): return None selected = min(len(categories), MAX_RANK_ROWS) dimension_labels = {"product": "产品", "group": "业务分组", "department": "产业部", "projectGroup": "项目组", "category": "报废类别"} title = f"{'黑片' if stage == 'black' else '亮片'}{dimension_labels[dimension]}报废重量排名" note = "保留正式 TOP 接口排名;只展示重量,不展示份额或总体贡献。" if dimension == "category": note = "按正式报废类别来源字段展示重量;只展示本次授权接口返回的类别,不推断总体贡献。" return _chart( turn_id=turn_id, chart_type="bar", title=title, subtitle=f"{period_label};按正式 TOP 接口顺序展示前 {selected} 项。", unit=unit, categories=categories[:MAX_RANK_ROWS], series=[{"key": metric, "label": f"报废重量({unit})", "values": values[:MAX_RANK_ROWS]}], evidence_refs=[_evidence_ref(document)] if _evidence_ref(document) else [], required_fields=(sorted(required_fields) if dimension == "category" else [f"{stage}_scrap_weight"]), scope=_chart_scope(scope, _release_id(document, result), period, view="overall" if dimension == "category" else dimension, stage=stage, category=category_selector, defect=defect_selector), period=period, stage=stage, metric=metric, coverage={"totalRows": groups, "returnedRows": selected, "truncated": len(categories) < groups or len(categories) > MAX_RANK_ROWS}, note=note, ) _FINE_CATEGORIES = { "black": {"责废", "料废"}, "bright": {"镀废", "材料废", "加工废", "扩散废"}, } def _fine_source_field_map(raw: Any, stage: str) -> dict[str, tuple[str, str]] | None: """Validate the tool's authoritative, stage-specific weight field catalog.""" if not isinstance(raw, list) or not raw or len(raw) > 100: return None fields: dict[str, tuple[str, str]] = {} for item in raw: if not isinstance(item, dict): return None key = _safe_text(item.get("key"), limit=160) label = _safe_text(item.get("label"), limit=160) category = _safe_text(item.get("category"), limit=80) source_field = item.get("sourceField") if (key is None or not key.endswith("重量") or label is None or category not in _FINE_CATEGORIES[stage] or source_field != key or key in fields): return None fields[key] = (label, category) return fields def _totals_only_categories(result: dict[str, Any], *, comparison: bool = False) -> set[str]: """Only classify a category as totals-only when every source row is covered. A positive expectedTotalsOnly count is common in mixed VCM releases: it means some rows have only a formal total, while other rows still have usable source defect weights. Treating any positive count as category-wide would erase that valid detail. """ field = "comparisonCategoryReconciliation" if comparison else "categoryReconciliation" rows = result.get(field) if not isinstance(rows, list): return set() coverage_key = "comparisonCoverage" if comparison else "coverage" coverage = result.get(coverage_key) fallback_rows = coverage.get("sourceRows") if isinstance(coverage, dict) else None if not comparison: fallback_rows = result.get("sourceRows", fallback_rows) categories: set[str] = set() for row in rows: if not isinstance(row, dict): continue expected = row.get("expectedTotalsOnly") count = expected.get("rows") if isinstance(expected, dict) else None source_rows = row.get("sourceRows", fallback_rows) if (isinstance(count, int) and not isinstance(count, bool) and count > 0 and isinstance(source_rows, int) and not isinstance(source_rows, bool) and source_rows > 0 and count == source_rows and isinstance(row.get("category"), str)): categories.add(row["category"]) return categories def _fine_defect_chart(document: dict[str, Any], result: dict[str, Any], turn_id: str) -> dict[str, Any] | None: if result.get("kind") != "quality_fine_defects" or result.get("dimension") != "defect": return None if result.get("grain") != "source_defect_weight" or result.get("stage") not in ("black", "bright"): return None release_id = _release_id(document, result) if release_id is None: return None coverage = result.get("coverage") if not isinstance(coverage, dict) or coverage.get("available") is not True: return None scope, _ = _scope(result.get("filters")) period, period_label, _ = _period(result.get("period")) if scope is None or period is None: return None comparison_period = None comparison_label = None source_rows: list[Any] current_fields = _fine_source_field_map(result.get("sourceFields"), result["stage"]) if current_fields is None: return None paired = result.get("pairedRows") if result.get("comparisonPeriod") is not None: comparison_period, comparison_label, _ = _period(result.get("comparisonPeriod")) if comparison_period is None or comparison_period == period or not isinstance(paired, list): return None comparison_coverage = result.get("comparisonCoverage") if not isinstance(comparison_coverage, dict) or comparison_coverage.get("available") is not True: return None comparison_fields = _fine_source_field_map(result.get("comparisonSourceFields"), result["stage"]) if comparison_fields is None or comparison_fields != current_fields: return None source_rows = paired rank_field = result.get("sort") if rank_field not in ("scrap_delta", "current_scrap"): return None delta_mode = rank_field == "scrap_delta" metric = "source_defect_delta_weight" if delta_mode else "source_defect_weight" unit = "kg" title = "来源具体缺陷报废增减" if delta_mode else "来源具体缺陷本期重量" required_fields = ["source_defect_delta_weight" if delta_mode else "source_defect_weight"] else: rows = result.get("rows") if not isinstance(rows, list): return None source_rows = rows delta_mode = False metric = "source_defect_weight" unit = "kg" title = "来源具体缺陷报废重量" required_fields = ["source_defect_weight"] if len(source_rows) == 0 or len(source_rows) > 100: return None total_only_current = _totals_only_categories(result) total_only_comparison = _totals_only_categories(result, comparison=True) if comparison_period else set() category_selector, category_ok = _optional_selector(result, "category") defect_selector, defect_ok = _optional_selector(result, "defect") if not category_ok or not defect_ok: return None if not _scope_compatible(scope, release_id, period=period, stage=result["stage"], category=category_selector, defect=defect_selector): return None categories: list[dict[str, str]] = [] values: list[float | None] = [] seen: set[str] = set() for row in source_rows: if not isinstance(row, dict): return None current = row.get("current") if isinstance(row.get("current"), dict) else {} comparison = row.get("comparison") if isinstance(row.get("comparison"), dict) else {} key = row.get("key") field_info = current_fields.get(key) if isinstance(key, str) else None if field_info is None or key in seen: return None field_label, field_category = field_info category_values = [candidate for candidate in ( current.get("category"), comparison.get("category"), row.get("category") ) if candidate is not None] if any(candidate != field_category for candidate in category_values): return None # A field can be absent from the detailed breakdown for all rows in one # snapshot, but a paired chart should preserve its unavailable delta as # null when the other period has usable detail. Drop only categories that # are totals-only on both sides; never encode them as zero. if (field_category in total_only_current and (comparison_period is None or field_category in total_only_comparison)): continue raw_labels = [candidate for candidate in ( row.get("label"), row.get("defect"), current.get("label"), comparison.get("label") ) if candidate is not None] if any(_safe_text(candidate, limit=160) != field_label for candidate in raw_labels): return None if delta_mode: available = row.get("deltaAvailable") is True raw = row.get("deltaWeight") if available else None value, valid = _finite_number(raw) if available and value is None: return None else: raw = row.get("weight") if not current else current.get("weight") value, valid = _valid_weight(raw) if not valid: return None seen.add(key) categories.append({"key": key, "label": field_label}) values.append(value) if not values or not any(value is not None for value in values): return None total_rows = result.get("pairedTotalRows") if comparison_period is not None else result.get("totalRows") if isinstance(total_rows, bool) or not isinstance(total_rows, int) or total_rows < len(source_rows): return None if comparison_period is not None: truncated = result.get("pairedTruncated") sort_complete = result.get("pairedRankingComplete") else: truncated = result.get("truncated") sort_complete = result.get("rankingComplete") if not isinstance(truncated, bool) or not isinstance(sort_complete, bool): return None stage_label = "黑片" if result["stage"] == "black" else "亮片" note = "具体缺陷按来源字段统计,不代表正式报废大类或总体贡献。" if result["stage"] == "bright" and (total_only_current or total_only_comparison): note += " VCM 亮片仅录合计时不绘制为零缺陷;细分未提供。" coverage = { "totalRows": total_rows, "returnedRows": len(categories), "truncated": truncated or len(categories) < len(source_rows), } return _chart( turn_id=turn_id, chart_type="bar", title=f"{stage_label}{title}", subtitle=(f"{comparison_label} → {period_label};" if comparison_label else f"{period_label};") + "按来源字段排序,缺失增量保留为空。", unit=unit, categories=categories[:MAX_RANK_ROWS], series=[{"key": metric, "label": title, "values": values[:MAX_RANK_ROWS]}], evidence_refs=[_evidence_ref(document)] if _evidence_ref(document) else [], required_fields=[row["key"] for row in categories[:MAX_RANK_ROWS]], scope=_chart_scope(scope, _release_id(document, result), period, stage=result["stage"], category=category_selector, defect=defect_selector), period=period, comparison_period=comparison_period, stage=result["stage"], metric=metric, coverage={**coverage, "returnedRows": min(len(categories), MAX_RANK_ROWS), "truncated": coverage["truncated"] or len(categories) > MAX_RANK_ROWS}, note=note, ) def _trend_chart_from_points( points: list[dict[str, Any]], *, release_id: str, scope: dict[str, Any], turn_id: str, evidence_refs: list[str], question: str, supplied_trend: bool, coverage_truncated: bool, ) -> list[dict[str, Any]]: if len(points) < 3 or len(points) > MAX_TREND_POINTS or coverage_truncated: return [] point_info: list[tuple[tuple[int, int, int], str, dict[str, Any]]] = [] seen: set[str] = set() for point in points: label, order = _trend_period(point.get("period")) if label is None or order is None or label in seen: return [] seen.add(label) snapshot = point.get("snapshot") if not isinstance(snapshot, dict): return [] point_info.append((order, label, snapshot)) point_info.sort(key=lambda item: item[0]) granularity = point_info[0][0][2] if any(order[2] != granularity for order, _, _ in point_info): return [] # Materialize missing whole periods as null observations so a chart never # draws a line across an unobserved month, quarter, or year. expanded: list[tuple[str, dict[str, Any]]] = [] by_order = {order: (label, snapshot) for order, label, snapshot in point_info} first, last = point_info[0][0], point_info[-1][0] cursor = first while cursor <= last: entry = by_order.get(cursor) if entry is None: year, month, grain = cursor if grain == 0: label = f"{year:04d}-{month:02d}" elif grain == 1: label = f"{year:04d}-Q{month // 3 + 1}" else: label = f"{year:04d}" expanded.append((label, {})) else: expanded.append(entry) if len(expanded) > MAX_TREND_POINTS: return [] year, month, grain = cursor if grain == 0: cursor = (year + 1, 1, 0) if month == 12 else (year, month + 1, 0) elif grain == 1: cursor = (year + 1, 1, 1) if month == 10 else (year, month + 3, 1) else: cursor = (year + 1, 0, 2) categories = [{"key": label, "label": label} for label, _ in expanded] start_label, end_label = expanded[0][0], expanded[-1][0] grain_name = {0: "month", 1: "quarter", 2: "year"}[granularity] range_period = {"start": start_label, "end": end_label, "label": f"{start_label} 至 {end_label}", "granularity": grain_name} charts: list[dict[str, Any]] = [] trend_name = "正式指标趋势" if supplied_trend else "正式指标期间趋势" asked_black, asked_bright = "黑片" in question, "亮片" in question explicit_stage_only = (asked_black or asked_bright) and not re.search(r"综合|总体", question) rate_metrics = [] if not explicit_stage_only: rate_metrics.append(("composite_rate", None, "综合合格率", "compositeRate")) all_stages = not (asked_black or asked_bright) and (not re.search(r"综合(?:合格)?率", question) or "阶段" in question) if asked_black or all_stages: rate_metrics.append(("black_rate", "black", "黑片合格率", "rate")) if asked_bright or all_stages: rate_metrics.append(("bright_rate", "bright", "亮片合格率", "rate")) for metric, stage, label, field in rate_metrics: if not _scope_compatible(scope, release_id, stage=stage): continue vals: list[float | None] = [] valid = True for _, point in expanded: nested = point.get(stage) if stage is not None else point raw = nested.get(field) if isinstance(nested, dict) else None point_coverage = point.get("coverage") if point.get("noData") is True or point.get("monthStatus") in ("future", "unavailable"): raw = None elif isinstance(point_coverage, dict): if stage is not None and point_coverage.get(stage + "Rows") == 0: raw = None elif stage is None and point_coverage.get("blackRows") == 0 and point_coverage.get("brightRows") == 0: raw = None value, okay = _valid_rate(raw) if not okay: valid = False break vals.append(value) if valid and sum(value is not None for value in vals) >= 3: charts.append(_chart( turn_id=turn_id, chart_type="line", title=f"{trend_name}({label})", subtitle="按时间顺序展示正式率值;缺失期间保留为空,不插值。", unit="ratio", categories=categories, series=[{"key": metric, "label": label, "values": vals}], evidence_refs=evidence_refs, required_fields=(["black_good_weight", "black_total_weight", "bright_good_weight", "bright_total_weight"] if metric == "composite_rate" else [f"{stage}_good_weight", f"{stage}_total_weight"]), scope=_chart_scope(scope, release_id, view="overall", stage=stage), period=range_period, stage=stage, metric=metric, coverage={"totalRows": len(expanded), "returnedRows": len(expanded), "truncated": False}, )) if re.search(r"重量|报废|废品|kg|公斤", question, re.IGNORECASE): weight_stages = [("black", "黑片报废重量"), ("bright", "亮片报废重量")] if asked_black and not asked_bright: weight_stages = [weight_stages[0]] elif asked_bright and not asked_black: weight_stages = [weight_stages[1]] for stage, label in weight_stages: if not _scope_compatible(scope, release_id, stage=stage): continue vals = [] valid = True for _, point in expanded: nested = point.get(stage) value, okay = _valid_weight(nested.get("scrapWeight") if isinstance(nested, dict) else None) if not okay: valid = False break vals.append(value) if valid and sum(value is not None for value in vals) >= 3: metric = "current_scrap_weight" charts.append(_chart( turn_id=turn_id, chart_type="line", title=f"{trend_name}({label})", subtitle="按时间顺序展示正式报废重量;缺失期间保留为空。", unit="kg", categories=categories, series=[{"key": metric, "label": label, "values": vals}], evidence_refs=evidence_refs, required_fields=[f"{stage}_scrap_weight"], scope=_chart_scope(scope, release_id, view="overall", stage=stage), period=range_period, stage=stage, metric=metric, coverage={"totalRows": len(expanded), "returnedRows": len(expanded), "truncated": False}, note="黑片与亮片分开;不合并为单阶段投入分母。", )) return charts def _metrics_trend_charts(document: dict[str, Any], result: dict[str, Any], turn_id: str, question: str) -> list[dict[str, Any]]: if result.get("kind") != "quality_metrics" or result.get("view") != "overall": return [] release_id = _release_id(document, result) scope, _ = _scope(result.get("filters")) if release_id is None or scope is None: return [] trend = result.get("trend") if not isinstance(trend, list) or len(trend) < 3: return [] truncated = result.get("trendTruncated") if not isinstance(truncated, bool): return [] trend_count = result.get("trendCount") if isinstance(trend_count, bool) or not isinstance(trend_count, int) or trend_count < len(trend): return [] points = [{"period": row.get("period"), "snapshot": row} for row in trend if isinstance(row, dict)] if len(points) != len(trend): return [] return _trend_chart_from_points( points, release_id=release_id, scope=scope, turn_id=turn_id, evidence_refs=[_evidence_ref(document)] if _evidence_ref(document) else [], question=question, supplied_trend=True, coverage_truncated=truncated or trend_count > MAX_TREND_POINTS, ) def _multi_query_trend(evidence: list[tuple[dict[str, Any], dict[str, Any]]], turn_id: str, question: str) -> list[dict[str, Any]]: groups: dict[tuple[str, str], list[tuple[dict[str, Any], dict[str, Any], dict[str, Any], str]]] = {} for document, result in evidence: if result.get("kind") != "quality_metrics" or result.get("view") != "overall": continue release_id = _release_id(document, result) scope, scope_key = _scope(result.get("filters")) period, label, order = _period(result.get("period")) summary = result.get("summary") if release_id is None or scope is None or scope_key is None or period is None or order is None or not isinstance(summary, dict): continue groups.setdefault((release_id, scope_key), []).append((document, result, period, label)) candidates: list[dict[str, Any]] = [] for (release_id, scope_key), values in groups.items(): if len(values) < 3 or len(values) > MAX_TREND_POINTS: continue scope, canonical = _scope(values[0][1].get("filters")) if scope is None or canonical != scope_key: continue periods = [] for document, result, period, label in values: _, _, order = _period(period) if order is None: periods = [] break periods.append((order, label, result["summary"], document)) if len(periods) != len(values) or len({item[1] for item in periods}) != len(periods): continue periods.sort(key=lambda item: item[0]) refs = [_evidence_ref(item[3]) for item in periods] points = [{"period": item[1], "snapshot": item[2]} for item in periods] charts = _trend_chart_from_points( points, release_id=release_id, scope=scope, turn_id=turn_id, evidence_refs=[ref for ref in refs if ref], question=question, supplied_trend=False, coverage_truncated=False, ) candidates.extend(charts) return candidates def _wants_visuals(question: str) -> tuple[bool, bool]: text = question if isinstance(question, str) else "" if _NO_CHART.search(text): return False, False explicit = bool(_EXPLICIT_CHART.search(text)) if explicit: return True, True if _SIMPLE_SINGLE_METRIC.fullmatch(text.strip()): return False, False intent = bool(_ANALYSIS_INTENT.search(text)) return intent, False def _requested_chart_type(question: str) -> str | None: text = question if isinstance(question, str) else "" def first_unnegated(pattern: re.Pattern[str]) -> re.Match[str] | None: for match in pattern.finditer(text): if not _NEGATED_STYLE_PREFIX.search(text[:match.start()]): return match return None # Pareto intent is stronger than generic composition wording in the same request. if first_unnegated(_PARETO_CHART): return "pareto" matches = [] horizontal = first_unnegated(_HORIZONTAL_BAR) if horizontal: matches.append((horizontal.start(), "bar")) for pattern, chart_type in ( (_COLUMN_CHART, "column"), (_AREA_CHART, "area"), (_HEATMAP_CHART, "heatmap"), (_DONUT_CHART, "donut"), (_LINE_CHART, "line"), (_BAR_CHART, "bar"), ): match = first_unnegated(pattern) if match: matches.append((match.start(), chart_type)) return min(matches, default=(0, None), key=lambda item: item[0])[1] def _requested_stages(question: str) -> list[str]: text = question if isinstance(question, str) else "" black, bright = "黑片" in text, "亮片" in text if black and not bright: return ["black"] if bright and not black: return ["bright"] return ["black", "bright"] def _is_period_trend(chart: dict[str, Any]) -> bool: period = chart.get("period") categories = chart.get("categories") return (isinstance(period, dict) and isinstance(period.get("start"), str) and isinstance(period.get("end"), str) and period.get("granularity") in ("month", "quarter", "year") and isinstance(categories, list) and len(categories) >= 3) def _apply_requested_chart_type(chart: dict[str, Any], question: str, kind: str) -> dict[str, Any]: chart_type = chart.get("type") requested = _requested_chart_type(question) if requested is not None: if requested in ("bar", "column") and chart_type in ("bar", "column"): chart_type = requested elif requested in ("line", "area", "heatmap") and chart_type in ("line", "area", "heatmap") and _is_period_trend(chart): chart_type = requested elif requested == "donut" and chart_type == "donut": chart_type = "donut" elif chart_type == "line" and _is_period_trend(chart): # Heatmaps are opt-in; ordinary time series retain a familiar line or area. if chart.get("metric") == "current_scrap_weight": chart_type = "area" elif kind == "quality_comparison" and chart_type == "bar" and chart.get("metric") in ( "composite_rate", "black_rate", "bright_rate"): # Formal two-period rates default to vertical columns; explicit horizontal # bars are preserved through the requested-style branch above. chart_type = "column" if chart_type != chart.get("type"): chart["type"] = chart_type chart.pop("id", None) chart["id"] = _visual_id(chart["originTurnId"], chart) return chart def _chart_end_rank(chart: dict[str, Any]) -> tuple[int, int, int]: period = chart.get("period") if isinstance(period, dict) and isinstance(period.get("end"), str): _, order = _trend_period(period["end"]) if order is not None: return order _, _, order = _period(period) return order or (0, 0, 0) def _candidate_priority(chart: dict[str, Any], kind: str, dimension: str | None, question: str) -> int: wants_trend = "趋势" in question if chart.get("type") == "line": if re.search(r"重量|报废|废品|kg|公斤", question, re.IGNORECASE) and chart.get("metric") == "current_scrap_weight": return 0 if not wants_trend: return 6 return {"composite_rate": 0, "black_rate": 1, "bright_rate": 2}.get(chart.get("metric"), 6) if kind == "quality_comparison": # A stage mentioned as the scope of a defect question should not displace # the explicitly requested product and defect charts from the three slots. if (chart.get("metric") != "composite_rate" and re.search(r"综合|总体", question) and re.search(r"产品|规格", question) and re.search(r"缺陷", question)): return 8 return 1 if wants_trend else (0 if chart.get("metric") == "composite_rate" else 1) if kind == "quality_changes": requested_dimension = None if re.search(r"产品|规格", question): requested_dimension = "product" elif "分组" in question: requested_dimension = "group" elif re.search(r"产业部|部门", question): requested_dimension = "department" base = {"product": 10, "group": 20, "department": 30}.get(dimension, 40) if requested_dimension == dimension: base = 4 if re.search(r"合格率|降幅|下降", question) and chart.get("metric") == "rate_drop_pp": base -= 1 if re.search(r"报废|增量|重量", question) and chart.get("metric") in ("scrap_delta", "current_scrap_weight"): base -= 1 return base if kind == "quality_top": requested_dimension = None if re.search(r"产品|规格", question): requested_dimension = "product" elif "分组" in question: requested_dimension = "group" elif re.search(r"产业部|部门", question): requested_dimension = "department" elif "项目组" in question: requested_dimension = "projectGroup" return 4 if requested_dimension == dimension else 12 if kind == "quality_fine_defects": return 5 if re.search(r"缺陷|责废|料废|外废|加工废|镀废", question) else 15 return 25 def _finalize(charts: list[dict[str, Any]], turn_id: str, *, unavailable: bool = False) -> dict[str, Any]: visuals: list[dict[str, Any]] = [] seen: set[str] = set() for chart in charts: if not isinstance(chart, dict) or len(visuals) >= MAX_VISUALS: continue chart_id = chart.get("id") if not isinstance(chart_id, str) or chart_id in seen: continue try: encoded = json.dumps(chart, ensure_ascii=False, separators=(",", ":"), allow_nan=False).encode("utf-8") except (TypeError, ValueError): continue if len(encoded) > MAX_BODY_BYTES: continue visuals.append(chart) seen.add(chart_id) body = {"visualSchemaVersion": VISUAL_SCHEMA_VERSION, "visualState": "ready" if visuals else ("unavailable" if unavailable else "not_requested"), "visuals": visuals} try: body_size = len(json.dumps(body, ensure_ascii=False, separators=(",", ":"), allow_nan=False).encode("utf-8")) except (TypeError, ValueError): body_size = MAX_BODY_BYTES + 1 while visuals and body_size > MAX_BODY_BYTES: visuals.pop() body["visualState"] = "ready" if visuals else "unavailable" body["visuals"] = visuals body_size = len(json.dumps(body, ensure_ascii=False, separators=(",", ":"), allow_nan=False).encode("utf-8")) if body_size > MAX_BODY_BYTES: return {"visualSchemaVersion": VISUAL_SCHEMA_VERSION, "visualState": "failed", "visuals": [], "error": "图表快照超出安全大小限制。"} return body def build_visuals(evidence: list[dict[str, Any]], question: str, turn_id: str) -> dict[str, Any]: """Return up to three safe chart snapshots from full trusted evidence docs. The function is intentionally non-fatal: exceptions return a short error state so a caller can preserve the already completed textual analysis. """ try: safe_turn_id = _safe_id(turn_id) if safe_turn_id is None: return {"visualSchemaVersion": VISUAL_SCHEMA_VERSION, "visualState": "unavailable", "visuals": [], "error": "轮次标识无效,未生成图表。"} wants_visuals, _ = _wants_visuals(question if isinstance(question, str) else "") if not wants_visuals: return _finalize([], safe_turn_id) if not isinstance(evidence, list): return {"visualSchemaVersion": VISUAL_SCHEMA_VERSION, "visualState": "unavailable", "visuals": [], "error": "没有可用的结构化证据。"} valid_evidence: list[tuple[dict[str, Any], dict[str, Any]]] = [] for document in evidence: result = _result(document) if result is None: continue if _release_id(document, result) is None: continue valid_evidence.append((document, result)) candidates: list[tuple[int, str, str | None, dict[str, Any]]] = [] for document, result in valid_evidence: text_question = question if isinstance(question, str) else "" kind = result.get("kind", "") dimension = result.get("dimension") if isinstance(result.get("dimension"), str) else None for chart in _comparison_charts(document, result, safe_turn_id, text_question): candidates.append((_candidate_priority(chart, kind, dimension, text_question), kind, dimension, chart)) for chart in _comparison_category_charts(document, result, safe_turn_id, text_question): candidates.append((_candidate_priority(chart, kind, dimension, text_question), kind, dimension, chart)) for chart in _metrics_category_charts(document, result, safe_turn_id, text_question): candidates.append((_candidate_priority(chart, kind, dimension, text_question), kind, dimension, chart)) change = _change_chart(document, result, safe_turn_id) if change is not None: candidates.append((_candidate_priority(change, kind, dimension, text_question), kind, dimension, change)) defect = _fine_defect_chart(document, result, safe_turn_id) if defect is not None: candidates.append((_candidate_priority(defect, kind, dimension, text_question), kind, dimension, defect)) top = _top_chart(document, result, safe_turn_id) if top is not None: candidates.append((_candidate_priority(top, kind, dimension, text_question), kind, dimension, top)) requested_type = _requested_chart_type(text_question) if requested_type in ("donut", "pareto"): share_chart = _share_chart_from_top_chart(top, document, result, safe_turn_id, requested_type) if share_chart is not None: candidates.append((_candidate_priority(share_chart, kind, dimension, text_question), kind, dimension, share_chart)) for chart in _metrics_trend_charts(document, result, safe_turn_id, text_question): candidates.append((_candidate_priority(chart, "metrics_trend", None, text_question), "metrics_trend", None, chart)) for chart in _multi_query_trend(valid_evidence, safe_turn_id, question if isinstance(question, str) else ""): candidates.append((_candidate_priority(chart, "metrics_trend", None, question if isinstance(question, str) else ""), "metrics_trend", None, chart)) requested_type = _requested_chart_type(question if isinstance(question, str) else "") styled_candidates: list[tuple[int, str, str | None, dict[str, Any]]] = [] for priority, kind, dimension, candidate in candidates: chart = _apply_requested_chart_type(candidate, question if isinstance(question, str) else "", kind) if requested_type is not None and chart.get("type") != requested_type: continue styled_candidates.append((priority, kind, dimension, chart)) candidates = styled_candidates candidates.sort(key=lambda item: (item[0], tuple(-part for part in _chart_end_rank(item[3])), item[3].get("id", ""))) charts: list[dict[str, Any]] = [] selected_ids: set[str] = set() selected_dimensions: set[str] = set() selected_defect_stages: set[str] = set() selected_share_stages: set[tuple[str, str]] = set() for _, kind, dimension, chart in candidates: chart_id = chart.get("id") if not isinstance(chart_id, str) or chart_id in selected_ids: continue share_stage = (chart.get("type"), chart.get("stage")) if chart.get("type") in ("donut", "pareto") and share_stage in selected_share_stages: continue if kind == "quality_changes" and dimension in selected_dimensions: continue if kind == "quality_fine_defects": stage = chart.get("stage") if stage in selected_defect_stages: continue charts.append(chart) selected_ids.add(chart_id) if kind == "quality_changes" and dimension: selected_dimensions.add(dimension) if kind == "quality_fine_defects" and chart.get("stage"): selected_defect_stages.add(chart["stage"]) if chart.get("type") in ("donut", "pareto"): selected_share_stages.add(share_stage) if len(charts) >= MAX_VISUALS: break return _finalize(charts, safe_turn_id, unavailable=wants_visuals) except Exception: # Never surface exception text: it could contain a path or source value. return { "visualSchemaVersion": VISUAL_SCHEMA_VERSION, "visualState": "failed", "visuals": [], "error": "图表整理遇到内部错误,已有文字分析可继续使用。", }