"""Native NAO reads through immutable, server-issued exploration scopes.""" from __future__ import annotations import copy import hashlib import json import time from pathlib import Path from nao_quality_tools import QualityTools, QualityToolError, normalize_filters from nao_query_contract import canonical_filters def _proofs(value): if not isinstance(value, dict): return [] result = value.get('protocolEvidence') # Never alias the signed response list. Callers use this helper while # filtering immutable evidence documents; extending the source list with # nested current/comparison proofs changes the proof count seen later by # strict scope validation. proofs = [result] if isinstance(result, dict) else list(result) if isinstance(result, list) else [] for side in ('current', 'comparison'): if isinstance(value.get(side), dict): proofs.extend(_proofs(value[side])) return list({p['queryId']: p for p in proofs if isinstance(p, dict) and isinstance(p.get('queryId'), str)}.values()) def native_model_view(result): """The full signed response stays in evidence; omit transport duplication.""" def project(value): if isinstance(value, list): return [project(item) for item in value] if not isinstance(value, dict): return value return {key:project(item) for key,item in value.items() if key not in ('protocolEvidence','evidencePath','apiSource') and not (key == 'meaning' and value.get('basis') == 'official_composite')} view = project(result) # Presentation only: raw signed values and proofs remain untouched. A # stage's own rate change and its contribution to composite have different # roles even though both use pp. from nao_native_contract import MASS_FIELDS, formal_display_metadata formal=result.get('kind') in ('quality_comparison','quality_metrics','quality_changes','quality_weight_ranking') fine=result.get('kind')=='quality_fine_defects' and result.get('unit')=='kg' def displays(node,path=()): if isinstance(node,list): for item in node:displays(item,path) elif isinstance(node,dict): metadata={} for key,value in list(node.items()): if isinstance(value,(dict,list)):displays(value,(*path,key));continue stage='黑片' if 'black' in path or key.startswith('black') else '亮片' if 'bright' in path or key.startswith('bright') else None field=unit=None if (formal or fine) and key in MASS_FIELDS:field,unit=key,'kg' elif 'stageDecomposition' in path and key.endswith('ContributionToCompositePP'):field,unit='stageContribution','pp' elif 'stageRateChangesPP' in path:field,unit='rateChange','pp';stage={'black':'黑片','bright':'亮片'}.get(key) if field: display=formal_display_metadata(value,field,unit,stage,signed=unit=='pp') if display:metadata[key]=display if metadata:node['formalDisplay']=metadata displays(view) if result.get('kind') == 'quality_changes' and isinstance(result.get('prioritySignals'),dict): rows = {row.get('key'):row for row in result.get('rows',[]) if isinstance(row,dict)} signals = {} for name, entries in result['prioritySignals'].items(): projected = [] for item in entries if isinstance(entries,list) else []: row = rows.get(item.get('key')) if isinstance(item,dict) else None if row is not None and all(key in row and row[key] == value for key,value in item.items()): projected.append({'key':item['key'], 'label':item.get('label',item['key']), 'sameAsReturnedRow':item['key']}) else: projected.append(project(item)) signals[name] = projected view['prioritySignals'] = signals return view def prepare_step(arguments, task, state): """Make a proposal, never an authorization. The server resolves every scope.""" args = copy.deepcopy(arguments) mode = args.get('mode') if mode == 'details': # The native protocol records complete, pageable investigation responses; # the older sample-details endpoint cannot supply that proof. args.update(mode='investigate', action='rows') mode = 'investigate' root = canonical_filters(task.get('filters') or {}) columns = root.pop('columnFilters', None) supplied = canonical_filters(args.get('filters') or {}) supplied_columns = supplied.pop('columnFilters', columns) for key, value in root.items(): if key in supplied and supplied[key] != value: raise QualityToolError('调查不能改变已确认条件;修改条件请在新一轮提出。') filters, _ = normalize_filters(args.get('scope'), {**root, **supplied}, scope_was_explicit='scope' in args) if not root.get('includeUnassigned') and filters.get('includeUnassigned') is False: filters.pop('includeUnassigned', None) if supplied_columns != columns or ('columnFilters' in args and args['columnFilters'] != (columns or [])): raise QualityToolError('调查不能修改已确认原表列条件。') if columns is not None: filters['columnFilters'] = columns args['columnFilters'] = copy.deepcopy(columns) args.pop('scope', None) for key in ('period', 'comparisonPeriod'): required = task.get(key) if key == 'comparisonPeriod' and mode not in ('compare', 'changes', 'defects', 'investigate'): continue if required is not None: if key in args and args[key] != required: from nao_period import normalize_period, expected_months supplied_period = normalize_period(args[key]) required_period = normalize_period(required) if (not supplied_period or not required_period or supplied_period['year'] != required_period['year'] or expected_months(supplied_period) != expected_months(required_period)): raise QualityToolError('调查期间必须沿用已确认任务。') args[key] = copy.deepcopy(required) args['filters'] = filters allowed = task.get('stages') or ['black', 'bright'] stage = args.get('stage') if stage is not None and stage not in allowed: raise QualityToolError('调查阶段超出已确认范围。') if len(allowed) == 1 and mode in ('defects', 'rank', 'top', 'investigate', 'details', 'changes'): args.setdefault('stage', allowed[0]) stage = args['stage'] if args.get('releaseId') not in (None, state['releaseId']): raise QualityToolError('调查不能切换数据版本。') args['releaseId'] = state['releaseId'] parent_ids = [] parent_filters = root | ({'columnFilters': columns} if columns is not None else {}) # A verified earlier parent scope can supply more than one inherited filter. candidates = [entry for entry in state.get('scopes', []) if entry.get('queryIds') and all(filters.get(k) == v for k, v in entry['filters'].items())] if candidates: parent = max(candidates, key=lambda entry: len(entry['filters'])) if len(parent['filters']) > len(parent_filters): parent_filters = parent['filters'] parent_ids = parent['queryIds'] extras = {k: v for k, v in filters.items() if k not in parent_filters} if set(extras) - {'department', 'group', 'product', 'projectGroup'} or len(extras) > 1: raise QualityToolError('请先取得父范围证据,再沿授权目录逐层下钻;不能一次增加未核验的多层条件。') selector = {'kind': 'base'} if extras: dimension, name = next(iter(extras.items())) selector = {'kind': 'catalog_members', 'dimension': dimension, 'names': [name]} node = {'nodeId': 'explore', 'selector': selector, 'visualPreference': task.get('visualPreference', 'auto'), 'visualType': None, 'comparisonRequired': False} if mode in ('query', 'compare'): if args.get('view', 'overall') != 'overall': raise QualityToolError('跨对象比较请使用changes批量排名;单个对象请用filters后compare/query。') if mode == 'compare': args.pop('view', None) node.update(purpose='trend' if mode == 'query' and task.get('trendRequired') else 'metrics', fields=list(task.get('fields') or ['rate']), stages=list(task.get('stages') or []), comparisonRequired=mode == 'compare') if not node['stages'] and node['fields'] != ['rate']: node['stages'] = ['black', 'bright'] elif mode == 'changes': node.update(purpose='changes', dimension=args.get('dimension'), fields=['rate', 'totalWeight', 'scrapWeight'], stages=[stage] if stage else [], comparisonRequired=True, sort=args.get('sort', 'scrap_delta'), limit=min(args.get('limit', 5), 10)) args['limit'] = node['limit'] elif mode in ('rank', 'defects'): # A single exact product already fixes the object. With no defect # field, the meaningful defect view is that product's defect breakdown. if (mode == 'defects' and args.get('dimension') == 'product' and not args.get('defect') and isinstance(filters.get('product'),str) and filters['product'] and not filters['product'].startswith('~qv1~')): args['dimension'] = 'defect' if mode == 'defects' and args.get('category') is not None: from nao_quality_tools import _normalize_category args['category'] = _normalize_category(stage, args['category']) node.update(purpose='ranking' if mode == 'rank' else 'defects', dimension=args.get('dimension', 'defect'), fields=[args.get('metric', 'totalWeight')] if mode == 'rank' else ['scrapWeight'], stages=[stage] if stage else [], limit=args.get('limit', 10), comparisonRequired=mode == 'defects' and bool(args.get('comparisonPeriod'))) args['limit'] = node['limit'] for key in ('category', 'defect'): if key in args: node[key] = args[key] if mode == 'defects': args.setdefault('dimension', 'defect') elif mode in ('investigate', 'details'): purpose = 'records' if mode == 'details' or args.get('action') == 'rows' else 'source' if not task.get('fullDetails' if purpose == 'records' else 'verifySource'): raise QualityToolError('原始记录或原件核验需要用户明确要求,普通原因分析不能自动读取。') if purpose == 'records': args.update(action='rows', recordFilter='all') args.setdefault('offset', 0) args['limit'] = min(args.get('limit', 100), 100) else: args.update(action='source', limit=100) args.pop('offset', None) args.pop('recordFilter', None) node.update(purpose=purpose, fields=[], stages=[stage] if stage else [], visualPreference='none', comparisonRequired=bool(args.get('comparisonPeriod'))) if args.get('fields'): node['sourceFields'] = {stage: copy.deepcopy(args['fields'])} else: raise QualityToolError('自主调查使用compare/query/changes/rank/defects;先读catalog了解能力。') scope_arguments = copy.deepcopy(args) if node['purpose'] == 'records': # Pages are parts of one authorized record snapshot, not new scopes. # Response caching below still uses the complete page arguments. scope_arguments.pop('offset', None) scope_arguments.pop('limit', None) request_key = hashlib.sha256(json.dumps(scope_arguments, sort_keys=True, ensure_ascii=False).encode()).hexdigest() node['nodeId'] = 'e' + request_key[:24] return args, {'requestKey': request_key, 'node': node, 'parentQueryIds': parent_ids} class NativeExplorationTools: def __init__(self, *, delegated, evidence_dir, task, identity, state_path): self.delegated, self.evidence_dir, self.task = delegated, Path(evidence_dir), task self.identity, self.state_path = identity, Path(state_path) def observation_coverage(self, result): snapshot = self.delegated.call('/api/analysis/protocol/queries', payload={}, method='POST') pairs = {(p.get('nodeId'),p.get('scopeId')) for p in _proofs(result)} rows = [row for row in snapshot.get('scopeCoverage', []) if (row.get('nodeId'),row.get('scopeId')) in pairs] def bounded(items): return list(dict.fromkeys(str(item)[:600] for item in items if item))[:12] return {**result, 'investigationCoverage': { 'scopeComplete': bool(rows) and all(row.get('complete') is True for row in rows), 'missingEvidence': bounded(gap for row in rows for gap in row.get('missingEvidence', [])), 'rootGoalGaps': bounded(snapshot.get('rootGoalGaps', [])), 'meaning': '正式结论须使用完整范围证据;未完整细项可换为明确已提供的具体字段查询,不能把缺失值当零。'}} def quality_data(self, arguments): from nao_quality_runtime import _atomic_json, _read_json, _require_private_regular_file, _file_lock from nao_protocol_execution import ScopedApi if not isinstance(arguments, dict): raise QualityToolError('quality_data参数必须是对象。') arguments = copy.deepcopy(arguments) fresh = arguments.pop('freshQuery', False) if type(fresh) is not bool: raise QualityToolError('freshQuery必须是布尔值,仅明确重查时使用。') # Even an in-turn cache hit must reauthorize the current turn. self.delegated.call('/api/analysis/model-authorization', method='GET') with _file_lock(self.state_path.with_suffix('.lock'), blocking=True): state = _read_json(self.state_path) if _require_private_regular_file(self.state_path) else {} if state.get('executionId') != self.identity['executionId']: state = {'executionId': self.identity['executionId'], 'releaseId': self.identity['releaseId'], 'cache': {}, 'scopes': [], 'noProgress': 0, 'readCount': 0} if state.get('halted'): raise QualityToolError('连续三次未取得新证据,已停止调查并保留已核实结果。') scoped = None try: if arguments.get('mode') == 'catalog': key = 'catalog-' + hashlib.sha256(json.dumps(arguments, sort_keys=True).encode()).hexdigest() if key in state['cache'] and not fresh: state['noProgress'] += 1 state['halted'] = state['noProgress'] >= 3 return {**copy.deepcopy(state['cache'][key]), 'reusedEvidence': True} result = QualityTools(api_factory=lambda: self.delegated, evidence_dir=self.evidence_dir).quality_data(arguments) state['cache'][key] = copy.deepcopy(result) state['noProgress'] = 0 return result args, proposal = prepare_step(arguments, self.task, state) QualityTools(api_factory=lambda: self.delegated, evidence_dir=self.evidence_dir)._validate_arguments(args) key = hashlib.sha256(json.dumps(args, sort_keys=True, ensure_ascii=False).encode()).hexdigest() if key in state['cache'] and not fresh: state['noProgress'] += 1 state['halted'] = state['noProgress'] >= 3 return {**self.observation_coverage(copy.deepcopy(state['cache'][key])), 'reusedEvidence': True, 'investigationNotice': '复用本轮相同查询证据;请依据结果换调查方向或结束答复。'} registrations = state.setdefault('registrations', {}) registered = registrations.get(proposal['requestKey']) if registered is None: registered = self.delegated.call('/api/analysis/protocol/exploration/steps', payload=proposal, method='POST') registrations[proposal['requestKey']] = copy.deepcopy(registered) scope = registered['scope'] child = registered['task'] if args.get('mode') == 'investigate' and args.get('fields'): args['fields'] = copy.deepcopy((child.get('investigationFields') or {}).get(args.get('stage'), args['fields'])) scoped = ScopedApi(self.delegated, registered['nodeId'], registered['scopeId']) scoped.read_count = state['readCount'] tools = QualityTools(api_factory=lambda: scoped, evidence_dir=self.evidence_dir, query_contract={'task': child, 'releaseId': state['releaseId'], 'exactScope': True, 'nodeId': registered['nodeId'], 'scopeId': registered['scopeId']}) tools._bulk_changes = True started = time.monotonic() result = tools.quality_data(args) state['queryElapsedMs'] = state.get('queryElapsedMs', 0) + round((time.monotonic() - started) * 1000) proof_ids = [p['queryId'] for p in _proofs(result)] if not proof_ids: raise QualityToolError('查询未返回执行证明,不能作为自主调查证据。') previous_result = state['cache'].get(key) same_content = bool(previous_result and sorted(p.get('responseHash') for p in _proofs(previous_result)) == sorted(p.get('responseHash') for p in _proofs(result))) state['cache'][key] = copy.deepcopy(result) state['scopes'].append({'nodeId': registered['nodeId'], 'scopeId': registered['scopeId'], 'filters': child['filters'], 'queryIds': proof_ids}) state['noProgress'] = state['noProgress'] + 1 if same_content else 0 state['halted'] = state['noProgress'] >= 3 if same_content: result['investigationNotice'] = '已明确重查,但正式响应没有新增内容;请依据已有结果换调查方向或结束。' return self.observation_coverage(result) except Exception as error: state['noProgress'] += 1 state['halted'] = state['noProgress'] >= 3 from nao_quality_runtime import RuntimeErrorSafe safe = str(error)[:600] if isinstance(error, (RuntimeErrorSafe, QualityToolError, ValueError)) else type(error).__name__ state.setdefault('errors', []).append({'type': type(error).__name__, 'message': safe}) state['errors'] = state['errors'][-12:] if isinstance(error, RuntimeErrorSafe): raise QualityToolError(safe) from None raise finally: if scoped is not None: state['readCount'] = scoped.read_count _atomic_json(self.state_path, state)