@josephyan/qingflow-cli 0.2.0-beta.1007 → 0.2.0-beta.1010

package/src/qingflow_mcp/tools/export_tools.py

@@ -0,0 +1,960 @@
+from __future__ import annotations
+
+import json
+import re
+from copy import deepcopy
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from time import monotonic, sleep
+from typing import Any, cast
+from uuid import uuid4
+
+from mcp.server.fastmcp import FastMCP
+
+from ..config import DEFAULT_PROFILE
+from ..errors import QingflowApiError
+from ..export_store import ExportJobStore
+from ..json_types import JSONObject
+from .base import ToolBase, tool_cn_name
+from .record_tools import AccessibleViewRoute, LAYOUT_ONLY_QUE_TYPES, RecordTools
+
+
+EXPORT_STATUS_BY_PROCESS_STATUS = {
+    1: "queued",
+    2: "running",
+    3: "succeeded",
+    4: "failed",
+    5: "failed",
+}
+DEFAULT_EXPORT_TIMEOUT_SECONDS = 60.0
+EXPORT_POLL_INTERVAL_SECONDS = 1.5
+_SAFE_FILE_CHARS = re.compile(r"[^0-9A-Za-z._-]+")
+LOCAL_TIMEZONE = datetime.now().astimezone().tzinfo or timezone.utc
+
+
+class ExportTools(ToolBase):
+    def __init__(
+        self,
+        sessions,
+        backend,
+        *,
+        job_store: ExportJobStore | None = None,
+    ) -> None:
+        super().__init__(sessions, backend)
+        self._record_tools = RecordTools(sessions, backend)
+        self._job_store = job_store or ExportJobStore()
+
+    def register(self, mcp: FastMCP) -> None:
+        @mcp.tool(description="Start an asynchronous xlsx export for a Qingflow record view and return an opaque export_handle.")
+        def record_export_start(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            view_id: str = "system:all",
+        ) -> dict[str, Any]:
+            return self.record_export_start(
+                profile=profile,
+                app_key=app_key,
+                view_id=view_id,
+            )
+
+        @mcp.tool(description="Get asynchronous record export status by opaque export_handle.")
+        def record_export_status_get(
+            profile: str = DEFAULT_PROFILE,
+            export_handle: str = "",
+        ) -> dict[str, Any]:
+            return self.record_export_status_get(
+                profile=profile,
+                export_handle=export_handle,
+            )
+
+        @mcp.tool(description="Get completed record export result, returning remote file links and optionally downloading files locally.")
+        def record_export_get(
+            profile: str = DEFAULT_PROFILE,
+            export_handle: str = "",
+            download_to_path: str | None = None,
+        ) -> dict[str, Any]:
+            return self.record_export_get(
+                profile=profile,
+                export_handle=export_handle,
+                download_to_path=download_to_path,
+            )
+
+        @mcp.tool(description="Start a record export, wait for completion, and download the xlsx locally while also returning remote download links.")
+        def record_export_direct(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            view_id: str = "system:all",
+            download_to_path: str | None = None,
+            wait_timeout_seconds: float | None = None,
+        ) -> dict[str, Any]:
+            return self.record_export_direct(
+                profile=profile,
+                app_key=app_key,
+                view_id=view_id,
+                download_to_path=download_to_path,
+                wait_timeout_seconds=wait_timeout_seconds,
+            )
+
+    @tool_cn_name("记录导出启动")
+    def record_export_start(
+        self,
+        *,
+        profile: str = DEFAULT_PROFILE,
+        app_key: str,
+        view_id: str = "system:all",
+    ) -> dict[str, Any]:
+        normalized_app_key = str(app_key or "").strip()
+        normalized_view_id = str(view_id or "").strip() or "system:all"
+        if not normalized_app_key:
+            return self._failed_export_result(
+                error_code="EXPORT_START_FAILED",
+                message="app_key is required",
+                extra={"view_id": normalized_view_id, "status": "failed"},
+            )
+
+        def runner(session_profile, context):
+            resolved_view, compatibility_warnings = self._record_tools._resolve_accessible_view_route(
+                profile,
+                context,
+                normalized_app_key,
+                view_id=normalized_view_id,
+                list_type=None,
+                view_key=None,
+                view_name=None,
+                allow_default=True,
+            )
+            export_config, export_config_warnings = self._build_export_config(
+                profile=profile,
+                context=context,
+                app_key=normalized_app_key,
+                resolved_view=resolved_view,
+            )
+            filter_bean = self._build_export_filter_bean(resolved_view)
+            started_at = _utc_now().replace(microsecond=0).isoformat()
+            socket_result = self.backend.start_socket_record_export(
+                context,
+                app_key=normalized_app_key,
+                view_id=resolved_view.view_id,
+                view_key=resolved_view.view_selection.view_key if resolved_view.view_selection is not None else None,
+                filter_bean=filter_bean,
+                export_config=export_config,
+            )
+            export_handle = uuid4().hex
+            self._job_store.put(
+                export_handle,
+                {
+                    "created_at": started_at,
+                    "profile": profile,
+                    "app_key": normalized_app_key,
+                    "view_id": resolved_view.view_id,
+                    "backend_export_id": str(socket_result.get("backend_export_id") or ""),
+                    "started_at": started_at,
+                    "uid": session_profile.uid,
+                },
+            )
+            warnings = [
+                *deepcopy(compatibility_warnings),
+                *deepcopy(export_config_warnings),
+                *deepcopy(cast(list[JSONObject], socket_result.get("warnings") or [])),
+            ]
+            return {
+                "ok": True,
+                "status": "accepted",
+                "app_key": normalized_app_key,
+                "view_id": resolved_view.view_id,
+                "export_handle": export_handle,
+                "file_urls": [],
+                "file_names": [],
+                "downloaded_files": [],
+                "warnings": warnings,
+                "verification": {
+                    "export_acknowledged": bool(socket_result.get("backend_export_id")),
+                    "view_route_supported": True,
+                },
+                "request_route": self.backend.describe_route(context),
+            }
+
+        try:
+            return self._run(profile, runner)
+        except RuntimeError as exc:
+            return self._runtime_error_as_result(
+                exc,
+                error_code="EXPORT_START_FAILED",
+                extra={"app_key": normalized_app_key, "view_id": normalized_view_id},
+            )
+
+    @tool_cn_name("记录导出状态")
+    def record_export_status_get(
+        self,
+        *,
+        profile: str = DEFAULT_PROFILE,
+        export_handle: str,
+    ) -> dict[str, Any]:
+        normalized_handle = str(export_handle or "").strip()
+        if not normalized_handle:
+            return self._failed_export_result(
+                error_code="CONFIG_ERROR",
+                message="export_handle is required",
+                extra={"status": "failed"},
+            )
+
+        def runner(_session_profile, context):
+            local_job = self._job_store.get(normalized_handle)
+            if local_job is None:
+                return self._failed_export_result(
+                    error_code="EXPORT_HANDLE_UNKNOWN",
+                    message="export_handle is missing or expired",
+                    extra={"export_handle": normalized_handle, "status": "failed"},
+                )
+            snapshot = self._resolve_export_snapshot(context, local_job)
+            return self._status_payload_from_snapshot(local_job, normalized_handle, snapshot)
+
+        try:
+            return self._run(profile, runner)
+        except RuntimeError as exc:
+            return self._runtime_error_as_result(
+                exc,
+                error_code="EXPORT_STATUS_FAILED",
+                extra={"export_handle": normalized_handle},
+            )
+
+    @tool_cn_name("记录导出结果")
+    def record_export_get(
+        self,
+        *,
+        profile: str = DEFAULT_PROFILE,
+        export_handle: str,
+        download_to_path: str | None = None,
+    ) -> dict[str, Any]:
+        normalized_handle = str(export_handle or "").strip()
+        if not normalized_handle:
+            return self._failed_export_result(
+                error_code="CONFIG_ERROR",
+                message="export_handle is required",
+                extra={"status": "failed"},
+            )
+
+        def runner(_session_profile, context):
+            local_job = self._job_store.get(normalized_handle)
+            if local_job is None:
+                return self._failed_export_result(
+                    error_code="EXPORT_HANDLE_UNKNOWN",
+                    message="export_handle is missing or expired",
+                    extra={"export_handle": normalized_handle, "status": "failed"},
+                )
+            snapshot = self._resolve_export_snapshot(context, local_job)
+            normalized_status = str(snapshot.get("status") or "unknown")
+            if normalized_status not in {"succeeded", "failed"}:
+                return self._failed_export_result(
+                    error_code="EXPORT_NOT_READY",
+                    message="export is not ready yet",
+                    extra={
+                        "status": "blocked",
+                        "export_handle": normalized_handle,
+                        "app_key": str(local_job.get("app_key") or ""),
+                        "view_id": str(local_job.get("view_id") or ""),
+                        "file_urls": snapshot.get("file_urls") or [],
+                        "file_names": snapshot.get("file_names") or [],
+                        "downloaded_files": [],
+                        "warnings": snapshot.get("warnings") or [],
+                        "verification": snapshot.get("verification") or {},
+                    },
+                )
+            if normalized_status == "failed":
+                return {
+                    **self._failed_export_result(
+                        error_code=str(snapshot.get("error_code") or "EXPORT_FAILED"),
+                        message=str(snapshot.get("message") or "export failed"),
+                        extra={
+                            "status": "failed",
+                            "export_handle": normalized_handle,
+                            "app_key": str(local_job.get("app_key") or ""),
+                            "view_id": str(local_job.get("view_id") or ""),
+                            "file_urls": snapshot.get("file_urls") or [],
+                            "file_names": snapshot.get("file_names") or [],
+                            "downloaded_files": [],
+                            "warnings": snapshot.get("warnings") or [],
+                            "verification": snapshot.get("verification") or {},
+                            "num": snapshot.get("num"),
+                            "process_status": snapshot.get("process_status"),
+                            "audit_record_status": snapshot.get("audit_record_status"),
+                        },
+                    ),
+                }
+            file_infos = cast(list[JSONObject], snapshot.get("file_infos") or [])
+            if not file_infos:
+                return self._failed_export_result(
+                    error_code="EXPORT_FILE_UNAVAILABLE",
+                    message="export completed but did not return downloadable files",
+                    extra={
+                        "status": "failed",
+                        "export_handle": normalized_handle,
+                        "app_key": str(local_job.get("app_key") or ""),
+                        "view_id": str(local_job.get("view_id") or ""),
+                        "warnings": snapshot.get("warnings") or [],
+                        "verification": snapshot.get("verification") or {},
+                    },
+                )
+            downloaded_files = self._download_export_files(
+                file_infos=file_infos,
+                download_to_path=download_to_path,
+                default_directory=None,
+                app_key=str(local_job.get("app_key") or ""),
+                view_id=str(local_job.get("view_id") or ""),
+            )
+            return {
+                "ok": True,
+                "status": "succeeded",
+                "export_handle": normalized_handle,
+                "app_key": str(local_job.get("app_key") or ""),
+                "view_id": str(local_job.get("view_id") or ""),
+                "num": snapshot.get("num"),
+                "process_status": snapshot.get("process_status"),
+                "error_code": snapshot.get("error_code"),
+                "audit_record_status": snapshot.get("audit_record_status"),
+                "file_urls": snapshot.get("file_urls") or [],
+                "file_names": snapshot.get("file_names") or [],
+                "downloaded_files": downloaded_files,
+                "warnings": snapshot.get("warnings") or [],
+                "verification": snapshot.get("verification") or {},
+                "request_route": self.backend.describe_route(context),
+            }
+
+        try:
+            return self._run(profile, runner)
+        except RuntimeError as exc:
+            return self._runtime_error_as_result(
+                exc,
+                error_code="EXPORT_GET_FAILED",
+                extra={"export_handle": normalized_handle},
+            )
+
+    @tool_cn_name("记录直接导出")
+    def record_export_direct(
+        self,
+        *,
+        profile: str = DEFAULT_PROFILE,
+        app_key: str,
+        view_id: str = "system:all",
+        download_to_path: str | None = None,
+        wait_timeout_seconds: float | None = None,
+    ) -> dict[str, Any]:
+        normalized_app_key = str(app_key or "").strip()
+        normalized_view_id = str(view_id or "").strip() or "system:all"
+        if not normalized_app_key:
+            return self._failed_export_result(
+                error_code="EXPORT_START_FAILED",
+                message="app_key is required",
+                extra={"status": "failed", "view_id": normalized_view_id},
+            )
+        timeout_seconds = self._normalize_timeout_seconds(wait_timeout_seconds)
+
+        def runner(_session_profile, context):
+            start_result = self.record_export_start(
+                profile=profile,
+                app_key=normalized_app_key,
+                view_id=normalized_view_id,
+            )
+            if not bool(start_result.get("ok")):
+                return start_result
+            export_handle = str(start_result.get("export_handle") or "")
+            deadline = monotonic() + timeout_seconds
+            last_snapshot: dict[str, Any] | None = None
+            while monotonic() < deadline:
+                local_job = self._job_store.get(export_handle)
+                if local_job is None:
+                    return self._failed_export_result(
+                        error_code="EXPORT_HANDLE_UNKNOWN",
+                        message="export_handle is missing or expired",
+                        extra={"status": "failed", "export_handle": export_handle},
+                    )
+                snapshot = self._resolve_export_snapshot(context, local_job)
+                last_snapshot = snapshot
+                normalized_status = str(snapshot.get("status") or "unknown")
+                if normalized_status == "succeeded":
+                    effective_download_path = download_to_path or str(Path.cwd())
+                    get_result = self.record_export_get(
+                        profile=profile,
+                        export_handle=export_handle,
+                        download_to_path=effective_download_path,
+                    )
+                    if bool(get_result.get("ok")):
+                        return get_result
+                    return {
+                        **get_result,
+                        "export_handle": export_handle,
+                        "file_urls": snapshot.get("file_urls") or [],
+                        "file_names": snapshot.get("file_names") or [],
+                    }
+                if normalized_status == "failed":
+                    return {
+                        "ok": False,
+                        "status": "failed",
+                        "error_code": str(snapshot.get("error_code") or "EXPORT_FAILED"),
+                        "message": str(snapshot.get("message") or "export failed"),
+                        "export_handle": export_handle,
+                        "app_key": str(local_job.get("app_key") or ""),
+                        "view_id": str(local_job.get("view_id") or ""),
+                        "num": snapshot.get("num"),
+                        "process_status": snapshot.get("process_status"),
+                        "audit_record_status": snapshot.get("audit_record_status"),
+                        "file_urls": snapshot.get("file_urls") or [],
+                        "file_names": snapshot.get("file_names") or [],
+                        "downloaded_files": [],
+                        "warnings": snapshot.get("warnings") or [],
+                        "verification": snapshot.get("verification") or {},
+                    }
+                if normalized_status == "unknown":
+                    warning_codes = {
+                        str(item.get("code") or "")
+                        for item in cast(list[JSONObject], snapshot.get("warnings") or [])
+                        if isinstance(item, dict)
+                    }
+                    if "EXPORT_HISTORY_AMBIGUOUS" in warning_codes:
+                        return {
+                            "ok": True,
+                            "status": "unknown",
+                            "export_handle": export_handle,
+                            "app_key": str(local_job.get("app_key") or ""),
+                            "view_id": str(local_job.get("view_id") or ""),
+                            "file_urls": snapshot.get("file_urls") or [],
+                            "file_names": snapshot.get("file_names") or [],
+                            "downloaded_files": [],
+                            "warnings": snapshot.get("warnings") or [],
+                            "verification": snapshot.get("verification") or {},
+                            "message": "export result could not be matched uniquely",
+                        }
+                remaining = deadline - monotonic()
+                if remaining <= 0:
+                    break
+                sleep(min(EXPORT_POLL_INTERVAL_SECONDS, remaining))
+            timeout_status = "running"
+            if isinstance(last_snapshot, dict) and str(last_snapshot.get("status") or "").strip():
+                timeout_status = str(last_snapshot.get("status") or timeout_status)
+            warnings = list(cast(list[JSONObject], start_result.get("warnings") or []))
+            warnings.append(
+                {
+                    "code": "EXPORT_WAIT_TIMEOUT",
+                    "message": "export is still running; reuse export_handle with record_export_status_get or record_export_get",
+                }
+            )
+            return {
+                "ok": True,
+                "status": timeout_status,
+                "export_handle": str(start_result.get("export_handle") or ""),
+                "app_key": normalized_app_key,
+                "view_id": str(start_result.get("view_id") or normalized_view_id),
+                "file_urls": (last_snapshot or {}).get("file_urls") or [],
+                "file_names": (last_snapshot or {}).get("file_names") or [],
+                "downloaded_files": [],
+                "warnings": warnings,
+                "verification": (last_snapshot or {}).get("verification") or start_result.get("verification") or {},
+                "message": "export did not finish before wait_timeout_seconds",
+            }
+
+        try:
+            return self._run(profile, runner)
+        except RuntimeError as exc:
+            return self._runtime_error_as_result(
+                exc,
+                error_code="EXPORT_DIRECT_FAILED",
+                extra={"app_key": normalized_app_key, "view_id": normalized_view_id},
+            )
+
+    def _build_export_filter_bean(self, resolved_view: AccessibleViewRoute) -> JSONObject:
+        filter_payload: JSONObject = {}
+        if resolved_view.kind == "system" and resolved_view.list_type is not None:
+            filter_payload["type"] = resolved_view.list_type
+        return {
+            "filter": filter_payload,
+            # Backend export code later auto-unboxes this field to primitive boolean.
+            # Sending explicit false avoids a null -> NPE -> 41100 failure path.
+            "auditRecordStatus": False,
+        }
+
+    def _build_export_config(
+        self,
+        *,
+        profile: str,
+        context,
+        app_key: str,
+        resolved_view: AccessibleViewRoute,
+    ) -> tuple[JSONObject, list[JSONObject]]:  # type: ignore[no-untyped-def]
+        browse_scope = self._record_tools._build_browse_write_scope(
+            profile,
+            context,
+            app_key,
+            resolved_view,
+            force_refresh=False,
+        )
+        index = browse_scope["index"]
+        visible_question_ids = cast(set[int], browse_scope.get("visible_question_ids") or set())
+        ordered_visible_fields = [
+            field
+            for field in self._record_tools._schema_fields_for_mode(
+                profile,
+                context,
+                app_key,
+                index,
+                schema_mode="browse",
+                resolved_view=resolved_view,
+            )
+            if field.que_id in visible_question_ids and field.que_type not in LAYOUT_ONLY_QUE_TYPES
+        ]
+        if not ordered_visible_fields:
+            ordered_visible_fields = [
+                field
+                for field in cast(Any, index).by_id.values()
+                if field.que_type not in LAYOUT_ONLY_QUE_TYPES
+            ]
+        question_export_config_list: list[JSONObject] = []
+        warnings: list[JSONObject] = []
+        for field in ordered_visible_fields:
+            if field.que_type is None:
+                warnings.append(
+                    {
+                        "code": "EXPORT_FIELD_TYPE_UNAVAILABLE",
+                        "message": f"Skipped field '{field.que_title}' because its field type could not be resolved.",
+                    }
+                )
+                continue
+            question_export_config_list.append(
+                {
+                    "queId": field.que_id,
+                    "queTitle": field.que_title,
+                    "queType": field.que_type,
+                    "exportStyle": "default",
+                }
+            )
+        if not question_export_config_list:
+            raise QingflowApiError.config_error(
+                "record export could not determine exportable fields for the selected view",
+                details={"error_code": "EXPORT_CONFIG_UNAVAILABLE"},
+            )
+        return {"questionExportConfigList": question_export_config_list}, warnings
+
+    def _resolve_export_snapshot(
+        self,
+        context,
+        local_job: dict[str, Any],
+    ) -> dict[str, Any]:  # type: ignore[no-untyped-def]
+        app_key = str(local_job.get("app_key") or "").strip()
+        process_payload = self._lookup_process_details(context, app_key=app_key)
+        history_page = self.backend.request(
+            "GET",
+            context,
+            "/app/apply/dataExport/record",
+            params={"appKey": app_key, "pageNum": 1, "pageSize": 100},
+        )
+        history_records = _extract_export_records(history_page)
+        matched_record, matched_by = _match_export_history_record(history_records, local_job=local_job)
+        if process_payload is not None:
+            normalized_status = _normalize_export_status(process_payload.get("processStatus") or process_payload.get("status"))
+            if normalized_status in {"queued", "running"}:
+                return {
+                    "status": normalized_status,
+                    "process_status": _coerce_int(process_payload.get("processStatus") or process_payload.get("status")),
+                    "num": _coerce_int(process_payload.get("num")),
+                    "error_code": process_payload.get("errorCode"),
+                    "audit_record_status": process_payload.get("auditRecordStatus"),
+                    "file_infos": _normalize_export_file_infos(process_payload.get("fileUrls")),
+                    "file_urls": _extract_export_file_urls(process_payload.get("fileUrls")),
+                    "file_names": _extract_export_file_names(process_payload.get("fileUrls")),
+                    "warnings": [],
+                    "verification": {
+                        "current_process_visible": True,
+                        "history_match_resolved": matched_record is not None,
+                    },
+                    "message": None,
+                }
+        if matched_record is None:
+            warning_code = "EXPORT_HISTORY_PENDING"
+            warning_message = "export has not appeared in export history yet"
+            if matched_by == "ambiguous":
+                warning_code = "EXPORT_HISTORY_AMBIGUOUS"
+                warning_message = "export result could not be matched uniquely in export history"
+            return {
+                "status": "unknown",
+                "process_status": None,
+                "num": None,
+                "error_code": None,
+                "audit_record_status": None,
+                "file_infos": [],
+                "file_urls": [],
+                "file_names": [],
+                "warnings": [{"code": warning_code, "message": warning_message}],
+                "verification": {
+                    "current_process_visible": process_payload is not None,
+                    "history_match_resolved": False,
+                },
+                "message": warning_message,
+            }
+        file_infos = _normalize_export_file_infos(matched_record.get("fileUrls"))
+        raw_process_status = _coerce_int(matched_record.get("processStatus"))
+        normalized_status = _normalize_export_status(raw_process_status)
+        message = None
+        if normalized_status == "failed":
+            message = "export failed"
+        return {
+            "status": normalized_status,
+            "process_status": raw_process_status,
+            "num": _coerce_int(matched_record.get("num")),
+            "error_code": matched_record.get("errorCode"),
+            "audit_record_status": matched_record.get("auditRecordStatus"),
+            "file_infos": file_infos,
+            "file_urls": [item.get("url") for item in file_infos if isinstance(item.get("url"), str)],
+            "file_names": [item.get("name") for item in file_infos if isinstance(item.get("name"), str)],
+            "warnings": [],
+            "verification": {
+                "current_process_visible": process_payload is not None,
+                "history_match_resolved": True,
+                "matched_by": matched_by,
+            },
+            "message": message,
+        }
+
+    def _lookup_process_details(self, context, *, app_key: str) -> JSONObject | None:  # type: ignore[no-untyped-def]
+        try:
+            payload = self.backend.request(
+                "GET",
+                context,
+                f"/process/{app_key}/details",
+                params={"taskType": 2},
+            )
+        except QingflowApiError as exc:
+            if exc.backend_code in {40002, 40027}:
+                return None
+            raise
+        if isinstance(payload, dict):
+            nested = payload.get("data")
+            if isinstance(nested, dict):
+                payload = nested
+            if isinstance(payload.get("detail"), dict):
+                return cast(JSONObject, payload.get("detail"))
+            if any(key in payload for key in ("processStatus", "progress", "num", "fileUrls", "errorCode")):
+                return cast(JSONObject, payload)
+        return None
+
+    def _status_payload_from_snapshot(
+        self,
+        local_job: dict[str, Any],
+        export_handle: str,
+        snapshot: dict[str, Any],
+    ) -> dict[str, Any]:
+        normalized_status = str(snapshot.get("status") or "unknown")
+        ok = normalized_status not in {"failed"} or snapshot.get("error_code") in (None, "", 0)
+        if normalized_status == "failed":
+            ok = False
+        return {
+            "ok": ok,
+            "status": normalized_status,
+            "export_handle": export_handle,
+            "app_key": str(local_job.get("app_key") or ""),
+            "view_id": str(local_job.get("view_id") or ""),
+            "num": snapshot.get("num"),
+            "process_status": snapshot.get("process_status"),
+            "error_code": snapshot.get("error_code"),
+            "audit_record_status": snapshot.get("audit_record_status"),
+            "file_urls": snapshot.get("file_urls") or [],
+            "file_names": snapshot.get("file_names") or [],
+            "downloaded_files": [],
+            "warnings": snapshot.get("warnings") or [],
+            "verification": snapshot.get("verification") or {},
+            "message": snapshot.get("message"),
+        }
+
+    def _download_export_files(
+        self,
+        *,
+        file_infos: list[JSONObject],
+        download_to_path: str | None,
+        default_directory: str | None,
+        app_key: str,
+        view_id: str,
+    ) -> list[JSONObject]:
+        if download_to_path is None and default_directory is None:
+            return []
+        effective_hint = download_to_path or default_directory
+        assert effective_hint is not None
+        targets = _resolve_download_targets(
+            effective_hint,
+            file_infos=file_infos,
+            app_key=app_key,
+            view_id=view_id,
+        )
+        downloaded_files: list[JSONObject] = []
+        for file_info, target in zip(file_infos, targets, strict=False):
+            url = str(file_info.get("url") or "").strip()
+            if not url:
+                continue
+            content = self.backend.download_binary(url)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(content)
+            downloaded_files.append(
+                {
+                    "file_name": str(file_info.get("name") or target.name),
+                    "path": str(target),
+                    "url": url,
+                }
+            )
+        return downloaded_files
+
+    def _normalize_timeout_seconds(self, wait_timeout_seconds: float | None) -> float:
+        if wait_timeout_seconds is None:
+            return DEFAULT_EXPORT_TIMEOUT_SECONDS
+        try:
+            value = float(wait_timeout_seconds)
+        except (TypeError, ValueError):
+            return DEFAULT_EXPORT_TIMEOUT_SECONDS
+        return value if value > 0 else DEFAULT_EXPORT_TIMEOUT_SECONDS
+
+    def _failed_export_result(
+        self,
+        *,
+        error_code: str,
+        message: str,
+        extra: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        payload = {
+            "ok": False,
+            "status": "failed",
+            "error_code": error_code,
+            "export_handle": None,
+            "app_key": None,
+            "view_id": None,
+            "num": None,
+            "process_status": None,
+            "audit_record_status": None,
+            "file_urls": [],
+            "file_names": [],
+            "downloaded_files": [],
+            "warnings": [],
+            "verification": {},
+            "message": message,
+        }
+        if extra:
+            payload.update(extra)
+        return payload
+
+    def _runtime_error_as_result(
+        self,
+        error: RuntimeError,
+        *,
+        error_code: str,
+        extra: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        try:
+            payload = json.loads(str(error))
+        except json.JSONDecodeError:
+            payload = {"message": str(error)}
+        response = self._failed_export_result(
+            error_code=((payload.get("details") or {}) if isinstance(payload.get("details"), dict) else {}).get("error_code") or error_code,
+            message=str(payload.get("message") or str(error)),
+        )
+        if extra:
+            response.update(extra)
+        return response
+
+
+def _extract_export_records(payload: Any) -> list[JSONObject]:
+    if isinstance(payload, dict):
+        for key in ("list", "records", "items"):
+            value = payload.get(key)
+            if isinstance(value, list):
+                return [item for item in value if isinstance(item, dict)]
+    if isinstance(payload, list):
+        return [item for item in payload if isinstance(item, dict)]
+    return []
+
+
+def _match_export_history_record(
+    records: list[JSONObject],
+    *,
+    local_job: dict[str, Any],
+) -> tuple[JSONObject | None, str | None]:
+    uid = _extract_operate_user_uid(local_job)
+    started_at = _parse_utc(local_job.get("started_at"))
+    candidates = records
+    if uid is not None:
+        candidates = [item for item in candidates if _extract_operate_user_uid(item.get("operateUser")) == uid]
+    if started_at is not None:
+        started_at = started_at.replace(microsecond=0)
+        parsed_candidates: list[tuple[JSONObject, datetime]] = []
+        for item in candidates:
+            operate_time = _parse_utc(item.get("operateTime")) or _parse_utc(item.get("operate_time"))
+            if operate_time is None:
+                continue
+            parsed_candidates.append((item, operate_time))
+        exact_or_after = [item for item, operate_time in parsed_candidates if operate_time >= started_at]
+        if len(exact_or_after) == 1:
+            return exact_or_after[0], "operate_user_started_at"
+        if len(exact_or_after) > 1:
+            return None, "ambiguous"
+        skew_tolerant = [
+            item
+            for item, operate_time in parsed_candidates
+            if operate_time >= (started_at - timedelta(seconds=5))
+        ]
+        if len(skew_tolerant) == 1:
+            return skew_tolerant[0], "operate_user_started_at_skew"
+        if len(skew_tolerant) > 1:
+            return None, "ambiguous"
+        candidates = []
+    if len(candidates) == 1:
+        return candidates[0], "operate_user_started_at"
+    if len(candidates) > 1:
+        return None, "ambiguous"
+    return None, None
+
+
+def _normalize_export_status(value: Any) -> str:
+    status_code = _coerce_int(value)
+    if status_code is not None:
+        return EXPORT_STATUS_BY_PROCESS_STATUS.get(status_code, "unknown")
+    text = str(value or "").strip().lower()
+    if text in {"queued", "running", "succeeded", "failed", "unknown"}:
+        return text
+    if text in {"line_up", "lineup"}:
+        return "queued"
+    if text in {"execute", "executing", "processing"}:
+        return "running"
+    if text in {"success", "completed"}:
+        return "succeeded"
+    if text in {"fail", "partly_fail", "partial_fail"}:
+        return "failed"
+    return "unknown"
+
+
+def _normalize_export_file_infos(value: Any) -> list[JSONObject]:
+    if not isinstance(value, list):
+        return []
+    items: list[JSONObject] = []
+    for item in value:
+        if not isinstance(item, dict):
+            continue
+        url = str(item.get("url") or "").strip()
+        name = str(item.get("name") or item.get("fileName") or "").strip()
+        payload: JSONObject = {}
+        if url:
+            payload["url"] = url
+        if name:
+            payload["name"] = name
+        if payload:
+            items.append(payload)
+    return items
+
+
+def _extract_export_file_urls(value: Any) -> list[str]:
+    return [str(item.get("url") or "").strip() for item in _normalize_export_file_infos(value) if str(item.get("url") or "").strip()]
+
+
+def _extract_export_file_names(value: Any) -> list[str]:
+    return [str(item.get("name") or "").strip() for item in _normalize_export_file_infos(value) if str(item.get("name") or "").strip()]
+
+
+def _extract_operate_user_uid(value: Any) -> int | None:
+    if isinstance(value, dict):
+        for key in ("uid", "userId", "id"):
+            uid = _coerce_int(value.get(key))
+            if uid is not None:
+                return uid
+    return _coerce_int(value)
+
+
+def _parse_utc(value: Any) -> datetime | None:
+    text = str(value or "").strip()
+    if not text:
+        return None
+    normalized = text.replace("Z", "+00:00")
+    try:
+        parsed = datetime.fromisoformat(normalized)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=LOCAL_TIMEZONE).astimezone(timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def _coerce_int(value: Any) -> int | None:
+    if value is None or value == "":
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _resolve_download_targets(
+    destination_hint: str,
+    *,
+    file_infos: list[JSONObject],
+    app_key: str,
+    view_id: str,
+) -> list[Path]:
+    path = Path(destination_hint).expanduser()
+    timestamp = _utc_now().strftime("%Y%m%dT%H%M%SZ")
+    if len(file_infos) > 1:
+        if path.exists() and not path.is_dir():
+            raise QingflowApiError.config_error("download_to_path must be a directory when multiple export files are returned")
+        if not path.exists() and path.suffix:
+            raise QingflowApiError.config_error("download_to_path must be a directory when multiple export files are returned")
+        path.mkdir(parents=True, exist_ok=True)
+        return [
+            path / _choose_export_file_name(
+                file_info,
+                app_key=app_key,
+                view_id=view_id,
+                timestamp=timestamp,
+                index=index,
+            )
+            for index, file_info in enumerate(file_infos, start=1)
+        ]
+    if path.exists() and path.is_dir():
+        return [
+            path / _choose_export_file_name(
+                file_infos[0],
+                app_key=app_key,
+                view_id=view_id,
+                timestamp=timestamp,
+                index=1,
+            )
+        ]
+    if path.suffix or path.exists():
+        return [path]
+    path.mkdir(parents=True, exist_ok=True)
+    return [
+        path / _choose_export_file_name(
+            file_infos[0],
+            app_key=app_key,
+            view_id=view_id,
+            timestamp=timestamp,
+            index=1,
+        )
+    ]
+
+
+def _choose_export_file_name(
+    file_info: JSONObject,
+    *,
+    app_key: str,
+    view_id: str,
+    timestamp: str,
+    index: int,
+) -> str:
+    remote_name = str(file_info.get("name") or "").strip()
+    if remote_name:
+        sanitized = _sanitize_filename(remote_name)
+        if sanitized:
+            return sanitized
+    suffix = ".xlsx"
+    safe_view = _sanitize_filename(view_id.replace(":", "_")) or "view"
+    return f"{_sanitize_filename(app_key) or 'app'}_{safe_view}_{timestamp}_{index}{suffix}"
+
+
+def _sanitize_filename(value: str) -> str:
+    base = _SAFE_FILE_CHARS.sub("_", value).strip("._")
+    return base or ""
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)