@josephyan/qingflow-cli 1.1.3 → 1.1.5

package/src/qingflow_mcp/tools/import_tools.py

@@ -17,7 +17,7 @@ from mcp.server.fastmcp import FastMCP
 from openpyxl import Workbook, load_workbook
 
 from ..config import DEFAULT_PROFILE
-from ..errors import QingflowApiError
+from ..errors import QingflowApiError, backend_code_int, is_auth_like_error, message_looks_like_invalid_token
 from ..import_store import ImportJobStore, ImportVerificationStore
 from ..json_types import JSONObject
 from .app_tools import _derive_import_capability
@@ -75,11 +75,12 @@ class ImportTools(ToolBase):
         """注册当前工具到 MCP 服务。"""
         @mcp.tool()
         def record_import_schema_get(
+            profile: str = DEFAULT_PROFILE,
             app_key: str = "",
             output_profile: str = "normal",
         ) -> dict[str, Any]:
             return self.record_import_schema_get(
-                profile=DEFAULT_PROFILE,
+                profile=profile,
                 app_key=app_key,
                 output_profile=output_profile,
             )
@@ -193,6 +194,22 @@ class ImportTools(ToolBase):
 
         def runner(session_profile, context):
             import_capability, import_warnings = self._fetch_import_capability(context, app_key)
+            if import_capability.get("can_import") is False and import_capability.get("auth_source") != "unknown":
+                return {
+                    "ok": False,
+                    "status": "failed",
+                    "app_key": app_key,
+                    "ws_id": session_profile.selected_ws_id,
+                    "request_route": self.backend.describe_route(context),
+                    "error_code": "IMPORT_AUTH_PRECHECK_FAILED",
+                    "message": "the current user does not have import permission for this app",
+                    "warnings": import_warnings,
+                    "import_capability": import_capability,
+                    "verification": {
+                        "import_auth_prechecked": True,
+                        "import_auth_precheck_passed": False,
+                    },
+                }
             _index, expected_columns, schema_fingerprint = self._resolve_import_schema_bundle(
                 profile,
                 context,
@@ -208,8 +225,15 @@ class ImportTools(ToolBase):
                 }
                 if isinstance(column.get("options"), list) and column.get("options"):
                     payload["options"] = column["options"]
-                if bool(column.get("requires_lookup")):
-                    payload["accepts_natural_input"] = True
+                if column["write_kind"] == "member":
+                    payload["import_value_format"] = "member_email"
+                    payload["format_hint"] = "Import files must use member email values."
+                elif column["write_kind"] == "relation":
+                    payload["import_value_format"] = "target_apply_id"
+                    payload["format_hint"] = "Import files must use the target record apply_id."
+                elif column["write_kind"] == "department":
+                    payload["import_value_format"] = "department_name"
+                    payload["format_hint"] = "Import files may use a department name within the field candidate scope."
                 if bool(column.get("requires_upload")):
                     payload["requires_upload"] = True
                 if isinstance(column.get("target_app_key"), str):
@@ -251,6 +275,21 @@ class ImportTools(ToolBase):
 
         def runner(session_profile, context):
             import_capability, import_warnings = self._fetch_import_capability(context, app_key)
+            if import_capability.get("can_import") is False and import_capability.get("auth_source") != "unknown":
+                return self._failed_template_result(
+                    app_key=app_key,
+                    error_code="IMPORT_AUTH_PRECHECK_FAILED",
+                    message="the current user does not have import permission for this app",
+                    request_route=self.backend.describe_route(context),
+                    extra={
+                        "warnings": import_warnings,
+                        "import_capability": import_capability,
+                        "verification": {
+                            "import_auth_prechecked": True,
+                            "import_auth_precheck_passed": False,
+                        },
+                    },
+                )
             field_index, expected_columns, schema_fingerprint = self._resolve_import_schema_bundle(
                 profile,
                 context,
@@ -260,12 +299,30 @@ class ImportTools(ToolBase):
             try:
                 payload = self.backend.request("GET", context, f"/app/{app_key}/apply/excelTemplate")
             except QingflowApiError as exc:
-                if import_capability.get("auth_source") == "apply_auth":
+                can_generate_local_template = bool(expected_columns) and (
+                    import_capability.get("auth_source") == "apply_auth"
+                    or (
+                        import_capability.get("auth_source") == "unknown"
+                        and not is_auth_like_error(exc)
+                        and backend_code_int(exc) in {40002, 40027}
+                    )
+                )
+                if can_generate_local_template:
                     downloaded_to_path = self._write_local_template(
                         expected_columns=expected_columns,
                         destination_hint=download_to_path,
                         app_key=app_key,
                     )
+                    template_warning = {
+                        "code": "IMPORT_TEMPLATE_LOCAL_FALLBACK",
+                        "message": "Official template download requires data management permission; MCP generated a local applicant-import template instead.",
+                    }
+                    if import_capability.get("auth_source") == "unknown":
+                        template_warning = {
+                            "code": "IMPORT_TEMPLATE_LOCAL_FALLBACK_AUTH_UNKNOWN",
+                            "message": "Official template download was permission-restricted and import permission could not be prechecked; MCP generated a local applicant-import template from readable applicant fields.",
+                        }
+                    _copy_api_error_fields(template_warning, exc)
                     return {
                         "ok": True,
                         "status": "partial_success",
@@ -276,18 +333,13 @@ class ImportTools(ToolBase):
                         "downloaded_to_path": downloaded_to_path,
                         "expected_columns": expected_columns,
                         "schema_fingerprint": schema_fingerprint,
-                        "warnings": import_warnings
-                        + [
-                            {
-                                "code": "IMPORT_TEMPLATE_LOCAL_FALLBACK",
-                                "message": "Official template download requires data management permission; MCP generated a local applicant-import template instead.",
-                            }
-                        ],
+                        "warnings": import_warnings + [template_warning],
                         "verification": {
                             "schema_fingerprint": schema_fingerprint,
                             "template_url_resolved": False,
                             "template_downloaded": True,
                             "template_source": "local_generated",
+                            "import_auth_prechecked": import_capability.get("auth_source") != "unknown",
                         },
                     }
                 return self._failed_template_result(
@@ -448,6 +500,7 @@ class ImportTools(ToolBase):
             issues = deepcopy(effective_local_check["issues"])
             can_import = bool(effective_local_check["can_import"])
             backend_verification = None
+            backend_failure_error_code = None
             if can_import:
                 try:
                     payload = self.backend.request_multipart(
@@ -478,19 +531,25 @@ class ImportTools(ToolBase):
                         )
                 except QingflowApiError as exc:
                     can_import = False
+                    backend_error_code = _import_permission_error_code(
+                        exc,
+                        permission_code="IMPORT_VERIFICATION_UNAUTHORIZED",
+                        default="BACKEND_IMPORT_VERIFICATION_FAILED",
+                    )
+                    backend_failure_error_code = backend_error_code
                     issues.append(
                         _issue(
-                            "BACKEND_IMPORT_VERIFICATION_FAILED",
+                            backend_error_code,
                             exc.message or "Backend import verification failed.",
                             severity="error",
                         )
                     )
-                    warnings.append(
-                        {
-                            "code": "IMPORT_VERIFICATION_FAILED",
-                            "message": "Backend verification failed; the file cannot be imported until verification succeeds.",
-                        }
-                    )
+                    warning = {
+                        "code": backend_error_code,
+                        "message": "Backend verification failed; the file cannot be imported until verification succeeds.",
+                    }
+                    _copy_api_error_fields(warning, exc)
+                    warnings.append(warning)
             verification_id = str(uuid4())
             verification_payload = {
                 "id": verification_id,
@@ -517,9 +576,11 @@ class ImportTools(ToolBase):
             }
             self._verification_store.put(verification_id, verification_payload)
             return {
-                "ok": True,
+                "ok": can_import,
                 "status": "success" if can_import else "failed",
-                "error_code": None if can_import else (effective_local_check.get("error_code") or local_check.get("error_code") or "IMPORT_VERIFICATION_FAILED"),
+                "error_code": None
+                if can_import
+                else (effective_local_check.get("error_code") or local_check.get("error_code") or backend_failure_error_code or "IMPORT_VERIFICATION_FAILED"),
                 "can_import": can_import,
                 "verification_id": verification_id,
                 "file_path": str(path.resolve()),
@@ -553,7 +614,11 @@ class ImportTools(ToolBase):
         try:
             return self._run(profile, runner)
         except RuntimeError as exc:
-            return self._runtime_error_as_result(exc, error_code="IMPORT_VERIFICATION_FAILED", extra={"can_import": False})
+            return self._runtime_error_as_result(
+                exc,
+                error_code="IMPORT_VERIFICATION_FAILED",
+                extra={"can_import": _runtime_import_can_import_value(exc)},
+            )
 
     @tool_cn_name("导入修复")
     def record_import_repair_local(
@@ -603,7 +668,8 @@ class ImportTools(ToolBase):
             applied_repairs: list[str] = []
             skipped_repairs: list[str] = []
             if "normalize_headers" in normalized_repairs:
-                if _repair_headers(sheet, expected_columns):
+                repair_header_columns = _repair_header_columns_from_stored_precheck(stored, expected_columns)
+                if _repair_headers(sheet, repair_header_columns):
                     applied_repairs.append("normalize_headers")
                 else:
                     skipped_repairs.append("normalize_headers")
@@ -687,11 +753,17 @@ class ImportTools(ToolBase):
                 return self._failed_start_result(error_code="IMPORT_VERIFICATION_STALE", message="verification_id does not belong to the requested app")
             if not bool(stored.get("can_import")):
                 return self._failed_start_result(error_code="IMPORT_VERIFICATION_FAILED", message="verification_id is not importable", extra={"accepted": False})
-            current_path = Path(str(stored.get("verified_file_path") or stored["file_path"]))
+            source_local_precheck = stored.get("source_local_precheck")
+            source_precheck_passed = isinstance(source_local_precheck, dict) and bool(source_local_precheck.get("can_import"))
+            if source_precheck_passed:
+                current_path = Path(str(stored.get("source_file_path") or stored["file_path"]))
+                expected_sha256 = stored.get("file_sha256")
+            else:
+                current_path = Path(str(stored.get("verified_file_path") or stored.get("source_file_path") or stored["file_path"]))
+                expected_sha256 = stored.get("verified_file_sha256") or stored.get("file_sha256")
             if not current_path.is_file():
-                return self._failed_start_result(error_code="IMPORT_VERIFICATION_STALE", message="verified file no longer exists")
+                return self._failed_start_result(error_code="IMPORT_VERIFICATION_STALE", message="verified import file no longer exists")
             current_sha256 = _sha256_file(current_path)
-            expected_sha256 = stored.get("verified_file_sha256") or stored.get("file_sha256")
             if current_sha256 != expected_sha256:
                 return self._failed_start_result(
                     error_code="IMPORT_FILE_CHANGED_AFTER_VERIFY",
@@ -729,8 +801,14 @@ class ImportTools(ToolBase):
                     excel_name=str(stored.get("file_name") or current_path.name),
                 )
             except QingflowApiError as exc:
-                error_code = "IMPORT_SOCKET_ACK_TIMEOUT" if exc.details and exc.details.get("error_code") == "IMPORT_SOCKET_ACK_TIMEOUT" else "IMPORT_VERIFICATION_FAILED"
-                return self._failed_start_result(error_code=error_code, message=exc.message, extra={"accepted": False, "file_url": file_url})
+                error_code = (
+                    "IMPORT_SOCKET_ACK_TIMEOUT"
+                    if exc.details and exc.details.get("error_code") == "IMPORT_SOCKET_ACK_TIMEOUT"
+                    else _import_permission_error_code(exc, permission_code="IMPORT_START_UNAUTHORIZED", default="IMPORT_START_FAILED")
+                )
+                details: JSONObject = {"accepted": False, "file_url": file_url}
+                _copy_api_error_fields(details, exc)
+                return self._failed_start_result(error_code=error_code, message=exc.message, extra=details)
             import_id = str(socket_result.get("import_id") or "")
             process_id_str = _normalize_optional_text(socket_result.get("process_id_str"))
             started_at = _utc_now().isoformat()
@@ -753,9 +831,11 @@ class ImportTools(ToolBase):
                 "ok": True,
                 "status": "accepted",
                 "accepted": True,
+                "write_executed": True,
+                "safe_to_retry": False,
                 "import_id": import_id,
                 "process_id_str": process_id_str,
-                    "source_file_name": str(stored.get("file_name") or current_path.name),
+                "source_file_name": str(stored.get("file_name") or current_path.name),
                 "file_url": file_url,
                 "warnings": warnings,
                 "verification": {
@@ -838,12 +918,66 @@ class ImportTools(ToolBase):
             if local_job is None and not normalized_import_id and not normalized_process_id:
                 recent = [item for item in self._job_store.list() if str(item.get("app_key")) == resolved_app_key]
                 local_job = recent[0] if recent else None
-            page = self.backend.request(
-                "GET",
-                context,
-                "/app/apply/dataImport/record",
-                params={"appKey": resolved_app_key, "pageNum": 1, "pageSize": 100},
-            )
+            try:
+                page = self.backend.request(
+                    "GET",
+                    context,
+                    "/app/apply/dataImport/record",
+                    params={"appKey": resolved_app_key, "pageNum": 1, "pageSize": 100},
+                )
+            except QingflowApiError as exc:
+                error_code = _import_permission_error_code(exc, permission_code="IMPORT_STATUS_UNAUTHORIZED", default="IMPORT_STATUS_UNAVAILABLE")
+                details: JSONObject = {
+                    "app_key": resolved_app_key,
+                    "import_id": normalized_import_id,
+                    "process_id_str": effective_process_id,
+                    "verification": {
+                        "status_lookup_completed": False,
+                        "process_id_verified": bool(effective_process_id),
+                    },
+                }
+                _copy_api_error_fields(details, exc)
+                if _is_import_permission_error(exc):
+                    return {
+                        "ok": True,
+                        "status": "unknown",
+                        "error_code": error_code,
+                        "app_key": resolved_app_key,
+                        "import_id": normalized_import_id or (local_job.get("import_id") if isinstance(local_job, dict) else None),
+                        "process_id_str": effective_process_id,
+                        "matched_by": "local_job" if isinstance(local_job, dict) else None,
+                        "source_file_name": local_job.get("source_file_name") if isinstance(local_job, dict) else None,
+                        "total_rows": None,
+                        "success_rows": None,
+                        "failed_rows": None,
+                        "progress": None,
+                        "error_file_urls": [],
+                        "operate_time": None,
+                        "operate_user": None,
+                        "accepted": bool(local_job or effective_process_id),
+                        "warnings": [
+                            {
+                                "code": error_code,
+                                "message": "import history is not readable; final import status is unknown",
+                                **{
+                                    key: details.get(key)
+                                    for key in ("category", "backend_code", "http_status", "request_id")
+                                    if details.get(key) is not None
+                                },
+                            }
+                        ],
+                        "verification": details["verification"],
+                        "details": {"status_readback_error": details},
+                        "backend_code": details.get("backend_code"),
+                        "request_id": details.get("request_id"),
+                        "http_status": details.get("http_status"),
+                        "message": "import history is not readable; final import status is unknown",
+                    }
+                return self._failed_status_result(
+                    error_code=error_code,
+                    message=exc.message,
+                    extra=details,
+                )
             records = _extract_import_records(page)
             matched_record, matched_by = _match_import_record(
                 records,
@@ -916,7 +1050,19 @@ class ImportTools(ToolBase):
         try:
             return self._run(profile, runner)
         except RuntimeError as exc:
-            return self._runtime_error_as_result(exc, error_code="IMPORT_STATUS_AMBIGUOUS")
+            return self._runtime_error_as_result(
+                exc,
+                error_code="IMPORT_STATUS_AMBIGUOUS",
+                extra={
+                    "app_key": normalized_app_key,
+                    "import_id": normalized_import_id,
+                    "process_id_str": normalized_process_id,
+                    "verification": {
+                        "status_lookup_completed": False,
+                        "process_id_verified": bool(normalized_process_id),
+                    },
+                },
+            )
 
     def _resolve_import_schema_bundle(
         self,
@@ -1011,6 +1157,9 @@ class ImportTools(ToolBase):
             "can_import": True,
             "extension": extension,
             "error_code": None,
+            "expected_header_titles": list(allowed_header_titles)
+            if allowed_header_titles
+            else [str(item["title"]) for item in expected_columns],
         }
         if extension not in SUPPORTED_IMPORT_EXTENSIONS:
             base_result["issues"].append(_issue("UNSUPPORTED_FILE_FORMAT", "Only .xlsx and .xls files are supported in import v1.", severity="error"))
@@ -1218,7 +1367,9 @@ class ImportTools(ToolBase):
                         "message": f"Member candidate scope for column '{column['title']}' could not be resolved safely during local precheck.",
                     }
                 raise
-            except RuntimeError:
+            except RuntimeError as exc:
+                if not _runtime_candidate_validation_skippable(exc):
+                    raise
                 return None, {
                     "code": "MEMBER_CANDIDATE_VALIDATION_SKIPPED",
                     "message": f"Member candidate scope for column '{column['title']}' could not be resolved safely during local precheck.",
@@ -1272,7 +1423,9 @@ class ImportTools(ToolBase):
                         "message": f"Department candidate scope for column '{column['title']}' could not be resolved safely during local precheck.",
                     }
                 raise
-            except RuntimeError:
+            except RuntimeError as exc:
+                if not _runtime_candidate_validation_skippable(exc):
+                    raise
                 return None, {
                     "code": "DEPARTMENT_CANDIDATE_VALIDATION_SKIPPED",
                     "message": f"Department candidate scope for column '{column['title']}' could not be resolved safely during local precheck.",
@@ -1397,11 +1550,31 @@ class ImportTools(ToolBase):
 
     def _fetch_import_capability(self, context, app_key: str) -> tuple[JSONObject, list[JSONObject]]:  # type: ignore[no-untyped-def]
         """执行内部辅助逻辑。"""
+        base_info_error: QingflowApiError | None = None
         try:
             payload = self.backend.request("GET", context, f"/app/{app_key}/baseInfo")
-        except QingflowApiError:
+        except QingflowApiError as exc:
+            if not _is_optional_import_capability_error(exc):
+                raise
+            base_info_error = exc
             payload = None
-        return _derive_import_capability(payload)
+        capability, warnings = _derive_import_capability(payload)
+        if base_info_error is not None:
+            for warning in warnings:
+                if warning.get("code") != "IMPORT_CAPABILITY_UNAVAILABLE":
+                    continue
+                warning["message"] = (
+                    "import capability precheck could not read app baseInfo; continuing with applicant schema "
+                    "when available, but do not treat import permission as verified."
+                )
+                if base_info_error.backend_code is not None:
+                    warning["backend_code"] = base_info_error.backend_code
+                if base_info_error.http_status is not None:
+                    warning["http_status"] = base_info_error.http_status
+                if base_info_error.request_id is not None:
+                    warning["request_id"] = base_info_error.request_id
+                break
+        return capability, warnings
 
     def _write_local_template(
         self,
@@ -1430,9 +1603,10 @@ class ImportTools(ToolBase):
         error_code: str,
         message: str,
         request_route: JSONObject | None = None,
+        extra: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         """执行内部辅助逻辑。"""
-        return {
+        payload = {
             "ok": False,
             "status": "failed",
             "error_code": error_code,
@@ -1446,6 +1620,9 @@ class ImportTools(ToolBase):
             "verification": {"template_url_resolved": False},
             "message": message,
         }
+        if extra:
+            payload.update(extra)
+        return payload
 
     def _failed_verify_result(
         self,
@@ -1458,7 +1635,7 @@ class ImportTools(ToolBase):
     ) -> dict[str, Any]:
         """执行内部辅助逻辑。"""
         payload = {
-            "ok": True,
+            "ok": False,
             "status": "failed",
             "error_code": error_code,
             "app_key": app_key,
@@ -1573,18 +1750,21 @@ class ImportTools(ToolBase):
         extra: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         """执行内部辅助逻辑。"""
-        try:
-            payload = json.loads(str(error))
-        except json.JSONDecodeError:
-            payload = {"message": str(error)}
+        payload = _runtime_error_payload(error)
+        details = payload.get("details") if isinstance(payload.get("details"), dict) else {}
         response = {
             "ok": False,
             "status": "failed",
-            "error_code": ((payload.get("details") or {}) if isinstance(payload.get("details"), dict) else {}).get("error_code") or error_code,
+            "error_code": details.get("error_code") or _runtime_error_code(payload, default=error_code),
             "warnings": [],
             "verification": {},
             "message": payload.get("message") or str(error),
         }
+        for key in ("category", "backend_code", "request_id", "http_status"):
+            if key in payload:
+                response[key] = payload.get(key)
+        if details:
+            response["details"] = details
         if extra:
             response.update(extra)
         return response
@@ -2042,6 +2222,20 @@ def _sheet_header_map(sheet) -> dict[str, int]:  # type: ignore[no-untyped-def]
     return mapping
 
 
+def _repair_header_columns_from_stored_precheck(stored: JSONObject, expected_columns: list[JSONObject]) -> list[JSONObject]:
+    for key in ("source_local_precheck", "local_precheck"):
+        precheck = stored.get(key)
+        if not isinstance(precheck, dict):
+            continue
+        titles = precheck.get("expected_header_titles")
+        if not isinstance(titles, list):
+            continue
+        normalized_titles = [title for title in (_normalize_optional_text(item) for item in titles) if title]
+        if normalized_titles:
+            return [{"title": title} for title in normalized_titles]
+    return expected_columns
+
+
 def _repair_headers(sheet, expected_columns: list[JSONObject]) -> bool:  # type: ignore[no-untyped-def]
     changed = False
     expected_by_key = {_normalize_header_key(item["title"]): item["title"] for item in expected_columns}
@@ -2060,9 +2254,11 @@ def _repair_headers(sheet, expected_columns: list[JSONObject]) -> bool:  # type:
     # Fallback for template-based files where headers were edited into non-canonical
     # values but column order is still intact. Keep any extra trailing system columns.
     for index, column in enumerate(expected_columns, start=1):
-        if index > len(header_cells):
-            break
         expected_title = str(column["title"]).strip()
+        if index > len(header_cells):
+            sheet.cell(row=1, column=index, value=expected_title)
+            changed = True
+            continue
         current_title = _normalize_optional_text(header_cells[index - 1].value)
         if current_title != expected_title:
             header_cells[index - 1].value = expected_title
@@ -2257,6 +2453,97 @@ def _normalize_import_status(value: Any) -> str:
     return "unknown"
 
 
+def _runtime_error_payload(error: RuntimeError) -> JSONObject:
+    try:
+        payload = json.loads(str(error))
+    except json.JSONDecodeError:
+        return {"message": str(error)}
+    return payload if isinstance(payload, dict) else {"message": str(error)}
+
+
+def _runtime_import_can_import_value(error: RuntimeError) -> bool | None:
+    payload = _runtime_error_payload(error)
+    category = str(payload.get("category") or "").strip().lower()
+    if category == "auth" or _coerce_int(payload.get("http_status")) == 401 or message_looks_like_invalid_token(payload.get("message")):
+        return None
+    backend_code = backend_code_int(
+        QingflowApiError(
+            category=category,
+            message=str(payload.get("message") or ""),
+            backend_code=payload.get("backend_code"),
+            http_status=_coerce_int(payload.get("http_status")),
+        )
+    )
+    return False if backend_code in {40002, 40027} else None
+
+
+def _runtime_candidate_validation_skippable(error: RuntimeError) -> bool:
+    payload = _runtime_error_payload(error)
+    category = str(payload.get("category") or "").strip().lower()
+    if category == "not_supported":
+        return True
+    if category in {"auth", "workspace"}:
+        return False
+    if message_looks_like_invalid_token(payload.get("message")):
+        return False
+    if _coerce_int(payload.get("http_status")) == 401:
+        return False
+    backend_code = backend_code_int(
+        QingflowApiError(
+            category=category,
+            message=str(payload.get("message") or ""),
+            backend_code=payload.get("backend_code"),
+            http_status=_coerce_int(payload.get("http_status")),
+        )
+    )
+    return backend_code in {40002, 40027, 404} or _coerce_int(payload.get("http_status")) == 404
+
+
+def _runtime_error_code(payload: JSONObject, *, default: str) -> str:
+    category = str(payload.get("category") or "").strip().lower()
+    http_status = _coerce_int(payload.get("http_status"))
+    if category == "auth" or http_status == 401 or message_looks_like_invalid_token(payload.get("message")):
+        return "AUTH_REQUIRED"
+    if category == "workspace":
+        return "WORKSPACE_NOT_SELECTED"
+    return default
+
+
+def _is_import_permission_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    return backend_code_int(error) in {40002, 40027}
+
+
+def _is_import_capability_auth_error(error: QingflowApiError) -> bool:
+    return is_auth_like_error(error)
+
+
+def _is_optional_import_capability_error(error: QingflowApiError) -> bool:
+    if _is_import_capability_auth_error(error):
+        return False
+    return _is_import_permission_error(error) or backend_code_int(error) == 404 or error.http_status == 404
+
+
+def _import_permission_error_code(error: QingflowApiError, *, permission_code: str, default: str) -> str:
+    if is_auth_like_error(error):
+        return "AUTH_REQUIRED"
+    if _is_import_permission_error(error):
+        return permission_code
+    return default
+
+
+def _copy_api_error_fields(payload: dict[str, Any], error: QingflowApiError) -> None:
+    if error.category:
+        payload["category"] = error.category
+    if error.backend_code is not None:
+        payload["backend_code"] = error.backend_code
+    if error.http_status is not None:
+        payload["http_status"] = error.http_status
+    if error.request_id:
+        payload["request_id"] = error.request_id
+
+
 def _normalize_error_file_urls(value: Any) -> list[str]:
     if isinstance(value, list):
         return [str(item).strip() for item in value if str(item).strip()]