628 lines
40 KiB
Python
628 lines
40 KiB
Python
"""Validation and exact evidence selection for bounded multi-node analysis plans.
|
||
|
||
The model proposes intent. The protocol service resolves each node into trusted
|
||
scope tasks; this module only checks the bounded wire shapes and binds evidence
|
||
back to those tasks.
|
||
"""
|
||
from __future__ import annotations
|
||
|
||
import copy
|
||
import re
|
||
|
||
from nao_period import expected_months, normalize_period
|
||
|
||
NODE_ID = re.compile(r"^[a-z][a-z0-9_-]{0,31}$")
|
||
PURPOSES = {"ranking", "metrics", "trend", "source", "records", "defects", "changes"}
|
||
SELECTOR_DIMENSIONS = {"product", "department", "group"}
|
||
DIMENSIONS = {"product", "department", "group", "defect"}
|
||
STAGES = {"black", "bright"}
|
||
FIELDS = {"rate", "scrapRate", "totalWeight", "scrapWeight"}
|
||
WEIGHTS = {"totalWeight", "scrapWeight"}
|
||
RANK_VISUALS = {"bar", "column", "pareto"}
|
||
TREND_VISUALS = {"line", "area", "heatmap"}
|
||
DEFECT_VISUALS = {"bar", "column", "pareto"}
|
||
|
||
|
||
class QueryPlanValidationError(ValueError):
|
||
def __init__(self, message, *, field, expected, received):
|
||
super().__init__(message)
|
||
self.field, self.expected, self.received = field, expected, received
|
||
|
||
|
||
def _defect_catalog(context):
|
||
"""Return the actor-authorized fine-defect directory supplied for planning."""
|
||
if not isinstance(context, dict):
|
||
return None
|
||
business = context.get("_businessCatalog")
|
||
if isinstance(business, dict) and isinstance(business.get("fineDefects"), dict):
|
||
return business["fineDefects"]
|
||
protocol = context.get("_protocol")
|
||
if isinstance(protocol, dict) and isinstance(protocol.get("defectCatalog"), dict):
|
||
return protocol["defectCatalog"]
|
||
return None
|
||
|
||
|
||
def _validate_defect_selection(context, stages, defect, category):
|
||
"""Validate selected source fields/categories against the actor catalog."""
|
||
catalog = _defect_catalog(context)
|
||
fields = catalog.get("fields") if isinstance(catalog, dict) else None
|
||
categories = catalog.get("categories") if isinstance(catalog, dict) else None
|
||
if not isinstance(fields, list) or not isinstance(categories, list):
|
||
raise ValueError("queryPlan缺陷字段或类别目录不可用,不能猜测细分字段")
|
||
for stage in stages:
|
||
available_fields = [item for item in fields if isinstance(item, dict)
|
||
and item.get("stage") == stage
|
||
and item.get("grain") == "source_defect_weight"
|
||
and item.get("available") is True
|
||
and item.get("countOnly") is not True]
|
||
if not available_fields:
|
||
raise ValueError(f"{stage}阶段没有已授权的具体缺陷重量字段")
|
||
field_entry = None
|
||
if defect is not None:
|
||
matches = [item for item in available_fields if item.get("key") == defect]
|
||
if len(matches) != 1:
|
||
raise ValueError(f"queryPlan缺陷字段不在{stage}阶段已授权的细分重量目录中")
|
||
field_entry = matches[0]
|
||
if category is not None:
|
||
matches = [item for item in categories if isinstance(item, dict)
|
||
and item.get("stage") == stage and item.get("category") == category
|
||
and item.get("available") is True]
|
||
if len(matches) != 1:
|
||
raise ValueError(f"queryPlan缺陷类别不在{stage}阶段已授权目录中")
|
||
if field_entry is not None and field_entry.get("category") != category:
|
||
raise ValueError("queryPlan缺陷字段与类别不匹配")
|
||
if field_entry is None and not any(item.get("category") == category for item in available_fields):
|
||
raise ValueError(f"{stage}阶段类别没有已授权的具体缺陷重量字段")
|
||
|
||
|
||
def _unique_values(value, allowed, name, *, minimum=0, maximum=None):
|
||
if not isinstance(value, list) or len(value) < minimum or maximum is not None and len(value) > maximum:
|
||
raise ValueError(f"queryPlan.{name}数量无效")
|
||
if any(not isinstance(item, str) or item not in allowed for item in value):
|
||
raise ValueError(f"queryPlan.{name}包含不支持的值")
|
||
if len(set(value)) != len(value):
|
||
raise ValueError(f"queryPlan.{name}不能重复")
|
||
return list(value)
|
||
|
||
|
||
def normalize_query_plan(value, *, root_task, root_value=None, context=None):
|
||
"""Strictly normalize the model's 1..8-node plan without resolving scope."""
|
||
if not isinstance(value, list) or not 1 <= len(value) <= 8:
|
||
raise ValueError("queryPlan必须是1到8个有界节点")
|
||
nodes = []
|
||
by_id = {}
|
||
protocol = (context or {}).get("_protocol") if isinstance(context, dict) else None
|
||
raw_root = root_value if isinstance(root_value, dict) else {}
|
||
available_rankings = protocol.get("availableRankings", []) if isinstance(protocol, dict) else []
|
||
if not isinstance(available_rankings, list):
|
||
available_rankings = []
|
||
period = normalize_period(root_task.get("period"))
|
||
if period is None:
|
||
raise ValueError("queryPlan必须继承已确认的root期间")
|
||
|
||
for index, raw in enumerate(value):
|
||
if not isinstance(raw, dict):
|
||
raise ValueError(f"queryPlan[{index}]必须是对象")
|
||
allowed = {"nodeId", "purpose", "fields", "stages", "visualType", "visualPreference",
|
||
"comparisonRequired", "selector", "dimension", "limit", "sourceFields",
|
||
"defect", "category", "sort", "optional"}
|
||
if set(raw) - allowed:
|
||
raise ValueError(f"queryPlan[{index}]包含未支持字段")
|
||
node_id = raw.get("nodeId")
|
||
purpose = raw.get("purpose")
|
||
if not isinstance(node_id, str) or not NODE_ID.fullmatch(node_id) or node_id in by_id:
|
||
raise ValueError("queryPlan.nodeId格式无效或重复")
|
||
if not isinstance(purpose, str) or purpose not in PURPOSES:
|
||
raise ValueError(f"queryPlan[{node_id}].purpose无效")
|
||
is_raw = purpose in ('source', 'records')
|
||
fields = _unique_values(raw.get("fields"), FIELDS, f"{node_id}.fields",
|
||
minimum=0 if is_raw else 1, maximum=4)
|
||
stages = _unique_values(raw.get("stages"), STAGES, f"{node_id}.stages", minimum=0, maximum=2)
|
||
visual_type = raw.get("visualType")
|
||
allowed_visuals = (set() if is_raw else TREND_VISUALS if purpose == "trend" else
|
||
RANK_VISUALS if purpose == 'ranking' else
|
||
DEFECT_VISUALS if purpose == 'defects' else {'bar', 'column'})
|
||
if purpose == 'defects' and 'visualType' not in raw:
|
||
visual_type = 'bar'
|
||
if visual_type is not None and (not isinstance(visual_type, str) or visual_type not in allowed_visuals):
|
||
raise ValueError(f"queryPlan[{node_id}].visualType与purpose不匹配")
|
||
preference = raw.get("visualPreference", 'none' if is_raw else root_task.get("visualPreference", "auto"))
|
||
if not isinstance(preference, str) or preference not in ("auto", "required", "none"):
|
||
raise ValueError(f"queryPlan[{node_id}].visualPreference无效")
|
||
comparison_required = raw.get("comparisonRequired", False)
|
||
if type(comparison_required) is not bool:
|
||
raise ValueError(f"queryPlan[{node_id}].comparisonRequired必须是boolean")
|
||
optional = raw.get('optional', False)
|
||
if type(optional) is not bool:
|
||
raise ValueError(f"queryPlan[{node_id}].optional必须是boolean")
|
||
selector = raw.get("selector", {"kind": "base"})
|
||
if not isinstance(selector, dict) or not isinstance(selector.get("kind"), str):
|
||
raise ValueError(f"queryPlan[{node_id}].selector无效")
|
||
kind = selector["kind"]
|
||
if kind == "base":
|
||
if set(selector) != {"kind"}:
|
||
raise ValueError(f"queryPlan[{node_id}] base selector不接受额外字段")
|
||
selector = {"kind": "base"}
|
||
elif kind == "catalog_members":
|
||
if (set(selector) != {"kind", "dimension", "names"}
|
||
or not isinstance(selector.get("dimension"), str) or selector.get("dimension") not in SELECTOR_DIMENSIONS):
|
||
raise ValueError(f"queryPlan[{node_id}] catalog_members selector结构无效")
|
||
names = selector.get("names")
|
||
if (not isinstance(names, list) or not 1 <= len(names) <= 10
|
||
or any(not isinstance(name, str) or not name.strip() or len(name) > 200 for name in names)
|
||
or len(set(names)) != len(names)):
|
||
raise ValueError(f"queryPlan[{node_id}] catalog_members.names须为1到10个唯一目录原名")
|
||
catalog = (context or {}).get("_businessCatalog", {}) if isinstance(context, dict) else {}
|
||
directory_key = {"department": "departments", "group": "groups", "product": None}[selector["dimension"]]
|
||
if directory_key:
|
||
directory = catalog.get(directory_key, []) if isinstance(catalog, dict) else []
|
||
if not isinstance(directory, list) or any(name not in directory for name in names):
|
||
raise ValueError(f"queryPlan[{node_id}] catalog_members.names不在授权目录中")
|
||
if selector["dimension"] == "group" and isinstance(catalog.get("groupDepartments"), dict):
|
||
parent = (root_task.get("filters") or {}).get("department")
|
||
if parent and any(catalog["groupDepartments"].get(name) != parent for name in names):
|
||
raise ValueError(f"queryPlan[{node_id}] group不属于root部门范围")
|
||
if selector["dimension"] == "department":
|
||
parent_group = (root_task.get("filters") or {}).get("group")
|
||
if parent_group and isinstance(catalog.get("groupDepartments"), dict):
|
||
if any(name != catalog["groupDepartments"].get(parent_group) for name in names):
|
||
raise ValueError(f"queryPlan[{node_id}] department与root group范围冲突")
|
||
else:
|
||
product_match = catalog.get("productMatch") if isinstance(catalog, dict) else None
|
||
candidates = product_match.get("candidates") if isinstance(product_match, dict) else None
|
||
candidate_names = {item.get("name") for item in candidates if isinstance(item, dict)} if isinstance(candidates, list) else set()
|
||
if not set(names) <= candidate_names:
|
||
raise ValueError(f"queryPlan[{node_id}] product names必须来自本轮已授权产品候选")
|
||
filters = root_task.get("filters") if isinstance(root_task.get("filters"), dict) else {}
|
||
for name in names:
|
||
entry = next(item for item in candidates if isinstance(item, dict) and item.get("name") == name)
|
||
if filters.get("department") and filters["department"] not in entry.get("departments", []):
|
||
raise ValueError(f"queryPlan[{node_id}] product不属于root department范围")
|
||
if filters.get("group") and filters["group"] not in entry.get("groups", []):
|
||
raise ValueError(f"queryPlan[{node_id}] product不属于root group范围")
|
||
selector = {"kind": kind, "dimension": selector["dimension"], "names": list(names)}
|
||
elif kind == 'changes_top':
|
||
if set(selector) != {'kind', 'sourceNodeId', 'count', 'stage'}:
|
||
raise ValueError(f'queryPlan[{node_id}] changes_top结构无效')
|
||
source = by_id.get(selector.get('sourceNodeId'))
|
||
count, selected_stage = selector.get('count'), selector.get('stage')
|
||
if (source is None or source['purpose'] != 'changes'
|
||
or type(count) is not int or not 1 <= count <= 3
|
||
or count > source['limit']
|
||
or selected_stage not in ('overall', 'black', 'bright', 'dominant')):
|
||
raise ValueError(f'queryPlan[{node_id}] changes_top必须引用前置批量对比实际Top,count为1到3')
|
||
if not optional:
|
||
raise ValueError(f'queryPlan[{node_id}] 结果驱动的下钻必须标记optional=true,允许没有不利对象时停止')
|
||
selector = copy.deepcopy(selector)
|
||
elif kind == "ranking_top":
|
||
if set(selector) != {"kind", "sourceNodeId", "stage", "metric", "count"}:
|
||
raise ValueError(f"queryPlan[{node_id}] ranking_top selector结构无效")
|
||
source_id = selector.get("sourceNodeId")
|
||
source = by_id.get(source_id)
|
||
stage, metric, count = selector.get("stage"), selector.get("metric"), selector.get("count")
|
||
if (source is None or source["purpose"] != "ranking" or source["dimension"] != "product"
|
||
or source["selector"].get("kind") != "base"):
|
||
raise ValueError(f"queryPlan[{node_id}] ranking_top必须引用前置base产品排名")
|
||
combined_source = stage == 'overall' and not source['stages'] and metric == 'scrapWeight'
|
||
if (not isinstance(stage, str) or stage not in STAGES and not combined_source
|
||
or not isinstance(metric, str) or metric not in WEIGHTS or type(count) is not int
|
||
or not 1 <= count <= 10 or count > source["limit"]):
|
||
raise ValueError(f"queryPlan[{node_id}] ranking_top阶段、指标或count无效")
|
||
if stage not in source["stages"] and not combined_source or metric not in source["fields"]:
|
||
raise ValueError(f"queryPlan[{node_id}] ranking_top只能选择源排名已查询的阶段和指标")
|
||
selector = {"kind": kind, "sourceNodeId": source_id, "stage": stage,
|
||
"metric": metric, "count": count}
|
||
elif kind == "previous_ranking":
|
||
if set(selector) != {"kind", "queryId", "stage", "metric", "ranks"}:
|
||
raise ValueError(f"queryPlan[{node_id}] previous_ranking selector结构无效")
|
||
query_id, stage, metric, ranks = (selector.get("queryId"), selector.get("stage"),
|
||
selector.get("metric"), selector.get("ranks"))
|
||
trusted = [item for item in available_rankings if isinstance(item, dict)
|
||
and item.get("queryId") == query_id and item.get("stage") == stage
|
||
and item.get("metric") == metric]
|
||
if (not isinstance(query_id, str) or not query_id or not isinstance(stage, str) or stage not in STAGES | {'overall'}
|
||
or not isinstance(metric, str) or metric not in WEIGHTS
|
||
or len(trusted) != 1 or not isinstance(ranks, list) or not 1 <= len(ranks) <= 10
|
||
or any(type(rank) is not int or not 1 <= rank <= 10 for rank in ranks)
|
||
or len(set(ranks)) != len(ranks)):
|
||
raise ValueError(f"queryPlan[{node_id}] previous_ranking只能引用可用排名并指定唯一rank")
|
||
if (trusted[0].get('dimension') not in SELECTOR_DIMENSIONS or not isinstance(trusted[0].get('period'), dict)
|
||
or not isinstance(trusted[0].get('filters'), dict) or not isinstance(trusted[0].get('rows'), list)):
|
||
raise ValueError(f"queryPlan[{node_id}] previous_ranking来源缺少可信排名上下文")
|
||
if purpose == 'ranking' and raw.get('dimension') != trusted[0].get('dimension'):
|
||
raise ValueError(f"queryPlan[{node_id}] previous_ranking维度必须与可信排名来源相同")
|
||
preview_rows = trusted[0].get("rows")
|
||
if isinstance(preview_rows, list):
|
||
known_ranks = {row.get("rank") for row in preview_rows if isinstance(row, dict)}
|
||
if known_ranks and not set(ranks) <= known_ranks:
|
||
raise ValueError(f"queryPlan[{node_id}] previous_ranking引用了未展示的历史名次")
|
||
selector = {"kind": kind, "queryId": query_id, "stage": stage,
|
||
"metric": metric, "ranks": list(ranks)}
|
||
else:
|
||
raise ValueError(f"queryPlan[{node_id}].selector.kind不支持")
|
||
|
||
node = {"nodeId": node_id, "purpose": purpose, "fields": fields, "stages": stages,
|
||
"visualType": visual_type, "visualPreference": preference,
|
||
"comparisonRequired": comparison_required, "selector": selector}
|
||
if 'optional' in raw:
|
||
node['optional'] = optional
|
||
if optional and kind != 'changes_top':
|
||
raise ValueError(f'queryPlan[{node_id}] optional只适用于由实际结果决定的changes_top下钻')
|
||
source_fields = raw.get('sourceFields')
|
||
if is_raw:
|
||
if fields or not stages or visual_type is not None or preference != 'none':
|
||
raise ValueError(f"queryPlan[{node_id}]原始读取节点必须fields=[]、stages非空、visualType=null、visualPreference=none")
|
||
if source_fields is not None:
|
||
if not isinstance(source_fields, dict) or set(source_fields) - set(stages):
|
||
raise ValueError(f"queryPlan[{node_id}].sourceFields必须按所选阶段提供授权字段key数组")
|
||
directory = (context or {}).get('_businessCatalog', {}).get('sourceFields', []) if isinstance(context, dict) else []
|
||
authorized = {item.get('key'): item for item in directory if isinstance(item, dict) and isinstance(item.get('key'), str)} if isinstance(directory, list) else {}
|
||
normalized_source_fields = {}
|
||
for stage, keys in source_fields.items():
|
||
if (not isinstance(keys, list) or not 1 <= len(keys) <= 32
|
||
or any(not isinstance(key, str) or not re.fullmatch(r'[A-Za-z0-9_]{1,100}', key) for key in keys)
|
||
or len(set(keys)) != len(keys)):
|
||
raise ValueError(f"queryPlan[{node_id}].sourceFields.{stage}必须是1到32个唯一稳定字段key")
|
||
for key in keys:
|
||
entry = authorized.get(key)
|
||
columns = entry.get('columns') if isinstance(entry, dict) else None
|
||
if (entry is None or entry.get('type') != 'source_value'
|
||
or stage not in entry.get('stages', [])
|
||
or not isinstance(columns, dict) or not isinstance(columns.get(stage), str)
|
||
or not columns[stage].strip()):
|
||
raise ValueError(f"queryPlan[{node_id}].sourceFields包含未授权或阶段不适用的字段key")
|
||
normalized_source_fields[stage] = list(keys)
|
||
node['sourceFields'] = normalized_source_fields
|
||
if purpose == 'source' and raw_root.get('verifySource') is False:
|
||
raise ValueError(f"queryPlan[{node_id}] source节点不能弱化root.verifySource")
|
||
if purpose == 'records' and raw_root.get('fullDetails') is False:
|
||
raise ValueError(f"queryPlan[{node_id}] records节点不能弱化root.fullDetails")
|
||
elif source_fields is not None:
|
||
raise ValueError(f"queryPlan[{node_id}]仅source/records节点接受sourceFields")
|
||
if purpose == 'changes':
|
||
dimension, limit, sort = raw.get('dimension'), raw.get('limit', 3), raw.get('sort', 'rate_drop')
|
||
if (dimension not in SELECTOR_DIMENSIONS or type(limit) is not int or not 1 <= limit <= 10
|
||
or sort not in ('rate_drop', 'current_rate', 'scrap_delta', 'current_scrap')
|
||
or len(stages) > 1 or not comparison_required
|
||
or kind not in ('base', 'changes_top')):
|
||
raise ValueError(f'queryPlan[{node_id}] changes需要维度、有界Top、排序、比较期及基础或结果范围')
|
||
if 'scrapRate' in fields:
|
||
raise ValueError(f'queryPlan[{node_id}] changes尚不支持报废率排名,不能替换成合格率')
|
||
if sort in ('rate_drop', 'current_rate') and 'rate' not in fields:
|
||
raise ValueError(f'queryPlan[{node_id}] 合格率排序不能改成重量指标')
|
||
if sort in ('scrap_delta','current_scrap') and 'scrapWeight' not in fields:
|
||
raise ValueError(f'queryPlan[{node_id}] 报废重量排序必须保留scrapWeight')
|
||
from nao_changes import diagnostic_intent, performance_intent
|
||
if (dimension=='product' and sort in ('rate_drop','current_rate')
|
||
and (diagnostic_intent(root_task.get('question')) or performance_intent(root_task.get('question')))
|
||
and not re.search(r'按.{0,8}(?:率|降幅).{0,6}(?:排|排序)|降幅.{0,4}(?:最大|最多)|率.{0,4}最低',root_task.get('question',''))):
|
||
raise ValueError('原因定位不能只按产品率降幅或本期低率筛选小批量:使用scrap_delta及fields=[rate,totalWeight,scrapWeight],结合两期投入和报废增量找线索;率排名只有用户明确要求时才单独使用')
|
||
node.update(dimension=dimension, limit=limit, sort=sort)
|
||
elif 'sort' in raw:
|
||
raise ValueError(f'queryPlan[{node_id}] sort仅用于changes')
|
||
elif purpose == "ranking":
|
||
dimension, limit = raw.get("dimension"), raw.get("limit")
|
||
combined = not stages and 'scrapWeight' in fields and set(fields) <= {'rate', 'scrapWeight'}
|
||
if not isinstance(dimension, str) or dimension not in SELECTOR_DIMENSIONS or not fields or not (combined or stages and not set(fields) - WEIGHTS):
|
||
raise ValueError(f"queryPlan[{node_id}] ranking必须指定维度、重量字段和阶段")
|
||
if type(limit) is not int or not 1 <= limit <= 10:
|
||
raise ValueError(f"queryPlan[{node_id}].limit须为1到10")
|
||
node.update(dimension=dimension, limit=limit)
|
||
elif purpose == "defects":
|
||
dimension = raw.get("dimension")
|
||
limit = raw.get("limit", 100)
|
||
defect = raw.get("defect")
|
||
category = raw.get("category")
|
||
if (dimension not in ('defect', 'product') or fields != ['scrapWeight'] or not stages
|
||
or type(limit) is not int or not 1 <= limit <= 100
|
||
or defect is not None and (not isinstance(defect, str) or not defect.strip())
|
||
or category is not None and (not isinstance(category, str) or not category.strip())):
|
||
raise ValueError(f"queryPlan[{node_id}] defects必须指定defect/product维度、scrapWeight、阶段和1到100的limit")
|
||
if dimension == 'product' and defect is None:
|
||
raise ValueError(f"queryPlan[{node_id}] dimension=product必须指定目录中的具体defect字段")
|
||
_validate_defect_selection(context, stages, defect, category)
|
||
node.update(dimension=dimension, limit=limit)
|
||
if defect is not None:
|
||
node['defect'] = defect
|
||
if category is not None:
|
||
node['category'] = category
|
||
elif "dimension" in raw or "limit" in raw:
|
||
raise ValueError(f"queryPlan[{node_id}]仅ranking接受dimension/limit")
|
||
elif "defect" in raw or "category" in raw:
|
||
raise ValueError(f"queryPlan[{node_id}]仅defects节点接受defect/category")
|
||
if not is_raw and purpose != 'changes' and not stages and fields != ["rate"] and not (
|
||
purpose == 'ranking' and 'scrapWeight' in fields and set(fields) <= {'rate', 'scrapWeight'}):
|
||
raise ValueError(f"queryPlan[{node_id}]仅综合合格率可省略stages")
|
||
if purpose not in ("metrics", "source", "records", "defects", "changes") and comparison_required:
|
||
raise ValueError(f"queryPlan[{node_id}]仅metrics/source/records/defects节点支持期间比较")
|
||
if purpose == "trend":
|
||
if comparison_required:
|
||
raise ValueError(f"queryPlan[{node_id}] trend不能与comparisonRequired混用")
|
||
if len(expected_months(period)) < 2:
|
||
raise ValueError(f"queryPlan[{node_id}] trend必须继承至少两个月的root期间")
|
||
if comparison_required and root_task.get("comparisonPeriod") is None:
|
||
raise ValueError(f"queryPlan[{node_id}] comparisonRequired需要root comparisonPeriod")
|
||
if purpose == "ranking" and selector.get("kind") == "catalog_members" and selector["dimension"] != node["dimension"]:
|
||
raise ValueError(f"queryPlan[{node_id}] catalog_members维度必须与排名维度一致")
|
||
if selector.get("kind") == "ranking_top" and purpose == "ranking" and node["dimension"] != "product":
|
||
raise ValueError(f"queryPlan[{node_id}] ranking_top仅允许产品排名")
|
||
by_id[node_id] = node
|
||
nodes.append(node)
|
||
|
||
base_rate_nodes = [node for node in nodes if node['purpose']=='metrics'
|
||
and node['fields']==['rate'] and node['selector']=={'kind':'base'}
|
||
and node['comparisonRequired'] and node['visualPreference']!='required']
|
||
if (any(not node['stages'] for node in base_rate_nodes)
|
||
and any(node['stages'] for node in base_rate_nodes)):
|
||
raise ValueError('同一范围综合率与阶段基线无需重复读取:保留一个base metrics比较节点fields=[rate]、stages=[],正式比较已同时返回总体与阶段基线;不要额外拆stage_rate节点')
|
||
|
||
# Ranking-top dependencies are checked after all node bodies have been
|
||
# normalized while still requiring the referenced node to precede them.
|
||
field_order = ('rate', 'scrapRate', 'totalWeight', 'scrapWeight')
|
||
union_fields = [field for field in field_order if any(field in node['fields'] for node in nodes)]
|
||
root_fields = root_task.get('fields', [])
|
||
if root_fields and set(root_fields) != set(union_fields):
|
||
raise ValueError("root fields必须精确描述queryPlan节点且保留用户真实要求")
|
||
if not root_fields:
|
||
root_task['fields'] = union_fields
|
||
required_dimensions = set()
|
||
for node in nodes:
|
||
if node["purpose"] in ("ranking", "changes"):
|
||
required_dimensions.add(node["dimension"])
|
||
selector = node["selector"]
|
||
if node['purpose'] == 'defects':
|
||
required_dimensions.add('defect')
|
||
if node['dimension'] == 'product':
|
||
required_dimensions.add('product')
|
||
if selector.get("kind") == "catalog_members":
|
||
required_dimensions.add(selector["dimension"])
|
||
elif selector.get("kind") == "ranking_top":
|
||
required_dimensions.add("product")
|
||
elif selector.get('kind') == 'changes_top':
|
||
required_dimensions.add(by_id[selector['sourceNodeId']]['dimension'])
|
||
elif selector.get("kind") == "previous_ranking":
|
||
preview = next(item for item in available_rankings
|
||
if isinstance(item, dict) and item.get("queryId") == selector["queryId"])
|
||
required_dimensions.add(preview.get("dimension"))
|
||
required_dimensions.discard(None)
|
||
dimension_order = ('product', 'department', 'group', 'defect')
|
||
required_dimension_list = [dimension for dimension in dimension_order if dimension in required_dimensions]
|
||
root_dimensions = root_task.get('dimensions', [])
|
||
if root_dimensions and set(root_dimensions) != set(required_dimension_list):
|
||
raise QueryPlanValidationError("root dimensions必须精确描述queryPlan节点实际对象;不能删除用户要求的维度,应让节点selector覆盖该维度",
|
||
field='queryPlan.dimensions', expected=required_dimension_list, received=root_dimensions)
|
||
if not root_dimensions:
|
||
root_task['dimensions'] = required_dimension_list
|
||
required_stages = list(stage for stage in ('black', 'bright')
|
||
if any(stage in node['stages'] for node in nodes))
|
||
root_stages = root_task.get('stages', [])
|
||
if root_stages and set(root_stages) != set(required_stages):
|
||
raise ValueError("root stages必须精确描述queryPlan节点阶段")
|
||
if not root_stages:
|
||
root_task['stages'] = required_stages
|
||
requires_trend = any(node["purpose"] == "trend" for node in nodes)
|
||
if 'trendRequired' in raw_root and bool(raw_root.get('trendRequired')) != requires_trend:
|
||
raise ValueError("root trendRequired必须忠实覆盖queryPlan中的真实趋势要求")
|
||
root_task['trendRequired'] = requires_trend
|
||
requires_comparison = any(node["comparisonRequired"] for node in nodes)
|
||
if 'comparisonRequired' in raw_root and bool(raw_root.get('comparisonRequired')) != requires_comparison:
|
||
raise ValueError("root comparisonRequired必须忠实覆盖queryPlan中的真实期间比较")
|
||
if root_task.get('comparisonPeriod') is not None and not requires_comparison:
|
||
explicitly_cleared = 'comparisonPeriod' in raw_root and raw_root.get('comparisonPeriod') is None
|
||
if not explicitly_cleared:
|
||
raise ValueError("root已有comparisonPeriod但queryPlan没有比较节点;须明确保留比较节点或清除期间")
|
||
root_task['comparisonRequired'] = requires_comparison
|
||
required_verify_source = any(node['purpose'] == 'source' for node in nodes)
|
||
required_full_details = any(node['purpose'] == 'records' for node in nodes)
|
||
for key, required in (('verifySource', required_verify_source), ('fullDetails', required_full_details)):
|
||
if key in raw_root and bool(raw_root.get(key)) != required:
|
||
raise ValueError(f"root {key}必须精确描述queryPlan原始读取节点且不能弱化真实要求")
|
||
root_task[key] = required
|
||
expected_dimension_stages = {dimension: [] for dimension in required_dimension_list}
|
||
for node in nodes:
|
||
if node['purpose'] in ('ranking', 'changes'):
|
||
expected_dimension_stages[node['dimension']] = list(dict.fromkeys(
|
||
[*expected_dimension_stages[node['dimension']], *node['stages']]))
|
||
elif node['purpose'] == 'defects':
|
||
affected = ['defect'] + (['product'] if node['dimension'] == 'product' else [])
|
||
for dimension in affected:
|
||
expected_dimension_stages[dimension] = list(dict.fromkeys(
|
||
[*expected_dimension_stages[dimension], *node['stages']]))
|
||
existing_stages = root_task.get('dimensionStages') if isinstance(root_task.get('dimensionStages'), dict) else {}
|
||
for dimension, stages in expected_dimension_stages.items():
|
||
if dimension in existing_stages and set(existing_stages[dimension]) != set(stages):
|
||
raise ValueError("root dimensionStages与queryPlan排名节点不一致")
|
||
root_task['dimensionStages'] = {dimension: list(existing_stages.get(dimension, stages))
|
||
if dimension in existing_stages else stages
|
||
for dimension, stages in expected_dimension_stages.items()}
|
||
return nodes
|
||
|
||
|
||
def derive_yoy_period(period):
|
||
normalized = normalize_period(period)
|
||
if not normalized or normalized["year"] <= 1900:
|
||
raise ValueError("comparisonMode=yoy需要可派生的root期间")
|
||
return {"year": normalized["year"] - 1,
|
||
**{key: value for key, value in normalized.items() if key != "year"}}
|
||
|
||
|
||
def scope_documents(evidence, scope, *, release_id=None):
|
||
"""Select only exact node/scope proofs and the scope task's exact frame."""
|
||
from nao_evidence_report import _filters
|
||
from nao_period import normalize_period
|
||
|
||
task = scope.get("task") if isinstance(scope, dict) else None
|
||
if not isinstance(task, dict):
|
||
return []
|
||
node_id, scope_id = scope.get("nodeId"), scope.get("scopeId")
|
||
expected_release = release_id
|
||
expected_filters = _filters(task.get("filters"))
|
||
try:
|
||
expected_period = normalize_period(task.get("period"))
|
||
expected_comparison = normalize_period(task.get("comparisonPeriod"))
|
||
except ValueError:
|
||
return []
|
||
if expected_period is None:
|
||
return []
|
||
purpose = scope.get('purpose')
|
||
selected = []
|
||
for document in evidence if isinstance(evidence, list) else []:
|
||
result = document.get("result") if isinstance(document, dict) else None
|
||
if not isinstance(result, dict):
|
||
continue
|
||
if expected_release is not None and (result.get("releaseId") != expected_release
|
||
or document.get("releaseId") not in (None, expected_release)):
|
||
continue
|
||
mode = document.get("mode")
|
||
proofs = result.get("protocolEvidence")
|
||
if isinstance(proofs, dict):
|
||
proofs = [proofs]
|
||
expected_proof_count = (2 if mode == 'compare'
|
||
or purpose == 'defects' and task.get('comparisonRequired') else 1)
|
||
if not isinstance(proofs, list) or len(proofs) != expected_proof_count or len({
|
||
proof.get('queryId') for proof in proofs if isinstance(proof, dict)}) != expected_proof_count or any(
|
||
not isinstance(proof, dict) or proof.get("nodeId") != node_id
|
||
or proof.get("scopeId") != scope_id for proof in proofs):
|
||
continue
|
||
filters = result.get("filters") if isinstance(result.get("filters"), dict) else result.get("filterBinding")
|
||
if _filters(filters) != expected_filters:
|
||
continue
|
||
if purpose == 'changes':
|
||
from nao_changes import validate_changes
|
||
try:
|
||
if mode != 'changes':
|
||
continue
|
||
validate_changes(result, task, expected_release)
|
||
except (ValueError, TypeError):
|
||
continue
|
||
elif purpose == 'ranking':
|
||
from nao_agent_task import dimension_stages
|
||
dimension = task.get('dimensions', [None])[0] if isinstance(task.get('dimensions'), list) else None
|
||
if (mode != 'rank' or result.get('kind') != 'quality_weight_ranking'
|
||
or result.get('dimension') != dimension
|
||
or result.get('metric') not in task.get('fields', [])
|
||
or result.get('stage') not in dimension_stages(task, dimension, combined=False)):
|
||
continue
|
||
elif purpose in ('source','records'):
|
||
expected_action = 'source' if purpose == 'source' else 'rows'
|
||
if mode != 'investigate' or result.get('kind') != 'quality_investigation' or result.get('action') != expected_action:
|
||
continue
|
||
if result.get('stage') not in task.get('stages',[]):
|
||
continue
|
||
sides = [('current', expected_period)]
|
||
if task.get('comparisonRequired'):
|
||
sides.append(('comparison', expected_comparison))
|
||
raw_sides_match = True
|
||
for side_name, wanted_period in sides:
|
||
side = result.get(side_name)
|
||
side_context = side.get('context') if isinstance(side,dict) else None
|
||
try:
|
||
actual_side_period = normalize_period({key:side_context[key] for key in
|
||
('year','month','quarter','monthStart','monthEnd') if key in side_context})
|
||
except (TypeError,ValueError):
|
||
actual_side_period = None
|
||
if (not isinstance(side_context,dict) or actual_side_period != wanted_period
|
||
or side_context.get('stage') != result.get('stage')):
|
||
raw_sides_match = False
|
||
break
|
||
if not raw_sides_match:
|
||
continue
|
||
if not task.get('comparisonRequired') and result.get('comparison') is not None:
|
||
continue
|
||
elif purpose == 'defects':
|
||
from nao_defect_report import expand_defect_model_view
|
||
result = expand_defect_model_view(result, (task.get('defectQuery') or {}).get('defect'))
|
||
if not isinstance(result, dict):
|
||
continue
|
||
query = task.get('defectQuery') if isinstance(task.get('defectQuery'), dict) else None
|
||
stage = result.get('stage')
|
||
if (mode != 'defects' or result.get('kind') != 'quality_fine_defects'
|
||
or not isinstance(query, dict)
|
||
or result.get('dimension') != query.get('dimension')
|
||
or result.get('defect') != query.get('defect')
|
||
or result.get('category') != query.get('category')
|
||
or stage not in task.get('stages', [])
|
||
or result.get('grain') != 'source_defect_weight'):
|
||
continue
|
||
if task.get('comparisonRequired'):
|
||
if (expected_comparison is None
|
||
or normalize_period(result.get('comparisonPeriod')) != expected_comparison
|
||
or result.get('pairingComplete') is not True
|
||
or result.get('pairedRankingComplete') is not True
|
||
or not isinstance(result.get('pairedRows'), list)):
|
||
continue
|
||
elif result.get('comparisonPeriod') is not None or result.get('pairedRows') is not None:
|
||
continue
|
||
coverage = result.get('coverage')
|
||
if (not isinstance(coverage, dict) or coverage.get('available') is not True
|
||
or result.get('rankingComplete') is not True or not isinstance(result.get('truncated'), bool)
|
||
or not isinstance(result.get('rows'), list)):
|
||
continue
|
||
elif mode not in ('query', 'compare') or result.get('kind') != ('quality_comparison' if mode == 'compare' else 'quality_metrics'):
|
||
continue
|
||
elif mode == 'query' and result.get('view') != 'overall':
|
||
continue
|
||
if purpose == 'trend' and mode != 'query':
|
||
continue
|
||
raw_purpose = purpose in ('source','records')
|
||
defect_purpose = purpose == 'defects'
|
||
if task.get('comparisonRequired') and mode not in ('compare', 'changes') and not raw_purpose and not defect_purpose:
|
||
continue
|
||
if not task.get('comparisonRequired') and mode == 'compare':
|
||
continue
|
||
if raw_purpose:
|
||
try:
|
||
actual_period = normalize_period(result.get("period"))
|
||
actual_comparison = normalize_period(result.get("comparisonPeriod"))
|
||
except ValueError:
|
||
continue
|
||
if (actual_period != expected_period
|
||
or task.get('comparisonRequired') and actual_comparison != expected_comparison
|
||
or not task.get('comparisonRequired') and actual_comparison is not None):
|
||
continue
|
||
elif mode == 'changes':
|
||
if (normalize_period(result.get('currentPeriod')) != expected_period
|
||
or normalize_period(result.get('comparisonPeriod')) != expected_comparison):
|
||
continue
|
||
elif mode == "compare":
|
||
current = (result.get("current") or {}).get("period")
|
||
comparison = (result.get("comparison") or {}).get("period")
|
||
if (expected_comparison is None or normalize_period(current) != expected_period
|
||
or normalize_period(comparison) != expected_comparison):
|
||
continue
|
||
elif defect_purpose:
|
||
try:
|
||
actual_period = normalize_period(result.get('period'))
|
||
actual_comparison = normalize_period(result.get('comparisonPeriod'))
|
||
except ValueError:
|
||
continue
|
||
if (actual_period != expected_period
|
||
or task.get('comparisonRequired') and actual_comparison != expected_comparison
|
||
or not task.get('comparisonRequired') and actual_comparison is not None):
|
||
continue
|
||
else:
|
||
try:
|
||
actual_period = normalize_period(result.get("period"))
|
||
except ValueError:
|
||
continue
|
||
if actual_period != expected_period:
|
||
continue
|
||
if mode == "rank":
|
||
if (result.get("dimension") != scope.get("task", {}).get("dimensions", [None])[0]
|
||
and result.get("dimension") not in scope.get("task", {}).get("dimensions", [])):
|
||
continue
|
||
selected.append(document)
|
||
return selected
|
||
|
||
|
||
def scope_context(scope, *, release_id, question=None):
|
||
"""Create a child-only context; root filters/task remain untouched."""
|
||
task = copy.deepcopy(scope["task"])
|
||
if question is not None and not isinstance(task.get("question"), str):
|
||
task["question"] = question
|
||
context = {"releaseId": release_id, "period": copy.deepcopy(task.get("period")),
|
||
"filters": copy.deepcopy(task.get("filters") or {}), "_agentTask": task}
|
||
if task.get("comparisonPeriod") is not None:
|
||
context["comparisonPeriod"] = copy.deepcopy(task["comparisonPeriod"])
|
||
return context
|