"""Factory MES OpenAPI connector。 目标地址全部来自管理员维护的可信系统目录；模型和普通用户只能传 operation_id 与结构化参数，不能传 URL。 """ from __future__ import annotations import json import re import time from dataclasses import dataclass from threading import Lock from typing import Any, Optional from urllib.parse import quote, urljoin, urlparse import httpx class FactoryMesError(RuntimeError): pass _HTTP_METHODS = ("get", "head", "post", "put", "patch", "delete") _SPEC_CACHE: dict[str, tuple[float, dict[str, Any]]] = {} _SPEC_LOCK = Lock() DEFAULT_QUERY_GUIDANCE = ( "产量、良率、缺陷、库存、绩效、趋势和按日/月汇总等统计聚合查询，" "统一先调用 BI dataset list，再执行匹配的数据集。日志和业务明细列表用于" "用户明确要求查看逐条记录、编号或追溯过程的场景。未匹配到 dataset 时，" "先限定范围或向用户确认明细查询需求。" ) DEFAULT_RECOMMENDED_OPERATIONS = ("bi_dataset_list", "bi_dataset_exec") def _bool_value(value: Any, default: bool) -> bool: raw = str(value if value is not None else "").strip().lower() if not raw: return default return raw in {"1", "true", "yes", "on"} def _validated_http_url(raw: str, label: str) -> str: value = (raw or "").strip().rstrip("/") parsed = urlparse(value) if parsed.scheme not in {"http", "https"} or not parsed.netloc: raise FactoryMesError(f"{label} 必须是有效的 http(s) URL") if parsed.username or parsed.password: raise FactoryMesError(f"{label} 不能内嵌凭据") return value @dataclass(frozen=True) class FactoryMesConfig: base_url: str openapi_url: str login_path: str allowed_post_operations: frozenset[str] timeout_seconds: float max_result_bytes: int max_total_result_bytes: int max_page_size: int verify_tls: bool query_guidance: str recommended_operation_ids: tuple[str, ...] @classmethod def from_mapping(cls, data: dict[str, Any]) -> "FactoryMesConfig": """从管理员保存的可信目录配置构建运行态配置。""" base = _validated_http_url(str(data.get("base_url") or ""), "base_url") spec = _validated_http_url( str(data.get("openapi_url") or ""), "openapi_url" ) login_path = str(data.get("login_path") or "/api/auth/token/").strip() if not login_path.startswith("/") or "://" in login_path: raise FactoryMesError("login_path 必须是站内绝对路径") raw_allowed = data.get("allowed_post_operations") or [] if isinstance(raw_allowed, str): raw_allowed = raw_allowed.split(",") if not isinstance(raw_allowed, (list, tuple, set)): raise FactoryMesError("allowed_post_operations 必须是字符串数组") allowed = frozenset(str(item).strip() for item in raw_allowed if str(item).strip()) guidance = str(data.get("query_guidance") or DEFAULT_QUERY_GUIDANCE).strip() if len(guidance) > 4000: raise FactoryMesError("query_guidance 不能超过 4000 字符") raw_recommended = data.get( "recommended_operation_ids", DEFAULT_RECOMMENDED_OPERATIONS ) if isinstance(raw_recommended, str): raw_recommended = raw_recommended.split(",") if not isinstance(raw_recommended, (list, tuple, set)): raise FactoryMesError("recommended_operation_ids 必须是字符串数组") recommended = tuple(dict.fromkeys( str(item).strip() for item in raw_recommended if str(item).strip() )) if len(recommended) > 30 or any(len(item) > 200 for item in recommended): raise FactoryMesError("recommended_operation_ids 最多 30 项且每项不超过 200 字符") max_result = max(4096, min(int(data.get("max_result_bytes", 65536)), 1048576)) return cls( base_url=base, openapi_url=spec, login_path=login_path, allowed_post_operations=allowed, timeout_seconds=max(1.0, min(float(data.get("timeout_seconds", 15)), 60.0)), max_result_bytes=max_result, max_total_result_bytes=max( max_result, min(int(data.get("max_total_result_bytes", 262144)), 4194304), ), max_page_size=max(1, min(int(data.get("max_page_size", 200)), 1000)), verify_tls=_bool_value(data.get("verify_tls"), True), query_guidance=guidance, recommended_operation_ids=recommended, ) class FactoryMesClient: def __init__(self, username: str, password: str, cfg: FactoryMesConfig): self.username = username self.password = password self.cfg = cfg def _client(self) -> httpx.Client: return httpx.Client( timeout=self.cfg.timeout_seconds, verify=self.cfg.verify_tls, follow_redirects=False, ) def authenticate(self) -> str: url = urljoin(self.cfg.base_url + "/", self.cfg.login_path.lstrip("/")) try: with self._client() as client: response = client.post( url, json={"username": self.username, "password": self.password}, ) except httpx.HTTPError as exc: raise FactoryMesError(f"Factory MES 登录连接失败: {type(exc).__name__}") from exc if response.status_code >= 400: raise FactoryMesError(f"Factory MES 登录失败(HTTP {response.status_code})") try: token = response.json().get("access", "") except (ValueError, AttributeError): token = "" if not isinstance(token, str) or not token: raise FactoryMesError("Factory MES 登录响应缺少 access token") return token def _fetch_spec(self, token: str) -> dict[str, Any]: now = time.monotonic() with _SPEC_LOCK: hit = _SPEC_CACHE.get(self.cfg.openapi_url) if hit and now - hit[0] < 300: return hit[1] try: with self._client() as client: response = client.get( self.cfg.openapi_url, headers={"Authorization": f"Bearer {token}"}, ) except httpx.HTTPError as exc: raise FactoryMesError(f"Factory OpenAPI 获取失败: {type(exc).__name__}") from exc if response.status_code >= 400: raise FactoryMesError(f"Factory OpenAPI 获取失败(HTTP {response.status_code})") try: spec = response.json() except ValueError as exc: raise FactoryMesError("Factory OpenAPI 不是有效 JSON") from exc if not isinstance(spec, dict) or not isinstance(spec.get("paths"), dict): raise FactoryMesError("Factory OpenAPI 缺少 paths") with _SPEC_LOCK: _SPEC_CACHE[self.cfg.openapi_url] = (now, spec) return spec @staticmethod def _operation_id(method: str, path: str, operation: dict[str, Any]) -> str: explicit = operation.get("operationId") if isinstance(explicit, str) and explicit.strip(): return explicit.strip() safe_path = re.sub(r"[^a-zA-Z0-9]+", "_", path).strip("_") return f"{method}_{safe_path}" @classmethod def _operations(cls, spec: dict[str, Any]) -> list[dict[str, Any]]: results: list[dict[str, Any]] = [] for path, path_item in (spec.get("paths") or {}).items(): if not isinstance(path_item, dict): continue common = path_item.get("parameters") or [] for method in _HTTP_METHODS: operation = path_item.get(method) if not isinstance(operation, dict): continue params = list(common) + list(operation.get("parameters") or []) results.append({ "operation_id": cls._operation_id(method, path, operation), "method": method.upper(), "path": path, "summary": operation.get("summary") or "", "description": operation.get("description") or "", "tags": operation.get("tags") or [], "parameters": params, "request_body": operation.get("requestBody"), }) return results def _spec_base_path(self, spec: dict[str, Any]) -> str: """Return the API path prefix declared by Swagger 2 / OpenAPI 3. The remote specification may describe a different host, but an external system definition is the only authority allowed to choose the target origin. OpenAPI ``servers`` therefore contributes only a same-origin path prefix. """ raw_base_path = spec.get("basePath") if raw_base_path is not None: if not isinstance(raw_base_path, str) or not raw_base_path.startswith("/"): raise FactoryMesError("Swagger basePath 必须是站内绝对路径") parsed = urlparse(raw_base_path) if parsed.netloc or parsed.query or parsed.fragment or "://" in raw_base_path: raise FactoryMesError("Swagger basePath 非法") return parsed.path.rstrip("/") servers = spec.get("servers") if not isinstance(servers, list) or not servers: return "" server = servers[0] raw_url = server.get("url") if isinstance(server, dict) else None if not isinstance(raw_url, str) or not raw_url.strip(): raise FactoryMesError("OpenAPI server URL 无效") raw_url = raw_url.strip() if "{" in raw_url or "}" in raw_url: raise FactoryMesError("OpenAPI server URL 包含未解析变量") declared = urlparse(raw_url) base = urlparse(self.cfg.base_url) if declared.netloc and (declared.scheme, declared.netloc) != ( base.scheme, base.netloc, ): raise FactoryMesError("OpenAPI server 越出 Factory MES 主机") if declared.query or declared.fragment: raise FactoryMesError("OpenAPI server URL 不能包含查询或片段") return ("/" + declared.path.lstrip("/")).rstrip("/") def _operation_url(self, spec: dict[str, Any], operation_path: str) -> str: prefix = self._spec_base_path(spec) base = urlparse(self.cfg.base_url) configured_path = base.path.rstrip("/") path = operation_path configured_has_prefix = bool(prefix) and ( configured_path == prefix or configured_path.endswith(prefix) ) operation_has_prefix = bool(prefix) and ( path == prefix or path.startswith(prefix + "/") ) if configured_has_prefix and operation_has_prefix: path = path[len(prefix):] or "/" elif prefix and not configured_has_prefix and not operation_has_prefix: path = prefix + "/" + path.lstrip("/") combined_path = "/".join( part.strip("/") for part in (configured_path, path) if part.strip("/") ) if operation_path.endswith("/") and combined_path: combined_path += "/" url = urljoin(f"{base.scheme}://{base.netloc}/", combined_path) call_origin = urlparse(url) if (call_origin.scheme, call_origin.netloc) != (base.scheme, base.netloc): raise FactoryMesError("接口目标越出 Factory MES 主机") return url def test_connection(self) -> dict[str, Any]: token = self.authenticate() spec = self._fetch_spec(token) return {"operation_count": len(self._operations(spec))} def search(self, query: str, limit: int = 12) -> list[dict[str, Any]]: query = (query or "").strip().lower() if not query: raise FactoryMesError("query 不能为空") token = self.authenticate() spec = self._fetch_spec(token) terms = list(dict.fromkeys( [query] + [x for x in re.split(r"[\s,，。/]+", query) if len(x) >= 2] )) recommended_order = { operation_id: index for index, operation_id in enumerate(self.cfg.recommended_operation_ids) } scored: list[tuple[int, int, dict[str, Any]]] = [] for op in self._operations(spec): method = op["method"].lower() if method not in {"get", "head"} and not ( method == "post" and op["operation_id"] in self.cfg.allowed_post_operations ): continue hay = " ".join([ op["operation_id"], op["path"], op["summary"], op["description"], " ".join(str(x) for x in op["tags"]), ]).lower() score = sum(5 if term == query and term in hay else 1 for term in terms if term in hay) recommended = op["operation_id"] in recommended_order if score or recommended: compact = dict(op) compact["parameters"] = [ { "name": p.get("name"), "in": p.get("in"), "required": bool(p.get("required")), "type": p.get("type") or (p.get("schema") or {}).get("type"), "description": p.get("description") or "", } for p in op["parameters"] if isinstance(p, dict) and "$ref" not in p ] compact.pop("request_body", None) compact["recommended"] = recommended scored.append(( 0 if recommended else 1, recommended_order.get(op["operation_id"], -score), compact, )) scored.sort(key=lambda item: (item[0], item[1], item[2]["operation_id"])) return [item[2] for item in scored[: max(1, min(int(limit), 30))]] def call( self, operation_id: str, arguments: Optional[dict[str, Any]] = None, body: Any = None, ) -> dict[str, Any]: token = self.authenticate() spec = self._fetch_spec(token) matches = [op for op in self._operations(spec) if op["operation_id"] == operation_id] if len(matches) != 1: raise FactoryMesError("operation_id 不存在或不唯一，请先搜索接口") op = matches[0] if not op["path"].startswith("/") or "://" in op["path"]: raise FactoryMesError("OpenAPI operation path 非法") method = op["method"].lower() if method not in {"get", "head"} and not ( method == "post" and operation_id in self.cfg.allowed_post_operations ): raise FactoryMesError(f"operation {operation_id} 未列入只读调用范围") supplied = dict(arguments or {}) path = op["path"] query: dict[str, Any] = {} headers = {"Authorization": f"Bearer {token}"} request_body = body for param in op["parameters"]: if not isinstance(param, dict) or "$ref" in param: continue name = param.get("name") location = param.get("in") if not isinstance(name, str): continue # Swagger 2 的 body 参数既可按搜索结果中的参数名放在 arguments， # 也可使用元工具独立的 body 字段；两者只取一个。 present = name in supplied or (location == "body" and request_body is not None) if param.get("required") and not present: raise FactoryMesError(f"缺少必填参数: {name}") if name not in supplied: continue value = supplied.pop(name) if location == "path": path = path.replace("{" + name + "}", quote(str(value), safe="")) elif location == "query": if name == "page_size": try: value = max(1, min(int(value), self.cfg.max_page_size)) except (TypeError, ValueError) as exc: raise FactoryMesError("page_size 必须是整数") from exc elif name == "page" and str(value).strip() == "0": raise FactoryMesError( "外部系统查询不允许 page=0 关闭分页，请使用 dataset 或分页查看明细" ) elif name == "pageoff" and _bool_value(value, False): raise FactoryMesError( "外部系统查询不允许关闭分页，请使用 dataset 或分页查看明细" ) query[name] = value elif location == "body" and request_body is None: request_body = value if supplied: raise FactoryMesError("存在接口定义之外的参数: " + ", ".join(sorted(supplied))) if "{" in path or "}" in path: raise FactoryMesError("路径参数未完整提供") url = self._operation_url(spec, path) try: with self._client() as client: response = client.request( method.upper(), url, params=query, json=request_body if method == "post" else None, headers=headers, ) except httpx.HTTPError as exc: raise FactoryMesError(f"Factory 接口调用失败: {type(exc).__name__}") from exc if response.status_code >= 400: raise FactoryMesError(f"Factory 接口返回 HTTP {response.status_code}") content_type = response.headers.get("content-type", "") try: payload: Any = response.json() if "json" in content_type else response.text except ValueError: payload = response.text encoded = json.dumps(payload, ensure_ascii=False, default=str) truncated = len(encoded.encode("utf-8")) > self.cfg.max_result_bytes if truncated: encoded = encoded.encode("utf-8")[: self.cfg.max_result_bytes].decode("utf-8", "ignore") payload = encoded return { "operation_id": operation_id, "status_code": response.status_code, "truncated": truncated, "data": payload, }