Files
quality_analyse/scripts/nao_quality_tools.py
T

1339 lines
83 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.
"""Read-only, release-bound quality center tools for NAO MCP stdio.
All business values come from the local authenticated HTTP API on 127.0.0.1:5281.
This module deliberately contains no database connection and no write endpoint.
"""
from __future__ import annotations
import copy
import json
import math
import os
import re
import sys
import threading
import uuid
from datetime import datetime, timezone
from decimal import Decimal, InvalidOperation
from pathlib import Path
from typing import Any, Callable
from urllib.parse import urlencode
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / "scripts"))
from dbgpt_trial_data import encoded_selection # noqa: E402
from local_api import Api # noqa: E402
EVIDENCE_DIR = ROOT / "output" / "nao-quality" / "tools"
MAX_PAGE_SIZE = 500
MAX_CHANGE_ROWS = 100_000
MAX_TREND_ROWS = 36
SCOPES: dict[str, str | None] = {
"overall": None,
"auto_combined": encoded_selection(["汽车交通-国内", "汽车交通-海外"]),
"auto_domestic": "汽车交通-国内",
"auto_overseas": "汽车交通-海外",
}
CATEGORIES: dict[str, dict[str, tuple[str, ...]]] = {
"black": {
"责废": ("责废", "黑片责废"),
"料废": ("料废", "黑片料废"),
"外废": ("外废", "黑片外废"),
},
"bright": {
"镀废": ("镀废", "亮片镀废"),
"材料废": ("材料废", "亮片材料废"),
"加工废": ("加工废", "亮片加工废"),
"扩散废": ("扩散废", "亮片扩散废"),
},
}
TOOL_DESCRIPTION = (
"只读查询质量中心正式 HTTP API(127.0.0.1:5281),供查询、比较、正式 TOP、变化线索、具体缺陷聚合和有界明细样本。"
"先调用 catalog 获取 releaseId,再在每次 query/compare/top/changes/defects/details 调用中显式传回该 ID。"
"catalog 不传 releaseId 时读取当前正式发布版本;比较只在同一发布版本内进行。"
"category 是黑片/亮片真实报废大类;defect 才是来源字段聚合的具体缺陷;product 表示规格。"
"具体缺陷结果来自 POST /api/analysis/defects,按原始缺陷字段键分别汇总,不跨字段合并。TOP share 仅按接口返回的 shareBasis 解读;"
"亮片类别份额不必等同阶段正式报废重量,不能据此声称总体贡献。details 是最多 100 行的样本,不能用于总体排名。"
)
QUALITY_DATA_SCHEMA: dict[str, Any] = {
"type": "object",
"properties": {
"mode": {"type": "string", "enum": ["catalog", "query", "compare", "top", "changes", "defects", "details"], "description": "先用 catalog 取发布版本;之后所有数据 mode 都必传 releaseId。defects 查询具体缺陷字段聚合。"},
"releaseId": {"type": "string", "minLength": 1, "description": "正式发布版本 ID。catalog 可省略以读取调用当时的 currentRelease;query/compare/top/changes/defects/details 必须显式传入 catalog 返回的 ID。"},
"scope": {"type": "string", "enum": list(SCOPES), "description": "overall、汽车交通合计、汽车交通国内或海外预设范围。若显式传 scope,则不得同时在 filters.group 传值。"},
"period": {
"type": "object", "additionalProperties": False,
"properties": {
"year": {"type": "integer", "minimum": 2000, "maximum": 2100},
"month": {"type": "integer", "minimum": 1, "maximum": 12},
"quarter": {"type": "integer", "minimum": 1, "maximum": 4},
},
"required": ["year"],
"description": "期间;year 必填。可再选 month 或 quarter,二者不能同时传。",
},
"comparisonPeriod": {
"type": "object", "additionalProperties": False,
"properties": {
"year": {"type": "integer", "minimum": 2000, "maximum": 2100},
"month": {"type": "integer", "minimum": 1, "maximum": 12},
"quarter": {"type": "integer", "minimum": 1, "maximum": 4},
},
"required": ["year"],
"description": "compare/changes/defects 的对照期间;使用同一 releaseId 和完全相同的筛选。",
},
"filters": {
"type": "object", "additionalProperties": False,
"properties": {
"department": {"type": "string", "minLength": 1},
"group": {"type": "string", "minLength": 1},
"product": {"type": "string", "minLength": 1, "description": "产品规格筛选。"},
"projectGroup": {"type": "string", "minLength": 1},
"includeUnassigned": {"type": "boolean"},
},
"description": "实际筛选值会原样传递给正式 API;工具不会忽略未知或冲突的筛选。",
},
"view": {"type": "string", "enum": ["overall", "department", "group", "product", "projectGroup"], "description": "query 的正式分组视图;changes 仅支持非 overall 维度。"},
"stage": {"type": "string", "enum": ["black", "bright"], "description": "TOP/details/defects 阶段;category 解读所用阶段。"},
"dimension": {"type": "string", "enum": ["category", "defect", "product", "department", "group", "projectGroup"], "description": "正式 TOP 维度;defect 是来源字段中的具体缺陷,product 是规格。changes 使用 product/department/group/projectGroup。defects 使用 defect 或 product。"},
"defect": {"type": "string", "minLength": 1, "description": "catalog 返回的具体缺陷源字段 key(不是显示名称);defects.dimension=product 时必填,用于按该字段排名规格。dimension=defect 可省略以查看具体缺陷聚合,也可指定 key 筛选。"},
"category": {
"type": "string",
"enum": ["责废", "料废", "外废", "镀废", "材料废", "加工废", "扩散废", "黑片责废", "黑片料废", "黑片外废", "亮片镀废", "亮片材料废", "亮片加工废", "亮片扩散废"],
"description": "真实报废大类筛选。黑片:责废/料废/外废;亮片:镀废/材料废/加工废/扩散废。不是具体缺陷;具体缺陷请用 defect。",
},
"limit": {"type": "integer", "minimum": 1, "maximum": 100, "description": "结果行数上限;details 最多 100 条样本;defects 每次最多请求 100 行。"},
"sort": {"type": "string", "enum": ["scrap_delta", "current_scrap", "rate_drop"], "description": "changes 排序:报废增量、当前报废重量、率下降线索;defects 支持 current_scrap 或 scrap_delta,默认单期按当前重量、带对照期按增量排序。"},
},
"required": ["mode"],
"allOf": [{
"if": {"properties": {"mode": {"not": {"const": "catalog"}}}, "required": ["mode"]},
"then": {"required": ["releaseId"]},
}],
"additionalProperties": False,
}
class QualityToolError(ValueError):
"""Safe, actionable error suitable for a model-facing tool response."""
def _json_safe(value: Any) -> Any:
if isinstance(value, Decimal):
return float(value)
if isinstance(value, dict):
return {str(key): _json_safe(item) for key, item in value.items()}
if isinstance(value, (list, tuple)):
return [_json_safe(item) for item in value]
if isinstance(value, float) and not math.isfinite(value):
return None
return value
def _number(value: Any, *, minimum: Decimal | None = None, maximum: Decimal | None = None) -> Decimal | None:
if value is None or isinstance(value, bool):
return None
try:
number = Decimal(str(value))
except (InvalidOperation, ValueError, TypeError):
return None
if not number.is_finite():
return None
if minimum is not None and number < minimum:
return None
if maximum is not None and number > maximum:
return None
return number
def _stage_summary(summary: dict[str, Any], stage: str) -> dict[str, Any]:
value = summary.get(stage)
return value if isinstance(value, dict) else {}
def _coverage_counts(snapshot: dict[str, Any]) -> tuple[int, int, int]:
coverage = snapshot.get("coverage") or {}
raw = _number(coverage.get("rawRows"))
included = _number(coverage.get("includedRows"))
months = coverage.get("sourceMonths") or []
black_rows = sum(int(_number(item.get("blackRows")) or 0) for item in months if isinstance(item, dict))
bright_rows = sum(int(_number(item.get("brightRows")) or 0) for item in months if isinstance(item, dict))
return int(raw or 0), int(included or 0), min(black_rows, bright_rows)
def _valid_period_coverage(snapshot: dict[str, Any], period: dict[str, int]) -> tuple[bool, str | None]:
black_ok, black_reason = _valid_stage_rate_coverage(snapshot, period, "black")
bright_ok, bright_reason = _valid_stage_rate_coverage(snapshot, period, "bright")
if not black_ok:
return False, black_reason
if not bright_ok:
return False, bright_reason
return True, None
def _valid_stage_rate_coverage(snapshot: dict[str, Any], period: dict[str, int], stage: str) -> tuple[bool, str | None]:
coverage_ok, reason = _valid_stage_period_coverage(snapshot, period, stage)
if not coverage_ok:
return False, reason
rate = _stage_metric(snapshot, stage, "rate")
total_weight = _stage_metric(snapshot, stage, "totalWeight")
qualified_weight = _stage_metric(snapshot, stage, "qualifiedWeight")
if rate is None or rate < 0 or rate > 1:
return False, f"{stage}阶段率缺失或不在0到1范围内,不能比较。"
if total_weight is None or total_weight <= 0:
return False, f"{stage}阶段总投入缺失或为0,不能比较率。"
if qualified_weight is None or qualified_weight < 0:
return False, f"{stage}阶段合格重量缺失或不合法,不能比较率。"
return True, None
def _valid_stage_period_coverage(snapshot: dict[str, Any], period: dict[str, int], stage: str) -> tuple[bool, str | None]:
coverage = snapshot.get("coverage") or {}
if not isinstance(coverage, dict):
return False, "接口未返回覆盖信息"
months = coverage.get("sourceMonths")
if not isinstance(months, list):
return False, "接口未返回分阶段月份覆盖"
if period.get("month") is not None:
expected = [period["month"]]
elif period.get("quarter") is not None:
first = (period["quarter"] - 1) * 3 + 1
expected = [first, first + 1, first + 2]
else:
expected = list(range(1, 13))
observed: dict[int, dict[str, int]] = {}
for item in months:
if not isinstance(item, dict) or item.get("year") != period["year"]:
continue
month_number = item.get("month")
if isinstance(month_number, int):
observed[month_number] = item
field = "blackRows" if stage == "black" else "brightRows"
missing = [m for m in expected if m not in observed or int(observed[m].get(field) or 0) <= 0]
if missing:
stage_name = "黑片" if stage == "black" else "亮片"
return False, f"所选期间存在缺失的{stage_name}来源月份:" + ",".join(f"{period['year']}-{m:02d}" for m in missing)
return True, None
def _stage_metric(snapshot: dict[str, Any], stage: str, field: str, category: str | None = None) -> Decimal | None:
summary = snapshot.get("summary")
if not isinstance(summary, dict):
return None
if category is None:
return _number(_stage_summary(summary, stage).get(field))
defects = _stage_summary(summary, stage).get("defects")
if not isinstance(defects, list):
return None
for defect in defects:
if isinstance(defect, dict) and defect.get("name") == category:
return _number(defect.get("weight"))
return None
def symmetric_stage_decomposition(
black_current: Any,
bright_current: Any,
black_comparison: Any,
bright_comparison: Any,
composite_delta: Any,
*,
black_current_total_weight: Any,
bright_current_total_weight: Any,
black_comparison_total_weight: Any,
bright_comparison_total_weight: Any,
) -> dict[str, Any]:
"""Return symmetric black/bright rate contributions in percentage points."""
values = [
_number(black_current, minimum=Decimal(0), maximum=Decimal(1)),
_number(bright_current, minimum=Decimal(0), maximum=Decimal(1)),
_number(black_comparison, minimum=Decimal(0), maximum=Decimal(1)),
_number(bright_comparison, minimum=Decimal(0), maximum=Decimal(1)),
_number(composite_delta),
]
if any(value is None for value in values):
return {"status": "unavailable", "reason": "阶段率缺失或超出 0 到 1 的合法范围,不能拆解。", "blackPP": None, "brightPP": None, "sumPP": None}
denominators = [
_number(black_current_total_weight, minimum=Decimal(0)),
_number(bright_current_total_weight, minimum=Decimal(0)),
_number(black_comparison_total_weight, minimum=Decimal(0)),
_number(bright_comparison_total_weight, minimum=Decimal(0)),
]
if any(value is None or value <= 0 for value in denominators):
return {"status": "unavailable", "reason": "至少一期的阶段总投入缺失或为 0,不能进行率拆解。", "blackPP": None, "brightPP": None, "sumPP": None}
black_now, bright_now, black_old, bright_old, official_delta = values # type: ignore[misc]
black_pp = (black_now - black_old) * (bright_now + bright_old) / Decimal(2) * Decimal(100)
bright_pp = (bright_now - bright_old) * (black_now + black_old) / Decimal(2) * Decimal(100)
total_pp = (black_pp + bright_pp)
official_pp = official_delta * Decimal(100)
if abs(total_pp - official_pp) > Decimal("0.0000001"):
return {
"status": "unavailable",
"reason": "阶段乘积拆解与正式综合率差不一致;可能存在其他正式计算规则,因此不归因到阶段。",
"blackPP": None, "brightPP": None, "sumPP": None,
}
return {
"status": "available",
"method": "black_delta*(bright_current+bright_comparison)/2; bright_delta*(black_current+black_comparison)/2",
"blackPP": black_pp,
"brightPP": bright_pp,
"sumPP": total_pp,
}
def _normalize_category(stage: str, category: str | None) -> str | None:
if category is None:
return None
if stage not in CATEGORIES:
raise QualityToolError("category 需要 stage=black 或 bright。")
for canonical, aliases in CATEGORIES[stage].items():
if category in aliases:
return canonical
choices = "、".join(CATEGORIES[stage])
raise QualityToolError(f"category 与 {stage} 阶段不匹配;可用分类:{choices}。")
def normalize_period(raw: Any, name: str = "period", *, required: bool = True) -> dict[str, int] | None:
if raw is None:
if required:
raise QualityToolError(f"缺少 {name};请提供 year,并可选 month 或 quarter。")
return None
if not isinstance(raw, dict):
raise QualityToolError(f"{name} 必须是对象。")
unknown = set(raw) - {"year", "month", "quarter"}
if unknown:
raise QualityToolError(f"{name} 含不支持字段:{', '.join(sorted(unknown))}。")
if "year" not in raw or isinstance(raw["year"], bool) or not isinstance(raw["year"], int) or not 2000 <= raw["year"] <= 2100:
raise QualityToolError(f"{name}.year 必须是 2000 到 2100 的整数。")
if "month" in raw and "quarter" in raw:
raise QualityToolError(f"{name} 不能同时指定 month 和 quarter。")
result = {"year": raw["year"]}
if "month" in raw:
value = raw["month"]
if isinstance(value, bool) or not isinstance(value, int) or not 1 <= value <= 12:
raise QualityToolError(f"{name}.month 必须是 1 到 12 的整数。")
result["month"] = value
if "quarter" in raw:
value = raw["quarter"]
if isinstance(value, bool) or not isinstance(value, int) or not 1 <= value <= 4:
raise QualityToolError(f"{name}.quarter 必须是 1 到 4 的整数。")
result["quarter"] = value
return result
def normalize_filters(scope: Any, raw: Any, *, scope_was_explicit: bool) -> tuple[dict[str, Any], str]:
if scope is None:
scope = "overall"
if not isinstance(scope, str) or scope not in SCOPES:
raise QualityToolError("scope 只能是 overall、auto_combined、auto_domestic 或 auto_overseas。")
if raw is None:
raw = {}
if not isinstance(raw, dict):
raise QualityToolError("filters 必须是对象。")
allowed = {"department", "group", "product", "projectGroup", "includeUnassigned"}
unknown = set(raw) - allowed
if unknown:
raise QualityToolError(f"filters 含不支持字段:{', '.join(sorted(unknown))}。")
explicit_group = raw.get("group")
if scope_was_explicit and explicit_group not in (None, ""):
raise QualityToolError("显式 scope 与 filters.group 不能同时指定;请选一个范围来源。")
result: dict[str, Any] = {}
for field in ("department", "group", "product", "projectGroup"):
value = raw.get(field)
if value is None or value == "":
continue
if not isinstance(value, str):
raise QualityToolError(f"filters.{field} 必须是字符串。")
value = value.strip()
if not value:
continue
result[field] = value
include = raw.get("includeUnassigned", False)
if not isinstance(include, bool):
raise QualityToolError("filters.includeUnassigned 必须是布尔值。")
result["includeUnassigned"] = include
scope_group = SCOPES[scope]
if scope_group is not None:
result["group"] = scope_group
return result, scope
class QualityTools:
"""Application logic behind the single `quality_data` MCP tool."""
def __init__(
self,
api_factory: Callable[[], Any] | None = None,
evidence_dir: str | Path = EVIDENCE_DIR,
) -> None:
self._api_factory = api_factory or Api
self._evidence_dir = Path(evidence_dir)
self._api: Any | None = None
self._metrics_cache: dict[str, dict[str, Any]] = {}
self._calls: list[dict[str, Any]] = []
self._lock = threading.RLock()
def _client(self) -> Any:
if self._api is None:
self._api = self._api_factory().login()
return self._api
def _call(self, method: str, path: str, params: dict[str, Any] | None = None,
payload: dict[str, Any] | None = None) -> dict[str, Any]:
params = {key: value for key, value in (params or {}).items() if value is not None}
encoded = urlencode(params)
request_path = path + ("?" + encoded if encoded else "")
result = self._client().call(request_path, payload, method=method)
if not isinstance(result, dict):
raise QualityToolError(f"正式接口 {path} 返回了无法识别的结构;请稍后重试或检查服务版本。")
self._calls.append({"method": method, "path": path, "params": _json_safe(params) if params else {},
"body": _json_safe(payload) if payload is not None else None})
return result
def _access_catalog(self) -> dict[str, Any]:
result = self._call("GET", "/api/analysis/tools/catalog")
if result.get("kind") != "analysis_catalog":
raise QualityToolError("正式权限目录响应不完整,未执行数据查询。请检查当前用户的质量分析权限。")
return result
def _release_index(self) -> dict[str, Any]:
result = self._call("GET", "/api/releases")
items = result.get("items")
if not isinstance(items, list):
raise QualityToolError("正式发布版本接口未返回版本目录;请检查质量中心服务。")
return result
@staticmethod
def _release_item(index: dict[str, Any], release_id: str) -> dict[str, Any]:
items = index.get("items") or []
for item in items:
if isinstance(item, dict) and item.get("id") == release_id:
if item.get("status") not in {"PUBLISHED", "ACTIVE"}:
raise QualityToolError(f"releaseId={release_id} 不是已发布版本;请从 catalog 选择已发布版本。")
return {"id": item.get("id"), "name": item.get("name"), "status": item.get("status")}
raise QualityToolError(f"releaseId={release_id} 不在正式发布目录中;请重新调用 catalog 获取有效版本。")
def _bind_release(self, requested: Any, mode: str) -> dict[str, Any]:
if requested is not None and (not isinstance(requested, str) or not requested.strip()):
raise QualityToolError("releaseId 必须是非空字符串。")
requested = requested.strip() if isinstance(requested, str) else None
if requested is None and mode != "catalog":
raise QualityToolError("请先调用 mode=catalog 获取 releaseId,并在本次及后续数据查询中显式传回该 ID。工具进程可能被多个聊天共用。")
index = self._release_index()
release_id = requested or index.get("currentReleaseId")
if not isinstance(release_id, str) or not release_id:
raise QualityToolError("质量中心当前没有已发布版本,无法查询。请先发布数据版本后重试。")
return self._release_item(index, release_id)
@staticmethod
def _validate_source_snapshot(response: dict[str, Any], release_id: str, period: dict[str, int],
filters: dict[str, Any], view: str) -> None:
release = response.get("release")
if not isinstance(release, dict) or release.get("id") != release_id:
observed = release.get("id") if isinstance(release, dict) else None
raise QualityToolError(f"正式指标接口版本绑定不一致(期望 {release_id},返回 {observed});结果已拒绝。")
context = response.get("context")
if not isinstance(context, dict):
raise QualityToolError("正式指标接口未返回 context;无法确认期间和筛选是否生效。")
for key in ("year", "month", "quarter"):
expected = period.get(key)
if context.get(key) != expected:
raise QualityToolError(f"正式指标接口未确认 {key} 筛选(期望 {expected},返回 {context.get(key)});结果已拒绝。")
for key in ("department", "group", "product", "projectGroup"):
expected = filters.get(key)
if context.get(key) != expected:
raise QualityToolError(f"正式指标接口未确认 filters.{key}(期望值与返回值不一致);结果已拒绝。")
if context.get("view") != view:
raise QualityToolError(f"正式指标接口未确认 view={view};结果已拒绝。")
if context.get("includeUnassigned") != filters.get("includeUnassigned", False):
raise QualityToolError("正式指标接口未确认 includeUnassigned;结果已拒绝。")
if not isinstance(response.get("summary"), dict) or not isinstance(response.get("coverage"), dict):
raise QualityToolError("正式指标接口缺少 summary 或 coverage,不能返回空数据成功。")
raw_rows, included_rows, _ = _coverage_counts(response)
if raw_rows <= 0 or included_rows <= 0:
raise QualityToolError("所选期间和筛选在该正式版本中没有可用覆盖数据;请检查 period、scope 和 filters。")
def _metrics(self, release_id: str, period: dict[str, int], filters: dict[str, Any], view: str,
*, row_limit: int | None = None, row_offset: int = 0) -> dict[str, Any]:
params: dict[str, Any] = {"releaseId": release_id, **period, "view": view,
"includeUnassigned": filters.get("includeUnassigned", False),
"trendGranularity": "month"}
for key in ("department", "group", "product", "projectGroup"):
if key in filters:
params[key] = filters[key]
if row_limit is not None:
params["rowLimit"] = row_limit
params["rowOffset"] = row_offset
if view != "overall":
params["rowOrder"] = "scrapDesc"
cache_key = json.dumps(params, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
if cache_key in self._metrics_cache:
response = copy.deepcopy(self._metrics_cache[cache_key])
# Cache hits only occur inside one tool invocation, after the same session
# already fetched this exact request through the formal metrics endpoint.
self._calls.append({"method": "GET", "path": "/api/metrics", "params": params,
"cache": "same-invocation release+filters"})
return response
response = self._call("GET", "/api/metrics", params)
self._validate_source_snapshot(response, release_id, period, filters, view)
self._metrics_cache[cache_key] = copy.deepcopy(response)
return response
@staticmethod
def _compact_stage(value: Any) -> dict[str, Any] | None:
if not isinstance(value, dict):
return None
fields = ("rate", "qualifiedWeight", "scrapWeight", "totalWeight", "headquartersScrapWeight",
"rateWithoutHeadquartersScrap", "defects")
return {key: _json_safe(value.get(key)) for key in fields if key in value}
@classmethod
def _compact_metric_row(cls, row: Any) -> dict[str, Any] | None:
if not isinstance(row, dict):
return None
return {
"key": row.get("key"), "label": row.get("label"), "department": row.get("department"),
"group": row.get("group"), "product": row.get("product"), "projectGroup": row.get("projectGroup"),
"compositeRate": _json_safe(row.get("compositeRate")),
"black": cls._compact_stage(row.get("black")), "bright": cls._compact_stage(row.get("bright")),
"coverage": _json_safe(row.get("coverage")),
}
def _query(self, release: dict[str, Any], period: dict[str, int], filters: dict[str, Any], view: str,
limit: int) -> dict[str, Any]:
response = self._metrics(release["id"], period, filters, view, row_limit=limit)
summary = self._compact_metric_row(response.get("summary"))
if summary is None:
raise QualityToolError("正式指标接口未返回 summary;请检查权限和期间。")
context = response["context"]
rows = response.get("rows") or []
trend = response.get("trend") or []
count = min(len(trend), MAX_TREND_ROWS)
compact_trend = [self._compact_metric_row(item) | {"period": item.get("period"), "periodLabel": item.get("periodLabel")}
for item in trend[:count] if isinstance(item, dict)]
return {
"kind": "quality_metrics", "release": release, "releaseId": release["id"],
"period": period, "filters": filters, "view": view,
"summary": summary,
"rows": [row for row in (self._compact_metric_row(item) for item in rows) if row is not None],
"rowCount": context.get("rowCount", len(rows)), "rowsReturned": len(rows),
"rowsTruncated": bool(context.get("rowCount", len(rows)) > len(rows)),
"trend": compact_trend, "trendCount": len(trend), "trendTruncated": len(trend) > count,
"coverage": _json_safe(response.get("coverage")),
"basis": "rate 和重量来自正式 MetricsController;本工具只做有界裁剪,不重算正式 KPI。",
}
@staticmethod
def _metric_difference(current: dict[str, Any], comparison: dict[str, Any]) -> dict[str, Any]:
current_ok, current_reason = _valid_period_coverage(current, current["_period"])
comparison_ok, comparison_reason = _valid_period_coverage(comparison, comparison["_period"])
valid = current_ok and comparison_ok
now = _number((current.get("summary") or {}).get("compositeRate"), minimum=Decimal(0), maximum=Decimal(1))
old = _number((comparison.get("summary") or {}).get("compositeRate"), minimum=Decimal(0), maximum=Decimal(1))
if not valid or now is None or old is None:
return {"available": False, "rate": None, "percentagePoints": None,
"reason": current_reason if not current_ok else comparison_reason if not comparison_ok else "正式综合率缺失或不合法。"}
return {"available": True, "rate": now - old, "percentagePoints": (now - old) * Decimal(100), "reason": None}
def _compare(self, release: dict[str, Any], current_period: dict[str, int], comparison_period: dict[str, int],
filters: dict[str, Any], category_stage: str | None, category: str | None) -> dict[str, Any]:
current_raw = self._metrics(release["id"], current_period, filters, "overall")
comparison_raw = self._metrics(release["id"], comparison_period, filters, "overall")
current = {**current_raw, "_period": current_period}
comparison = {**comparison_raw, "_period": comparison_period}
delta = self._metric_difference(current, comparison)
contribution: dict[str, Any]
if not delta["available"]:
contribution = {"status": "unavailable", "reason": delta["reason"], "blackPP": None, "brightPP": None, "sumPP": None}
else:
contribution = symmetric_stage_decomposition(
_stage_metric(current_raw, "black", "rate"), _stage_metric(current_raw, "bright", "rate"),
_stage_metric(comparison_raw, "black", "rate"), _stage_metric(comparison_raw, "bright", "rate"),
delta["rate"],
black_current_total_weight=_stage_metric(current_raw, "black", "totalWeight"),
bright_current_total_weight=_stage_metric(current_raw, "bright", "totalWeight"),
black_comparison_total_weight=_stage_metric(comparison_raw, "black", "totalWeight"),
bright_comparison_total_weight=_stage_metric(comparison_raw, "bright", "totalWeight"),
)
result = {
"kind": "quality_comparison", "release": release, "releaseId": release["id"],
"current": self._comparison_side(current_raw, current_period),
"comparison": self._comparison_side(comparison_raw, comparison_period),
"delta": delta, "stageDecomposition": contribution,
"coverage": {"current": _json_safe(current_raw.get("coverage")), "comparison": _json_safe(comparison_raw.get("coverage"))},
"filterBinding": filters,
"basis": "正式率直接取自同一 releaseId 的 MetricsController;阶段分解仅在完整覆盖且与正式综合率差一致时提供。",
}
# Use explicit names so the model cannot mistake composite contributions
# for each stage's own rate change.
result["stageDecomposition"] = {
**{key: value for key, value in contribution.items() if key not in ("blackPP", "brightPP")},
"blackContributionToCompositePP": contribution.get("blackPP"),
"brightContributionToCompositePP": contribution.get("brightPP"),
"meaning": "对综合合格率变化的数学拆解,不是黑片/亮片本身的率变化,也不是生产根因。",
}
result["stageRateChangesPP"] = {
stage: ((_stage_metric(current_raw, stage, "rate") - _stage_metric(comparison_raw, stage, "rate")) * Decimal(100)
if _valid_stage_rate_coverage(current_raw, current_period, stage)[0]
and _valid_stage_rate_coverage(comparison_raw, comparison_period, stage)[0]
and _stage_metric(current_raw, stage, "rate") is not None
and _stage_metric(comparison_raw, stage, "rate") is not None else None)
for stage in ("black", "bright")
}
if category is not None and category_stage is not None:
current_weight = _stage_metric(current_raw, category_stage, "scrapWeight", category)
comparison_weight = _stage_metric(comparison_raw, category_stage, "scrapWeight", category)
current_category_coverage, _ = _valid_stage_period_coverage(current_raw, current_period, category_stage)
comparison_category_coverage, _ = _valid_stage_period_coverage(comparison_raw, comparison_period, category_stage)
category_comparable = current_category_coverage and comparison_category_coverage
result["category"] = {
"stage": category_stage, "name": category, "meaning": "正式报废大类,不是具体缺陷",
"currentWeight": current_weight, "comparisonWeight": comparison_weight,
"deltaWeight": current_weight - comparison_weight if category_comparable and current_weight is not None and comparison_weight is not None else None,
"deltaAvailable": category_comparable and current_weight is not None and comparison_weight is not None,
}
return result
@classmethod
def _comparison_side(cls, response: dict[str, Any], period: dict[str, int]) -> dict[str, Any]:
summary = cls._compact_metric_row(response.get("summary")) or {}
return {"period": period, "compositeRate": summary.get("compositeRate"),
"black": summary.get("black"), "bright": summary.get("bright"),
"coverage": _json_safe(response.get("coverage"))}
def _top(self, release: dict[str, Any], period: dict[str, int], filters: dict[str, Any], stage: str,
dimension: str, category: str | None, limit: int) -> dict[str, Any]:
api_category = _normalize_category(stage, category)
params: dict[str, Any] = {"releaseId": release["id"], "stage": stage, "dimension": dimension,
"includeUnassigned": filters.get("includeUnassigned", False), "limit": limit,
**period}
if api_category is not None:
params["category"] = api_category
for key in ("department", "group", "product", "projectGroup"):
if key in filters:
params[key] = filters[key]
response = self._call("GET", "/api/analytics/top", params)
if response.get("releaseId") != release["id"]:
raise QualityToolError("正式 TOP 接口返回的 releaseId 与请求不一致;结果已拒绝。")
if response.get("stage") != stage or response.get("dimension") != dimension:
raise QualityToolError("正式 TOP 接口没有确认 stage/dimension;结果已拒绝。")
query = response.get("resultQuery")
if not isinstance(query, dict) or query.get("releaseId") != release["id"]:
raise QualityToolError("正式 TOP 接口未返回可核验的筛选回显;结果已拒绝。")
for key, expected in {**period, **filters, "stage": stage, "dimension": dimension,
"category": api_category}.items():
if key == "includeUnassigned":
continue
if query.get(key) != expected:
raise QualityToolError(f"正式 TOP 接口未确认 {key} 筛选;结果已拒绝。")
if query.get("includeUnassigned") != filters.get("includeUnassigned", False):
raise QualityToolError("正式 TOP 接口未确认 includeUnassigned;结果已拒绝。")
raw_rows = response.get("rows")
if not isinstance(raw_rows, list):
raise QualityToolError("正式 TOP 接口未返回 rows;请检查期间、筛选和权限。")
raw_coverage = response.get("coverage") or {}
if int(_number(raw_coverage.get("rawRows")) or 0) <= 0 or not raw_rows:
raise QualityToolError("正式 TOP 接口在当前期间和筛选下没有可用排名数据;请检查期间、筛选和授权。")
return {
"kind": "quality_top", "release": release, "releaseId": release["id"], "period": period,
"filters": filters, "stage": stage, "dimension": dimension, "category": api_category,
"rows": [{key: _json_safe(row.get(key)) for key in ("rank", "key", "label", "sourceCategory", "weight", "denominator", "share", "coverage")}
for row in raw_rows if isinstance(row, dict)],
"denominator": _json_safe(response.get("denominator")), "shareBasis": response.get("shareBasis"),
"coverage": _json_safe(response.get("coverage")), "rankingCoverage": _json_safe(response.get("rankingCoverage")),
"cumulativeThresholdApplied": response.get("cumulativeThresholdApplied"),
"notice": response.get("notice"), "resultId": response.get("resultId"),
"meaning": "category 是真实报废大类,不是具体缺陷;share 只按 shareBasis 表述,亮片类别份额不必等同阶段正式报废重量,也不代表总体贡献。",
}
@staticmethod
def _index_rows(response: dict[str, Any], dimension: str, side_name: str) -> dict[str, dict[str, Any]]:
rows = response.get("rows")
if not isinstance(rows, list):
raise QualityToolError(f"{side_name}正式 rows 不是列表,无法做全量配对。")
if len(rows) > MAX_CHANGE_ROWS:
raise QualityToolError(f"{side_name}分组行超过安全上限 {MAX_CHANGE_ROWS};请收窄筛选。")
index: dict[str, dict[str, Any]] = {}
for row in rows:
if not isinstance(row, dict):
raise QualityToolError(f"{side_name}rows 含无效记录,无法配对。")
key = row.get("key")
if key is None or str(key) == "":
raise QualityToolError(f"{side_name}正式 rows 存在空 key,不能可靠做全外连接。")
key = str(key)
if key in index:
raise QualityToolError(f"{side_name}正式 rows 存在重复 key={key!r},不能可靠做全外连接。")
index[key] = row
return index
@classmethod
def _row_scrap(cls, row: dict[str, Any] | None, stage: str | None, category: str | None) -> Decimal | None:
if row is None:
return Decimal(0) # The key is known to be absent on this side of the complete outer join.
if stage and category:
return _stage_metric({"summary": {stage: row.get(stage)}}, stage, "scrapWeight", category)
black = _number(((row.get("black") or {}).get("scrapWeight"))) if isinstance(row.get("black"), dict) else None
bright = _number(((row.get("bright") or {}).get("scrapWeight"))) if isinstance(row.get("bright"), dict) else None
if black is None or bright is None:
return None
return black + bright
@classmethod
def _row_rate(cls, row: dict[str, Any] | None, stage: str | None) -> Decimal | None:
if row is None:
return None
coverage = row.get("coverage")
if not isinstance(coverage, dict):
return None
required_stages = (stage,) if stage else ("black", "bright")
for required in required_stages:
field = f"{required}Rows"
if (_number(coverage.get(field), minimum=Decimal(1)) is None):
return None
block = row.get(required)
if not isinstance(block, dict):
return None
total_weight = _number(block.get("totalWeight"), minimum=Decimal(0))
if total_weight is None or total_weight <= 0:
return None
if _number(block.get("qualifiedWeight"), minimum=Decimal(0)) is None:
return None
if _number(block.get("rate"), minimum=Decimal(0), maximum=Decimal(1)) is None:
return None
if stage:
value = (row.get(stage) or {}).get("rate") if isinstance(row.get(stage), dict) else None
else:
value = row.get("compositeRate")
return _number(value, minimum=Decimal(0), maximum=Decimal(1))
@classmethod
def _row_weight(cls, row: dict[str, Any] | None, field: str, stage: str | None) -> Decimal | None:
if row is None:
return Decimal(0)
stages = (stage,) if stage else ("black", "bright")
values: list[Decimal] = []
for selected in stages:
block = row.get(selected)
if not isinstance(block, dict):
return None
value = _number(block.get(field), minimum=Decimal(0))
if value is None:
return None
values.append(value)
return sum(values, Decimal(0))
@staticmethod
def _row_category_weight(row: dict[str, Any] | None, stage: str | None, category: str | None) -> Decimal | None:
if category is None or stage is None:
return None
if row is None:
return Decimal(0)
return _stage_metric({"summary": {stage: row.get(stage)}}, stage, "scrapWeight", category)
def _full_rows(self, release: dict[str, Any], period: dict[str, int], filters: dict[str, Any],
dimension: str) -> dict[str, Any]:
all_rows: list[dict[str, Any]] = []
offset = 0
total: int | None = None
while True:
page = self._metrics(release["id"], period, filters, dimension,
row_limit=MAX_PAGE_SIZE, row_offset=offset)
context = page.get("context") or {}
reported_total = context.get("rowCount")
if isinstance(reported_total, bool) or not isinstance(reported_total, int) or reported_total < 0:
raise QualityToolError("正式分页接口未返回可靠 rowCount;不能声称变化清单完整。")
if total is None:
total = reported_total
elif total != reported_total:
raise QualityToolError("分页期间 rowCount 发生变化;本次变化清单已拒绝,请重试同一 releaseId。")
page_rows = page.get("rows")
if not isinstance(page_rows, list):
raise QualityToolError("正式分页接口未返回 rows;不能声称变化清单完整。")
if len(page_rows) > MAX_PAGE_SIZE or (total > offset and len(page_rows) == 0):
raise QualityToolError("正式分页接口返回不完整页;不能声称变化清单完整。")
all_rows.extend(page_rows)
offset += len(page_rows)
if offset >= total:
break
if len(page_rows) < MAX_PAGE_SIZE:
raise QualityToolError("正式分页在 rowCount 前结束;不能声称变化清单完整。")
if offset > MAX_CHANGE_ROWS:
raise QualityToolError(f"分组行超过安全上限 {MAX_CHANGE_ROWS};请收窄筛选。")
if len(all_rows) != total:
raise QualityToolError("正式分页总行数对账失败;不能声称变化清单完整。")
merged = copy.deepcopy(page)
merged["rows"] = all_rows
return merged
def _changes(self, release: dict[str, Any], current_period: dict[str, int], comparison_period: dict[str, int],
filters: dict[str, Any], dimension: str, stage: str | None, category: str | None,
sort: str, limit: int) -> dict[str, Any]:
if category is not None:
if stage is None:
raise QualityToolError("changes.category 需要同时指定 stage=black 或 bright。")
category = _normalize_category(stage, category)
current_raw = self._full_rows(release, current_period, filters, dimension)
comparison_raw = self._full_rows(release, comparison_period, filters, dimension)
current_index = self._index_rows(current_raw, dimension, "current")
comparison_index = self._index_rows(comparison_raw, dimension, "comparison")
if stage is None:
current_coverage_ok, current_coverage_reason = _valid_period_coverage(current_raw, current_period)
comparison_coverage_ok, comparison_coverage_reason = _valid_period_coverage(comparison_raw, comparison_period)
else:
current_coverage_ok, current_coverage_reason = _valid_stage_rate_coverage(current_raw, current_period, stage)
comparison_coverage_ok, comparison_coverage_reason = _valid_stage_rate_coverage(comparison_raw, comparison_period, stage)
rates_comparable = current_coverage_ok and comparison_coverage_ok
keys = set(current_index) | set(comparison_index)
records: list[dict[str, Any]] = []
for key in keys:
now_row, old_row = current_index.get(key), comparison_index.get(key)
now_scrap = self._row_weight(now_row, "scrapWeight", stage)
old_scrap = self._row_weight(old_row, "scrapWeight", stage)
total_scrap_delta = now_scrap - old_scrap if now_scrap is not None and old_scrap is not None else None
now_category_scrap = self._row_category_weight(now_row, stage, category)
old_category_scrap = self._row_category_weight(old_row, stage, category)
category_delta = now_category_scrap - old_category_scrap if now_category_scrap is not None and old_category_scrap is not None else None
scrap_delta = category_delta if category is not None else total_scrap_delta
now_total = self._row_weight(now_row, "totalWeight", stage)
old_total = self._row_weight(old_row, "totalWeight", stage)
now_qualified = self._row_weight(now_row, "qualifiedWeight", stage)
old_qualified = self._row_weight(old_row, "qualifiedWeight", stage)
now_rate = self._row_rate(now_row, stage)
old_rate = self._row_rate(old_row, stage)
rate_drop = old_rate - now_rate if rates_comparable and now_rate is not None and old_rate is not None else None
source = now_row or old_row or {}
volume_note = None
if stage is None:
volume_note = "未指定 stage:重量字段是 black+bright 两阶段求和,仅作分组描述,不等于独立投入或分母;投入分析请分阶段查看。"
if old_row is None:
volume_note = (volume_note + " " if volume_note else "") + "新进分组;不存在期报废按 0 仅用于重量增量描述,率保持 null。"
elif now_row is None:
volume_note = (volume_note + " " if volume_note else "") + "退出分组;不存在期报废按 0 仅用于重量增量描述,率保持 null。"
records.append({
"key": key, "label": source.get("label"), "dimension": dimension,
"present": {"current": now_row is not None, "comparison": old_row is not None},
"changeType": "new" if old_row is None else "exit" if now_row is None else "continuing",
"current": {"totalWeight": now_total, "qualifiedWeight": now_qualified, "scrapWeight": now_scrap,
"categoryScrapWeight": now_category_scrap, "rate": now_rate},
"comparison": {"totalWeight": old_total, "qualifiedWeight": old_qualified, "scrapWeight": old_scrap,
"categoryScrapWeight": old_category_scrap, "rate": old_rate},
"totalWeightDelta": now_total - old_total if now_total is not None and old_total is not None else None,
"qualifiedWeightDelta": now_qualified - old_qualified if now_qualified is not None and old_qualified is not None else None,
"totalScrapDelta": total_scrap_delta, "categoryScrapDelta": category_delta,
"scrapDelta": scrap_delta, "rateDrop": rate_drop,
"volumeNote": volume_note,
})
if stage is None:
for side in ("current", "comparison"):
record_side = records[-1][side]
record_side.pop("totalWeight")
record_side.pop("qualifiedWeight")
raw_side = now_row if side == "current" else old_row
record_side["blackInputWeight"] = self._row_weight(raw_side, "totalWeight", "black")
record_side["brightInputWeight"] = self._row_weight(raw_side, "totalWeight", "bright")
records[-1].pop("totalWeightDelta")
records[-1].pop("qualifiedWeightDelta")
def sortable(value: Any) -> Decimal:
return value if isinstance(value, Decimal) else Decimal("-Infinity")
if sort == "scrap_delta":
records.sort(key=lambda row: (sortable(row["scrapDelta"]), str(row["key"])), reverse=True)
elif sort == "current_scrap":
current_sort_weight = "categoryScrapWeight" if category is not None else "scrapWeight"
records.sort(key=lambda row: (sortable(row["current"][current_sort_weight]), str(row["key"])), reverse=True)
else:
records.sort(key=lambda row: (sortable(row["rateDrop"]), str(row["key"])), reverse=True)
for rank, record in enumerate(records, 1):
record["rank"] = rank
current_coverage = _json_safe(current_raw.get("coverage"))
comparison_coverage = _json_safe(comparison_raw.get("coverage"))
reason = current_coverage_reason if not current_coverage_ok else comparison_coverage_reason if not comparison_coverage_ok else None
return {
"kind": "quality_changes", "release": release, "releaseId": release["id"],
"currentPeriod": current_period, "comparisonPeriod": comparison_period, "filters": filters,
"dimension": dimension, "stage": stage, "category": category, "sort": sort,
"rows": _json_safe(records[:limit]), "totalRows": len(records), "returnedRows": min(limit, len(records)),
"truncated": len(records) > limit,
"weightBasis": (f"仅使用正式 {stage} 阶段重量字段。" if stage else
"scrapWeight 是 black + bright 两阶段报废重量和;投入分别见 blackInputWeight/brightInputWeight,不提供跨阶段投入总量。"),
"rateBasis": (f"使用正式 {stage} 阶段 rate;rateDrop 还要求该行阶段 totalWeight>0、qualifiedWeight 有效且 coverage 有效。" if stage else
"使用正式 compositeRate;rateDrop 还要求每行 black/bright 两阶段 totalWeight>0、qualifiedWeight 有效且 coverage 有效。"),
"coverage": {"current": current_coverage, "comparison": comparison_coverage,
"rateComparable": rates_comparable, "rateUnavailableReason": reason},
"notice": "变化行是分组线索;投入/报废增量和分组率不能加总解释总体率。未指定 stage 时 black+bright 重量和仅作分组描述,不代表独立投入或分母;投入变化请分阶段分析。",
}
def _details(self, release: dict[str, Any], period: dict[str, int], filters: dict[str, Any], stage: str,
limit: int) -> dict[str, Any]:
payload: dict[str, Any] = {"releaseId": release["id"], "stage": stage, "limit": limit, **period,
"includeUnassigned": filters.get("includeUnassigned", False)}
payload.update({key: filters[key] for key in ("department", "group", "product", "projectGroup") if key in filters})
response = self._call("POST", "/api/analysis/tools/details", payload=payload)
range_info = response.get("range")
if not isinstance(range_info, dict) or range_info.get("releaseId") != release["id"]:
raise QualityToolError("正式明细接口未确认 releaseId;样本结果已拒绝。")
for key in ("year", "month", "quarter", "department", "group", "product", "projectGroup"):
if range_info.get(key) != payload.get(key):
raise QualityToolError(f"正式明细接口未确认 {key} 筛选;结果已拒绝。")
if range_info.get("includeUnassigned") != filters.get("includeUnassigned", False):
raise QualityToolError("正式明细接口未确认 includeUnassigned;结果已拒绝。")
rows = response.get("rows")
if not isinstance(rows, list) or len(rows) > limit or not rows:
raise QualityToolError("正式明细接口返回样本结构不完整;结果已拒绝。")
return {
"kind": "quality_details_sample", "release": release, "releaseId": release["id"],
"period": period, "filters": filters, "stage": stage, "rows": _json_safe(rows),
"rowCount": response.get("rowCount"), "limit": response.get("limit"),
"sampled": True, "truncated": response.get("truncated"),
"scopeExplanation": response.get("scopeExplanation"),
"notice": "仅为正式接口返回的有限样本,不能当总体排名、分布或全量明细。",
}
@staticmethod
def _compact_defect_row(row: dict[str, Any]) -> dict[str, Any]:
return {field: _json_safe(row.get(field)) for field in
("key", "label", "category", "defect", "weight", "sourceRows", "presentRows", "missingRows", "invalidRows", "negativeRows")}
@staticmethod
def _validate_defect_response(response: dict[str, Any], release: dict[str, Any], period: dict[str, int],
filters: dict[str, Any], stage: str, dimension: str,
defect: str | None, category: str | None, limit: int) -> list[dict[str, Any]]:
if response.get("releaseId") != release["id"]:
raise QualityToolError("具体缺陷接口返回的 releaseId 与请求不一致;结果已拒绝。")
if response.get("kind") != "fine_defect_top":
raise QualityToolError("具体缺陷接口 kind 不是 fine_defect_top;结果已拒绝。")
context = response.get("context")
if not isinstance(context, dict):
raise QualityToolError("具体缺陷接口未返回 context;无法确认期间和筛选是否生效。")
expected_context = {**period, **filters, "stage": stage, "dimension": dimension,
"defect": defect, "category": category}
for field in ("year", "month", "quarter", "department", "group", "product", "projectGroup",
"includeUnassigned", "stage", "dimension", "defect", "category"):
expected = expected_context.get(field)
if field == "includeUnassigned":
expected = filters.get(field, False)
if context.get(field) != expected:
raise QualityToolError(f"具体缺陷接口未确认 {field} 筛选;结果已拒绝。")
if response.get("grain") != "source_defect_weight":
raise QualityToolError("具体缺陷接口 grain 不是 source_defect_weight;不能把响应解释为来源缺陷重量。")
rows = response.get("rows")
if not isinstance(rows, list) or len(rows) > limit or len(rows) > 100:
raise QualityToolError("具体缺陷接口 rows 结构或行数超出请求上限;结果已拒绝。")
coverage = response.get("coverage")
if not isinstance(coverage, dict) or not isinstance(coverage.get("available"), bool):
raise QualityToolError("具体缺陷接口未返回 coverage;无法说明数据覆盖。")
if not rows and coverage.get("available") is not False:
raise QualityToolError("具体缺陷接口标记为可用但 rows 为空;响应不一致。")
if rows and coverage.get("available") is False:
raise QualityToolError("具体缺陷接口返回 rows 但 coverage.available=false;响应不一致。")
if not isinstance(response.get("categoryReconciliation"), list):
raise QualityToolError("具体缺陷接口未返回 categoryReconciliation;无法核对类别口径。")
if not isinstance(response.get("sourceFields"), list) or not isinstance(response.get("notice"), str):
raise QualityToolError("具体缺陷接口未返回 sourceFields/notice;响应不完整。")
# Check row identities before aggregate counts so malformed duplicate keys
# are reported as such instead of being masked by their count mismatch.
QualityTools._index_rows({"rows": rows}, dimension, "defect")
total_groups = response.get("totalGroups")
if isinstance(total_groups, bool) or not isinstance(total_groups, int) or total_groups < len(rows):
raise QualityToolError("具体缺陷接口 totalGroups 与 rows 不一致;结果已拒绝。")
if not isinstance(response.get("rowsTruncated"), bool):
raise QualityToolError("具体缺陷接口未返回 rowsTruncated;无法说明 TOP 是否截断。")
return rows
def _defect_snapshot(self, release: dict[str, Any], period: dict[str, int], filters: dict[str, Any],
stage: str, dimension: str, defect: str | None, category: str | None,
limit: int) -> dict[str, Any]:
payload: dict[str, Any] = {"releaseId": release["id"], "mode": "top", **period, "stage": stage,
"dimension": dimension, "includeUnassigned": filters.get("includeUnassigned", False),
"limit": limit}
payload.update({key: filters[key] for key in ("department", "group", "product", "projectGroup") if key in filters})
if defect is not None:
payload["defect"] = defect.strip()
if category is not None:
payload["category"] = category
response = self._call("POST", "/api/analysis/defects", payload=payload)
rows = self._validate_defect_response(response, release, period, filters, stage, dimension,
payload.get("defect"), category, limit)
return {
"period": period, "rows": rows, "coverage": _json_safe(response["coverage"]),
"categoryReconciliation": _json_safe(response["categoryReconciliation"]),
"sourceFields": _json_safe(response["sourceFields"]), "notice": response["notice"],
"totalGroups": response["totalGroups"], "rowsTruncated": response["rowsTruncated"],
"sourceRows": response.get("sourceRows"), "available": response["coverage"]["available"],
}
@staticmethod
def _pair_defect_snapshots(current: dict[str, Any], comparison: dict[str, Any], dimension: str,
sort: str) -> dict[str, Any]:
current_index = QualityTools._index_rows({"rows": current["rows"]}, dimension, "current defect")
comparison_index = QualityTools._index_rows({"rows": comparison["rows"]}, dimension, "comparison defect")
paired = []
complete = (current["available"] and comparison["available"] and
not current["rowsTruncated"] and not comparison["rowsTruncated"])
for key in sorted(set(current_index) | set(comparison_index)):
now_row, old_row = current_index.get(key), comparison_index.get(key)
now_weight = _number(now_row.get("weight"), minimum=Decimal(0)) if now_row is not None else None
old_weight = _number(old_row.get("weight"), minimum=Decimal(0)) if old_row is not None else None
comparable = now_row is not None and old_row is not None and now_weight is not None and old_weight is not None
if now_row is not None and old_row is not None:
change_type = "continuing"
elif complete:
change_type = "new" if old_row is None else "exit"
else:
change_type = "not_returned_due_to_incomplete_coverage"
paired.append({
"key": key,
"present": {"current": now_row is not None, "comparison": old_row is not None},
"changeType": change_type,
"current": QualityTools._compact_defect_row(now_row) if now_row is not None else None,
"comparison": QualityTools._compact_defect_row(old_row) if old_row is not None else None,
"deltaWeight": now_weight - old_weight if comparable else None,
"deltaAvailable": comparable,
"deltaUnavailableReason": None if comparable else (
"任一期覆盖不可用或 TOP 已截断,单侧未返回不能推断新增/退出;" if not complete else "") +
"任一期缺少该字段行或重量缺失/非法;不以 0 补齐。",
})
def ranking_value(row: dict[str, Any]) -> Decimal | None:
if sort == "scrap_delta":
value = row.get("deltaWeight")
else:
current_row = row.get("current")
value = current_row.get("weight") if isinstance(current_row, dict) else None
return _number(value)
paired.sort(key=lambda row: (ranking_value(row) is None,
-ranking_value(row) if ranking_value(row) is not None else Decimal(0),
str(row["key"])))
return {"rows": paired, "totalRows": len(paired), "complete": complete}
def _defects(self, release: dict[str, Any], period: dict[str, int], comparison_period: dict[str, int] | None,
filters: dict[str, Any], stage: str, dimension: str, defect: str | None,
category: str | None, limit: int, sort: str | None) -> dict[str, Any]:
category_name = _normalize_category(stage, category) if category is not None else None
effective_sort = sort or ("scrap_delta" if comparison_period is not None else "current_scrap")
# Comparison retrieves the endpoint's full bounded field catalog (<=100) on each side.
fetch_limit = 100 if comparison_period is not None else limit
current = self._defect_snapshot(release, period, filters, stage, dimension, defect, category_name, fetch_limit)
current_rows = list(current["rows"])
def current_weight(row: dict[str, Any]) -> Decimal | None:
return _number(row.get("weight"), minimum=Decimal(0))
current_rows.sort(key=lambda row: (current_weight(row) is None,
-current_weight(row) if current_weight(row) is not None else Decimal(0),
str(row["key"])))
result: dict[str, Any] = {
"kind": "quality_fine_defects", "release": release, "releaseId": release["id"],
"period": period, "filters": filters, "stage": stage, "dimension": dimension,
"defect": defect.strip() if isinstance(defect, str) else None, "category": category_name,
"grain": "source_defect_weight", "rows": [_json_safe(self._compact_defect_row(row)) for row in current_rows[:limit]],
"totalRows": current["totalGroups"], "rowsReturned": min(limit, len(current_rows)),
"truncated": current["rowsTruncated"] or len(current_rows) > limit,
"sort": effective_sort,
"rankingBasis": ("按正式来源重量降序;无效/缺失重量置末,key升序打破并列。" +
("只在正式接口已返回的分组集合内排序,存在截断时不是全局TOP。"
if current["rowsTruncated"] else "正式接口返回分组未截断。")),
"rankingComplete": not current["rowsTruncated"],
"sourceRows": current["sourceRows"], "available": current["available"], "coverage": current["coverage"],
"categoryReconciliation": current["categoryReconciliation"], "sourceFields": current["sourceFields"],
"notice": current["notice"],
"semantics": "具体缺陷按来源字段键分别聚合;category 是真实报废大类,不将来源字段折叠或改称大类。",
}
if comparison_period is not None:
comparison = self._defect_snapshot(release, comparison_period, filters, stage, dimension, defect,
category_name, 100)
paired = self._pair_defect_snapshots(current, comparison, dimension, effective_sort)
result["comparisonPeriod"] = comparison_period
result["pairedRows"] = [_json_safe(row) for row in paired["rows"][:limit]]
result["pairedTotalRows"] = paired["totalRows"]
result["pairedTruncated"] = paired["totalRows"] > limit
result["comparisonCoverage"] = comparison["coverage"]
result["comparisonCategoryReconciliation"] = comparison["categoryReconciliation"]
result["comparisonSourceFields"] = comparison["sourceFields"]
result["comparisonNotice"] = comparison["notice"]
result["comparisonTotalGroups"] = comparison["totalGroups"]
result["pairingComplete"] = paired["complete"]
result["pairedTruncated"] = paired["totalRows"] > limit or not paired["complete"]
result["pairingMethod"] = "按接口原始 row.key 精确 full outer 配对;新进/退出保留 present 标记,任一期缺行时增量为 null,不补 0。"
result["pairedRankingBasis"] = (
("按 deltaWeight 降序" if effective_sort == "scrap_delta" else "按当前期来源重量降序") +
";不可计算项置末,key升序打破并列。" +
("比较两期均未截断,覆盖完整时为全量配对排序。" if paired["complete"] else
"只对两期正式接口已返回集合的配对结果排序,不是全局增量TOP;单侧缺失不推断新进/退出。"))
result["pairedRankingComplete"] = paired["complete"]
if effective_sort == "scrap_delta":
result["notice"] += " 对照结果按可计算 deltaWeight 排序,缺侧/非法重量的 delta 为 null 并置末。"
if not paired["complete"]:
result["notice"] += " 至少一期接口结果被截断或覆盖不可用;pairedRows 仅为返回集合变化,不能称全局增量TOP。"
return result
def _catalog(self, release: dict[str, Any], access: dict[str, Any], fine_defect_stage: str | None = None) -> dict[str, Any]:
options = self._call("GET", "/api/options", {"releaseId": release["id"]})
years = options.get("years")
if not isinstance(years, list) or not years:
raise QualityToolError("该发布版本没有可用期间目录;请检查版本和数据覆盖。")
numeric_years = sorted({int(year) for year in years if isinstance(year, int) and not isinstance(year, bool)})
if not numeric_years:
raise QualityToolError("正式期间目录未返回有效年份。")
latest = numeric_years[-1]
probe = self._metrics(release["id"], {"year": latest}, {"includeUnassigned": False}, "overall")
periods = []
for item in (probe.get("trend") or []):
if not isinstance(item, dict):
continue
value = item.get("period") or item.get("month")
text = str(value or "")
match = re.fullmatch(r"(\d{4})-(\d{2})", text)
if match and int(match.group(1)) == latest:
periods.append(int(match.group(2)))
if not periods:
for item in (probe.get("coverage") or {}).get("sourceMonths", []):
if isinstance(item, dict) and item.get("year") == latest and isinstance(item.get("month"), int):
periods.append(item["month"])
field_items = access.get("visibleDefectFields") or []
visible_codes = {str(item.get("code")) for item in field_items if isinstance(item, dict) and item.get("code")}
categories = []
for stage, mapping in CATEGORIES.items():
prefix = "black_" if stage == "black" else "bright_"
for label, aliases in mapping.items():
codes = {
"责废": "black_responsibility_scrap", "料废": "black_material_scrap", "外废": "black_external_scrap",
"镀废": "bright_plating_scrap", "材料废": "bright_material_scrap",
"加工废": "bright_processing_scrap", "扩散废": "bright_diffusion_scrap",
}
code = codes[label]
if code in visible_codes:
categories.append({"stage": stage, "name": label, "aliases": list(aliases), "kind": "正式报废大类"})
access_fields = access.get("visibleWeightFields") or []
def option_summary(key: str) -> dict[str, Any]:
values = options.get(key)
if not isinstance(values, list):
raise QualityToolError(f"正式选项接口未返回 {key};目录响应不完整。")
clean = sorted({str(value) for value in values if value is not None and str(value).strip()})
return {"count": len(clean), "examples": clean[:15], "examplesTruncated": len(clean) > 15}
fine_payload: dict[str, Any] = {"releaseId": release["id"], "mode": "catalog"}
if fine_defect_stage is not None:
fine_payload["stage"] = fine_defect_stage
fine = self._call("POST", "/api/analysis/defects", payload=fine_payload)
if fine.get("kind") != "fine_defect_catalog" or fine.get("releaseId") != release["id"]:
raise QualityToolError("具体缺陷目录接口未确认 kind/releaseId;目录结果已拒绝。")
if fine.get("grain") != "source_defect_weight" or not isinstance(fine.get("fields"), list):
raise QualityToolError("具体缺陷目录缺少来源字段目录或 grain;目录结果已拒绝。")
if fine.get("scanned") is not False:
raise QualityToolError("具体缺陷目录未确认 scanned=false;不能将其作为轻量字段目录。")
if not isinstance(fine.get("categories"), list) or not isinstance(fine.get("stages"), list) or not isinstance(fine.get("limitations"), list):
raise QualityToolError("具体缺陷目录 categories/stages/limitations 结构不完整。")
fine_context = fine.get("context")
if not isinstance(fine_context, dict) or fine_context.get("stage") != fine_defect_stage:
raise QualityToolError("具体缺陷目录未确认 stage 筛选;目录结果已拒绝。")
fine_defects = {
"endpoint": "POST /api/analysis/defects", "kind": fine["kind"], "grain": fine["grain"],
"stages": _json_safe(fine["stages"]), "categories": _json_safe(fine["categories"]),
"fields": _json_safe(fine["fields"]), "scanned": fine["scanned"],
"context": _json_safe(fine.get("context")), "limitations": _json_safe(fine["limitations"]),
"dimensions": ["defect", "product"],
"semantics": "来源具体缺陷字段按目录原始 key 分别汇总;category 是真实报废大类;dimension=product 需指定 defect key。",
}
return {
"kind": "quality_catalog", "release": release, "releaseId": release["id"],
"periods": {"years": numeric_years, "latestYear": latest,
"availableMonthsInLatestYear": sorted(set(periods)),
"monthRange": {"minimum": 1, "maximum": 12}, "quarterRange": {"minimum": 1, "maximum": 4}},
"dimensions": access.get("dimensions") or [],
"topDimensions": access.get("topDimensions") or [],
"grouping": access.get("grouping") or [], "categories": categories,
"metrics": [{key: item.get(key) for key in ("code", "name", "unit", "dimensions") if key in item}
for item in (access.get("metrics") or []) if isinstance(item, dict)],
"availableFilters": {"department": option_summary("departments"), "group": option_summary("groups"),
"product": option_summary("products"), "projectGroup": option_summary("projectGroups")},
"authorization": {"queryCatalog": True, "visibleWeightFieldCount": len(access_fields),
"visibleWeightFields": access_fields,
"visibleDefectCategoryCount": len(visible_codes),
"dataScope": access.get("scope")},
"filters": {"scopePresets": list(SCOPES), "actual": ["department", "group", "product", "projectGroup", "includeUnassigned"]},
"fineDefects": fine_defects,
"limitations": access.get("limitations") or [],
}
def _validate_arguments(self, args: dict[str, Any]) -> None:
unknown = set(args) - {"mode", "releaseId", "scope", "period", "comparisonPeriod", "filters", "view", "stage", "dimension", "category", "defect", "limit", "sort"}
if unknown:
raise QualityToolError(f"不支持参数:{', '.join(sorted(unknown))}。请按 quality_data schema 调整请求。")
if args.get("mode") not in {"catalog", "query", "compare", "top", "changes", "defects", "details"}:
raise QualityToolError("mode 必须是 catalog/query/compare/top/changes/defects/details 之一。")
limit = args.get("limit", 20)
if isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= 100:
raise QualityToolError("limit 必须是 1 到 100 的整数。")
mode = args["mode"]
if mode == "catalog":
unused = {"period", "comparisonPeriod", "scope", "filters", "view", "dimension", "category", "defect", "limit", "sort"} & set(args)
if unused:
raise QualityToolError(f"catalog 不接受这些参数:{', '.join(sorted(unused))}。")
if args.get("stage") is not None and args.get("stage") not in CATEGORIES:
raise QualityToolError("catalog.stage 只能是 black 或 bright。")
elif mode == "query":
if "comparisonPeriod" in args or "stage" in args or "dimension" in args or "category" in args or "defect" in args or "sort" in args:
raise QualityToolError("query 不接受 comparisonPeriod/stage/dimension/category/defect/sort;请用 view 指定分组。")
elif mode == "compare":
if "view" in args or "dimension" in args or "sort" in args or "defect" in args:
raise QualityToolError("compare 只比较整体正式率;不接受 view/dimension/sort。")
if args.get("category") is not None and args.get("stage") not in CATEGORIES:
raise QualityToolError("compare.category 需要 stage=black 或 bright。")
if args.get("stage") is not None and args.get("stage") not in CATEGORIES:
raise QualityToolError("compare.stage 只能是 black 或 bright。")
if args.get("stage") is not None and args.get("category") is None:
raise QualityToolError("compare.stage 只用于比较指定 category;未指定 category 时请删除 stage。")
elif mode == "top":
if "view" in args or "comparisonPeriod" in args or "sort" in args or "defect" in args:
raise QualityToolError("top 不接受 view/comparisonPeriod/sort。")
if args.get("stage") not in CATEGORIES:
raise QualityToolError("top 必须指定 stage=black 或 bright。")
if args.get("dimension") not in {"category", "product", "department", "group", "projectGroup"}:
raise QualityToolError("top 必须指定 category/product/department/group/projectGroup 维度。")
elif mode == "changes":
if "view" in args or "defect" in args:
raise QualityToolError("changes 使用 dimension,不接受 view。")
if args.get("dimension") not in {"product", "department", "group", "projectGroup"}:
raise QualityToolError("changes 必须指定 product/department/group/projectGroup 维度。")
if args.get("sort", "scrap_delta") not in {"scrap_delta", "current_scrap", "rate_drop"}:
raise QualityToolError("changes.sort 只能是 scrap_delta/current_scrap/rate_drop。")
if args.get("stage") is not None and args.get("stage") not in CATEGORIES:
raise QualityToolError("changes.stage 只能是 black 或 bright。")
elif mode == "details":
if "view" in args or "comparisonPeriod" in args or "dimension" in args or "category" in args or "defect" in args or "sort" in args:
raise QualityToolError("details 只接受 period/stage/filters/limit。")
if args.get("stage") not in CATEGORIES:
raise QualityToolError("details 必须指定 stage=black 或 bright。")
elif mode == "defects":
if "view" in args:
raise QualityToolError("defects 不接受 view;请指定 dimension=defect 或 product。")
if args.get("stage") not in CATEGORIES:
raise QualityToolError("defects 必须指定 stage=black 或 bright。")
if args.get("dimension") not in {"defect", "product"}:
raise QualityToolError("defects.dimension 必须是 defect 或 product。")
if args.get("sort", "scrap_delta" if args.get("comparisonPeriod") is not None else "current_scrap") not in {"scrap_delta", "current_scrap"}:
raise QualityToolError("defects.sort 只能是 scrap_delta 或 current_scrap。")
if args.get("comparisonPeriod") is None and args.get("sort") == "scrap_delta":
raise QualityToolError("单期 defects 没有增量可排;请删除 sort 或使用 current_scrap。")
if args.get("dimension") == "product" and not isinstance(args.get("defect"), str):
raise QualityToolError("defects.dimension=product 必须指定 defect;请先按 dimension=defect 查看目录或TOP。")
if "defect" in args and (not isinstance(args["defect"], str) or not args["defect"].strip()):
raise QualityToolError("defect 必须是非空来源字段键或缺陷名称。")
if args.get("category") is not None:
_normalize_category(args["stage"], args["category"])
def _write_evidence(self, result: dict[str, Any], mode: str) -> tuple[str, str]:
evidence_id = "nao-quality-" + uuid.uuid4().hex
evidence_ref = self._evidence_ref(evidence_id)
path = self._evidence_dir / f"{evidence_id}.json"
document = {
"evidenceId": evidence_id,
"evidenceRef": evidence_ref,
"createdAt": datetime.now(timezone.utc).isoformat(),
"tool": "quality_data", "mode": mode,
"releaseId": result.get("releaseId"),
"apiSource": {"base": "http://127.0.0.1:5281", "calls": self._calls},
"result": _json_safe(result),
}
path.parent.mkdir(parents=True, exist_ok=True)
data = (json.dumps(document, ensure_ascii=False, indent=2, allow_nan=False) + "\n").encode("utf-8")
fd = os.open(path, os.O_CREAT | os.O_TRUNC | os.O_WRONLY, 0o600)
try:
with os.fdopen(fd, "wb") as output:
output.write(data)
except Exception:
try:
os.close(fd)
except OSError:
pass
raise
return evidence_id, str(path.resolve())
@staticmethod
def _evidence_ref(evidence_id: str) -> str:
prefix = "nao-quality-"
if not evidence_id.startswith(prefix) or len(evidence_id) <= len(prefix):
raise QualityToolError("内部证据编号格式异常;结果未返回。")
return "Q" + evidence_id[len(prefix):len(prefix) + 8].upper()
def quality_data(self, arguments: dict[str, Any]) -> dict[str, Any]:
if not isinstance(arguments, dict):
raise QualityToolError("quality_data arguments 必须是 JSON 对象。")
with self._lock:
self._calls = []
self._validate_arguments(arguments)
# Short-lived cache can de-duplicate identical calls inside compare/catalog;
# never carry cached data across MCP calls where API permissions may change.
self._metrics_cache.clear()
mode = arguments["mode"]
release = self._bind_release(arguments.get("releaseId"), mode)
if mode == "catalog":
access = self._access_catalog()
result = self._catalog(release, access, arguments.get("stage"))
else:
# This formal authorization check is intentionally repeated per invocation,
# including cache hits, so cached metrics never bypass current API access.
access = self._access_catalog()
raw_filters = arguments.get("filters", {})
filters, selected_scope = normalize_filters(arguments.get("scope"), raw_filters,
scope_was_explicit="scope" in arguments)
limit = arguments.get("limit", 20)
if mode == "query":
period = normalize_period(arguments.get("period"))
view = arguments.get("view", "overall")
if view not in {"overall", "department", "group", "product", "projectGroup"}:
raise QualityToolError("view 只能是 overall/department/group/product/projectGroup。")
result = self._query(release, period, filters, view, limit)
elif mode == "compare":
current = normalize_period(arguments.get("period"), "period")
comparison = normalize_period(arguments.get("comparisonPeriod"), "comparisonPeriod")
stage = arguments.get("stage")
category = _normalize_category(stage, arguments.get("category")) if arguments.get("category") is not None else None
result = self._compare(release, current, comparison, filters, stage if category else None, category)
elif mode == "top":
period = normalize_period(arguments.get("period"))
result = self._top(release, period, filters, arguments["stage"], arguments["dimension"],
arguments.get("category"), limit)
elif mode == "changes":
current = normalize_period(arguments.get("period"), "period")
comparison = normalize_period(arguments.get("comparisonPeriod"), "comparisonPeriod")
stage = arguments.get("stage")
result = self._changes(release, current, comparison, filters, arguments["dimension"], stage,
arguments.get("category"), arguments.get("sort", "scrap_delta"), limit)
elif mode == "defects":
current = normalize_period(arguments.get("period"), "period")
comparison = normalize_period(arguments.get("comparisonPeriod"), "comparisonPeriod", required=False)
result = self._defects(release, current, comparison, filters, arguments["stage"],
arguments["dimension"], arguments.get("defect"),
arguments.get("category"), limit, arguments.get("sort"))
else:
period = normalize_period(arguments.get("period"))
result = self._details(release, period, filters, arguments["stage"], limit)
result["selectedScope"] = selected_scope
evidence_id, evidence_path = self._write_evidence(result, mode)
result["evidenceId"] = evidence_id
result["evidenceRef"] = self._evidence_ref(evidence_id)
result["evidencePath"] = evidence_path
result["apiSource"] = {"base": "http://127.0.0.1:5281", "paths": list(dict.fromkeys(call["path"] for call in self._calls)),
"releaseId": release["id"]}
return _json_safe(result)
def tool_definition() -> dict[str, Any]:
return {
"name": "quality_data",
"description": TOOL_DESCRIPTION,
"inputSchema": copy.deepcopy(QUALITY_DATA_SCHEMA),
}
__all__ = [
"QualityToolError", "QualityTools", "QUALITY_DATA_SCHEMA", "TOOL_DESCRIPTION", "tool_definition",
"normalize_filters", "normalize_period", "symmetric_stage_decomposition",
]