"""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、变化线索、具体缺陷聚合和有界明细样本。" "investigate提供全量相关统计、分页明细、字段字典、冻结规则映射和归档原表核验。仅当差额明显改变结论、来源失败、范围不一致或用户要求核对原件/完整记录时进一步调查;VCM亮片仅录合计及普通小额差异按业务口径说明,不自动专项核验。不推断现场原因。先调用 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": { "freshQuery": {"type": "boolean", "description": "仅明确要求重新执行相同查询时为true,默认false;自主调查中其他相同查询复用当轮证据。"}, "mode": {"type": "string", "enum": ["catalog", "query", "rank", "compare", "top", "changes", "defects", "details", "investigate"], "description": "先用 catalog 取发布版本;rank按单期正式分组重量全量排序后选Top,生产重量柏拉图必须用rank而非query截断结果。"}, "metric": {"type":"string","enum":["totalWeight","scrapWeight"],"description":"仅rank使用:totalWeight阶段生产/投入重量,scrapWeight阶段报废重量;占比分母为同范围全部分组的正式重量。"}, "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为总体;auto_combined是汽车交通业务别名,即department=新能源汽车磁钢,并非group多选;auto_domestic/auto_overseas为明确的国内/海外子分组。优先沿用本轮_agentTask.filters。显式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}, "monthStart": {"type": "integer", "minimum": 1, "maximum": 12}, "monthEnd": {"type": "integer", "minimum": 1, "maximum": 12}, }, "required": ["year"], "description": "期间;year必填,可选month、quarter或成对monthStart/monthEnd,三种不能混用;连续月份不能只传最后一月。", }, "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}, "monthStart": {"type": "integer", "minimum": 1, "maximum": 12}, "monthEnd": {"type": "integer", "minimum": 1, "maximum": 12}, }, "required": ["year"], "description": "仅compare/changes/defects/investigate可用;top禁止传入。investigate用于核验/分页读取两个已确认期间。对照期间;使用同一 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__。"}, "exclusions": {"type": "object", "additionalProperties": False, "properties": {key: {"type": "array", "minItems": 1, "maxItems": 50, "items": {"type": "string", "minLength": 1, "maxLength": 256}} for key in ("department", "group", "product", "projectGroup")}, "description": "排除的维度值;空或未分配值使用 __UNASSIGNED__。支持 query/rank/compare/changes/details/investigate/defects,其他模式明确拒绝。"}, "includeUnassigned": {"type": "boolean"}, }, "description": "实际筛选值会原样传递给正式 API;工具不会忽略未知或冲突的筛选。", }, "columnFilters": {"type": ["array", "null"], "maxItems": 20, "items": {"type": "object", "additionalProperties": False, "properties": { "field": {"type": "string", "minLength": 1}, "stages": {"type": "array", "minItems": 1, "maxItems": 2, "items": {"type": "string", "enum": ["black", "bright"]}}, "operator": {"type": "string", "enum": ["in", "not_in", "is_empty", "not_empty"]}, "values": {"type": "array", "minItems": 1, "maxItems": 50, "items": {"type": "string", "maxLength": 256}}, }, "required": ["field", "stages", "operator"]}, "description": "仅query/compare/rank/investigate/defects使用。必须是当前catalog.sourceFields授权的完整替换列表;null或[]清除全部。规则AND、values OR,文本大小写、空格及前导零按原文匹配。is_empty/not_empty不得带values。"}, "view": {"type": "string", "enum": ["overall", "department", "group", "product", "projectGroup"], "description": "query 的正式分组视图;changes 仅支持非 overall 维度。"}, "stage": {"type": ["string", "null"], "enum": ["black", "bright", None], "description": "top/details/defects/investigate必须明确black/bright。rank单阶段传black/bright;rank的metric=scrapWeight且stage省略或null时,合计黑片+亮片报废总重全量排序,并保留正式综合合格率。投入重量rank仍必须指定阶段。changes可选,未传为综合范围。"}, "dimension": {"type": "string", "enum": ["category", "defect", "product", "department", "group", "projectGroup"], "description": "top模式仅category/product/department/group/projectGroup,不能用defect;具体缺陷TOP必须使用mode=defects、dimension=defect。product是规格。changes 使用 product/department/group/projectGroup。defects 使用 defect 或 product;未指定具体 defect 字段时,省略 dimension 默认按 defect 查询阶段具体缺陷。"}, "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": 100000, "description": "结果上限;investigate.action=source最多核验100000行,rows每页最多100行;details/defects最多100行。"}, "action": {"type":"string","enum":["overview","rows","fields","source"],"description":"investigate动作:overview全量统计/冻结规则,source核验归档原表(最多100000),rows分页明细,fields字段字典。用户要求核验或主要结论受影响时使用;正常统计不必为小额差异专项调查。"}, "offset": {"type":"integer","minimum":0,"maximum":10000000}, "recordFilter": {"type":"string","enum":["all","differences","unexpectedDifferences"]}, "sourceRevisionId": {"type":"string","minLength":1,"maxLength":64}, "fields": {"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"minItems":1,"maxItems":32,"description":"investigate选择源字段;省略时核对所选大类全部细分和总计。先fields查字典,不能猜列。"}, "sort": {"type": "string", "enum": ["scrap_delta", "current_scrap", "rate_drop", "current_rate"], "description": "仅changes/defects可用;top禁止传入。changes 排序:报废增量、当前报废重量、率下降、本期合格率最低;defects 仅支持 current_scrap 或 scrap_delta。"}, }, "required": ["mode"], "allOf": [{ "if": {"properties": {"mode": {"not": {"const": "catalog"}}}, "required": ["mode"]}, "then": {"required": ["releaseId"]}, }, { "if": {"properties": {"mode": {"enum": ["top", "defects", "details", "investigate"]}}, "required": ["mode"]}, "then": {"required": ["stage"]}, }, { "if": {"properties": {"mode": {"const": "top"}}, "required": ["mode"]}, "then": {"properties": {"dimension": {"enum": ["category", "product", "department", "group", "projectGroup"]}}}, }, { "if": {"properties": {"mode": {"const": "defects"}}, "required": ["mode"]}, "then": {"properties": {"dimension": {"enum": ["defect", "product"]}}}, }, { "if": {"properties": {"mode": {"const": "defects"}, "dimension": {"const": "product"}}, "required": ["mode", "dimension"]}, "then": {"required": ["defect"]}, }], "additionalProperties": False, } class QualityToolError(ValueError): """Safe, actionable error suitable for a model-facing tool response.""" class SourceCoverageUnavailable(QualityToolError): """A bound official response has no source rows; defaults are not facts.""" def __init__(self, period): from nao_evidence_report import period as period_label super().__init__(period_label(period) + '在当前筛选下没有可用的已发布来源数据,无法给出正式指标;查询期间和筛选已保留。') self.period = copy.deepcopy(period) 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 _private_rank_response_trace(response: Any) -> dict[str, Any]: """Summarize the exact ranking snapshot for private failure diagnosis only. Do not persist dimension keys/labels, filters, query strings, or arbitrary response fields. The returned shape is enough to distinguish absent stage sources from missing/invalid formal totals and grouping values. """ if not isinstance(response, dict): return {'responseType': type(response).__name__} def count_value(value): return value if type(value) is int and value >= 0 else None def count_state(mapping, key): if not isinstance(mapping, dict) or key not in mapping: return 'missing' return 'known' if count_value(mapping.get(key)) is not None else 'invalid' def numeric_value(value): number = _number(value) return str(number) if number is not None else None coverage = response.get('coverage') coverage = coverage if isinstance(coverage, dict) else {} summary = response.get('summary') summary = summary if isinstance(summary, dict) else {} summary_coverage = summary.get('coverage') summary_coverage = summary_coverage if isinstance(summary_coverage, dict) else {} context = response.get('context') context = context if isinstance(context, dict) else {} source_months = [] raw_months = coverage.get('sourceMonths') if isinstance(raw_months, list): for item in raw_months[:36]: if not isinstance(item, dict): continue entry = {key: count_value(item.get(key)) for key in ('year', 'month', 'blackRows', 'brightRows')} entry['countStates'] = {key: count_state(item, key) for key in ('blackRows', 'brightRows')} source_months.append(entry) missing_stages = [] raw_missing = coverage.get('missingStages') if isinstance(raw_missing, list): for item in raw_missing[:36]: if not isinstance(item, dict): continue stage = item.get('stage') entry = {key: count_value(item.get(key)) for key in ('year', 'month')} entry['stage'] = stage if stage in ('black', 'bright') else None entry['stageState'] = 'known' if stage in ('black', 'bright') else 'invalid-or-missing' missing_stages.append(entry) stage_blocks = {} for stage in ('black', 'bright'): value = summary.get(stage) block = value if isinstance(value, dict) else None stage_blocks[stage] = { 'present': block is not None, 'keys': sorted(key for key in block if key in { 'rate', 'scrapRate', 'qualifiedWeight', 'scrapWeight', 'totalWeight', 'headquartersScrapWeight', 'rateWithoutHeadquartersScrap', 'defects' }) if block is not None else [], 'values': ({key: numeric_value(block.get(key)) for key in ( 'rate', 'scrapRate', 'qualifiedWeight', 'scrapWeight', 'totalWeight', 'headquartersScrapWeight', 'rateWithoutHeadquartersScrap' ) if key in block} if block is not None else {}), } rows = response.get('rows') rows = rows if isinstance(rows, list) else None row_shape = {'count': len(rows) if rows is not None else None, 'contextRowCount': count_value(context.get('rowCount')), 'stageCoverage': {'blackRows': 0, 'brightRows': 0, 'missing': {'blackRows': 0, 'brightRows': 0}, 'invalid': {'blackRows': 0, 'brightRows': 0}}, 'stageBlocks': {stage: {'missing': 0, 'null': 0, 'object': 0, 'other': 0} for stage in ('black', 'bright')}, 'sample': []} if rows is not None: for row in rows: if not isinstance(row, dict): for stage in ('black', 'bright'): row_shape['stageCoverage']['invalid'][stage + 'Rows'] += 1 for stage in ('black', 'bright'): row_shape['stageBlocks'][stage]['other'] += 1 continue row_coverage = row.get('coverage') for stage in ('black', 'bright'): field = stage + 'Rows' state = count_state(row_coverage, field) if state == 'known': row_shape['stageCoverage'][field] += count_value(row_coverage[field]) else: row_shape['stageCoverage'][state][field] += 1 if len(row_shape['sample']) < 12: sample = {'compositeRate': numeric_value(row.get('compositeRate')), 'coverage': {stage + 'Rows': count_value((row.get('coverage') or {}).get(stage + 'Rows')) for stage in ('black', 'bright')} if isinstance(row.get('coverage'), dict) else None, 'coverageStates': {stage + 'Rows': count_state(row.get('coverage'), stage + 'Rows') for stage in ('black', 'bright')}, 'stages': {}} for stage in ('black', 'bright'): block = row.get(stage, '__missing__') if block == '__missing__': row_shape['stageBlocks'][stage]['missing'] += 1 sample['stages'][stage] = {'state': 'missing'} elif block is None: row_shape['stageBlocks'][stage]['null'] += 1 sample['stages'][stage] = {'state': 'null'} elif isinstance(block, dict): row_shape['stageBlocks'][stage]['object'] += 1 sample['stages'][stage] = { 'state': 'object', 'values': {key: numeric_value(block.get(key)) for key in ( 'rate', 'scrapRate', 'qualifiedWeight', 'scrapWeight', 'totalWeight', 'headquartersScrapWeight', 'rateWithoutHeadquartersScrap' ) if key in block}, } else: row_shape['stageBlocks'][stage]['other'] += 1 sample['stages'][stage] = {'state': 'other'} row_shape['sample'].append(sample) else: for stage in ('black', 'bright'): block = row.get(stage, '__missing__') if block == '__missing__': row_shape['stageBlocks'][stage]['missing'] += 1 elif block is None: row_shape['stageBlocks'][stage]['null'] += 1 elif isinstance(block, dict): row_shape['stageBlocks'][stage]['object'] += 1 else: row_shape['stageBlocks'][stage]['other'] += 1 evidence = response.get('protocolEvidence') evidence = evidence if isinstance(evidence, dict) else {} query_id = evidence.get('queryId') if not isinstance(query_id, str) or not re.fullmatch(r'[A-Za-z0-9_-]{1,128}', query_id): query_id = None response_hash = evidence.get('responseHash') if not isinstance(response_hash, str) or not re.fullmatch(r'[a-fA-F0-9]{64}', response_hash): response_hash = None return { 'queryId': query_id, 'responseHash': response_hash, 'responseKeys': sorted(key for key in response if key in { 'kind', 'release', 'releaseId', 'context', 'summary', 'rows', 'coverage', 'protocolEvidence' }), 'context': {key: context.get(key) for key in ('view', 'year', 'month', 'quarter', 'monthStart', 'monthEnd') if type(context.get(key)) is int or context.get(key) in ('overall', 'product', 'department', 'group')}, 'coverage': { key: count_value(coverage.get(key)) for key in ( 'rawRows', 'includedRows', 'excludedBlankRows', 'unmappedRows', 'projectGroupUnconfiguredRows' ) if key in coverage }, 'coverageSourceMonths': source_months, 'coverageMissingStages': missing_stages, 'summaryCoverage': {key: count_value(summary_coverage.get(key)) for key in ('blackRows', 'brightRows') if key in summary_coverage}, 'summaryCompositeRate': numeric_value(summary.get('compositeRate')), 'summaryStages': stage_blocks, 'rows': row_shape, } 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_composite_rate_reference(snapshot: dict[str, Any], period: dict[str, int]) -> tuple[bool, str | None]: """Validate a server-provided composite rate without rebuilding its formula. Every requested month must have known counts for both stages and a positive source count for at least one of them. When a snapshot supplies stage denominators, at least one source-covered stage must also have a positive total weight. Legacy snapshots that omit denominator fields can still use known-positive source-row coverage and the official composite. """ coverage = snapshot.get("coverage") months = coverage.get("sourceMonths") if isinstance(coverage, dict) else None if not isinstance(months, list): return False, "接口未返回分阶段月份覆盖。" from nao_period import expected_months try: expected = expected_months(period) except ValueError: return False, "业务期间无效,不能核验综合率来源覆盖。" observed: dict[int, dict[str, Any]] = {} for item in months: if not isinstance(item, dict) or item.get("year") != period["year"]: continue month = item.get("month") if type(month) is int and 1 <= month <= 12: if month in observed: return False, f"{period['year']}-{month:02d}存在重复的阶段来源覆盖。" observed[month] = item source_months = {"black": set(), "bright": set()} for month in expected: item = observed.get(month) if item is None: return False, f"所选期间缺少综合率来源月份:{period['year']}-{month:02d}。" counts = {} for stage in ("black", "bright"): field = f"{stage}Rows" value = item.get(field) if type(value) is not int or value < 0: return False, f"{period['year']}-{month:02d}{field}覆盖未知或不合法。" counts[stage] = value if value > 0: source_months[stage].add(month) if not any(counts.values()): return False, f"{period['year']}-{month:02d}两阶段均无有效来源。" summary = snapshot.get("summary") if not isinstance(summary, dict): # Comparison snapshots carry the same formal fields at their top level. summary = snapshot composite = _number(summary.get("compositeRate"), minimum=Decimal(0)) if composite is None: return False, "服务端正式compositeRate缺失或不合法。" stage_summaries = {stage: _stage_summary(summary, stage) for stage in ("black", "bright")} denominator_explicit = any("totalWeight" in values for values in stage_summaries.values()) if denominator_explicit: positive_denominator = any( bool(source_months[stage]) and (_number(stage_summaries[stage].get("totalWeight"), minimum=Decimal(0)) or Decimal(0)) > 0 for stage in ("black", "bright") ) if not positive_denominator: return False, "没有来源有效且总投入大于0的阶段,不能引用综合率。" return True, None def _row_composite_rate(row: dict[str, Any]) -> Decimal | None: """Reference an official row rate with either measured stage as its source. Coverage must be known for both stages. The server owns stage substitution; this check neither rebuilds that formula nor copies stage weights. """ coverage = row.get("coverage") if not isinstance(coverage, dict): return None counts = {stage: coverage.get(stage + "Rows") for stage in ("black", "bright")} if any(type(count) is not int or count < 0 for count in counts.values()): return None if not any(counts[stage] > 0 and isinstance(row.get(stage), dict) and (_number((row.get(stage) or {}).get("totalWeight")) or Decimal(0)) > 0 for stage in counts): return None return _number(row.get("compositeRate"), minimum=Decimal(0)) 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: return False, f"{stage}阶段正式率缺失或为负,不能比较。" 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_rate_reference(snapshot: dict[str, Any], period: dict[str, int], stage: str) -> tuple[bool, str | None]: """Validate a backend stage-rate reference for display without recomputing it. Unlike stage decomposition, citing the backend's already-computed rate does not require a separate qualifiedWeight value. A positive total and known source coverage are still required so a default rate of 1 is not presented as observed data. """ 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") if rate is None or rate < 0: return False, f"{stage}阶段正式率缺失或为负,不能引用。" if total_weight is None or total_weight <= 0: return False, f"{stage}阶段总投入缺失或为0,不能引用率。" return True, None def _valid_stage_scrap_rate_reference(snapshot: dict[str, Any], period: dict[str, int], stage: str) -> tuple[bool, str | None]: """Validate an official stage scrap-rate reference and its formal weights.""" coverage_ok, reason = _valid_stage_period_coverage(snapshot, period, stage) if not coverage_ok: return False, reason total_weight = _stage_metric(snapshot, stage, "totalWeight") scrap_weight = _stage_metric(snapshot, stage, "scrapWeight") scrap_rate = _stage_metric(snapshot, stage, "scrapRate") if total_weight is None or total_weight <= 0: return False, f"{stage}阶段总投入缺失或为0,不能引用报废率。" if scrap_weight is None or scrap_weight < 0: return False, f"{stage}阶段报废重量缺失或为负,不能引用报废率。" if scrap_rate is None or scrap_rate < 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, "接口未返回分阶段月份覆盖" from nao_period import expected_months try: expected = expected_months(period) except ValueError: return False, "业务期间无效,不能核验阶段来源覆盖。" 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 type(month_number) is int and 1 <= month_number <= 12: observed[month_number] = item field = "blackRows" if stage == "black" else "brightRows" missing = [m for m in expected if m not in observed or _number(observed[m].get(field), minimum=Decimal(1)) is None] 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): # Comparison sides and compacted single-period snapshots may expose # formal stage blocks directly at the top level. summary = snapshot 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)), _number(bright_current, minimum=Decimal(0)), _number(black_comparison, minimum=Decimal(0)), _number(bright_comparison, minimum=Decimal(0)), _number(composite_delta), ] if any(value is None for value in values): return {"status": "unavailable", "reason": "阶段正式率缺失、为负或不是有限数值,不能拆解。", "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 from nao_period import normalize_period as canonical_period try: result = canonical_period(raw) except ValueError as error: raise QualityToolError(f"{name} 无效:{error}") from None if not 2000 <= result['year'] <= 2100: raise QualityToolError(f"{name}.year 必须是 2000 到 2100 的整数。") 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 必须是对象。") from nao_query_contract import canonical_filters try: raw = canonical_filters(raw) except ValueError as error: raise QualityToolError(str(error)) from None allowed = {"department", "group", "product", "projectGroup", "extraFilters", "exclusions", "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} exclusions = raw.get("exclusions", {}) if not isinstance(exclusions, dict): raise QualityToolError("exclusions 必须是维度到字符串数组的对象。") normalized_exclusions = {} for key, values in exclusions.items(): if key not in {"department", "group", "product", "projectGroup"} or not isinstance(values, list) or not 1 <= len(values) <= 50 or any(not isinstance(v, str) or not v.strip() or len(v) > 256 for v in values): raise QualityToolError("exclusions 只支持 department/group/product/projectGroup,每项须为 1 到 50 个有效字符串。") normalized_exclusions[key] = list(dict.fromkeys(values)) if normalized_exclusions: result["exclusions"] = normalized_exclusions include = raw.get("includeUnassigned", False) if not isinstance(include, bool): raise QualityToolError("filters.includeUnassigned 必须是布尔值。") result["includeUnassigned"] = include scope_group = SCOPES[scope] if scope == 'auto_combined': if result.get('department') not in (None, '新能源汽车磁钢'): raise QualityToolError('汽车交通别名与产业部范围冲突。') result['department'] = '新能源汽车磁钢' elif 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, query_contract: dict | None = None, ) -> 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() self._query_contract = query_contract 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,list)) 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, column_filters: list[dict[str, Any]] | None = None) -> 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", "monthStart", "monthEnd"): 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("exclusions", {}) != filters.get("exclusions", {}): raise QualityToolError("正式指标接口未确认排除条件;结果已拒绝。") if context.get("view") != view: raise QualityToolError(f"正式指标接口未确认 view={view};结果已拒绝。") if column_filters is not None: receipts = [response.get('filters'), context.get('filters')] echoed = [item.get('columnFilters') for item in receipts if isinstance(item, dict) and 'columnFilters' in item] if 'columnFilters' in context: echoed.append(context.get('columnFilters')) # An empty replacement clears all rules. The metrics API omits an # empty list from its echo; absence is equivalent only in this case. if not echoed and column_filters or any(item != column_filters for item in echoed): raise QualityToolError('正式指标接口未原样确认 filters.columnFilters;结果已拒绝。') 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 SourceCoverageUnavailable(period) 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, column_filters: list[dict[str, Any]] | None = None) -> 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", "exclusions"): if key in filters: params[key] = filters[key] if column_filters is not None: params['columnFilters'] = copy.deepcopy(column_filters) 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, column_filters) 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", "scrapRate", "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, column_filters: list[dict[str, Any]] | None = None) -> dict[str, Any]: response = self._metrics(release["id"], period, filters, view, row_limit=limit, column_filters=column_filters) 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, "columnFilters": copy.deepcopy(column_filters)} if column_filters is not None else 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")), **{key:copy.deepcopy(context[key]) for key in ('calculationRules','metricFormulaDescriptions') if key in context}, **({"protocolEvidence": response["protocolEvidence"]} if isinstance(response.get("protocolEvidence"),dict) else {}), "basis": "rate 和重量来自正式 MetricsController;本工具只做有界裁剪,不重算正式 KPI。", } @staticmethod def _metric_difference(current: dict[str, Any], comparison: dict[str, Any]) -> dict[str, Any]: current_ok, current_reason = _valid_composite_rate_reference(current, current["_period"]) comparison_ok, comparison_reason = _valid_composite_rate_reference(comparison, comparison["_period"]) valid = current_ok and comparison_ok now = _number((current.get("summary") or {}).get("compositeRate"), minimum=Decimal(0)) old = _number((comparison.get("summary") or {}).get("compositeRate"), minimum=Decimal(0)) 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, column_filters: list[dict[str, Any]] | None = None) -> dict[str, Any]: options = {"column_filters": column_filters} if column_filters is not None else {} current_raw = self._metrics(release["id"], current_period, filters, "overall", **options) comparison_raw = self._metrics(release["id"], comparison_period, filters, "overall", **options) 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: current_stages_ok, current_stages_reason = _valid_period_coverage(current_raw, current_period) comparison_stages_ok, comparison_stages_reason = _valid_period_coverage(comparison_raw, comparison_period) if not current_stages_ok or not comparison_stages_ok: contribution = {"status": "unavailable", "reason": current_stages_reason if not current_stages_ok else comparison_stages_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,"columnFilters":copy.deepcopy(column_filters)} if column_filters is not None else filters), **({"protocolEvidence":[current_raw["protocolEvidence"],comparison_raw["protocolEvidence"]]} if isinstance(current_raw.get("protocolEvidence"),dict) and isinstance(comparison_raw.get("protocolEvidence"),dict) else {}), "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")), **{key:copy.deepcopy(response.get('context',{}).get(key)) for key in ('calculationRules','metricFormulaDescriptions') if key in response.get('context',{})}, **({'protocolEvidence': copy.deepcopy(response['protocolEvidence'])} if isinstance(response.get('protocolEvidence'), dict) else {})} 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 if stage is None: return _row_composite_rate(row) 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)) 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)) @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 getattr(self, '_bulk_changes', False) or sort == 'current_rate': if category is not None: raise QualityToolError('正式批量比较不支持类别排序;请查询正式类别或来源缺陷。') if dimension not in ('department', 'group', 'product'): raise QualityToolError('正式批量比较支持department/group/product。') batch_filters = copy.deepcopy(filters) if self._query_contract and self._query_contract.get('exactScope'): batch_filters = copy.deepcopy(self._query_contract['task'].get('filters') or {}) elif batch_filters.get('includeUnassigned') is False: batch_filters.pop('includeUnassigned') result = self._call('POST', '/api/analysis/changes', payload={ 'releaseId': release['id'], 'period': current_period, 'comparisonPeriod': comparison_period, 'filters': batch_filters, 'dimension': dimension, 'stage': stage, 'sort': sort, 'fields': ['rate', 'totalWeight', 'scrapWeight'], 'limit': min(limit, 10), }) from nao_evidence_report import _filters if (result.get('kind') != 'quality_changes' or result.get('completeRanking') is not True or result.get('sort') != sort or _filters(result.get('filters')) != _filters(filters)): raise QualityToolError('正式批量比较未返回同范围完整排名。') return result 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_composite_rate_reference(current_raw, current_period) comparison_coverage_ok, comparison_coverage_reason = _valid_composite_rate_reference(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 priority_signals = None if dimension == "product" and category is None: # Three separate, full-population rankings keep size, change and # rate signals visible without inventing a business weight or # treating a tiny denominator as proof of a major problem. def signal(record: dict[str, Any]) -> dict[str, Any]: return {key: record.get(key) for key in ("key", "label", "changeType", "scrapDelta", "rateDrop", "current", "comparison")} def ranked(value, *, positive=True): candidates = [(value(row), row) for row in records] candidates = [(amount, row) for amount, row in candidates if amount is not None and (amount > 0 if positive else amount >= 0)] candidates.sort(key=lambda pair: (-pair[0], str(pair[1]["key"]))) return [_json_safe(signal(row)) for _, row in candidates[:5]] priority_signals = { "scrapIncrease": ranked(lambda row: row.get("scrapDelta")), "currentScrap": ranked(lambda row: row.get("current", {}).get("scrapWeight")), "rateDrop": ranked(lambda row: row.get("rateDrop")), "basis": "分别按正向报废增量、本期报废重量、可比合格率降幅排序;各项保留两期分阶段投入或单阶段投入。" "三列不是统一贡献分数;小投入与新增/退出规格需单独解释,不能仅凭率降幅或重量称为生产根因。", } 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 response = { "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 要求两期来源覆盖已知且每行至少一个有来源阶段的正式总重为正。"), "coverage": {"current": current_coverage, "comparison": comparison_coverage, "rateComparable": rates_comparable, "rateUnavailableReason": reason}, "notice": "变化行是分组线索;投入/报废增量和分组率不能加总解释总体率。未指定 stage 时 black+bright 重量和仅作分组描述,不代表独立投入或分母;投入变化请分阶段分析。", } if priority_signals is not None: response["prioritySignals"] = priority_signals return response 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", "exclusions") 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("exclusions", {}) != filters.get("exclusions", {}): raise QualityToolError("正式明细接口未确认排除条件;结果已拒绝。") 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 _normalized_scope_selection(value: Any) -> tuple[str, ...] | None: """Normalize the server's scalar-or-set representation for scope filters.""" if value is None: return () if isinstance(value, str): values = [value] elif isinstance(value, list): values = value else: return None if any(not isinstance(item, str) or not item.strip() for item in values): return None if len(values) != len(set(values)): return None return tuple(sorted(values)) @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", "monthStart", "monthEnd", "department", "group", "product", "projectGroup", "extraFilters", "exclusions", "includeUnassigned", "stage", "dimension", "defect", "category"): expected = expected_context.get(field) if field == "includeUnassigned": expected = filters.get(field, False) if field in ('extraFilters', 'exclusions'): expected = filters.get(field, {}) actual = context.get(field, {}) elif field in ('department', 'group', 'product', 'projectGroup'): if (QualityTools._normalized_scope_selection(actual := context.get(field)) is None or QualityTools._normalized_scope_selection(expected) is None or QualityTools._normalized_scope_selection(actual) != QualityTools._normalized_scope_selection(expected)): raise QualityToolError(f"具体缺陷接口未确认 {field} 筛选;结果已拒绝。") continue else: actual = context.get(field) if actual != expected: raise QualityToolError(f"具体缺陷接口未确认 {field} 筛选;结果已拒绝。") expected_columns = filters.get('columnFilters') if expected_columns is not None: receipts = [response.get('filters'), context.get('filters')] echoed = [item.get('columnFilters') for item in receipts if isinstance(item, dict) and 'columnFilters' in item] if 'columnFilters' in context: echoed.append(context.get('columnFilters')) if not echoed or any(item != expected_columns for item in echoed): raise QualityToolError('具体缺陷接口未原样确认 filters.columnFilters;结果已拒绝。') 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", "exclusions", "columnFilters") 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) response_proof = response.get('protocolEvidence') if self._query_contract and self._query_contract.get('exactScope'): required = ('queryId','attemptId','sessionId','turnId','revision','executionId','responseHash','nodeId','scopeId') if (not isinstance(response_proof,dict) or any(key not in response_proof for key in required) or response_proof.get('nodeId') != self._query_contract.get('nodeId') or response_proof.get('scopeId') != self._query_contract.get('scopeId')): raise QualityToolError("具体缺陷接口未返回绑定当前node/scope的正式protocolEvidence;结果已拒绝。") 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"], "protocolEvidence": copy.deepcopy(response_proof) if isinstance(response_proof, dict) else None, } @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") # Resolve the bounded source-field candidates before slicing the visible # TOP, so presentation truncation does not mean an incomplete ranking. # Product populations may exceed this bound and retain their coverage limit. fetch_limit = 100 if comparison_period is not None or dimension == 'defect' 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。" snapshots = [current] if comparison_period is not None: snapshots.append(comparison) actual_proofs = [copy.deepcopy(snapshot['protocolEvidence']) for snapshot in snapshots if isinstance(snapshot.get('protocolEvidence'), dict)] if actual_proofs: result['protocolEvidence'] = actual_proofs[0] if len(actual_proofs) == 1 else actual_proofs return result def _investigate(self, release, period, comparison, filters, args): action = args.get("action", "overview") category = _normalize_category(args["stage"], args["category"]) if args.get("category") is not None else None def fetch(selected_period): payload = {"releaseId":release["id"], **selected_period, **filters, "stage":args["stage"], "action":action, "limit":args.get("limit",20)} payload.setdefault('includeUnassigned', False) if category is not None: payload["category"] = category for key in ("offset","recordFilter","sourceRevisionId","fields"): if key in args: payload[key]=args[key] response = self._call("POST", "/api/analysis/investigate", payload=payload) context = response.get("context") expected = {"releaseId":release["id"], "stage":args["stage"], "category":category, "includeUnassigned":False, "sourceRevisionId":args.get("sourceRevisionId"), **selected_period, **filters} if response.get("kind") != "quality_investigation" or response.get("action") != action or not isinstance(context,dict): raise QualityToolError("调查接口未确认kind/action/context;结果已拒绝。") for key in ("releaseId","stage","year","month","quarter","monthStart","monthEnd", "department","group","product","projectGroup","includeUnassigned", "category","sourceRevisionId","columnFilters","exclusions"): # The investigation endpoint canonicalizes an omitted column # filter to an empty list in its response context. Treat that # canonical form as equivalent to omission; any selected # non-empty filter still has to match exactly. default = {} if key == 'exclusions' else [] if key == 'columnFilters' else None if context.get(key, default) != expected.get(key, default): raise QualityToolError(f"调查接口未确认{key}范围;结果已拒绝。") if context.get("extraFilters",{}) != filters.get("extraFilters",{}): raise QualityToolError("调查接口未确认额外筛选。") total=response.get("totalRows") if isinstance(total,bool) or not isinstance(total,int) or total<0 or response.get("aggregateComplete") is not True: raise QualityToolError("调查接口未确认全量统计覆盖。") if not isinstance(response.get("categories"),list) or not isinstance(response.get("lineage"),list): raise QualityToolError("调查接口缺少类别或来源。") if action=="rows": rows=response.get("rows"); offset=args.get("offset",0) if not isinstance(rows,list) or len(rows)>args.get("limit",20) or response.get("offset")!=offset or response.get("returnedRows")!=len(rows): raise QualityToolError("调查分页响应与请求不一致。") matching=response.get("matchingRows") if not isinstance(matching,int) or isinstance(matching,bool) or not 0<=matching<=total: raise QualityToolError("调查分页缺少匹配总数。") more=offset+len(rows) 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 [] source_fields = access.get('sourceFields') if source_fields is not None and not isinstance(source_fields, list): raise QualityToolError('正式权限目录 sourceFields 结构无效。') 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", "exclusions", "includeUnassigned"], "extraFields": access.get("extraFields", [])}, "sourceFields": _json_safe(source_fields) if isinstance(source_fields, list) else None, "fineDefects": fine_defects, "investigation": {"mode":"investigate", "actions":["overview","rows","fields","source"], "fullAggregate":True,"sourceMaxRows":100000,"pageLimit":100,"fieldLimit":32,"readOnly":True,"requiresEvidencePermission":True,"next":"正常分析按原始数据统计展示,VCM合计口径和其他小额差异不必专项追查;用户要求或影响主要结论时再核验原表。"}, "limitations": access.get("limitations") or [], } def _validate_arguments(self, args: dict[str, Any]) -> None: unknown = set(args) - {"mode", "releaseId", "scope", "period", "comparisonPeriod", "filters", "columnFilters", "view", "stage", "dimension", "category", "defect", "limit", "sort", "action", "offset", "recordFilter", "sourceRevisionId", "fields", "metric", "freshQuery"} if unknown: raise QualityToolError(f"不支持参数:{', '.join(sorted(unknown))}。请按 quality_data schema 调整请求。") if 'freshQuery' in args and type(args['freshQuery']) is not bool: raise QualityToolError('freshQuery必须是布尔值。') if args.get("mode") not in {"catalog", "query", "rank", "compare", "top", "changes", "defects", "details", "investigate"}: raise QualityToolError("mode 必须是 catalog/query/rank/compare/top/changes/defects/details/investigate 之一。") mode = args["mode"] limit = args.get("limit", 20) max_limit = 100000 if mode == 'investigate' and args.get('action') == 'source' else 100 if isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= max_limit: raise QualityToolError(f"limit 必须是 1 到 {max_limit} 的整数。") if 'columnFilters' in args: if mode not in ('query','compare','rank','investigate','defects'): raise QualityToolError('columnFilters仅支持正式query/compare/rank/investigate/defects模式。') if args['columnFilters'] is not None and (not isinstance(args['columnFilters'], list) or len(args['columnFilters']) > 20): raise QualityToolError('columnFilters必须是最多20项的完整规则数组,null或[]表示清除。') if 'metric' in args and mode != 'rank': raise QualityToolError('metric仅用于rank。') extras = {"action", "offset", "recordFilter", "sourceRevisionId", "fields"} & set(args) if extras and mode != "investigate": raise QualityToolError("action/offset/recordFilter/sourceRevisionId/fields仅用于investigate。") if mode == "investigate": if {"view", "dimension", "defect", "sort"} & set(args) or args.get("stage") not in CATEGORIES: raise QualityToolError("investigate需要stage,不接受view/dimension/defect/sort。") if args.get("action", "overview") not in {"overview", "rows", "fields", "source"}: raise QualityToolError("investigate.action无效。") if args.get("recordFilter", "all") not in {"all", "differences", "unexpectedDifferences"}: raise QualityToolError("recordFilter无效。") if args.get("action","overview")!="rows" and {"offset","recordFilter"}&set(args): raise QualityToolError("offset/recordFilter只用于rows。") offset=args.get("offset",0) if isinstance(offset,bool) or not isinstance(offset,int) or not 0<=offset<=10_000_000: raise QualityToolError("offset必须是0到10000000整数。") revision=args.get("sourceRevisionId") if revision is not None and (not isinstance(revision,str) or not re.fullmatch(r"[a-zA-Z0-9-]{1,64}",revision)): raise QualityToolError("sourceRevisionId无效。") fields=args.get("fields") if fields is not None and (not isinstance(fields,list) or not 1<=len(fields)<=32 or any(not isinstance(f,str) or not f.strip() or len(f)>200 for f in fields)): raise QualityToolError("fields须为1至32个源字段。") if args.get("category") is not None: _normalize_category(args["stage"],args["category"]) 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 == "rank": if ({'view','comparisonPeriod','sort','category','defect'} & set(args) or not (args.get('stage') in CATEGORIES or args.get('stage') is None and args.get('metric') == 'scrapWeight') or args.get('dimension') not in {'product','department','group'} or args.get('metric') not in {'totalWeight','scrapWeight'}): raise QualityToolError('rank必须指定stage、dimension=product/department/group、metric=totalWeight/scrapWeight;不接受view、comparisonPeriod或报废类别。') 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", "current_rate"}: raise QualityToolError("changes.sort 只能是 scrap_delta/current_scrap/rate_drop/current_rate。") 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,它表示按一个具体缺陷排名规格。若要查看已选规格的全部缺陷,请用filters.product选择规格,并设dimension=defect。") 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"]) @staticmethod def _model_view(result): if result.get("kind") == "quality_fine_defects": view = copy.deepcopy(result) for name, categories_key in (("coverage", "categoryReconciliation"), ("comparisonCoverage", "comparisonCategoryReconciliation")): coverage = view.get(name) if isinstance(coverage, dict) and isinstance(coverage.get("categories"), list) and coverage["categories"] == result.get(categories_key): coverage.pop("categories") coverage["categoriesRef"] = categories_key # Each drilldown repeats the same coverage keys for every source # field and both periods. Keep all values, but transmit those keys # once; the immutable evidence remains in its original structure. for name in ("sourceFields", "comparisonSourceFields"): for field in view.get(name, []): for key in ("label", "sourceField"): if field.get("key") is not None and field.get(key) == field.get("key"): field.pop(key, None) for name in ("categoryReconciliation", "comparisonCategoryReconciliation"): for category in view.get(name, []): components = category.get("components") if not isinstance(components, list) or not components or not all(isinstance(row, dict) for row in components): continue columns = list(dict.fromkeys(key for row in components for key in row)) # Do not conflate an absent property with an explicit null. # Irregular upstream shapes keep their original dictionaries. if not all(set(row) == set(columns) for row in components): continue category.pop("components") category["componentColumns"] = columns category["componentValues"] = [[row[key] for key in columns] for row in components] view["modelViewNotice"] = "重复字段统计采用列式表示:componentValues各列按componentColumns解释;coverage.categoriesRef指向同一响应的对账类别;sourceFields中省略的label/sourceField与key相同。重量、缺失/非法/负值计数和对账状态均保留,完整原结构保存在本次evidenceRef对应证据中。" return view if result.get("kind") != "quality_investigation": return result view = copy.deepcopy(result) columns = ["field", "rows", "numericRows", "nullOrBlankRows", "keyAbsentRows", "invalidNumericRows", "negativeRows", "numericSum"] for name in ("current", "comparison"): side = view.get(name) if not isinstance(side, dict): continue if result.get("action") != "fields": side.pop("fieldDictionary", None) for category in side.get("categories", []): rows = category.pop("fields", []) category["fieldCoverageColumns"] = columns category["fieldCoverage"] = [[row.get("field"), *[(row.get("coverage") or {}).get(key) for key in columns[1:]]] for row in rows] proof = side.get("sourceVerification") if isinstance(proof, dict) and proof.get("allSelectedValuesMatchStored") is True: for source in proof.get("files", []): source["verifiedFields"] = [row.get("field") for row in source.pop("fields", [])] source["coverageBasis"] = "全部命中原表值与存储一致,字段计数见类别fieldCoverage;完整逐字段原件统计保存在本次证据中。" if result.get("action") == "source": side.pop("largestDifferenceExamples", None) side["nextSteps"] = (["原件未完整匹配,不能套用VCM例外;用rows+recordFilter=differences保留全部差额,并明确原件缺失/不一致证据。"] if not isinstance(proof,dict) or proof.get("allSelectedValuesMatchStored") is not True else ["若unexpectedDifferenceRows>0,调用rows+recordFilter=unexpectedDifferences;以matchingRows/hasMore核对完整剩余。原件已匹配时说明表内差异,不能归因为漏导入。"]) view["modelViewNotice"] = "仅压缩重复字段统计;全量范围、精确合计、缺失/非法/负值计数、对账状态与来源证明保留。完整响应保存在真实evidenceRef对应证据中。" return view 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 对象。") if self._query_contract: from nao_query_contract import bind_query try: arguments = bind_query(arguments, self._query_contract) except ValueError as error: raise QualityToolError(str(error)) from None # A stage-wide defect read has one unambiguous default. Normalize a # missing dimension before validation, retaining every release, period # and filter. A named defect or explicit invalid dimension still needs # the caller to state its intended grouping. if arguments.get("mode") == "defects" and "dimension" not in arguments and "defect" not in arguments: arguments = {**arguments, "dimension": "defect"} 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"] if mode not in ('query', 'compare', 'rank', 'changes', 'investigate', 'defects') and any( isinstance(arguments.get(key), dict) and any(k in arguments[key] for k in ('monthStart', 'monthEnd')) for key in ('period', 'comparisonPeriod')): raise QualityToolError('连续月份范围目前仅支持正式query/compare/rank/investigate;未执行其他查询。') 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) column_filters = None if 'columnFilters' in arguments: from nao_query_contract import validate_column_filters try: column_filters = validate_column_filters(arguments.get('columnFilters'), access.get('sourceFields')) except ValueError as error: raise QualityToolError(str(error)) from None if filters.get("exclusions") and mode == "top": raise QualityToolError(f"{mode} 模式暂不支持排除条件;未执行数据查询。") limit = arguments.get("limit", 20) if mode == "rank": from nao_weight_ranking import rank_response period = normalize_period(arguments.get('period')) response = self._metrics(release['id'], period, filters, arguments['dimension'], column_filters=column_filters) ranking_filters = ({**filters, 'columnFilters': copy.deepcopy(column_filters)} if column_filters is not None else filters) try: result = rank_response(response, release, period, ranking_filters, arguments['dimension'], arguments.get('stage'), arguments['metric'], arguments.get('limit', 10)) except Exception as error: # The normal result and exception remain unchanged. Attach # a bounded, identifier-free summary so the protocol layer # can store the exact source shape in its private trace. try: error._quality_private_rank_trace = _private_rank_response_trace(response) except Exception: pass raise elif 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, column_filters) 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, column_filters) 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") if column_filters is not None: if not getattr(self, '_bulk_changes', False) and arguments.get('sort') != 'current_rate': raise QualityToolError('列筛选的changes必须使用服务器授权的正式批量接口。') filters = {**filters, 'columnFilters': copy.deepcopy(column_filters)} result = self._changes(release, current, comparison, filters, arguments["dimension"], stage, arguments.get("category"), arguments.get("sort", "scrap_delta"), limit) elif mode == "investigate": period = normalize_period(arguments.get("period")) comparison = normalize_period(arguments.get("comparisonPeriod"), "comparisonPeriod", required=False) if column_filters is not None: filters = {**filters, 'columnFilters': copy.deepcopy(column_filters)} result = self._investigate(release, period, comparison, filters, arguments) elif mode == "defects": current = normalize_period(arguments.get("period"), "period") comparison = normalize_period(arguments.get("comparisonPeriod"), "comparisonPeriod", required=False) if column_filters is not None: filters = {**filters, 'columnFilters': copy.deepcopy(column_filters)} 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(self._model_view(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", ]