Files
quality_analyse/scripts/analysis_visuals.py
T
lyun ff7bbe3e46 同步:完善质量分析工作台并更新主题字体
同步已上线的智能分析执行协议、来源查询、图表报告与管理页面配套代码。
补齐数据库迁移、运行依赖和回归测试,保留原有指标计算口径。
统一午夜黑及其他主题的控件细节、中文和业务数字字体。
排除本地业务数据、凭据、预览、发布与验收产物。

验证:生产构建通过,320项前端回归通过;本轮仅同步Git,不再次部署。
2026-10-30 22:40:58 +08:00

2658 lines
134 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""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
try:
from .nao_period import PERIOD_KEYS, normalize_period
except ImportError:
from nao_period import PERIOD_KEYS, normalize_period
VISUAL_SCHEMA_VERSION = 1
MAX_VISUALS = 12
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", "monthStart", "monthEnd", "department", "group", "product", "projectGroup",
"view", "includeUnassigned", "releaseId", "extraFilters", "exclusions", "columnFilters", "columnLabels", "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"图表|画图|绘图|画.{0,12}排名|可视化|趋势图|柱状图|柱形图|竖向柱|纵向柱|折线图|条形图|横条图|"
r"横向柱|水平柱|面积图|面积趋势|热力图|热图|环状图|环形图|环状|环形|甜甜圈|饼图|"
r"构成|占比|排名图|柏拉图|帕累托|pareto|瀑布图|waterfall"
)
_NO_CHART = re.compile(
r"不画图|不用(?:画图|绘图|图表?|可视化|配图)|不要(?:绘图|图表?|可视化|配图)|"
r"不需要(?:绘图|图表?|可视化|配图)|无需(?:绘图|图表?|配图)|不必(?:画图|绘图|图表?|配图)|"
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)
_WATERFALL_CHART = re.compile(r"瀑布图|waterfall", 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|"
# Common business phrasing must not depend on the user saying “分析” or “图表”.
r"下滑|下跌|走低|下行|下探|回落|降低|下挫|降幅|跌幅|滑坡|退步|退化|"
r"变差|变坏|变糟|变低|变高|最差|较差|很差|偏低|不理想|不佳|不好|糟糕|堪忧|"
r"(?:质量|表现)(?:明显|比较|相对)?差|不达标|未达标|低于目标|超标|垫底|落后|掉队|"
r"(?:掉|降|跌)(?:得|的|了).{0,4}(?:多|大|厉害|严重)|"
r"不稳定|波动|起伏|异常|不正常|忽高忽低|"
r"突增|骤增|激增|飙升|变多|增多|增加|变少|减少|"
r"好转|变好|提升|提高|升高|回升|上扬|走高|向好|"
r"环比|同比|差异|差距|差别|关注|重点",
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 > 4:
return None, False
if value is None or isinstance(value, bool):
return value, True
if isinstance(value, str):
text = _safe_text(value, limit=256)
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) > 50:
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
exclusions = clean.get('exclusions')
if exclusions is not None:
if not isinstance(exclusions, dict) or set(exclusions) - {'department', 'group', 'product', 'projectGroup'}:
return None, None
if any(not isinstance(values, list) or not 1 <= len(values) <= 50
or any(not isinstance(value, str) or not value.strip() or len(value) > 256 for value in values)
for values in exclusions.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 PERIOD_KEYS:
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 _scope_caption(scope: dict[str, Any]) -> str | None:
labels = (("department", "产业部"), ("group", "业务分组"), ("product", "产品"),
("category", "类别"), ("defect", "具体缺陷"))
parts = []
for key, label in labels:
value = _safe_text(scope.get(key), limit=80)
if value:
parts.append(f"{label}:{value}")
caption = ",".join(parts)
return caption[:200] if caption else None
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
try:
clean = normalize_period(value)
except ValueError:
return None, None, None
if clean is None:
return None, None, None
year = clean['year']
if not 2000 <= year <= 2100:
return None, None, None
if 'monthStart' in clean:
start, end = clean['monthStart'], clean['monthEnd']
return clean, f"{year:04d}-{start:02d}..{end:02d}", (year, start, 3)
if 'month' in clean:
return clean, f"{year:04d}-{clean['month']:02d}", (year, clean['month'], 0)
if 'quarter' in clean:
quarter = clean['quarter']
return clean, f"{year:04d}-Q{quarter}", (year, (quarter - 1) * 3 + 1, 1)
return clean, str(year), (year, 0, 2)
def _trend_period(value: Any) -> tuple[str | None, tuple[int, int, int] | None]:
if isinstance(value, dict):
if 'monthStart' in value or 'monthEnd' in value:
return None, None
_, 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,
section_key: str | None = None,
dimension: 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 section_key in {"overview", "stage", "department", "group", "product", "category_black",
"category_bright", "defect_black", "defect_bright", "trend", "composition"}:
chart["sectionKey"] = section_key
if dimension in {"department", "group", "product", "category", "defect"}:
chart["dimension"] = dimension
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_scrap_rate(value: Any) -> tuple[float | None, bool]:
"""Accept the formal scrap ratio without imposing a 100% ceiling."""
number, valid = _finite_number(value)
if not valid or (number is not None and number < 0):
return None, False
return number, True
def _stage_period_source_covered(snapshot: dict[str, Any], stage: str) -> bool:
period = snapshot.get("period")
if not isinstance(period, dict):
return False
try:
from nao_quality_tools import _valid_stage_period_coverage
return _valid_stage_period_coverage(snapshot, period, stage)[0]
except (KeyError, TypeError, ValueError):
return False
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 PERIOD_KEYS:
if key in scope and period.get(key) != scope[key]:
return False
return True
def _both_stage_totals_explicitly_unusable(point: dict[str, Any]) -> bool:
"""Do not chart a legacy fallback 100% with two explicit empty denominators.
Older chart evidence omitted totals; keep that legacy shape separate from
current snapshots that explicitly state zero/null totals for both stages.
"""
for stage in ('black', 'bright'):
values = point.get(stage)
if not isinstance(values, dict) or 'totalWeight' not in values:
return False
total, valid = _finite_number(values['totalWeight'])
if valid and total is not None and total > 0:
return False
return True
def _comparison_charts(document: dict[str, Any], result: dict[str, Any], turn_id: str, question: str,
requested_stage: str | None = None, *, semantic_fields: set[str] | None = None,
semantic_stages: list[str] | None = None) -> 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")
composite_available=(isinstance(delta,dict) and delta.get("available") is True
and not _both_stage_totals_explicitly_unusable(current)
and not _both_stage_totals_explicitly_unusable(comparison))
refs = [_evidence_ref(document)] if _evidence_ref(document) else []
categories = [
{"key": "comparison", "label": comparison_label},
{"key": "current", "label": current_label},
]
rate_question = re.sub(r"报废率", "", question)
asked_black = bool(re.search(r"黑片.{0,8}(?:合格率|不良率|率)|(?:合格率|不良率|率).{0,8}黑片", rate_question))
asked_bright = bool(re.search(r"亮片.{0,8}(?:合格率|不良率|率)|(?:合格率|不良率|率).{0,8}亮片", rate_question))
asked_scrap_black = bool(re.search(r"黑片.{0,8}报废率|报废率.{0,8}黑片", question))
asked_scrap_bright = bool(re.search(r"亮片.{0,8}报废率|报废率.{0,8}亮片", question))
broad_overall = bool(re.search(r"原因|整体分析|总体分析|整体|总体|不良率|综合质量", rate_question))
explicit_stage_only = (asked_black or asked_bright) and not re.search(r"综合|总体|整体", question)
if requested_stage in ('black','bright'):
asked_black,asked_bright=requested_stage=='black',requested_stage=='bright'
explicit_stage_only=True
metrics: list[tuple[str, str | None, str, Any, Any, str]] = []
if not explicit_stage_only and composite_available:
metrics.append(("composite_rate", None, "综合合格率", comparison.get("compositeRate"), current.get("compositeRate"), "composite_rate"))
stage_changes = result.get("stageRateChangesPP")
requested_stages = []
if asked_black or broad_overall and not explicit_stage_only:
requested_stages.append(("black", "黑片合格率", "black_rate"))
if asked_bright or broad_overall and not explicit_stage_only:
requested_stages.append(("bright", "亮片合格率", "bright_rate"))
for stage, label, metric in requested_stages:
if semantic_fields is not None and "rate" not in semantic_fields:
continue
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))
scrap_rate_requested = ("scrapRate" in semantic_fields if semantic_fields is not None
else bool(re.search(r"报废率", question)))
if scrap_rate_requested:
if requested_stage in ("black", "bright"):
scrap_stages = [requested_stage]
elif semantic_fields is not None and semantic_stages:
scrap_stages = [stage for stage in semantic_stages if stage in ("black", "bright")]
else:
scrap_stages = [stage for stage, asked in (("black", asked_scrap_black), ("bright", asked_scrap_bright))
if asked] or ["black", "bright"]
for stage in scrap_stages:
old_side, now_side = comparison.get(stage), current.get(stage)
old_side = old_side if isinstance(old_side, dict) else {}
now_side = now_side if isinstance(now_side, dict) else {}
if (not _stage_period_source_covered(comparison, stage)
or not _stage_period_source_covered(current, stage)):
continue
label = ("黑片" if stage == "black" else "亮片") + "报废率"
metrics.append((f"{stage}_scrap_rate", stage, label,
old_side.get("scrapRate"), now_side.get("scrapRate"),
f"{stage}_scrap_rate"))
charts: list[dict[str, Any]] = []
scrap_rate_only = bool(re.search(r"报废率", question)
and not re.search(r"合格率|良率|不良率", question))
if semantic_fields is not None:
metrics = [item for item in metrics
if item[0] in ("black_scrap_rate", "bright_scrap_rate")
or "rate" in semantic_fields]
elif scrap_rate_only:
metrics = [item for item in metrics if item[0] in ("black_scrap_rate", "bright_scrap_rate")]
for metric, stage, label, old_raw, now_raw, required in metrics:
if not _scope_compatible(scope, release_id, period=current_period, stage=stage):
continue
validator = (_valid_scrap_rate if metric in ("black_scrap_rate", "bright_scrap_rate")
else _valid_rate)
old_value, old_ok = validator(old_raw)
now_value, now_ok = validator(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}_scrap_weight", f"{stage}_total_weight"]
if metric in ("black_scrap_rate", "bright_scrap_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},
section_key="overview" if metric == "composite_rate" else "stage",
))
if semantic_fields is not None:
selected_stages = semantic_stages or []
for field in ('totalWeight', 'scrapWeight'):
if field not in semantic_fields:
continue
for stage in selected_stages:
old_side = comparison.get(stage) if isinstance(comparison.get(stage), dict) else {}
now_side = current.get(stage) if isinstance(current.get(stage), dict) else {}
if (not _stage_period_source_covered(comparison, stage)
or not _stage_period_source_covered(current, stage)
or not _scope_compatible(scope, release_id, period=current_period, stage=stage)):
continue
old_value, old_ok = _finite_number(old_side.get(field))
now_value, now_ok = _finite_number(now_side.get(field))
# Signed black input corrections are rendered on monthly lines;
# a two-point comparison bar does not silently rebase that value.
if (not old_ok or not now_ok or old_value is None or now_value is None
or old_value < 0 or now_value < 0):
continue
metric = stage + ('_total_weight' if field == 'totalWeight' else '_scrap_weight')
label = ('黑片' if stage == 'black' else '亮片') + ('投入重量' if field == 'totalWeight' else '报废重量')
charts.append(_chart(
turn_id=turn_id, chart_type='bar', title=f'正式{label}期间对比',
subtitle=f'比较期 {comparison_label},本期 {current_label};使用正式重量指标。',
unit='kg', categories=categories,
series=[{'key': metric, 'label': label, 'values': [old_value, now_value]}],
evidence_refs=refs,
required_fields=[f'{stage}_{"total" if field == "totalWeight" else "scrap"}_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},
section_key='stage'))
return charts
def _comparison_waterfall(document: dict[str, Any], result: dict[str, Any], turn_id: str,
question: str, *, allow_semantic: bool = False) -> dict[str, Any] | None:
"""Use the service's balanced decomposition for math-only attribution."""
if result.get("kind") != "quality_comparison" or (not allow_semantic and not re.search(
r"原因|整体分析|总体分析|拆解|分解|归因|为什么", question)):
return None
release_id = _release_id(document, result)
scope, _ = _scope(result.get("filterBinding"))
current, comparison = result.get("current"), result.get("comparison")
delta, decomposition = result.get("delta"), result.get("stageDecomposition")
if (release_id is None or scope is None or not isinstance(current, dict)
or not isinstance(comparison, dict) or not isinstance(delta, dict)
or delta.get("available") is not True or not isinstance(decomposition, dict)
or decomposition.get("status") != "available"):
return None
period, current_label, _ = _period(current.get("period"))
comparison_period, comparison_label, _ = _period(comparison.get("period"))
if (period is None or comparison_period is None or period == comparison_period
or not _scope_compatible(scope, release_id, period=period)):
return None
values = []
for field in ("blackContributionToCompositePP", "brightContributionToCompositePP", "sumPP"):
value, valid = _finite_number(decomposition.get(field))
if not valid or value is None or abs(value) > 100:
return None
values.append(value)
reported_delta, delta_valid = _finite_number(delta.get("percentagePoints"))
if not delta_valid or reported_delta is None or abs(reported_delta) > 100:
return None
if not math.isclose(values[0] + values[1], values[2], rel_tol=1e-10, abs_tol=1e-6):
return None
if not math.isclose(values[2], reported_delta, rel_tol=1e-10, abs_tol=1e-6):
return None
refs = [_evidence_ref(document)] if _evidence_ref(document) else []
return _chart(
turn_id=turn_id,
chart_type="waterfall",
title="综合合格率变化的影响拆解",
subtitle=f"{comparison_label} → {current_label};展示两阶段对正式综合率变化的影响。",
unit="pp",
categories=[
{"key": "black", "label": "黑片影响"},
{"key": "bright", "label": "亮片影响"},
{"key": "total", "label": "合计"},
],
series=[{"key": "composite_impact_pp", "label": "对综合合格率变化的影响(pp)", "values": values}],
evidence_refs=refs,
required_fields=["black_good_weight", "black_total_weight", "bright_good_weight", "bright_total_weight"],
scope=_chart_scope(scope, release_id, period),
period=period,
comparison_period=comparison_period,
metric="composite_impact_pp",
coverage={"totalRows": 3, "returnedRows": 3, "truncated": False},
note="仅为正式合格率变化的拆解,不代表生产根因。",
section_key="overview",
)
def _comparison_category_delta_charts(document: dict[str, Any], result: dict[str, Any], turn_id: str,
question: str, *, allow_semantic: bool = False,
requested_stages: list[str] | None = None) -> list[dict[str, Any]]:
if (result.get("kind") != "quality_comparison"
or (not allow_semantic and not re.search(r"原因|整体分析|总体分析|报废类别|类别增减|正式类别", question))):
return []
release_id = _release_id(document, result)
scope, _ = _scope(result.get("filterBinding"))
current, comparison = result.get("current"), result.get("comparison")
if release_id is None or scope 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
or scope.get("category") not in (None, "") or scope.get("defect") not in (None, "")):
return []
charts: list[dict[str, Any]] = []
stages = requested_stages if requested_stages else ["black", "bright"]
for stage in stages:
if not _scope_compatible(scope, release_id, period=current_period, stage=stage):
continue
now_side, old_side = current.get(stage), comparison.get(stage)
if not isinstance(now_side, dict) or not isinstance(old_side, dict):
continue
now_defs, old_defs = now_side.get("defects"), old_side.get("defects")
expected = _DEFECT_FIELDS[stage]
if not isinstance(now_defs, list) or not isinstance(old_defs, list):
continue
def read_formal(items: list[Any]) -> dict[str, float] | None:
parsed: dict[str, float] = {}
for item in items:
if not isinstance(item, dict):
return None
label = _safe_text(item.get("name"), limit=80)
field = expected.get(label) if label is not None else None
weight, valid = _valid_weight(item.get("weight"))
if field is None or not valid or weight is None or field in parsed:
return None
parsed[field] = weight
return parsed
now_values, old_values = read_formal(now_defs), read_formal(old_defs)
if (now_values is None or old_values is None or set(now_values) != set(expected.values())
or set(old_values) != set(expected.values()) or sum(now_values.values()) + sum(old_values.values()) <= 0):
continue
ordered = list(expected.items())
labels, fields = [item[0] for item in ordered], [item[1] for item in ordered]
values = [now_values[field] - old_values[field] for field in fields]
stage_label = "黑片" if stage == "black" else "亮片"
charts.append(_chart(
turn_id=turn_id,
chart_type="bar",
title=f"{stage_label}正式报废类别重量增减",
subtitle=f"{comparison_label} → {current_label};按正式类别逐项相减,正负方向均保留。",
unit="kg",
categories=[{"key": field, "label": label} for field, label in zip(fields, labels)],
series=[{"key": "source_defect_delta_weight", "label": "报废重量增减(kg)", "values": values}],
evidence_refs=[_evidence_ref(document)] if _evidence_ref(document) else [],
required_fields=fields,
scope=_chart_scope(scope, release_id, current_period, view="overall", stage=stage),
period=current_period,
comparison_period=comparison_period,
stage=stage,
metric="source_defect_delta_weight",
coverage={"totalRows": len(fields), "returnedRows": len(fields), "truncated": False},
note="展示正式报废类别各自的期间增减,不代表总体合格率贡献。",
section_key=f"category_{stage}",
dimension="category",
))
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="占比按本图已列类别重量合计计算,不代表正式报废总量占比。",
section_key="composition",
dimension="category",
)
def _comparison_category_charts(document: dict[str, Any], result: dict[str, Any], turn_id: str,
question: str, *, semantic_chart_type: str | None = None,
semantic_stages: list[str] | None = None) -> list[dict[str, Any]]:
chart_type = semantic_chart_type if semantic_chart_type in ("donut", "pareto") else _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 = semantic_stages if semantic_stages is not None else _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, *, semantic_chart_type: str | None = None,
semantic_stages: list[str] | None = None) -> list[dict[str, Any]]:
chart_type = semantic_chart_type if semantic_chart_type in ("donut", "pareto") else _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 = semantic_stages if semantic_stages is not None else _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["sectionKey"] = "composition"
result_chart["dimension"] = "category"
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_rate':
title = '分组本期合格率排名'
metric = (stage+'_rate') if stage else 'composite_rate'
unit, label, field = 'ratio', '本期合格率', 'rate'
required_fields = ([f'{stage}_good_weight',f'{stage}_total_weight'] if stage else
['black_good_weight','black_total_weight','bright_good_weight','bright_total_weight'])
def value_for(row: dict[str, Any]) -> tuple[float | None, bool]:
value, valid = _finite_number((row.get('current') or {}).get('rate'))
return value, valid and (value is None or 0 <= value <= 1)
note = '按本期正式合格率由低到高排列;结合两期投入和报废增量判断,缺失阶段不作为实测100%。'
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("分组", "产品")
if order == "rate_drop":
title = title.replace("合格率变化排名", "合格率降幅线索")
note = "条形末端显示具体变化:正值为下降,负值为改善,单位是百分点。本图只按率降幅排序,未纳入投入规模;少量生产或投入骤变的规格不能仅凭此图认定为重点,需结合分阶段投入与报废增量核查。"
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),
}
scope_caption = _scope_caption(scope)
return _chart(
turn_id=turn_id,
chart_type="bar",
title=title,
subtitle=(f"范围 {scope_caption};" if scope_caption else "")
+ 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,
section_key={"product": "product", "group": "group", "department": "department"}[result["dimension"]],
dimension=result["dimension"],
)
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", *PERIOD_KEYS}
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 (*PERIOD_KEYS, "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 PERIOD_KEYS):
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 (*PERIOD_KEYS, "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,
section_key=(f"category_{stage}" if dimension == "category" else
{"product": "product", "group": "group", "department": "department"}.get(dimension, "group")),
dimension=("group" if dimension == "projectGroup" else
dimension if dimension in ("product", "group", "department", "category") else None),
)
_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") if item.get("label") is not None else item.get("key"), limit=160)
category = _safe_text(item.get("category"), limit=80)
source_field = item.get("sourceField", item.get("key"))
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:
from nao_defect_report import expand_defect_model_view
result = expand_defect_model_view(result, result.get('defect') if isinstance(result, dict) else None)
if not isinstance(result, dict):
return None
dimension = result.get("dimension")
if result.get("kind") != "quality_fine_defects" or dimension not in ("defect", "product"):
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
selected_defect = result.get("defect")
if dimension == "product" and (not isinstance(selected_defect, str)
or selected_defect not in current_fields):
return None
selected_field = current_fields.get(selected_defect) if selected_defect is not None else 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 dimension == "defect" and isinstance(key, str)
else selected_field if dimension == "product" 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
if dimension == "defect":
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
chart_label = field_label
else:
side_defects = [candidate for candidate in (row.get("defect"), current.get("defect"),
comparison.get("defect")) if candidate is not None]
if any(candidate != selected_defect for candidate in side_defects):
return None
raw_chart_label = next((candidate for candidate in (row.get("label"), current.get("label"),
comparison.get("label"))
if isinstance(candidate, str) and candidate.strip()), None)
chart_label = _safe_text(raw_chart_label, limit=MAX_LABEL_LENGTH)
if chart_label is None:
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": chart_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),
}
scope_caption = _scope_caption(scope)
return _chart(
turn_id=turn_id,
chart_type="bar",
title=f"{stage_label}{title}",
subtitle=(f"范围 {scope_caption};" if scope_caption else "")
+ (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=([selected_defect] if dimension == "product" else
[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,
section_key=f"defect_{result['stage']}" if dimension == "defect" else "product",
dimension=dimension,
)
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,
semantic_fields: set[str] | None = None,
semantic_stages: list[str] | None = None,
minimum_points: int = 3,
) -> list[dict[str, Any]]:
if len(points) < minimum_points 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
rate_question = re.sub(r"报废率", "", question)
asked_rate_black = "黑片" in rate_question
asked_rate_bright = "亮片" in rate_question
scrap_rate_only = bool(re.search(r"报废率", question)
and not re.search(r"合格率|良率|不良率", question))
explicit_stage_only = (asked_rate_black or asked_rate_bright) and not re.search(r"综合|总体", rate_question)
rate_metrics = []
if semantic_fields is None:
if not explicit_stage_only:
rate_metrics.append(("composite_rate", None, "综合合格率", "compositeRate"))
all_stages = not (asked_rate_black or asked_rate_bright) and (not re.search(r"综合(?:合格)?率", rate_question) or "阶段" in question)
if asked_rate_black or all_stages:
rate_metrics.append(("black_rate", "black", "黑片合格率", "rate"))
if asked_rate_bright or all_stages:
rate_metrics.append(("bright_rate", "bright", "亮片合格率", "rate"))
elif "rate" in semantic_fields:
stages = semantic_stages or []
if stages:
rate_metrics.extend(("black_rate", "black", "黑片合格率", "rate") for stage in stages if stage == "black")
rate_metrics.extend(("bright_rate", "bright", "亮片合格率", "rate") for stage in stages if stage == "bright")
else:
rate_metrics.append(("composite_rate", None, "综合合格率", "compositeRate"))
if semantic_fields is None and scrap_rate_only:
rate_metrics = []
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 (type(point_coverage.get(stage + "Rows")) is not int
or point_coverage[stage + "Rows"] <= 0):
raw = None
elif stage is None and (not all(type(point_coverage.get(name)) is int and point_coverage[name] >= 0
for name in ("blackRows", "brightRows"))
or not any(point_coverage[name] > 0 for name in ("blackRows", "brightRows"))):
raw = None
if stage is not None and isinstance(nested, dict) and 'totalWeight' in nested:
total, total_valid = _finite_number(nested['totalWeight'])
if not total_valid or total is None or total <= 0:
raw = None
if stage is None and _both_stage_totals_explicitly_unusable(point):
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) >= minimum_points:
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},
section_key="trend",
))
scrap_rate_requested = ("scrapRate" in semantic_fields if semantic_fields is not None
else bool(re.search(r"报废率", question)))
if scrap_rate_requested:
if semantic_fields is not None and semantic_stages:
scrap_rate_stages = [stage for stage in semantic_stages if stage in ("black", "bright")]
else:
scrap_rate_stages = [stage for stage, asked in (("black", asked_black), ("bright", asked_bright))
if asked] or ["black", "bright"]
for stage in scrap_rate_stages:
if not _scope_compatible(scope, release_id, stage=stage):
continue
vals: list[float | None] = []
valid = True
for _, point in expanded:
nested = point.get(stage)
point_coverage = point.get("coverage")
stage_rows = point_coverage.get(stage + "Rows") if isinstance(point_coverage, dict) else None
raw = nested.get("scrapRate") if isinstance(nested, dict) else None
if (point.get("noData") is True or point.get("monthStatus") in ("future", "unavailable")
or not isinstance(point_coverage, dict) or not isinstance(stage_rows, int)
or isinstance(stage_rows, bool) or stage_rows <= 0):
raw = None
total, total_valid = _finite_number(nested.get('totalWeight') if isinstance(nested, dict) else None)
scrap, scrap_valid = _finite_number(nested.get('scrapWeight') if isinstance(nested, dict) else None)
if (not total_valid or total is None or total <= 0
or not scrap_valid or scrap is None or scrap < 0):
raw = None
value, okay = _valid_scrap_rate(raw)
if not okay:
valid = False
break
vals.append(value)
if valid and sum(value is not None for value in vals) >= minimum_points:
metric = f"{stage}_scrap_rate"
label = ("黑片" if stage == "black" else "亮片") + "报废率"
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=[f"{stage}_scrap_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},
note="按已发布月份展示,缺失月份不补零。",
section_key="trend",
))
weight_fields = ([('totalWeight' if re.search(r'投入|产量|总重|总重量', question) else 'scrapWeight')]
if semantic_fields is None else
[field for field in ('scrapWeight', 'totalWeight') if field in semantic_fields])
if ((semantic_fields is None and re.search(r"重量|报废|废品|kg|公斤", question, re.IGNORECASE))
or (semantic_fields is not None and weight_fields)):
weight_stages = [("black", field, ("黑片报废重量" if field == 'scrapWeight' else "黑片投入重量"))
for field in weight_fields]
weight_stages += [("bright", field, ("亮片报废重量" if field == 'scrapWeight' else "亮片投入重量"))
for field in weight_fields]
if semantic_fields is not None and semantic_stages:
weight_stages = [item for item in weight_stages if item[0] in semantic_stages]
elif asked_black and not asked_bright:
weight_stages = [item for item in weight_stages if item[0] == 'black']
elif asked_bright and not asked_black:
weight_stages = [item for item in weight_stages if item[0] == 'bright']
for stage, field, 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)
raw = nested.get(field) if isinstance(nested, dict) else None
value, okay = _finite_number(raw)
if field == 'scrapWeight' and okay and value is not None and value < 0:
okay = False
if field == 'totalWeight' and stage != 'black' and okay and value is not None and value < 0:
okay = False
if not okay:
valid = False
break
vals.append(value)
if valid and sum(value is not None for value in vals) >= minimum_points:
metric = "current_scrap_weight" if field == 'scrapWeight' else stage+'_total_weight'
charts.append(_chart(
turn_id=turn_id,
chart_type="line",
title=f"{trend_name}({label})",
subtitle=("按时间顺序展示正式报废重量;缺失期间保留为空。" if field == 'scrapWeight'
else "按时间顺序展示正式投入重量;黑片负向修正原值保留,不填零。"),
unit="kg",
categories=categories,
series=[{"key": metric, "label": label, "values": vals}],
evidence_refs=evidence_refs,
required_fields=[f"{stage}_{'scrap' if field == 'scrapWeight' else '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},
note=("黑片与亮片分开;不合并为单阶段投入分母。" if field == 'scrapWeight'
else "黑片负向投入重量修正按正式原值展示;亮片投入重量仍要求非负。"),
section_key="trend",
))
return charts
def _metrics_trend_charts(document: dict[str, Any], result: dict[str, Any], turn_id: str, question: str, *,
semantic_fields: set[str] | None = None,
semantic_stages: list[str] | None = None,
selected_period: dict[str, Any] | None = None,
minimum_points: int = 3) -> 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) < minimum_points:
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 []
# When the parent explicitly supplies monthly provenance, a row cannot
# promote an unknown parent count to a known zero or a positive count.
parent_coverage = result.get('coverage')
source_months = parent_coverage.get('sourceMonths') if isinstance(parent_coverage, dict) else None
if isinstance(parent_coverage, dict) and 'sourceMonths' in parent_coverage and not isinstance(source_months, list):
return []
if isinstance(source_months, list):
by_month = {}
duplicates = set()
for item in source_months:
if not isinstance(item, dict):
continue
if type(item.get('year')) is not int or type(item.get('month')) is not int or not 1 <= item['month'] <= 12:
continue
key = (item['year'], item['month'])
if key in by_month:
duplicates.add(key)
by_month[key] = item
for point in points:
_, order = _trend_period(point.get('period'))
if order is None or order[2] != 0:
continue
key = (order[0], order[1])
parent = by_month.get(key) if key not in duplicates else None
row = point['snapshot']
counts = row.get('coverage') if isinstance(row.get('coverage'), dict) else {}
combined = dict(counts)
for stage in ('black', 'bright'):
field = stage + 'Rows'
a = counts.get(field)
b = parent.get(field) if isinstance(parent, dict) else None
combined[field] = min(a, b) if type(a) is int and a >= 0 and type(b) is int and b >= 0 else None
point['snapshot'] = {**row, 'coverage': combined}
period_scope = None
try:
selected = normalize_period(selected_period) if selected_period is not None else None
except ValueError:
return []
if selected is not None and 'monthStart' in selected:
period_scope = selected
for point in points:
label, order = _trend_period(point.get('period'))
if (label is None or order is None or order[2] != 0
or order[0] != selected['year']
or not selected['monthStart'] <= order[1] <= selected['monthEnd']):
return []
chart_scope = dict(scope)
if period_scope is not None:
chart_scope.update(period_scope)
return _trend_chart_from_points(
points,
release_id=release_id,
scope=chart_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,
semantic_fields=semantic_fields,
semantic_stages=semantic_stages,
minimum_points=minimum_points,
)
def _multi_query_trend(evidence: list[tuple[dict[str, Any], dict[str, Any]]], turn_id: str, question: str, *,
semantic_fields: set[str] | None = None,
semantic_stages: list[str] | None = None) -> 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"))
if isinstance(period, dict) and 'monthStart' in period:
continue
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,
semantic_fields=semantic_fields,
semantic_stages=semantic_stages,
)
candidates.extend(charts)
return candidates
_AGENT_TASK_KINDS = {"analysis", "metrics", "explain", "restate", "report", "source_verify", "details"}
_AGENT_DIMENSIONS = {"department", "group", "product", "defect"}
_AGENT_STAGES = {"black", "bright"}
_AGENT_FIELDS = {"rate", "scrapRate", "totalWeight", "scrapWeight"}
_AGENT_VISUAL_TYPES = {"bar", "column", "line", "area", "heatmap", "donut", "pareto", "waterfall"}
def _agent_task(context: Any, question: Any) -> dict[str, Any] | None:
"""Accept only the server-validated semantic task for this exact question."""
if not isinstance(context, dict) or not isinstance(question, str):
return None
task = context.get("_agentTask")
if not isinstance(task, dict) or task.get("version") != 1 or task.get("question") != question:
return None
if (task.get("kind") not in _AGENT_TASK_KINDS
or task.get("visualPreference") not in ("auto", "required", "none")
or task.get("visualType") not in (None, *_AGENT_VISUAL_TYPES)):
return None
for key, allowed in (("dimensions", _AGENT_DIMENSIONS), ("stages", _AGENT_STAGES), ("fields", _AGENT_FIELDS)):
values = task.get(key)
if not isinstance(values, list) or any(value not in allowed for value in values):
return None
return task
def _visual_context(context: Any) -> Any:
"""Keep semantic metadata out of the existing evidence-scope matcher."""
if not isinstance(context, dict) or "_agentTask" not in context:
return context
clean = {key: value for key, value in context.items() if key != "_agentTask"}
task = context.get('_agentTask')
if (isinstance(task,dict) and isinstance(task.get('period'),dict)
and 'monthStart' in task['period']
and not any(key in clean for key in PERIOD_KEYS)
and not isinstance(clean.get('period'),dict)
and not isinstance(clean.get('currentPeriod'),dict)):
clean['period'] = task['period']
return clean
def _requested_visual_period(context: Any, task: dict[str, Any] | None) -> dict[str, Any] | None:
if isinstance(context, dict):
selected = context.get('period') or context.get('currentPeriod')
if isinstance(selected, dict):
return selected
top_level = {key: context[key] for key in PERIOD_KEYS if key in context}
if top_level:
return top_level
selected = task.get('period') if isinstance(task, dict) else None
return selected if isinstance(selected, dict) else None
def _semantic_chart_dimension(chart: dict[str, Any]) -> str | None:
dimension = chart.get("dimension")
if dimension in _AGENT_DIMENSIONS:
return dimension
if dimension in ("category", "defect"):
return "defect"
section = chart.get("sectionKey")
if section in _AGENT_DIMENSIONS:
return section
if isinstance(section, str) and (section.startswith("category_") or section.startswith("defect_")):
return "defect"
scope = chart.get("scope") if isinstance(chart.get("scope"), dict) else {}
for key in ("department", "group", "product"):
if scope.get(key) not in (None, "", [], {}):
return key
if scope.get("category") not in (None, "", [], {}) or scope.get("defect") not in (None, "", [], {}):
return "defect"
return None
def _semantic_has_dimension(chart: dict[str, Any], dimension: str) -> bool:
if _semantic_chart_dimension(chart) == dimension:
return True
scope = chart.get("scope") if isinstance(chart.get("scope"), dict) else {}
scope_key = "category" if dimension == "defect" else dimension
return scope.get(scope_key) not in (None, "", [], {})
def _semantic_chart_matches(chart: dict[str, Any], task: dict[str, Any]) -> bool:
dimensions = task["dimensions"]
overview = chart.get('metric') == 'composite_rate' and task['kind'] in ('analysis', 'report')
if dimensions and not overview and not any(_semantic_has_dimension(chart, dimension) for dimension in dimensions):
return False
stages = task["stages"]
if stages and chart.get("stage") not in stages and not (overview and set(stages) == {'black', 'bright'}):
return False
fields = task["fields"] if task['kind'] == 'metrics' else []
if fields:
metric = chart.get("metric")
if metric in ("composite_rate", "black_rate", "bright_rate", "rate_drop_pp", "composite_impact_pp"):
field = "rate"
elif metric in ("black_scrap_rate", "bright_scrap_rate"):
field = "scrapRate"
elif metric in ("black_total_weight", "bright_total_weight"):
field = 'totalWeight'
elif metric in ("current_scrap_weight", "scrap_delta", "source_defect_weight", "source_defect_delta_weight", "black_scrap_weight", "bright_scrap_weight"):
field = "scrapWeight"
else:
return False
if field not in fields:
return False
return True
def _semantic_chart_priority(chart: dict[str, Any], task: dict[str, Any]) -> tuple[int, int, int, str, str]:
section_order = {"overview": 0, "stage": 1, "trend": 2, "department": 3, "group": 4,
"product": 5, "category_black": 6, "category_bright": 7,
"defect_black": 8, "defect_bright": 9, "composition": 10}
metric_order = {"composite_rate": 0, "black_rate": 1, "bright_rate": 2,
"black_scrap_rate": 3, "bright_scrap_rate": 4, "composite_impact_pp": 5,
"rate_drop_pp": 6, "scrap_delta": 7, "current_scrap_weight": 8,
"source_defect_delta_weight": 9, "source_defect_weight": 10}
dimensions = task["dimensions"]
dimension_order = next((index for index, value in enumerate(dimensions)
if _semantic_has_dimension(chart, value)), len(dimensions))
return (dimension_order, section_order.get(chart.get("sectionKey"), 20),
metric_order.get(chart.get("metric"), 20), str(chart.get("stage") or ""), str(chart.get("id") or ""))
def _semantic_type_chart(chart: dict[str, Any], chart_type: str | None) -> dict[str, Any] | None:
if chart_type is None:
if (chart.get("type") == "bar" and chart.get("sectionKey") in ("overview", "stage")
and chart.get("metric") in ("composite_rate", "black_rate", "bright_rate",
"black_scrap_rate", "bright_scrap_rate")):
chart_type = "column"
elif chart.get("type") == "line" and _is_period_trend(chart) and chart.get("metric") == "current_scrap_weight":
chart_type = "area"
else:
return chart
existing = chart.get("type")
compatible = (
chart_type in ("bar", "column") and existing in ("bar", "column")
or chart_type == "line" and existing == "line" and _is_period_trend(chart, minimum_points=2)
or chart_type in ("area", "heatmap") and existing in ("line", "area", "heatmap") and _is_period_trend(chart, minimum_points=3)
or chart_type in ("donut", "pareto") and existing == chart_type
or chart_type == "waterfall" and existing == "waterfall"
)
if not compatible:
return None
if existing != chart_type:
chart = dict(chart)
chart["type"] = chart_type
chart.pop("id", None)
chart["id"] = _visual_id(chart["originTurnId"], chart)
return chart
def _semantic_auto_chartable(candidates: list[tuple[int, str, str | None, dict[str, Any]]]) -> bool:
"""Require multiple evidenced observations, never a lone scalar result."""
return any(isinstance(item[3].get("categories"), list) and len(item[3]["categories"]) >= 2
and isinstance(item[3].get("series"), list)
and any(isinstance(series, dict) and isinstance(series.get("values"), list)
and sum(value is not None for value in series["values"]) >= 2
for series in item[3]["series"])
for item in 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 _explicit_rate_rank_view(question: str) -> bool:
"""A raw product rate ranking is only useful when the user asks for that view."""
if not re.search(r"合格率|良率|率降幅|率下降", question):
return False
return bool(re.search(
r"画图|绘图|图表|可视化|排名图|条形图|柱状图|柱形图|(?:画|绘).{0,15}(?:产品|规格|合格率|良率)|"
r"排名|排行|排序|前\s*\d+\s*名|降幅(?:最大|最多)|下降(?:最大|最多)", question
))
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"),
(_WATERFALL_CHART, "waterfall"),
):
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], *, minimum_points: int = 3) -> 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) >= minimum_points)
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 == "line" and chart_type in ("line", "area", "heatmap") and _is_period_trend(chart, minimum_points=2):
chart_type = requested
elif requested in ("area", "heatmap") and chart_type in ("line", "area", "heatmap") and _is_period_trend(chart, minimum_points=3):
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", "black_scrap_rate", "bright_scrap_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:
"""Choose chapter-relevant views without letting incidental rankings lead."""
metric = chart.get("metric")
section = chart.get("sectionKey")
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"
broad_cause = bool(re.search(r"原因|分析|拆解|分解|归因", question))
explicit_rate_rank = bool(re.search(r"率降幅|合格率变化排名|率下降排名|排名.*合格率", question))
if metric == "current_scrap_weight" and re.search(r"重量|报废|废品|kg|公斤", question, re.IGNORECASE):
return 0 if "趋势" in question else 3
scope = chart.get("scope") if isinstance(chart.get("scope"), dict) else {}
scope_specificity = sum(scope.get(key) not in (None, "", [], {}) for key in (
"department", "group", "product", "category", "defect"
))
if chart.get("type") in ("donut", "pareto") or section == "composition":
return 0
if chart.get("type") in ("line", "area", "heatmap") or section == "trend":
if "趋势" in question:
return {"composite_rate": 0, "black_rate": 1, "bright_rate": 2,
"black_scrap_rate": 2, "bright_scrap_rate": 2,
"current_scrap_weight": 3}.get(metric, 5)
return 8
if metric == "composite_rate" and section == "overview":
return 0
if metric == "composite_impact_pp":
return 1 if broad_cause else 5
if section == "stage":
return 2 if broad_cause or re.search(r"黑片|亮片|阶段", question) else 6
if metric == "rate_drop_pp":
if explicit_rate_rank:
return 2
if broad_cause:
return {"department": 3, "group": 4}.get(section, 20)
return {"department": 7, "group": 8}.get(section, 20)
if section == "product" or kind == "quality_top" and dimension == "product":
if requested_dimension == "product":
return 3 if metric in ("scrap_delta", "current_scrap_weight") else 4
return 4 if metric in ("scrap_delta", "current_scrap_weight") else 10
if section == "department" or kind == "quality_top" and dimension == "department":
return 4 if metric in ("scrap_delta", "current_scrap_weight") else 6
if section == "group" or kind == "quality_top" and dimension in ("group", "projectGroup"):
return 5 if metric in ("scrap_delta", "current_scrap_weight") else 7
if section in ("category_black", "category_bright"):
return 5 if broad_cause or re.search(r"报废类别|类别增减|正式类别", question) else 9
if section in ("defect_black", "defect_bright"):
# 优先阶段汇总;局部追查图保留自身筛选范围,仍可作为补充视图。
return 6 + min(scope_specificity, 3) + (0 if broad_cause else 2)
if kind == "quality_top":
return 4 if requested_dimension == dimension else 10
return 12
def _chart_selection_key(chart: dict[str, Any]) -> str:
semantic = {key: chart.get(key) for key in (
"type", "sectionKey", "dimension", "metric", "stage", "scope", "period", "comparisonPeriod",
"categories", "series",
)}
return json.dumps(semantic, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False)
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 _bound_visual_evidence(evidence, context):
"""Use the text finalizer's exact period/scope anchor, never scope depth."""
try:
from .nao_evidence_report import select_comparison_frames,_filters,_frame_key,_same_periods,_matches_context,_period_key
except ImportError:
from nao_evidence_report import select_comparison_frames,_filters,_frame_key,_same_periods,_matches_context,_period_key
roots,limitations=select_comparison_frames([d for d,_ in evidence],context)
if roots and limitations:
# The textual answer explicitly keeps these frames separate. Charts may
# show their own labelled scopes too, without favouring the broadest one.
return evidence,False
root=roots[0]['result'] if len(roots)==1 else None
accepted=[]
for document,result in evidence:
if root is None:
if result.get('kind') in ('quality_fine_defects','quality_changes'):
# Fine-defect comparisons store their two periods directly,
# unlike formal quality_comparison's current/comparison pair.
# Adapt only the local frame matcher input; keep the evidence
# document and chart semantics unchanged.
frame = {'kind':'quality_comparison',
'current':{'period':result.get('period') or result.get('currentPeriod') or {}},
'comparison':{'period':result.get('comparisonPeriod') or {}},
'filterBinding':result.get('filters') or {}}
else:
frame={'current':{'period':result.get('period') or result.get('currentPeriod') or {}},'filterBinding':result.get('filters') or {}}
if _matches_context(frame,context):accepted.append((document,result))
continue
if result.get('kind')=='quality_comparison':
if _frame_key(result)==_frame_key(root):accepted.append((document,result))
continue
parent=_filters(root.get('filterBinding'));child=_filters(result.get('filters'))
if not all(child.get(k)==v for k,v in parent.items()):continue
if bool(child.get('includeUnassigned'))!=bool(parent.get('includeUnassigned')):continue
if result.get('kind') in ('quality_changes','quality_fine_defects'):
if _same_periods(result,root):accepted.append((document,result))
elif _period_key(result.get('period'))==_period_key(root['current'].get('period')):
accepted.append((document,result))
return accepted,True
def _bound_trend_evidence(evidence, context):
"""A year's monthly trend may use its months; snapshot charts still require exact periods."""
try:
from .nao_evidence_report import _matches_context, _filters, select_comparison_frames
except ImportError:
from nao_evidence_report import _matches_context, _filters, select_comparison_frames
if not isinstance(context, dict):
return evidence
roots, limitations = select_comparison_frames([document for document, _ in evidence], context)
root_document = roots[0] if len(roots) == 1 and not limitations else None
root = root_document['result'] if root_document else None
if root is not None:
context = {**context, 'period': root.get('current', {}).get('period') or {},
'filters': root.get('filterBinding') or {}}
selected = context.get('period') or context.get('currentPeriod')
if not isinstance(selected, dict):
selected = {key: context[key] for key in PERIOD_KEYS if key in context}
requested_period = None
if selected:
try:
requested_period = normalize_period({key: selected[key] for key in PERIOD_KEYS if key in selected})
except ValueError:
return []
accepted = []
for document, result in evidence:
if result.get('kind') != 'quality_metrics':
continue
if root is not None and (_filters(result.get('filters')) != _filters(root.get('filterBinding'))
or _release_id(document, result) != _release_id(root_document, root)):
continue
period = result.get('period') or {}
try:
actual_period = normalize_period(period)
except ValueError:
continue
if requested_period is not None and 'monthStart' in requested_period:
if actual_period != requested_period:
if (not actual_period or actual_period.get('year') != requested_period['year']
or 'month' not in actual_period
or not requested_period['monthStart'] <= actual_period['month'] <= requested_period['monthEnd']):
continue
elif requested_period is not None:
if 'month' in requested_period and actual_period != requested_period:
continue
if 'quarter' in requested_period and actual_period != requested_period:
if (actual_period.get('year') != requested_period['year']
or 'month' not in actual_period
or (actual_period['month'] - 1) // 3 + 1 != requested_period['quarter']):
continue
if ('month' not in requested_period and 'quarter' not in requested_period
and actual_period.get('year') != requested_period['year']):
continue
if selected.get('year') is not None and period.get('year') != selected['year']:
continue
if selected.get('month') is not None and period.get('month') != selected['month']:
continue
if selected.get('monthStart') is not None:
if (period.get('month') is not None
and not selected['monthStart'] <= period['month'] <= selected['monthEnd']):
continue
if period.get('month') is None and actual_period != requested_period:
continue
if selected.get('quarter') is not None:
quarter = period.get('quarter')
month = period.get('month')
if quarter is None and isinstance(month, int) and 1 <= month <= 12:
quarter = (month - 1) // 3 + 1
if quarter != selected['quarter']:
continue
granularity = context.get('trendGranularity') or selected.get('granularity')
actual = ('month' if period.get('month') is not None or period.get('monthStart') is not None
else 'quarter' if period.get('quarter') is not None else 'year')
if granularity in ('month', 'quarter', 'year') and granularity != actual:
continue
# Keep the same scope check while allowing the explicitly selected year's sub-periods.
scope_context = {k: v for k, v in context.items()
if k not in ('period', 'currentPeriod', 'comparisonPeriod', *PERIOD_KEYS)}
frame = {'current': {'period': period}, 'filterBinding': result.get('filters') or {}}
if _matches_context(frame, scope_context):
accepted.append((document, result))
return accepted
def build_visuals(evidence: list[dict[str, Any]], question: str, turn_id: str, *, context=None) -> dict[str, Any]:
"""Return up to twelve 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": "轮次标识无效,未生成图表。"}
semantic_task = _agent_task(context, question)
semantic_mode = semantic_task is not None
if semantic_mode and semantic_task["visualPreference"] == "none":
return _finalize([], safe_turn_id)
if not semantic_mode:
wants_visuals, explicit_visuals = _wants_visuals(question if isinstance(question, str) else "")
if not wants_visuals:
return _finalize([], safe_turn_id)
else:
explicit_visuals = (semantic_task["visualPreference"] == "required"
or isinstance(semantic_task.get('defectQuery'), dict)
and semantic_task.get('visualType') is not None)
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))
visual_context = _visual_context(context)
requested_visual_period = _requested_visual_period(context, semantic_task)
anchored=False
trend_evidence = _bound_trend_evidence(valid_evidence, visual_context)
if visual_context is not None:
valid_evidence,anchored=_bound_visual_evidence(valid_evidence,visual_context)
candidates: list[tuple[int, str, str | None, dict[str, Any]]] = []
if semantic_mode:
text_question = ""
semantic_type = semantic_task["visualType"]
semantic_stages = semantic_task["stages"] or None
semantic_fields = (set(semantic_task["fields"]) or None) if semantic_task['kind'] == 'metrics' else None
context_stage = visual_context.get("stage") if isinstance(visual_context, dict) else None
if semantic_task["stages"]:
comparison_stages = ([None] + semantic_task["stages"] if semantic_task['kind'] in ('analysis', 'report')
and set(semantic_task['stages']) == {'black', 'bright'} else semantic_task['stages'])
elif context_stage in ("black", "bright"):
comparison_stages = [context_stage]
else:
comparison_stages = [None, "black", "bright"]
semantic_defect = "defect" in semantic_task["dimensions"]
for document, result in valid_evidence:
kind = result.get("kind", "")
dimension = result.get("dimension") if isinstance(result.get("dimension"), str) else None
from nao_weight_ranking import ranking_chart
ranking = ranking_chart(document,safe_turn_id,semantic_task)
if ranking is not None:
candidates.append((0,kind,dimension,ranking))
for requested_stage in comparison_stages:
for chart in _comparison_charts(
document, result, safe_turn_id, text_question, requested_stage,
semantic_fields=semantic_fields, semantic_stages=semantic_stages):
candidates.append((0, kind, dimension, chart))
if context_stage not in ("black", "bright") and (semantic_fields is None or "rate" in semantic_fields):
waterfall = _comparison_waterfall(document, result, safe_turn_id, text_question,
allow_semantic=True)
if waterfall is not None:
candidates.append((0, kind, dimension, waterfall))
if semantic_defect and (semantic_fields is None or "scrapWeight" in semantic_fields):
for chart in _comparison_category_delta_charts(
document, result, safe_turn_id, text_question, allow_semantic=True,
requested_stages=semantic_task["stages"] or None):
candidates.append((0, kind, dimension, chart))
for chart in _comparison_category_charts(
document, result, safe_turn_id, text_question,
semantic_chart_type=semantic_type, semantic_stages=semantic_stages):
candidates.append((0, kind, dimension, chart))
for chart in _metrics_category_charts(
document, result, safe_turn_id, text_question,
semantic_chart_type=semantic_type, semantic_stages=semantic_stages):
candidates.append((0, kind, dimension, chart))
change = _change_chart(document, result, safe_turn_id)
if change is not None:
candidates.append((0, kind, dimension, change))
defect = _fine_defect_chart(document, result, safe_turn_id)
if defect is not None:
candidates.append((0, kind, dimension, defect))
top = _top_chart(document, result, safe_turn_id)
if top is not None:
candidates.append((0, kind, dimension, top))
if semantic_type in ("donut", "pareto"):
share_chart = _share_chart_from_top_chart(top, document, result, safe_turn_id, semantic_type)
if share_chart is not None:
candidates.append((0, kind, dimension, share_chart))
for chart in _metrics_trend_charts(
document, result, safe_turn_id, text_question,
semantic_fields=semantic_fields, semantic_stages=semantic_stages,
selected_period=requested_visual_period,
minimum_points=2 if semantic_type == 'line' else 3):
candidates.append((0, "metrics_trend", None, chart))
for chart in _multi_query_trend(
trend_evidence, safe_turn_id, text_question,
semantic_fields=semantic_fields, semantic_stages=semantic_stages):
candidates.append((0, "metrics_trend", None, chart))
else:
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
requested_stage=context.get('stage') if isinstance(context,dict) else None
for chart in _comparison_charts(document, result, safe_turn_id, text_question,requested_stage):
candidates.append((_candidate_priority(chart, kind, dimension, text_question), kind, dimension, chart))
waterfall = None if requested_stage in ('black','bright') else _comparison_waterfall(document, result, safe_turn_id, text_question)
if waterfall is not None:
candidates.append((_candidate_priority(waterfall, kind, dimension, text_question), kind, dimension, waterfall))
for chart in _comparison_category_delta_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:
# A rate-only product bar chart makes tiny runs look like the main concern.
if not (dimension == "product" and change.get("metric") == "rate_drop_pp"
and not _explicit_rate_rank_view(text_question)):
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,
selected_period=requested_visual_period):
candidates.append((_candidate_priority(chart, "metrics_trend", None, text_question), "metrics_trend", None, chart))
for chart in _multi_query_trend(trend_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))
styled_candidates: list[tuple[int, str, str | None, dict[str, Any]]] = []
for priority, kind, dimension, candidate in candidates:
if semantic_mode:
if not _semantic_chart_matches(candidate, semantic_task):
continue
chart = _semantic_type_chart(candidate, semantic_task["visualType"])
if (chart is None and semantic_task['visualPreference'] == 'auto'
and not isinstance(semantic_task.get('defectQuery'), dict)):
# A model-chosen style is a hint. Preserve the renderer's
# evidenced chart instead of inventing shares/trend axes or
# discarding valid weights when that style cannot be built.
chart = _semantic_type_chart(candidate, None)
if chart is not None:
styled_candidates.append((priority, kind, dimension, chart))
else:
requested_type = _requested_chart_type(question if isinstance(question, str) else "")
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
if semantic_mode and semantic_task["visualPreference"] == "auto" and not explicit_visuals:
if not _semantic_auto_chartable(candidates):
candidates = []
stage_order = {"black": 0, "bright": 1, None: 2}
metric_order = {"composite_rate": 0, "black_rate": 1, "bright_rate": 2,
"black_scrap_rate": 3, "bright_scrap_rate": 4,
"scrap_delta": 5, "source_defect_delta_weight": 6}
def scope_depth(chart):
scope = chart.get("scope") if isinstance(chart.get("scope"), dict) else {}
return sum(scope.get(key) not in (None, "", [], {}) for key in ("department", "group", "product", "category", "defect"))
comparisons = [chart for _, _, _, chart in candidates if chart.get("metric") == "composite_rate" and chart.get("sectionKey") == "overview"]
primary_depth = min((scope_depth(chart) for chart in comparisons), default=0)
def chapter_priority(item):
chart = item[3]
# 产品追查比较不能挤占主体分析的类别、组织和缺陷图。
extra_scope = max(0, scope_depth(chart) - primary_depth) if context is None or anchored else 0
section = chart.get("sectionKey", "")
penalty = 20 * extra_scope if section in ("overview", "stage") or section.startswith("category_") else 0
return item[0] + penalty
if semantic_mode:
candidates.sort(key=lambda item: _semantic_chart_priority(item[3], semantic_task))
else:
candidates.sort(key=lambda item: (
chapter_priority(item), tuple(-part for part in _chart_end_rank(item[3])),
stage_order.get(item[3].get("stage"), 3),
metric_order.get(item[3].get("metric"), 10),
item[3].get("sectionKey", ""), item[3].get("id", ""),
))
primary_chapters = []
additional_views = []
chapter_keys = set()
for item in candidates:
chart = item[3]
section = chart.get("sectionKey")
chapter_key = (section, chart.get("metric") if section in ("overview", "stage", "trend") else None,
chart.get("type") if section == "composition" else None,
chart.get("stage") if section == "composition" else None)
if chapter_key in chapter_keys:
additional_views.append(item)
else:
chapter_keys.add(chapter_key)
primary_chapters.append(item)
# 先覆盖各个可用章节,再分配同章不同范围的补充视图。
candidates = primary_chapters + additional_views
charts: list[dict[str, Any]] = []
selected_ids: set[str] = set()
selected_semantics: set[str] = set()
selected_share_stages: set[tuple] = 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
semantic_key = _chart_selection_key(chart)
if semantic_key in selected_semantics:
continue
share_stage = (chart.get("type"), chart.get("stage"),
chart.get('dimension') if chart.get('coverage',{}).get('shareBasis')=='all_scope_weight' else None,
chart.get('metric') if chart.get('coverage',{}).get('shareBasis')=='all_scope_weight' else None)
if chart.get("type") in ("donut", "pareto") and share_stage in selected_share_stages:
continue
charts.append(chart)
selected_ids.add(chart_id)
selected_semantics.add(semantic_key)
if chart.get("type") in ("donut", "pareto"):
selected_share_stages.add(share_stage)
if len(charts) >= MAX_VISUALS:
break
# A normal analysis can reuse prior-turn facts without issuing a fresh
# chartable query. Only an explicit chart request needs an unavailable
# notice when this turn has no chart snapshot.
return _finalize(charts, safe_turn_id, unavailable=explicit_visuals)
except Exception:
# Never surface exception text: it could contain a path or source value.
return {
"visualSchemaVersion": VISUAL_SCHEMA_VERSION,
"visualState": "failed",
"visuals": [],
"error": "图表整理遇到内部错误,已有文字分析可继续使用。",
}