@qingflow-tech/qingflow-app-user-mcp 1.0.10 → 1.0.12

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
@@ -193,6 +193,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,
@@ -251,6 +267,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 +291,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 +325,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 +492,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 +523,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 +568,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 +606,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(
@@ -729,8 +786,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 +816,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 +903,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 +1035,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,
@@ -1218,7 +1349,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 +1405,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 +1532,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 +1585,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 +1602,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 +1617,7 @@ class ImportTools(ToolBase):
     ) -> dict[str, Any]:
         """执行内部辅助逻辑。"""
         payload = {
-            "ok": True,
+            "ok": False,
             "status": "failed",
             "error_code": error_code,
             "app_key": app_key,
@@ -1573,18 +1732,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
@@ -2257,6 +2419,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()]

package/src/qingflow_mcp/tools/navigation_tools.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from mcp.server.fastmcp import FastMCP
 
 from ..config import DEFAULT_PROFILE
-from ..errors import QingflowApiError, raise_tool_error
+from ..errors import QingflowApiError, backend_code_int, is_auth_like_error, raise_tool_error
 from ..json_types import JSONObject
 from .base import ToolBase, tool_cn_name
 
@@ -85,8 +85,26 @@ class NavigationTools(ToolBase):
             params: JSONObject = {"pageNum": page_num, "pageSize": page_size}
             if query_key:
                 params["queryCondition"] = query_key
-            result = self.backend.request("GET", context, "/navigation/page", params=params)
-            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "page": result}
+            fallback_error: QingflowApiError | None = None
+            try:
+                result = self.backend.request("GET", context, "/navigation/page", params=params)
+                response = {"profile": profile, "ws_id": session_profile.selected_ws_id, "status": "draft", "page": result}
+            except QingflowApiError as exc:
+                if not _is_optional_draft_navigation_read_error(exc):
+                    raise
+                fallback_error = exc
+                result = self.backend.request("GET", context, "/navigation", params={"pageNum": page_num, "pageSize": page_size})
+                response = {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "status": "published",
+                    "requested_status": "draft",
+                    "page": result,
+                }
+            if fallback_error is not None:
+                response["warnings"] = [_navigation_fallback_warning("NAVIGATION_DRAFT_PAGE_UNAVAILABLE", fallback_error)]
+                response["verification"] = {"draft_readable": False, "published_fallback_used": True}
+            return response
 
         return self._run(profile, runner)
 
@@ -97,8 +115,26 @@ class NavigationTools(ToolBase):
             params: JSONObject = {}
             if query_key:
                 params["queryCondition"] = query_key
-            result = self.backend.request("GET", context, "/navigation/all", params=params)
-            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "items": result}
+            fallback_error: QingflowApiError | None = None
+            try:
+                result = self.backend.request("GET", context, "/navigation/all", params=params)
+                response = {"profile": profile, "ws_id": session_profile.selected_ws_id, "status": "draft", "items": result}
+            except QingflowApiError as exc:
+                if not _is_optional_draft_navigation_read_error(exc):
+                    raise
+                fallback_error = exc
+                result = self.backend.request("GET", context, "/navigation", params={"pageNum": 1, "pageSize": 1000})
+                response = {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "status": "published",
+                    "requested_status": "draft",
+                    "items": result,
+                }
+            if fallback_error is not None:
+                response["warnings"] = [_navigation_fallback_warning("NAVIGATION_DRAFT_ALL_UNAVAILABLE", fallback_error)]
+                response["verification"] = {"draft_readable": False, "published_fallback_used": True}
+            return response
 
         return self._run(profile, runner)
 
@@ -108,13 +144,39 @@ class NavigationTools(ToolBase):
         self._require_navigation_item_id(navigation_item_id)
 
         def runner(session_profile, context):
-            result = self.backend.request(
-                "GET",
-                context,
-                f"/navigation/detail/{navigation_item_id}",
-                params={"status": status},
-            )
-            return {"profile": profile, "ws_id": session_profile.selected_ws_id, "navigation_item_id": navigation_item_id, "result": result}
+            requested_status = str(status or "draft")
+            fallback_error: QingflowApiError | None = None
+            try:
+                result = self.backend.request(
+                    "GET",
+                    context,
+                    f"/navigation/detail/{navigation_item_id}",
+                    params={"status": requested_status},
+                )
+                effective_status = requested_status
+            except QingflowApiError as exc:
+                if requested_status != "draft" or not _is_optional_draft_navigation_read_error(exc):
+                    raise
+                fallback_error = exc
+                effective_status = "published"
+                result = self.backend.request(
+                    "GET",
+                    context,
+                    f"/navigation/detail/{navigation_item_id}",
+                    params={"status": effective_status},
+                )
+            response = {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "navigation_item_id": navigation_item_id,
+                "status": effective_status,
+                "requested_status": requested_status,
+                "result": result,
+            }
+            if fallback_error is not None:
+                response["warnings"] = [_navigation_fallback_warning("NAVIGATION_DRAFT_DETAIL_UNAVAILABLE", fallback_error)]
+                response["verification"] = {"draft_readable": False, "published_fallback_used": True}
+            return response
 
         return self._run(profile, runner)
 
@@ -208,3 +270,20 @@ class NavigationTools(ToolBase):
         """执行内部辅助逻辑。"""
         if navigation_item_id <= 0:
             raise_tool_error(QingflowApiError.config_error("navigation_item_id must be positive"))
+
+
+def _is_optional_draft_navigation_read_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    backend_code = backend_code_int(error)
+    return backend_code in {40002, 40027, 404} or error.http_status == 404
+
+
+def _navigation_fallback_warning(code: str, error: QingflowApiError) -> JSONObject:
+    return {
+        "code": code,
+        "message": "draft navigation data is unavailable; returned published navigation data instead",
+        "backend_code": error.backend_code,
+        "http_status": error.http_status,
+        "request_id": error.request_id,
+    }