1353 lines
85 KiB
Python
1353 lines
85 KiB
Python
"""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},
|
||
"extraFilters": {"type":"object", "additionalProperties":{"type":"array","items":{"type":"string"},"maxItems":50},"description":"catalog的筛选字段key到值数组,例如customerCode或blankProducer;空值为__EMPTY__。"},
|
||
"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", "extraFilters", "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
|
||
extra = raw.get("extraFilters", {})
|
||
if not isinstance(extra, dict) or len(extra)>20:
|
||
raise QualityToolError("extraFilters 必须为字段到值数组的对象。")
|
||
for key, values in extra.items():
|
||
if not isinstance(key,str) or not re.fullmatch(r"[a-zA-Z][a-zA-Z0-9_]{0,63}",key) or not isinstance(values,list) or len(values)>50 or any(not isinstance(v,str) or not v.strip() or len(v)>256 for v in values):
|
||
raise QualityToolError("extraFilters 的字段或值无效。")
|
||
if extra: result["extraFilters"] = {k:list(dict.fromkeys(v)) for k,v in extra.items() if v}
|
||
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({k:json.dumps(v,ensure_ascii=False,separators=(",",":")) if isinstance(v,dict) else v for k,v in params.items()})
|
||
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("extraFilters",{}) != filters.get("extraFilters",{}):
|
||
raise QualityToolError("正式指标接口未确认新增筛选;结果已拒绝。")
|
||
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", "extraFilters"):
|
||
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", "extraFilters"):
|
||
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", "extraFilters") if key in filters})
|
||
response = self._call("POST", "/api/analysis/tools/details", payload=payload)
|
||
if isinstance(response.get("range"),dict) and response["range"].get("extraFilters",{}) != filters.get("extraFilters",{}):
|
||
raise QualityToolError("明细接口未确认新增筛选;结果已拒绝。")
|
||
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;无法确认期间和筛选是否生效。")
|
||
if context.get("extraFilters",{}) != filters.get("extraFilters",{}):
|
||
raise QualityToolError("具体缺陷接口未确认新增筛选;结果已拒绝。")
|
||
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", "extraFilters") 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", "extraFilters", "includeUnassigned"], "extraFields": access.get("extraFields", [])},
|
||
"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",
|
||
]
|