from __future__ import annotations import io import json import logging import sys import tempfile import unittest from pathlib import Path from urllib.parse import parse_qs, urlsplit ROOT = Path(__file__).resolve().parents[1] sys.path.insert(0, str(ROOT / "scripts")) from dbgpt_trial_data import encoded_selection from nao_quality_mcp import MCPServer, serve from nao_quality_tools import ( QualityToolError, QualityTools, normalize_filters, symmetric_stage_decomposition, tool_definition, ) RELEASE = "release-a" def snapshot_period(year: int, month: int | None, view: str, params: dict, rows: list[dict] | None = None) -> dict: months = [month] if month is not None else list(range(1, 13)) rate_by_month = {1: (0.94, 0.96), 2: (0.95, 0.97), 3: (0.96, 0.98)} black_rate, bright_rate = rate_by_month.get(month or 2, (0.95, 0.97)) black_scrap = 11.0 + (month or 2) bright_scrap = 7.0 + (month or 2) summary = { "key": "overall", "label": "总体", "compositeRate": black_rate * bright_rate, "black": {"rate": black_rate, "qualifiedWeight": 1000.0, "scrapWeight": black_scrap, "totalWeight": 1000.0 + black_scrap, "defects": [{"name": "责废", "weight": black_scrap / 2, "rate": 0.5}, {"name": "料废", "weight": black_scrap / 3, "rate": 1 / 3}, {"name": "外废", "weight": black_scrap / 6, "rate": 1 / 6}]}, "bright": {"rate": bright_rate, "qualifiedWeight": 900.0, "scrapWeight": bright_scrap, "totalWeight": 900.0 + bright_scrap, "defects": [{"name": "镀废", "weight": bright_scrap / 4, "rate": 0.25}, {"name": "材料废", "weight": bright_scrap / 4, "rate": 0.25}, {"name": "加工废", "weight": bright_scrap / 4, "rate": 0.25}, {"name": "扩散废", "weight": bright_scrap / 4, "rate": 0.25}]}, "coverage": {"blackRows": 10, "brightRows": 12}, } source_months = [{"year": year, "month": current, "blackRows": 10, "brightRows": 12} for current in months] context = {"year": year, "month": month, "quarter": None, "view": view, "department": params.get("department"), "group": params.get("group"), "product": params.get("product"), "projectGroup": params.get("projectGroup"), "includeUnassigned": params.get("includeUnassigned", False), "exclusions": json.loads(params["exclusions"]) if "exclusions" in params else {}} if rows is None: rows = [summary] if view != "overall" else [] row_count = len(rows) if "rowLimit" in params: start = int(params.get("rowOffset", 0)) rows = rows[start:start + params["rowLimit"]] context["rowCount"] = 1 if view != "overall" else len(rows) context["rowCount"] = row_count trend = [{"period": f"{year}-{current:02d}", "periodLabel": f"{year}-{current:02d}", **summary} for current in months] return { "release": {"id": params.get("releaseId", RELEASE), "name": "发布版本 A", "status": "PUBLISHED"}, "context": context, "summary": summary, "rows": rows, "trend": trend, "defects": {"black": summary["black"]["defects"], "bright": summary["bright"]["defects"]}, "coverage": {"rawRows": len(months) * 22, "includedRows": len(months) * 22, "excludedBlankRows": 0, "unmappedRows": 0, "projectGroupUnconfiguredRows": 0, "missingStages": [], "sourceMonths": source_months}, } class FakeApi: def __init__(self, *, bad_coverage_month: int | None = None, zero_denominator_month: int | None = None, products: dict[int, list[dict]] | None = None) -> None: self.calls: list[tuple[str, str, dict | None]] = [] self.bad_coverage_month = bad_coverage_month self.zero_denominator_month = zero_denominator_month self.products = products or {} self.current_release_id = RELEASE def login(self): return self @staticmethod def _product_row(key: str, product: str, black_scrap: float, bright_scrap: float, black_rate: float = 0.95, bright_rate: float = 0.97) -> dict: return {"key": key, "product": product, "label": product, "compositeRate": black_rate * bright_rate, "black": {"rate": black_rate, "qualifiedWeight": 100.0, "scrapWeight": black_scrap, "totalWeight": 100.0 + black_scrap, "defects": [{"name": "责废", "weight": black_scrap}]}, "bright": {"rate": bright_rate, "qualifiedWeight": 100.0, "scrapWeight": bright_scrap, "totalWeight": 100.0 + bright_scrap, "defects": [{"name": "镀废", "weight": bright_scrap}]}, "coverage": {"blackRows": 4, "brightRows": 5}} def call(self, path: str, payload=None, method=None): self.calls.append((method or "GET", path, payload)) parsed = urlsplit(path) params = {key: values[-1] for key, values in parse_qs(parsed.query).items()} for key in ("year", "month", "quarter", "rowLimit", "rowOffset", "limit"): if key in params: params[key] = int(params[key]) if "includeUnassigned" in params: params["includeUnassigned"] = params["includeUnassigned"].lower() == "true" if parsed.path == "/api/releases": return {"currentReleaseId": self.current_release_id, "items": [ {"id": RELEASE, "name": "发布版本 A", "status": "PUBLISHED"}, {"id": "candidate", "name": "候选", "status": "CANDIDATE"}, {"id": "release-b", "name": "发布版本 B", "status": "PUBLISHED"}, ]} if parsed.path == "/api/analysis/tools/catalog": return {"kind": "analysis_catalog", "visibleWeightFields": ["black_scrap_weight"], "visibleDefectFields": [{"code": "black_responsibility_scrap", "name": "责废"}], "dimensions": [{"key": "product"}], "topDimensions": ["category", "product"], "grouping": ["overall", "product"], "scope": "当前授权范围", "limitations": []} if parsed.path == "/api/options": return {"years": [2025, 2026], "departments": [], "groups": [], "products": [], "projectGroups": []} if parsed.path == "/api/metrics": year = int(params["year"]) month = int(params["month"]) if "month" in params else None view = params.get("view", "overall") rows = self.products.get(month or 0, []) if view == "product" else None result = snapshot_period(year, month, view, params, rows) if self.bad_coverage_month == month: result["coverage"]["sourceMonths"][0]["brightRows"] = 0 result["coverage"]["missingStages"] = [{"year": year, "month": month, "stage": "bright"}] if self.zero_denominator_month == month: result["summary"]["bright"]["qualifiedWeight"] = 0 result["summary"]["bright"]["scrapWeight"] = 0 result["summary"]["bright"]["totalWeight"] = 0 result["summary"]["bright"]["rate"] = 0 result["summary"]["compositeRate"] = 0 return result if parsed.path == "/api/analytics/top": result_query = {key: value for key, value in params.items() if key in {"releaseId", "stage", "dimension", "category", "year", "month", "quarter", "department", "group", "product", "projectGroup", "includeUnassigned", "limit"}} return {"releaseId": params.get("releaseId"), "stage": params.get("stage"), "dimension": params.get("dimension"), "category": params.get("category", ""), "denominator": 10, "shareBasis": "当前筛选下分组对象重量合计;不表示总体贡献", "rankingCoverage": {"complete": False}, "coverage": {"rawRows": 22}, "rows": [{"rank": 1, "key": "规格 A", "label": "规格 A", "sourceCategory": "责废", "weight": 10, "denominator": 10, "share": 1, "coverage": {"rows": 2}}], "cumulativeThresholdApplied": False, "resultId": "top-id", "resultQuery": result_query} if parsed.path == "/api/analysis/tools/details": assert method == "POST" return {"kind": "analysis_details", "rows": [{"product": "规格 A"}], "rowCount": 1, "limit": payload["limit"], "sampled": True, "truncated": True, "scopeExplanation": "有限样本不代表全部明细。", "range": {**{key: payload.get(key) for key in ("releaseId", "stage", "year", "month", "quarter", "department", "group", "product", "projectGroup", "includeUnassigned")}, "exclusions": payload.get("exclusions", {})}} if parsed.path == "/api/analysis/defects": assert method == "POST" if payload.get("mode") == "catalog": return {"kind": "fine_defect_catalog", "releaseId": payload["releaseId"], "release": {"id": payload["releaseId"], "status": "PUBLISHED"}, "context": {"stage": payload.get("stage"), "mode": "catalog"}, "grain": "source_defect_weight", "stages": [payload.get("stage")] if payload.get("stage") else ["black", "bright"], "categories": [{"stage": "black", "category": "责废", "available": True, "formalComponent": "black_responsibility_scrap"}], "fields": [{"stage": "black", "key": "责废尺寸重量", "label": "责废尺寸重量", "category": "责废", "sourceField": "责废尺寸重量", "available": True}], "scanned": False, "limitations": ["固定源字段目录"]} year, month = payload["year"], payload.get("month", 1) if payload.get("dimension") == "product": rows = [{"key": "product-a", "label": "规格 A", "category": payload.get("category") or "责废", "defect": payload.get("defect"), "weight": 13 if month == 3 else 10, "sourceRows": 8, "presentRows": 8, "missingRows": 0, "invalidRows": 0, "negativeRows": 0}] else: by_month = { 1: [ {"key": "责废尺寸重量", "label": "责废尺寸重量", "category": "责废", "weight": 10, "sourceRows": 8, "presentRows": 8, "missingRows": 0, "invalidRows": 0, "negativeRows": 0}, {"key": "料废尺寸重量", "label": "料废尺寸重量", "category": "料废", "weight": 4, "sourceRows": 8, "presentRows": 8, "missingRows": 0, "invalidRows": 0, "negativeRows": 0}, {"key": "责废缺角重量", "label": "责废缺角重量", "category": "责废", "weight": 2, "sourceRows": 8, "presentRows": 8, "missingRows": 0, "invalidRows": 0, "negativeRows": 0}, ], 3: [ {"key": "责废尺寸重量", "label": "责废尺寸重量", "category": "责废", "weight": 13, "sourceRows": 9, "presentRows": 9, "missingRows": 0, "invalidRows": 0, "negativeRows": 0}, {"key": "料废尺寸重量", "label": "料废尺寸重量", "category": "料废", "weight": 5, "sourceRows": 9, "presentRows": 9, "missingRows": 0, "invalidRows": 0, "negativeRows": 0}, {"key": "责废刀丝重量", "label": "责废刀丝重量", "category": "责废", "weight": 1, "sourceRows": 9, "presentRows": 9, "missingRows": 0, "invalidRows": 0, "negativeRows": 0}, ], } rows = by_month.get(month, by_month[1]) if payload.get("defect") and payload.get("dimension") != "product": rows = [row for row in rows if row["key"] == payload["defect"]] if payload.get("category"): rows = [row for row in rows if row["category"] == payload["category"]] context = {key: payload.get(key) for key in ("year", "month", "quarter", "monthStart", "monthEnd", "department", "group", "product", "projectGroup", "includeUnassigned", "stage", "dimension", "defect", "category")} context.update(extraFilters=payload.get("extraFilters", {}), exclusions=payload.get("exclusions", {}), columnFilters=payload.get("columnFilters", []), filters={"columnFilters": payload.get("columnFilters", [])}) return {"kind": "fine_defect_top", "releaseId": payload["releaseId"], "release": {"id": payload["releaseId"], "status": "PUBLISHED"}, "context": {**context, "mode": "top"}, "grain": "source_defect_weight", "rows": rows[:payload["limit"]], "totalGroups": len(rows), "rowsTruncated": len(rows) > payload["limit"], "sourceRows": 8, "coverage": {"available": True, "sourceRows": 8, "hasValidWeights": True, "categories": [{"category": "责废", "isReconciled": True}]}, "categoryReconciliation": [{"category": "责废", "isReconciled": True}], "sourceFields": [{"key": row["key"], "label": row["label"], "category": row["category"], "sourceField": row["key"]} for row in rows], "notice": "来源字段聚合,不跨字段合并。"} raise AssertionError(f"Unexpected API path: {path}") class QualityToolsTests(unittest.TestCase): def setUp(self): self.temp = tempfile.TemporaryDirectory() self.api = FakeApi() self.tools = QualityTools(api_factory=lambda: self.api, evidence_dir=self.temp.name) def tearDown(self): self.temp.cleanup() def test_schema_has_one_tool_and_modes(self): definition = tool_definition() self.assertEqual(definition["name"], "quality_data") self.assertEqual(definition["inputSchema"]["properties"]["mode"]["enum"], ["catalog", "query", "rank", "compare", "top", "changes", "defects", "details", "investigate"]) self.assertIn("defect", definition["inputSchema"]["properties"]) self.assertFalse(definition["inputSchema"]["additionalProperties"]) self.assertEqual(definition["inputSchema"]["allOf"][0]["then"]["required"], ["releaseId"]) def test_scope_wire_encoding_and_filter_conflict(self): filters, scope = normalize_filters("auto_combined", {}, scope_was_explicit=True) self.assertEqual(filters["department"], '新能源汽车磁钢') self.assertNotIn('group', filters) self.assertEqual(scope, "auto_combined") with self.assertRaisesRegex(QualityToolError, "不能同时指定"): normalize_filters("auto_domestic", {"group": "汽车交通-国内"}, scope_was_explicit=True) explicit_group, _ = normalize_filters(None, {"group": "研发组"}, scope_was_explicit=False) self.assertEqual(explicit_group["group"], "研发组") def test_exclusions_reach_metrics_and_details_and_are_checked(self): exclusions = {"product": ["规格+T", "__UNASSIGNED__"]} filters = {"exclusions": exclusions} result = self.tools.quality_data({"mode": "compare", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}, "comparisonPeriod": {"year": 2026, "month": 1}, "filters": filters}) metric_calls = [parse_qs(urlsplit(path).query) for _, path, _ in self.api.calls if urlsplit(path).path == "/api/metrics"] self.assertEqual(2, len(metric_calls)) self.assertTrue(all(json.loads(call["exclusions"][0]) == exclusions for call in metric_calls)) self.tools.quality_data({"mode": "details", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}, "stage": "black", "filters": filters}) detail = next(payload for _, path, payload in self.api.calls if path == "/api/analysis/tools/details") self.assertEqual(exclusions, detail["exclusions"]) snapshot = snapshot_period(2026, 3, "overall", {"releaseId": RELEASE}) with self.assertRaisesRegex(QualityToolError, "未确认排除"): self.tools._validate_source_snapshot(snapshot, RELEASE, {"year": 2026, "month": 3}, {**filters, "includeUnassigned": False}, "overall") def test_details_rejects_missing_exclusion_echo(self): class MissingExclusionEchoApi(FakeApi): def call(self, path, payload=None, method=None): response = super().call(path, payload, method) if path == "/api/analysis/tools/details": response["range"].pop("exclusions", None) return response api = MissingExclusionEchoApi() tools = QualityTools(api_factory=lambda: api, evidence_dir=self.temp.name) with self.assertRaisesRegex(QualityToolError, "未确认排除"): tools.quality_data({"mode": "details", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}, "stage": "black", "filters": {"exclusions": {"product": ["P"]}}}) def test_exclusions_are_validated_unsupported_modes_reject_and_defects_forwards_them(self): for exclusions in ({"product": []}, {"unknown": ["x"]}, {"product": [None]}, None): with self.subTest(exclusions=exclusions), self.assertRaises(QualityToolError): normalize_filters(None, {"exclusions": exclusions}, scope_was_explicit=False) with self.assertRaisesRegex(QualityToolError, "暂不支持排除条件"): self.tools.quality_data({"mode": "top", "releaseId": RELEASE, "period": {"year": 2026}, "filters": {"exclusions": {"product": ["P"]}}, "stage": "black", "dimension": "product"}) result = self.tools.quality_data({"mode": "defects", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}, "filters": {"exclusions": {"product": ["P"]}}, "stage": "black", "dimension": "defect", "limit": 10}) request = next(payload for method, path, payload in reversed(self.api.calls) if method == "POST" and urlsplit(path).path == "/api/analysis/defects") self.assertEqual(request["exclusions"], {"product": ["P"]}) self.assertEqual(result["filters"]["exclusions"], {"product": ["P"]}) self.assertFalse(any(urlsplit(path).path == "/api/analytics/top" for _, path, _ in self.api.calls)) def test_symmetric_decomposition_is_exact_in_percentage_points(self): result = symmetric_stage_decomposition( 0.96, 0.98, 0.94, 0.96, 0.96 * 0.98 - 0.94 * 0.96, black_current_total_weight=100, bright_current_total_weight=90, black_comparison_total_weight=80, bright_comparison_total_weight=70) self.assertEqual(result["status"], "available") self.assertAlmostEqual(float(result["blackPP"] + result["brightPP"]), 100 * (0.96 * 0.98 - 0.94 * 0.96), places=10) def test_missing_or_invalid_stage_rate_blocks_decomposition(self): for invalid in (None, "bad", -0.1, 1.01): result = symmetric_stage_decomposition(invalid, 0.98, 0.94, 0.96, 0.02, black_current_total_weight=100, bright_current_total_weight=100, black_comparison_total_weight=100, bright_comparison_total_weight=100) self.assertEqual(result["status"], "unavailable") self.assertIsNone(result["blackPP"]) def test_symmetric_decomposition_refuses_zero_stage_denominator(self): result = symmetric_stage_decomposition( 0.0, 0.98, 0.94, 0.96, 0.02, black_current_total_weight=0, bright_current_total_weight=100, black_comparison_total_weight=100, bright_comparison_total_weight=100) self.assertEqual(result["status"], "unavailable") self.assertIsNone(result["blackPP"]) def test_compare_pins_same_release_and_reuses_filters(self): result = self.tools.quality_data({ "mode": "compare", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}, "comparisonPeriod": {"year": 2026, "month": 1}, "filters": {"department": "汽车交通", "group": "汽车交通-国内", "product": "规格 A", "projectGroup": "项目甲", "includeUnassigned": False}, }) self.assertEqual(result["releaseId"], RELEASE) self.assertTrue(result["delta"]["available"]) self.assertEqual(result["stageDecomposition"]["status"], "available") self.assertNotIn("blackPP", result["stageDecomposition"]) self.assertAlmostEqual(result["stageRateChangesPP"]["black"], 2.0) self.assertAlmostEqual(result["stageRateChangesPP"]["bright"], 2.0) self.assertNotAlmostEqual(result["stageDecomposition"]["blackContributionToCompositePP"], 2.0) metric_calls = [call for call in self.api.calls if urlsplit(call[1]).path == "/api/metrics"] self.assertEqual(len(metric_calls), 2) for _, path, _ in metric_calls: query = parse_qs(urlsplit(path).query) self.assertEqual(query["releaseId"], [RELEASE]) self.assertEqual(query["department"], ["新能源汽车磁钢"]) self.assertEqual(query["group"], ["汽车交通-国内"]) self.assertEqual(query["product"], ["规格 A"]) self.assertEqual(query["projectGroup"], ["项目甲"]) self.assertTrue(result["evidencePath"].endswith(result["evidenceId"] + ".json")) self.assertRegex(result["evidenceRef"], r"^Q[0-9A-F]{8}$") evidence = json.loads(Path(result["evidencePath"]).read_text()) self.assertEqual(evidence["evidenceRef"], result["evidenceRef"]) def test_compare_single_stage_coverage_keeps_composite_but_not_missing_stage_delta(self): self.api.bad_coverage_month = 3 result = self.tools.quality_data({ "mode": "compare", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}, "comparisonPeriod": {"year": 2026, "month": 1}, }) self.assertTrue(result["delta"]["available"]) self.assertIsNotNone(result["delta"]["percentagePoints"]) self.assertIsNone(result["stageRateChangesPP"]["bright"]) self.assertEqual(result["stageDecomposition"]["status"], "unavailable") def test_compare_zero_stage_denominator_uses_backend_composite_without_stage_fallback(self): self.api.zero_denominator_month = 3 result = self.tools.quality_data({ "mode": "compare", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}, "comparisonPeriod": {"year": 2026, "month": 1}, }) self.assertTrue(result["delta"]["available"]) self.assertIsNotNone(result["delta"]["percentagePoints"]) self.assertIsNone(result["stageRateChangesPP"]["bright"]) self.assertEqual(result["stageDecomposition"]["status"], "unavailable") def test_data_modes_require_release_and_catalog_refreshes_current(self): with self.assertRaisesRegex(QualityToolError, "显式传回"): self.tools.quality_data({"mode": "query", "period": {"year": 2026, "month": 3}}) first = self.tools.quality_data({"mode": "catalog"}) self.api.current_release_id = "release-b" second = self.tools.quality_data({"mode": "catalog"}) self.assertEqual(first["releaseId"], RELEASE) self.assertEqual(second["releaseId"], "release-b") explicit = self.tools.quality_data({"mode": "query", "releaseId": RELEASE, "period": {"year": 2026, "month": 1}}) self.assertEqual(explicit["releaseId"], RELEASE) metric_calls = [call for call in self.api.calls if urlsplit(call[1]).path == "/api/metrics"] ids = [parse_qs(urlsplit(call[1]).query)["releaseId"][0] for call in metric_calls] self.assertEqual(ids, [RELEASE, "release-b", RELEASE]) def test_scope_is_returned_and_metrics_cache_does_not_cross_calls(self): args = {"mode": "query", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}, "scope": "auto_combined"} first = self.tools.quality_data(args) second = self.tools.quality_data(args) expected = encoded_selection(["汽车交通-国内", "汽车交通-海外"]) self.assertEqual(first["selectedScope"], "auto_combined") self.assertEqual(first["filters"]["department"], '新能源汽车磁钢') self.assertEqual(second["selectedScope"], "auto_combined") metric_calls = [call for call in self.api.calls if urlsplit(call[1]).path == "/api/metrics"] self.assertEqual(len(metric_calls), 2) def test_candidate_release_is_rejected(self): with self.assertRaisesRegex(QualityToolError, "不是已发布版本"): self.tools.quality_data({"mode": "query", "releaseId": "candidate", "period": {"year": 2026, "month": 1}}) def test_top_product_category_preserves_basis_and_coverage(self): result = self.tools.quality_data({"mode": "top", "period": {"year": 2026, "month": 3}, "releaseId": RELEASE, "stage": "black", "dimension": "product", "category": "黑片责废"}) self.assertEqual(result["category"], "责废") self.assertIn("不表示总体贡献", result["shareBasis"]) self.assertIn("coverage", result) self.assertIn("亮片类别份额不必等同阶段正式报废重量", result["meaning"]) call = next(item for item in self.api.calls if urlsplit(item[1]).path == "/api/analytics/top") self.assertEqual(parse_qs(urlsplit(call[1]).query)["category"], ["责废"]) def test_catalog_describes_fine_defect_endpoint_without_calling_it(self): result = self.tools.quality_data({"mode": "catalog"}) capability = result["fineDefects"] self.assertEqual(capability["endpoint"], "POST /api/analysis/defects") self.assertIn("defect", capability["dimensions"]) self.assertFalse(capability["scanned"]) self.assertEqual(capability["fields"][0]["key"], "责废尺寸重量") catalog_call = next(call for call in self.api.calls if urlsplit(call[1]).path == "/api/analysis/defects") self.assertEqual(catalog_call[2]["mode"], "catalog") def test_defects_query_preserves_source_field_keys_and_filters(self): result = self.tools.quality_data({"mode": "defects", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}, "scope": "auto_domestic", "filters": {"department": "汽车交通", "product": "规格 A"}, "stage": "black", "dimension": "defect", "category": "黑片责废", "limit": 2}) self.assertEqual(result["grain"], "source_defect_weight") self.assertEqual(result["category"], "责废") self.assertEqual(result["selectedScope"], "auto_domestic") self.assertEqual(result["rows"][0]["key"], "责废尺寸重量") self.assertEqual(result["rowsReturned"], 2) self.assertIn("source_defect_weight", result["grain"]) call = next(item for item in self.api.calls if urlsplit(item[1]).path == "/api/analysis/defects") self.assertEqual(call[0], "POST") self.assertEqual(call[2]["releaseId"], RELEASE) self.assertEqual(call[2]["group"], "汽车交通-国内") self.assertEqual(call[2]["department"], "新能源汽车磁钢") self.assertEqual(call[2]["category"], "责废") def test_defects_accepts_java_normalized_scope_sets_but_rejects_added_values(self): class NormalizedScopeApi(FakeApi): def call(inner, path, payload=None, method=None): response = super().call(path, payload, method) if urlsplit(path).path == "/api/analysis/defects" and payload.get("mode") == "top": for key in ("department", "group", "product", "projectGroup"): value = response["context"].get(key) response["context"][key] = [] if value is None else [value] return response api = NormalizedScopeApi() tools = QualityTools(api_factory=lambda: api, evidence_dir=self.temp.name) # Java echoes the normalized empty sets for unset scope filters. empty_result = tools.quality_data({"mode": "defects", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}, "stage": "black", "dimension": "defect"}) self.assertTrue(empty_result["coverage"]["available"]) # A selected scalar and its singleton collection have the same scope. selected_result = tools.quality_data({"mode": "defects", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}, "filters": {"department": "部门A", "group": "组A", "product": "规格A", "projectGroup": "项目A"}, "stage": "black", "dimension": "defect"}) self.assertTrue(selected_result["coverage"]["available"]) original_call = api.call def added_scope_value(path, payload=None, method=None): response = original_call(path, payload, method) if urlsplit(path).path == "/api/analysis/defects" and payload.get("mode") == "top": response["context"]["group"] = [payload["group"], "未请求组"] return response api.call = added_scope_value with self.assertRaisesRegex(QualityToolError, "未确认 group"): tools.quality_data({"mode": "defects", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}, "filters": {"group": "组A"}, "stage": "black", "dimension": "defect"}) def test_defects_preserves_month_range_exclusions_and_authorized_column_filters(self): class AuthorizedColumnApi(FakeApi): def call(inner, path, payload=None, method=None): response = super().call(path, payload, method) if path == "/api/analysis/tools/catalog": response["sourceFields"] = [{"key": "customerCode", "label": "客户代码", "type": "source_value", "stages": ["black"], "columns": {"black": "customer_code"}, "operators": ["in"]}] return response api = AuthorizedColumnApi() tools = QualityTools(api_factory=lambda: api, evidence_dir=self.temp.name) rule = {"field": "customerCode", "stages": ["black"], "operator": "in", "values": ["C-17"]} result = tools.quality_data({"mode": "defects", "releaseId": RELEASE, "period": {"year": 2026, "monthStart": 3, "monthEnd": 9}, "filters": {"exclusions": {"product": ["规格甲"]}}, "columnFilters": [rule], "stage": "black", "dimension": "defect", "limit": 100}) request = next(payload for method, path, payload in reversed(api.calls) if method == "POST" and urlsplit(path).path == "/api/analysis/defects") self.assertEqual((request["monthStart"], request["monthEnd"]), (3, 9)) self.assertEqual(request["exclusions"], {"product": ["规格甲"]}) self.assertEqual(request["columnFilters"], [rule]) self.assertEqual(result["period"], {"year": 2026, "monthStart": 3, "monthEnd": 9}) self.assertEqual(result["filters"]["columnFilters"], [rule]) def test_reported_stage_defect_calls_default_missing_dimension_without_changing_scope(self): for stage in ("black", "bright"): with self.subTest(stage=stage): arguments = {"mode": "defects", "releaseId": RELEASE, "stage": stage, "period": {"year": 2026, "month": 3}, "comparisonPeriod": {"year": 2026, "month": 1}, "filters": {"product": "规格 A"}, "limit": 20} result = self.tools.quality_data(arguments) self.assertEqual(result["dimension"], "defect") self.assertEqual(result["stage"], stage) self.assertEqual(result["filters"]["product"], "规格 A") self.assertEqual(result["period"], arguments["period"]) self.assertEqual(result["comparisonPeriod"], arguments["comparisonPeriod"]) self.assertNotIn("dimension", arguments) def test_missing_defect_dimension_is_not_guessed_for_specific_field_queries(self): with self.assertRaisesRegex(QualityToolError, "dimension"): self.tools.quality_data({"mode": "defects", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}, "stage": "black", "defect": "责废尺寸重量"}) def test_defects_compare_full_outer_pairs_without_zero_filling(self): result = self.tools.quality_data({"mode": "defects", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}, "comparisonPeriod": {"year": 2026, "month": 1}, "stage": "black", "dimension": "defect", "limit": 10}) rows = {row["key"]: row for row in result["pairedRows"]} self.assertEqual(result["pairedTotalRows"], 4) self.assertAlmostEqual(rows["责废尺寸重量"]["deltaWeight"], 3) self.assertEqual(rows["责废刀丝重量"]["changeType"], "new") self.assertFalse(rows["责废刀丝重量"]["deltaAvailable"]) self.assertIsNone(rows["责废刀丝重量"]["deltaWeight"]) self.assertEqual(rows["责废缺角重量"]["changeType"], "exit") self.assertIsNone(rows["责废缺角重量"]["deltaWeight"]) calls = [call for call in self.api.calls if urlsplit(call[1]).path == "/api/analysis/defects"] self.assertEqual([call[2]["limit"] for call in calls], [100, 100]) def test_single_defect_top_fetches_bounded_candidates_before_presentation_limit(self): result=self.tools.quality_data({'mode':'defects','releaseId':RELEASE,'period':{'year':2026,'month':3}, 'stage':'black','dimension':'defect','limit':1}) calls=[call for call in self.api.calls if urlsplit(call[1]).path=='/api/analysis/defects'] self.assertEqual(calls[-1][2]['limit'],100) self.assertEqual(len(result['rows']),1);self.assertEqual(result['totalRows'],3) self.assertTrue(result['rankingComplete']);self.assertTrue(result['truncated']) self.assertEqual(result['rows'][0]['weight'],13) def test_defects_product_ranking_requires_concrete_defect(self): with self.assertRaisesRegex(QualityToolError, "必须指定 defect"): self.tools.quality_data({"mode": "defects", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}, "stage": "black", "dimension": "product"}) result = self.tools.quality_data({"mode": "defects", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}, "stage": "black", "dimension": "product", "defect": "责废尺寸重量"}) self.assertEqual(result["rows"][0]["label"], "规格 A") self.assertEqual(result["defect"], "责废尺寸重量") def test_defect_delta_ranking_precedes_limit_and_keeps_negative_order(self): def snapshot(values): return {"available": True, "rowsTruncated": False, "rows": [{"key": key, "weight": weight} for key, weight in values.items()]} current = snapshot({"a": 8, "b": 4, "龘": 30, "missing": None}) previous = snapshot({"a": 10, "b": 5, "龘": 10, "missing": 2}) paired = QualityTools._pair_defect_snapshots(current, previous, "defect", "scrap_delta") self.assertEqual([row["key"] for row in paired["rows"]], ["龘", "b", "a", "missing"]) self.assertEqual(paired["rows"][0]["deltaWeight"], 20) def test_defects_rejects_duplicate_keys_or_unconfirmed_context(self): original_call = self.api.call def duplicate_call(path, payload=None, method=None): result = original_call(path, payload, method) if urlsplit(path).path == "/api/analysis/defects": result["rows"].append(dict(result["rows"][0])) return result self.api.call = duplicate_call with self.assertRaisesRegex(QualityToolError, "重复 key"): self.tools.quality_data({"mode": "defects", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}, "stage": "black", "dimension": "defect"}) self.api.call = original_call def wrong_context(path, payload=None, method=None): result = original_call(path, payload, method) if urlsplit(path).path == "/api/analysis/defects": result["context"]["product"] = "另一个规格" return result self.api.call = wrong_context with self.assertRaisesRegex(QualityToolError, "未确认 product"): self.tools.quality_data({"mode": "defects", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}, "filters": {"product": "规格 A"}, "stage": "black", "dimension": "defect"}) def test_full_outer_change_marks_new_and_exit_and_does_not_fill_rates(self): self.api.products = { 1: [FakeApi._product_row("a", "规格 A", 10, 5), FakeApi._product_row("b", "规格 B", 4, 2)], 3: [FakeApi._product_row("a", "规格 A", 13, 4), FakeApi._product_row("c", "规格 C", 2, 1)], } result = self.tools.quality_data({"mode": "changes", "period": {"year": 2026, "month": 3}, "releaseId": RELEASE, "comparisonPeriod": {"year": 2026, "month": 1}, "dimension": "product", "limit": 10}) by_key = {row["key"]: row for row in result["rows"]} self.assertEqual(result["totalRows"], 3) self.assertEqual(by_key["c"]["changeType"], "new") self.assertEqual(by_key["c"]["comparison"]["scrapWeight"], 0) self.assertIsNone(by_key["c"]["comparison"]["rate"]) self.assertEqual(by_key["b"]["changeType"], "exit") self.assertEqual(by_key["b"]["current"]["scrapWeight"], 0) self.assertIsNone(by_key["b"]["current"]["rate"]) self.assertIn("black + bright 两阶段", result["weightBasis"]) self.assertNotIn("totalWeight", by_key["c"]["current"]) self.assertIn("blackInputWeight", by_key["c"]["current"]) self.assertIn("brightInputWeight", by_key["c"]["current"]) self.assertNotIn("crossStageWeightSum", by_key["c"]["current"]) self.assertNotIn("totalWeightDelta", by_key["c"]) self.assertEqual([row["rank"] for row in result["rows"]], [1, 2, 3]) self.assertIn("不等于独立投入", by_key["c"]["volumeNote"]) self.assertIn("正式 compositeRate", result["rateBasis"]) signals = result["prioritySignals"] self.assertEqual(signals["scrapIncrease"][0]["label"], "规格 C") self.assertIn("blackInputWeight", signals["scrapIncrease"][0]["current"]) self.assertIn("brightInputWeight", signals["scrapIncrease"][0]["comparison"]) self.assertIn("不是统一贡献分数", signals["basis"]) def test_duplicate_and_missing_row_keys_are_rejected(self): with self.assertRaisesRegex(QualityToolError, "重复 key"): QualityTools._index_rows({"rows": [{"key": "x"}, {"key": "x"}]}, "product", "current") with self.assertRaisesRegex(QualityToolError, "空 key"): QualityTools._index_rows({"rows": [{"key": None}]}, "product", "current") def test_category_absence_is_null_and_present_row_missing_stage_is_null(self): row = {"key": "x", "black": {"scrapWeight": None, "defects": []}, "bright": {"scrapWeight": 5}} self.assertIsNone(QualityTools._row_scrap(row, "black", "责废")) self.assertIsNone(QualityTools._row_scrap({"key": "x", "black": None, "bright": {"scrapWeight": 5}}, None, None)) self.assertEqual(QualityTools._row_scrap(None, None, None), 0) def test_changes_rate_requires_row_level_stage_coverage(self): row = {"compositeRate": 0.95, "black": {"rate": 0.96, "totalWeight": 4, "qualifiedWeight": 3}, "bright": {"rate": 0.99, "totalWeight": 0, "qualifiedWeight": 0}, "coverage": {"blackRows": 3, "brightRows": 0}} self.assertIsNone(QualityTools._row_rate(row, None)) self.assertAlmostEqual(float(QualityTools._row_rate(row, "black")), 0.96) self.assertIsNone(QualityTools._row_rate(row, "bright")) self.assertIsNone(QualityTools._row_rate({**row, "coverage": None}, "black")) positive = {**row, "bright": {"rate": 0.99, "totalWeight": 5, "qualifiedWeight": 4}, "coverage": {"blackRows": 3, "brightRows": 2}} self.assertAlmostEqual(float(QualityTools._row_rate(positive, None)), 0.95) def test_details_always_labels_bounded_sample(self): result = self.tools.quality_data({"mode": "details", "period": {"year": 2026, "month": 3}, "releaseId": RELEASE, "stage": "black", "limit": 5}) self.assertTrue(result["sampled"]) self.assertTrue(result["truncated"]) self.assertIn("不能当总体排名", result["notice"]) def test_catalog_returns_concise_periods_and_release_binding(self): result = self.tools.quality_data({"mode": "catalog"}) self.assertEqual(result["releaseId"], RELEASE) self.assertEqual(result["periods"]["years"], [2025, 2026]) self.assertEqual(result["periods"]["availableMonthsInLatestYear"], list(range(1, 13))) def test_empty_coverage_is_an_error_not_success(self): original_call = self.api.call def empty_call(path, payload=None, method=None): parsed = urlsplit(path) if parsed.path == "/api/metrics": result = original_call(path, payload, method) result["coverage"]["rawRows"] = 0 result["coverage"]["includedRows"] = 0 return result return original_call(path, payload, method) self.api.call = empty_call with self.assertRaisesRegex(QualityToolError, "2026年3月.*没有可用的已发布来源数据"): self.tools.quality_data({"mode": "query", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}}) def test_custom_formula_metadata_survives_query_and_both_comparison_sides(self): original=self.api.call rules={'combined':'configured_custom_formula','supportsStageContribution':False} descriptions={'rate':'正式自定义综合率'} def with_rules(path,payload=None,method=None): result=original(path,payload,method) if urlsplit(path).path == '/api/metrics': result['context'].update(calculationRules=rules,metricFormulaDescriptions=descriptions) return result self.api.call=with_rules queried=self.tools.quality_data({'mode':'query','releaseId':RELEASE,'period':{'year':2026,'month':3}}) self.assertEqual(queried['calculationRules'],rules) compared=self.tools.quality_data({'mode':'compare','releaseId':RELEASE, 'period':{'year':2026,'month':3},'comparisonPeriod':{'year':2026,'month':2}}) for side in ('current','comparison'): self.assertEqual(compared[side]['calculationRules'],rules) self.assertEqual(compared[side]['metricFormulaDescriptions'],descriptions) def test_mcp_json_rpc_initialize_list_ping_and_notification(self): server = MCPServer(tools=self.tools) initialized = server.handle({"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05"}}) self.assertEqual(initialized["result"]["serverInfo"]["name"], "quality") listed = server.handle({"jsonrpc": "2.0", "id": 2, "method": "tools/list"}) self.assertEqual([tool["name"] for tool in listed["result"]["tools"]], ["quality_data"]) self.assertEqual(server.handle({"jsonrpc": "2.0", "method": "notifications/initialized"}), None) self.assertEqual(server.handle({"jsonrpc": "2.0", "id": 3, "method": "ping"})["result"], {}) def test_mcp_initialize_negotiates_newer_client_protocol(self): server = MCPServer(tools=self.tools) response = server.handle({"jsonrpc": "2.0", "id": "new-client", "method": "initialize", "params": {"protocolVersion": "2025-11-25"}}) self.assertEqual(response["result"]["protocolVersion"], "2025-03-26") def test_mcp_tools_call_and_newline_stdio(self): server = MCPServer(tools=self.tools, logger=logging.getLogger("test.nao_quality_mcp")) call = server.handle({"jsonrpc": "2.0", "id": 8, "method": "tools/call", "params": {"name": "quality_data", "arguments": { "mode": "query", "releaseId": RELEASE, "period": {"year": 2026, "month": 3}}}}) self.assertEqual(call["result"]["structuredContent"]["releaseId"], RELEASE) self.assertFalse(call["result"]["isError"]) request_lines = [ {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05"}}, {"jsonrpc": "2.0", "method": "notifications/initialized"}, {"jsonrpc": "2.0", "id": 2, "method": "tools/list"}, {"jsonrpc": "2.0", "id": 3, "method": "ping"}, ] source = io.StringIO("\n".join(json.dumps(item) for item in request_lines) + "\n") output = io.StringIO() from unittest.mock import patch with patch("nao_quality_mcp._configure_logger", return_value=logging.getLogger("test.nao_quality_mcp")): serve(source, output, tools=self.tools) responses = [json.loads(line) for line in output.getvalue().splitlines()] self.assertEqual([item["id"] for item in responses], [1, 2, 3]) self.assertEqual(responses[1]["result"]["tools"][0]["name"], "quality_data") if __name__ == "__main__": unittest.main()