"""``calculator``:唯一允许产生“新数字”的工具,因此输入必须可溯源。 支持的运算: * ``sum`` / ``mean`` / ``median`` / ``min`` / ``max`` / ``count`` —— 统计; * ``growth``((本期/上期-1))、``ratio``(a/b)、``index``(a/b*1000)、``share``(a/合计); * ``expression`` —— 只允许数字、四则运算、括号和已绑定变量名(无函数、无属性访问)。 返回值同时给出 ``inputs``(每个输入值及其来源 call_id/row_hash)与 ``_trace.calculation_id``;核验层据此验证“答案里的数字由这些输入算出”。 """ from __future__ import annotations import ast import hashlib import json import statistics from decimal import Decimal, DivisionByZero, InvalidOperation from .ledger import ledger from .objects import new_id ALLOWED_OPS = {"sum", "mean", "avg", "median", "min", "max", "count", "growth", "ratio", "index", "share", "expression"} class CalcError(ValueError): """计算参数非法。""" def _decimal(value: object) -> Decimal: if isinstance(value, Decimal): return value if isinstance(value, bool): raise CalcError("布尔值不能参与计算") try: return Decimal(str(value).replace(",", "").strip()) except (InvalidOperation, AttributeError, ValueError) as error: raise CalcError(f"无法转换为数值: {value!r}") from error class _Evaluator(ast.NodeVisitor): """白名单式表达式求值(不使用 eval)。""" def __init__(self, variables: dict[str, Decimal]) -> None: self.variables = variables self.used: list[str] = [] def evaluate(self, expression: str) -> Decimal: try: tree = ast.parse(expression, mode="eval") except SyntaxError as error: raise CalcError(f"表达式语法错误: {error.msg}") from error return self.visit(tree.body) def visit_BinOp(self, node: ast.BinOp): # noqa: N802 left = self.visit(node.left) right = self.visit(node.right) if isinstance(node.op, ast.Add): return left + right if isinstance(node.op, ast.Sub): return left - right if isinstance(node.op, ast.Mult): return left * right if isinstance(node.op, ast.Div): if right == 0: raise CalcError("除数为 0") return left / right if isinstance(node.op, ast.Pow): return left**right if isinstance(node.op, ast.Mod): if right == 0: raise CalcError("取模的除数为 0") return left % right raise CalcError(f"不支持的运算符: {type(node.op).__name__}") def visit_UnaryOp(self, node: ast.UnaryOp): # noqa: N802 value = self.visit(node.operand) if isinstance(node.op, ast.USub): return -value if isinstance(node.op, ast.UAdd): return value raise CalcError("不支持的一元运算") def visit_Constant(self, node: ast.Constant): # noqa: N802 if isinstance(node.value, bool) or not isinstance(node.value, (int, float)): raise CalcError("表达式只允许数字常量") return _decimal(node.value) def visit_Name(self, node: ast.Name): # noqa: N802 if node.id not in self.variables: raise CalcError(f"未绑定变量: {node.id}") self.used.append(node.id) return self.variables[node.id] def visit_Expression(self, node: ast.Expression): # noqa: N802 return self.visit(node.body) def generic_visit(self, node): # noqa: D401 raise CalcError(f"表达式包含不允许的语法: {type(node).__name__}") def _result_hash(payload: object) -> str: return "sha256:" + hashlib.sha256(json.dumps(payload, sort_keys=True, ensure_ascii=False, default=str).encode("utf-8")).hexdigest() def calculate( op: str, inputs: list[dict] | None = None, expression: str | None = None, *, session_id: str = "", label: str = "", ) -> dict: """执行一次计算并登记台账。""" op = str(op or "sum").lower() if op not in ALLOWED_OPS: raise CalcError(f"不支持的运算: {op}(可用:{sorted(ALLOWED_OPS)})") inputs = inputs or [] if not inputs and op not in ("expression",): raise CalcError("至少需要一个输入值") values: list[Decimal] = [] enriched: list[dict] = [] unverified = 0 for index, item in enumerate(inputs): if isinstance(item, (int, float, str)): item = {"value": item} if not isinstance(item, dict): raise CalcError(f"第 {index + 1} 个输入格式错误") raw = item.get("value") if raw is None: raise CalcError(f"第 {index + 1} 个输入缺少 value") value = _decimal(raw) values.append(value) call_id = str(item.get("from_call_id") or "") row_hash = str(item.get("row_hash") or "") verified = False if call_id: entry = ledger.get(call_id) if entry: verified = True if row_hash: payload_text = json.dumps(entry["result"], ensure_ascii=False, default=str) verified = row_hash in payload_text if not verified: unverified += 1 enriched.append( { "index": index, "label": str(item.get("label") or ""), "value": str(value), "from_call_id": call_id or None, "row_hash": row_hash or None, "verified": verified, } ) variables = {chr(ord("a") + index): value for index, value in enumerate(values)} variables.update({f"v{index + 1}": value for index, value in enumerate(values)}) if op in ("sum", "mean", "avg", "median", "min", "max", "count"): if op == "sum": result = sum(values) elif op in ("mean", "avg"): result = sum(values) / len(values) elif op == "median": result = _decimal(statistics.median(sorted(values))) elif op == "min": result = min(values) elif op == "max": result = max(values) else: result = _decimal(len(values)) shown = f"{op}({', '.join(str(value) for value in values)})" elif op == "growth": if len(values) != 2: raise CalcError("growth 需要两个输入:[本期, 上期]") if values[1] == 0: raise CalcError("上期为 0,环比无法计算(按需求留空而不是填 0)") result = values[0] / values[1] - 1 shown = f"({values[0]} / {values[1]} - 1)" elif op == "ratio": if len(values) != 2: raise CalcError("ratio 需要两个输入:[分子, 分母]") if values[1] == 0: raise CalcError("分母为 0,比值无法计算") result = values[0] / values[1] shown = f"({values[0]} / {values[1]})" elif op == "index": if len(values) != 2: raise CalcError("index 需要两个输入:[当期, 基期]") if values[1] == 0: raise CalcError("基期为 0,指数无法计算") result = values[0] / values[1] * Decimal(1000) shown = f"({values[0]} / {values[1]} * 1000)" elif op == "share": if len(values) < 2: raise CalcError("share 需要 [部分, 合计]") if values[1] == 0: raise CalcError("合计为 0,占比无法计算") result = values[0] / values[1] shown = f"({values[0]} / {values[1]})" else: if not expression: raise CalcError("expression 运算需要提供 expression") evaluator = _Evaluator(variables) result = evaluator.evaluate(expression) shown = expression if not result.is_finite(): raise CalcError("计算结果不是有限数值") calculation_id = new_id("calc") input_signature = [{"value": str(value), "from_call_id": item["from_call_id"], "row_hash": item["row_hash"]} for value, item in zip(values, enriched)] trace = { "calculation_id": calculation_id, "result_hash": _result_hash({"result": str(result), "inputs": input_signature, "op": op}), "op": op, } payload = { "call_id": calculation_id, "tool": "calculator", "op": op, "label": label, "expression": shown, "result": str(result), "inputs": enriched, "unverified_inputs": unverified, "all_inputs_verified": unverified == 0, "_trace": trace, } ledger.record( calculation_id, "calculator", {"op": op, "inputs": inputs, "expression": expression, "label": label}, payload, session_id=session_id, rows=[ { "values": {"result": str(result)}, "_trace": {"object_id": "", "table": "calculator", "row_index": -1, "row_hash": trace["result_hash"]}, } ], ) return payload