@josephyan/qingflow-app-builder-mcp 0.2.0-beta.4 → 0.2.0-beta.41

package/src/qingflow_mcp/tools/import_tools.py

@@ -0,0 +1,1164 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import mimetypes
+import shutil
+from copy import deepcopy
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from mcp.server.fastmcp import FastMCP
+from openpyxl import load_workbook
+
+from ..config import DEFAULT_PROFILE
+from ..errors import QingflowApiError
+from ..import_store import ImportJobStore, ImportVerificationStore
+from ..json_types import JSONObject
+from .base import ToolBase
+from .file_tools import FileTools
+from .record_tools import RecordTools
+
+
+SUPPORTED_IMPORT_EXTENSIONS = {".xlsx", ".xls"}
+REPAIRABLE_IMPORT_EXTENSIONS = {".xlsx"}
+SAFE_REPAIRS = {
+    "normalize_headers",
+    "trim_trailing_blank_rows",
+    "normalize_enum_values",
+    "normalize_date_formats",
+    "normalize_number_formats",
+    "normalize_url_cells",
+}
+
+
+class ImportTools(ToolBase):
+    def __init__(
+        self,
+        sessions,
+        backend,
+        *,
+        verification_store: ImportVerificationStore | None = None,
+        job_store: ImportJobStore | None = None,
+    ) -> None:
+        super().__init__(sessions, backend)
+        self._record_tools = RecordTools(sessions, backend)
+        self._file_tools = FileTools(sessions, backend)
+        self._verification_store = verification_store or ImportVerificationStore()
+        self._job_store = job_store or ImportJobStore()
+
+    def register(self, mcp: FastMCP) -> None:
+        @mcp.tool(description="Get the official app import template and the expected applicant import columns.")
+        def record_import_template_get(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            download_to_path: str | None = None,
+        ) -> dict[str, Any]:
+            return self.record_import_template_get(
+                profile=profile,
+                app_key=app_key,
+                download_to_path=download_to_path,
+            )
+
+        @mcp.tool(description="Verify a local Excel import file and produce the only verification_id allowed for import start.")
+        def record_import_verify(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            file_path: str = "",
+        ) -> dict[str, Any]:
+            return self.record_import_verify(
+                profile=profile,
+                app_key=app_key,
+                file_path=file_path,
+            )
+
+        @mcp.tool(description="Repair a local .xlsx import file after explicit user authorization, then re-verify it.")
+        def record_import_repair_local(
+            profile: str = DEFAULT_PROFILE,
+            verification_id: str = "",
+            authorized_file_modification: bool = False,
+            output_path: str | None = None,
+            selected_repairs: list[str] | None = None,
+        ) -> dict[str, Any]:
+            return self.record_import_repair_local(
+                profile=profile,
+                verification_id=verification_id,
+                authorized_file_modification=authorized_file_modification,
+                output_path=output_path,
+                selected_repairs=selected_repairs,
+            )
+
+        @mcp.tool(description="Start import from a successful verification_id. being_enter_auditing must be passed explicitly.")
+        def record_import_start(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            verification_id: str = "",
+            being_enter_auditing: bool | None = None,
+            view_key: str | None = None,
+        ) -> dict[str, Any]:
+            return self.record_import_start(
+                profile=profile,
+                app_key=app_key,
+                verification_id=verification_id,
+                being_enter_auditing=being_enter_auditing,
+                view_key=view_key,
+            )
+
+        @mcp.tool(description="Get import status by process_id_str, import_id, or the latest remembered import in the current app.")
+        def record_import_status_get(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            import_id: str | None = None,
+            process_id_str: str | None = None,
+        ) -> dict[str, Any]:
+            return self.record_import_status_get(
+                profile=profile,
+                app_key=app_key,
+                import_id=import_id,
+                process_id_str=process_id_str,
+            )
+
+    def record_import_template_get(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        download_to_path: str | None = None,
+    ) -> dict[str, Any]:
+        if not app_key.strip():
+            return self._failed_template_result(app_key=app_key, error_code="IMPORT_TEMPLATE_UNAUTHORIZED", message="app_key is required")
+
+        def runner(session_profile, context):
+            expected_columns, schema_fingerprint = self._expected_import_columns(profile, context, app_key)
+            try:
+                payload = self.backend.request("GET", context, f"/app/{app_key}/apply/excelTemplate")
+            except QingflowApiError as exc:
+                return self._failed_template_result(
+                    app_key=app_key,
+                    error_code="IMPORT_TEMPLATE_UNAUTHORIZED",
+                    message=exc.message,
+                    request_route=self.backend.describe_route(context),
+                )
+            template_url = _pick_template_url(payload)
+            if not template_url:
+                return self._failed_template_result(
+                    app_key=app_key,
+                    error_code="IMPORT_TEMPLATE_UNAUTHORIZED",
+                    message="template endpoint did not return excelUrl",
+                    request_route=self.backend.describe_route(context),
+                )
+            downloaded_to_path = None
+            warnings: list[JSONObject] = []
+            verification = {
+                "schema_fingerprint": schema_fingerprint,
+                "template_url_resolved": True,
+                "template_downloaded": False,
+            }
+            if download_to_path:
+                destination = _resolve_template_download_path(download_to_path, app_key=app_key)
+                destination.parent.mkdir(parents=True, exist_ok=True)
+                content = self.backend.download_binary(template_url)
+                destination.write_bytes(content)
+                downloaded_to_path = str(destination)
+                verification["template_downloaded"] = True
+            return {
+                "ok": True,
+                "status": "success",
+                "app_key": app_key,
+                "ws_id": session_profile.selected_ws_id,
+                "request_route": self.backend.describe_route(context),
+                "template_url": template_url,
+                "downloaded_to_path": downloaded_to_path,
+                "expected_columns": expected_columns,
+                "schema_fingerprint": schema_fingerprint,
+                "warnings": warnings,
+                "verification": verification,
+            }
+
+        try:
+            return self._run(profile, runner)
+        except RuntimeError as exc:
+            return self._runtime_error_as_result(exc, error_code="IMPORT_TEMPLATE_UNAUTHORIZED")
+
+    def record_import_verify(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        file_path: str,
+    ) -> dict[str, Any]:
+        if not app_key.strip():
+            return self._failed_verify_result(app_key=app_key, file_path=file_path, error_code="IMPORT_VERIFICATION_FAILED", message="app_key is required")
+        path = Path(file_path).expanduser()
+        if not path.is_file():
+            return self._failed_verify_result(app_key=app_key, file_path=file_path, error_code="IMPORT_VERIFICATION_FAILED", message="file_path must point to an existing file")
+
+        def runner(session_profile, context):
+            expected_columns, schema_fingerprint = self._expected_import_columns(profile, context, app_key)
+            local_check = self._local_verify(
+                path=path,
+                app_key=app_key,
+                expected_columns=expected_columns,
+                schema_fingerprint=schema_fingerprint,
+            )
+            warnings = deepcopy(local_check["warnings"])
+            issues = deepcopy(local_check["issues"])
+            can_import = bool(local_check["can_import"])
+            backend_verification = None
+            if can_import:
+                try:
+                    payload = self.backend.request_multipart(
+                        "POST",
+                        context,
+                        f"/app/{app_key}/upload/verification",
+                        files={
+                            "file": (
+                                path.name,
+                                path.read_bytes(),
+                                mimetypes.guess_type(path.name)[0] or "application/octet-stream",
+                            )
+                        },
+                    )
+                    if isinstance(payload, dict):
+                        backend_verification = payload
+                    else:
+                        backend_verification = {}
+                    if not bool(backend_verification.get("beingValidated", True)):
+                        can_import = False
+                        issues.append(
+                            _issue(
+                                "BACKEND_IMPORT_VERIFICATION_REJECTED",
+                                "Backend verification rejected the file for import.",
+                                severity="error",
+                            )
+                        )
+                except QingflowApiError as exc:
+                    can_import = False
+                    issues.append(
+                        _issue(
+                            "BACKEND_IMPORT_VERIFICATION_FAILED",
+                            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.",
+                        }
+                    )
+            verification_id = str(uuid4())
+            verification_payload = {
+                "id": verification_id,
+                "created_at": _utc_now().isoformat(),
+                "profile": profile,
+                "app_key": app_key,
+                "file_path": str(path.resolve()),
+                "file_name": path.name,
+                "file_sha256": local_check["file_sha256"],
+                "file_size": local_check["file_size"],
+                "schema_fingerprint": schema_fingerprint,
+                "can_import": can_import,
+                "issues": issues,
+                "warnings": warnings,
+                "apply_rows": backend_verification.get("applyRows") if isinstance(backend_verification, dict) else None,
+                "backend_verification": backend_verification,
+                "local_precheck": local_check,
+            }
+            self._verification_store.put(verification_id, verification_payload)
+            return {
+                "ok": True,
+                "status": "success" if can_import else "failed",
+                "error_code": None if can_import else (local_check.get("error_code") or "IMPORT_VERIFICATION_FAILED"),
+                "can_import": can_import,
+                "verification_id": verification_id,
+                "file_path": str(path.resolve()),
+                "file_name": path.name,
+                "file_sha256": local_check["file_sha256"],
+                "file_size": local_check["file_size"],
+                "schema_fingerprint": schema_fingerprint,
+                "apply_rows": backend_verification.get("applyRows") if isinstance(backend_verification, dict) else None,
+                "issues": issues,
+                "repair_suggestions": local_check["repair_suggestions"],
+                "warnings": warnings,
+                "verification": {
+                    "local_precheck_passed": bool(local_check["local_precheck_passed"]),
+                    "backend_verification_passed": can_import and isinstance(backend_verification, dict),
+                    "schema_fingerprint": schema_fingerprint,
+                    "file_sha256": local_check["file_sha256"],
+                    "file_format": local_check["extension"],
+                    "local_precheck_limited": bool(local_check["local_precheck_limited"]),
+                },
+            }
+
+        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})
+
+    def record_import_repair_local(
+        self,
+        *,
+        profile: str,
+        verification_id: str,
+        authorized_file_modification: bool,
+        output_path: str | None = None,
+        selected_repairs: list[str] | None = None,
+    ) -> dict[str, Any]:
+        if not verification_id.strip():
+            return self._failed_repair_result(error_code="IMPORT_VERIFICATION_FAILED", message="verification_id is required")
+        if not authorized_file_modification:
+            return self._failed_repair_result(
+                error_code="IMPORT_REPAIR_NOT_AUTHORIZED",
+                message="record_import_repair_local requires authorized_file_modification=true",
+            )
+        unknown_repairs = sorted({item for item in (selected_repairs or []) if item not in SAFE_REPAIRS})
+        if unknown_repairs:
+            return self._failed_repair_result(
+                error_code="IMPORT_REPAIR_FORMAT_UNSUPPORTED",
+                message=f"unknown selected_repairs: {', '.join(unknown_repairs)}",
+            )
+
+        def runner(_session_profile, context):
+            stored = self._verification_store.get(verification_id)
+            if stored is None:
+                return self._failed_repair_result(error_code="IMPORT_VERIFICATION_STALE", message="verification_id is missing or expired")
+            source_path = Path(str(stored["file_path"]))
+            extension = source_path.suffix.lower()
+            if extension not in REPAIRABLE_IMPORT_EXTENSIONS:
+                return self._failed_repair_result(
+                    error_code="IMPORT_REPAIR_FORMAT_UNSUPPORTED",
+                    message="record_import_repair_local v1 only supports .xlsx files",
+                    extra={"source_file_path": str(source_path)},
+                )
+            expected_columns, _ = self._expected_import_columns(profile, context, str(stored["app_key"]))
+            normalized_repairs = set(selected_repairs or SAFE_REPAIRS)
+            destination = _resolve_repaired_output_path(source_path, output_path=output_path)
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(source_path, destination)
+
+            workbook = load_workbook(destination)
+            sheet = workbook[workbook.sheetnames[0]]
+            applied_repairs: list[str] = []
+            skipped_repairs: list[str] = []
+            if "normalize_headers" in normalized_repairs:
+                if _repair_headers(sheet, expected_columns):
+                    applied_repairs.append("normalize_headers")
+                else:
+                    skipped_repairs.append("normalize_headers")
+            if "trim_trailing_blank_rows" in normalized_repairs:
+                if _trim_trailing_blank_rows(sheet):
+                    applied_repairs.append("trim_trailing_blank_rows")
+                else:
+                    skipped_repairs.append("trim_trailing_blank_rows")
+            if "normalize_enum_values" in normalized_repairs:
+                if _normalize_enum_values(sheet, expected_columns):
+                    applied_repairs.append("normalize_enum_values")
+                else:
+                    skipped_repairs.append("normalize_enum_values")
+            if "normalize_date_formats" in normalized_repairs:
+                if _normalize_date_formats(sheet):
+                    applied_repairs.append("normalize_date_formats")
+                else:
+                    skipped_repairs.append("normalize_date_formats")
+            if "normalize_number_formats" in normalized_repairs:
+                if _normalize_number_formats(sheet):
+                    applied_repairs.append("normalize_number_formats")
+                else:
+                    skipped_repairs.append("normalize_number_formats")
+            if "normalize_url_cells" in normalized_repairs:
+                if _normalize_url_cells(sheet):
+                    applied_repairs.append("normalize_url_cells")
+                else:
+                    skipped_repairs.append("normalize_url_cells")
+            workbook.save(destination)
+
+            verification_result = self.record_import_verify(
+                profile=profile,
+                app_key=str(stored["app_key"]),
+                file_path=str(destination),
+            )
+            new_verification_id = verification_result.get("verification_id")
+            return {
+                "ok": bool(verification_result.get("ok")),
+                "status": verification_result.get("status"),
+                "error_code": verification_result.get("error_code"),
+                "source_file_path": str(source_path),
+                "repaired_file_path": str(destination),
+                "applied_repairs": applied_repairs,
+                "skipped_repairs": skipped_repairs,
+                "new_verification_id": new_verification_id,
+                "can_import_after_repair": bool(verification_result.get("can_import")),
+                "post_repair_issues": verification_result.get("issues", []),
+                "warnings": verification_result.get("warnings", []),
+                "verification": {
+                    "source_preserved": True,
+                    "repair_authorized": True,
+                    "reverified": True,
+                    "selected_repairs": sorted(normalized_repairs),
+                },
+            }
+
+        try:
+            return self._run(profile, runner)
+        except RuntimeError as exc:
+            return self._runtime_error_as_result(exc, error_code="IMPORT_REPAIR_FORMAT_UNSUPPORTED")
+
+    def record_import_start(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        verification_id: str,
+        being_enter_auditing: bool | None,
+        view_key: str | None = None,
+    ) -> dict[str, Any]:
+        if being_enter_auditing is None:
+            return self._failed_start_result(error_code="IMPORT_VERIFICATION_FAILED", message="being_enter_auditing must be passed explicitly")
+
+        def runner(session_profile, context):
+            stored = self._verification_store.get(verification_id)
+            if stored is None:
+                return self._failed_start_result(error_code="IMPORT_VERIFICATION_STALE", message="verification_id is missing or expired")
+            if str(stored.get("app_key")) != app_key:
+                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["file_path"]))
+            if not current_path.is_file():
+                return self._failed_start_result(error_code="IMPORT_VERIFICATION_STALE", message="verified file no longer exists")
+            current_sha256 = _sha256_file(current_path)
+            if current_sha256 != stored.get("file_sha256"):
+                return self._failed_start_result(
+                    error_code="IMPORT_FILE_CHANGED_AFTER_VERIFY",
+                    message="the file changed after verification; run record_import_verify again",
+                    extra={"accepted": False},
+                )
+            _, current_schema_fingerprint = self._expected_import_columns(profile, context, app_key)
+            if current_schema_fingerprint != stored.get("schema_fingerprint"):
+                return self._failed_start_result(
+                    error_code="IMPORT_SCHEMA_CHANGED_AFTER_VERIFY",
+                    message="the applicant schema changed after verification; run record_import_verify again",
+                    extra={"accepted": False},
+                )
+            upload_result = self._file_tools.file_upload_local(
+                profile=profile,
+                upload_kind="login",
+                file_path=str(current_path),
+            )
+            file_url = upload_result.get("download_url")
+            if not isinstance(file_url, str) or not file_url.strip():
+                return self._failed_start_result(error_code="IMPORT_VERIFICATION_FAILED", message="file upload did not return download_url")
+            try:
+                socket_result = self.backend.start_socket_data_import(
+                    context,
+                    app_key=app_key,
+                    being_enter_auditing=bool(being_enter_auditing),
+                    view_key=view_key,
+                    excel_url=file_url,
+                    excel_name=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})
+            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()
+            self._job_store.put(
+                import_id,
+                {
+                    "created_at": started_at,
+                    "profile": profile,
+                    "app_key": app_key,
+                    "import_id": import_id,
+                    "process_id_str": process_id_str,
+                    "source_file_name": current_path.name,
+                    "started_at": started_at,
+                    "file_url": file_url,
+                    "verification_id": verification_id,
+                },
+            )
+            warnings = deepcopy(socket_result.get("warnings", []))
+            return {
+                "ok": True,
+                "status": "accepted",
+                "accepted": True,
+                "import_id": import_id,
+                "process_id_str": process_id_str,
+                "source_file_name": current_path.name,
+                "file_url": file_url,
+                "warnings": warnings,
+                "verification": {
+                    "verification_id_valid": True,
+                    "file_hash_verified": True,
+                    "schema_fingerprint_verified": True,
+                    "upload_staged": True,
+                    "import_acknowledged": bool(import_id),
+                },
+            }
+
+        try:
+            return self._run(profile, runner)
+        except RuntimeError as exc:
+            return self._runtime_error_as_result(exc, error_code="IMPORT_VERIFICATION_FAILED", extra={"accepted": False})
+
+    def record_import_status_get(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        import_id: str | None = None,
+        process_id_str: str | None = None,
+    ) -> dict[str, Any]:
+        if not app_key.strip():
+            return self._failed_status_result(error_code="IMPORT_STATUS_AMBIGUOUS", message="app_key is required")
+
+        def runner(_session_profile, context):
+            local_job = None
+            normalized_import_id = _normalize_optional_text(import_id)
+            normalized_process_id = _normalize_optional_text(process_id_str)
+            if normalized_import_id:
+                local_job = self._job_store.get(normalized_import_id)
+            if local_job is None and normalized_process_id:
+                matches = [item for item in self._job_store.list() if _normalize_optional_text(item.get("process_id_str")) == normalized_process_id]
+                local_job = matches[0] if len(matches) == 1 else None
+            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")) == app_key]
+                local_job = recent[0] if recent else None
+            page = self.backend.request(
+                "GET",
+                context,
+                "/app/apply/dataImport/record",
+                params={"appKey": app_key, "pageNum": 1, "pageSize": 100},
+            )
+            records = _extract_import_records(page)
+            matched_record, matched_by = _match_import_record(
+                records,
+                local_job=local_job,
+                process_id_str=normalized_process_id,
+            )
+            if matched_record is None:
+                return self._failed_status_result(
+                    error_code="IMPORT_STATUS_AMBIGUOUS",
+                    message="could not uniquely resolve an import record from the provided identifiers",
+                    extra={"matched_by": matched_by},
+                )
+            normalized_process = _normalize_optional_text(
+                matched_record.get("processIdStr") or matched_record.get("processId") or matched_record.get("process_id_str")
+            )
+            if local_job is not None and normalized_import_id:
+                self._job_store.put(
+                    normalized_import_id,
+                    {
+                        **local_job,
+                        "created_at": local_job.get("created_at") or _utc_now().isoformat(),
+                        "process_id_str": normalized_process,
+                    },
+                )
+            total_rows = _coerce_int(matched_record.get("totalNumber") or matched_record.get("total_rows"))
+            success_rows = _coerce_int(matched_record.get("successNum") or matched_record.get("success_rows"))
+            failed_rows = _coerce_int(matched_record.get("errorNum") or matched_record.get("failed_rows"))
+            progress = _coerce_int(matched_record.get("importPercentage") or matched_record.get("progress"))
+            return {
+                "ok": True,
+                "status": _normalize_optional_text(matched_record.get("processStatus")) or "unknown",
+                "import_id": normalized_import_id or (local_job.get("import_id") if isinstance(local_job, dict) else None),
+                "process_id_str": normalized_process,
+                "matched_by": matched_by,
+                "source_file_name": matched_record.get("sourceFileName") or matched_record.get("source_file_name"),
+                "total_rows": total_rows,
+                "success_rows": success_rows,
+                "failed_rows": failed_rows,
+                "progress": progress,
+                "error_file_urls": _normalize_error_file_urls(matched_record.get("errorFileUrls")),
+                "operate_time": matched_record.get("operateTime"),
+                "operate_user": matched_record.get("operateUser"),
+                "warnings": [],
+                "verification": {
+                    "status_lookup_completed": True,
+                    "matched_by": matched_by,
+                    "process_id_verified": bool(normalized_process),
+                },
+            }
+
+        try:
+            return self._run(profile, runner)
+        except RuntimeError as exc:
+            return self._runtime_error_as_result(exc, error_code="IMPORT_STATUS_AMBIGUOUS")
+
+    def _expected_import_columns(self, profile: str, context, app_key: str) -> tuple[list[JSONObject], str]:  # type: ignore[no-untyped-def]
+        index = self._record_tools._get_field_index(profile, context, app_key, force_refresh=False)
+        ws_id = self.sessions.get_profile(profile).selected_ws_id
+        expected_columns: list[JSONObject] = []
+        for field in index.by_id.values():
+            payload = self._record_tools._schema_field_payload(
+                profile,
+                context,
+                field,
+                workflow_node_id=None,
+                ws_id=ws_id,
+                schema_mode="applicant",
+            )
+            if not bool(payload.get("writable")):
+                continue
+            expected_columns.append(
+                {
+                    "field_id": payload["field_id"],
+                    "title": payload["title"],
+                    "que_type": payload["que_type"],
+                    "required": bool(field.required),
+                    "write_kind": payload["write_kind"],
+                    "options": payload.get("options", []),
+                    "requires_lookup": bool(payload.get("requires_lookup")),
+                    "requires_upload": bool(payload.get("requires_upload")),
+                    "target_app_key": payload.get("target_app_key"),
+                    "target_app_name": payload.get("target_app_name"),
+                }
+            )
+        expected_columns.sort(key=lambda item: int(item["field_id"]))
+        schema_fingerprint = hashlib.sha256(
+            json.dumps(expected_columns, ensure_ascii=False, sort_keys=True).encode("utf-8")
+        ).hexdigest()
+        return expected_columns, schema_fingerprint
+
+    def _local_verify(
+        self,
+        *,
+        path: Path,
+        app_key: str,
+        expected_columns: list[JSONObject],
+        schema_fingerprint: str,
+    ) -> dict[str, Any]:
+        extension = path.suffix.lower()
+        file_sha256 = _sha256_file(path)
+        base_result = {
+            "app_key": app_key,
+            "file_path": str(path.resolve()),
+            "file_size": path.stat().st_size,
+            "file_sha256": file_sha256,
+            "schema_fingerprint": schema_fingerprint,
+            "issues": [],
+            "warnings": [],
+            "repair_suggestions": [],
+            "local_precheck_passed": True,
+            "local_precheck_limited": False,
+            "can_import": True,
+            "extension": extension,
+            "error_code": None,
+        }
+        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"))
+            base_result["local_precheck_passed"] = False
+            base_result["can_import"] = False
+            base_result["error_code"] = "IMPORT_FILE_FORMAT_UNSUPPORTED"
+            return base_result
+        if extension == ".xls":
+            base_result["warnings"].append(
+                {
+                    "code": "IMPORT_LOCAL_PRECHECK_LIMITED",
+                    "message": ".xls files are allowed for verify/start, but v1 local precheck is limited and repair is unsupported.",
+                }
+            )
+            base_result["local_precheck_limited"] = True
+            return base_result
+
+        try:
+            workbook = load_workbook(path, read_only=True, data_only=False)
+        except Exception as exc:
+            base_result["issues"].append(_issue("WORKBOOK_OPEN_FAILED", f"Workbook could not be opened: {exc}", severity="error"))
+            base_result["local_precheck_passed"] = False
+            base_result["can_import"] = False
+            base_result["error_code"] = "IMPORT_VERIFICATION_FAILED"
+            return base_result
+
+        if not workbook.sheetnames:
+            base_result["issues"].append(_issue("SHEET_MISSING", "Workbook does not contain any sheets.", severity="error"))
+            base_result["local_precheck_passed"] = False
+            base_result["can_import"] = False
+            base_result["error_code"] = "IMPORT_VERIFICATION_FAILED"
+            return base_result
+        sheet = workbook[workbook.sheetnames[0]]
+        header_row = [cell.value for cell in next(sheet.iter_rows(min_row=1, max_row=1), [])]
+        header_analysis = _analyze_headers(header_row, expected_columns)
+        base_result["issues"].extend(header_analysis["issues"])
+        base_result["repair_suggestions"].extend(header_analysis["repair_suggestions"])
+        trailing_blank_rows = _count_trailing_blank_rows(sheet)
+        if trailing_blank_rows > 0:
+            base_result["warnings"].append(
+                {
+                    "code": "TRAILING_BLANK_ROWS",
+                    "message": f"Workbook contains {trailing_blank_rows} trailing blank rows that can be safely removed.",
+                }
+            )
+            base_result["repair_suggestions"].append("trim_trailing_blank_rows")
+        enum_suggestions = _find_enum_repairs(sheet, expected_columns)
+        if enum_suggestions:
+            base_result["warnings"].append(
+                {
+                    "code": "ENUM_VALUE_NORMALIZATION_AVAILABLE",
+                    "message": "Some enum-like cells can be normalized to exact template values without changing meaning.",
+                }
+            )
+            base_result["repair_suggestions"].append("normalize_enum_values")
+        base_result["repair_suggestions"] = sorted(set(base_result["repair_suggestions"]))
+        if any(issue.get("severity") == "error" for issue in base_result["issues"]):
+            base_result["local_precheck_passed"] = False
+            base_result["can_import"] = False
+            base_result["error_code"] = "IMPORT_VERIFICATION_FAILED"
+        return base_result
+
+    def _failed_template_result(
+        self,
+        *,
+        app_key: str,
+        error_code: str,
+        message: str,
+        request_route: JSONObject | None = None,
+    ) -> dict[str, Any]:
+        return {
+            "ok": False,
+            "status": "failed",
+            "error_code": error_code,
+            "app_key": app_key,
+            "template_url": None,
+            "downloaded_to_path": None,
+            "expected_columns": [],
+            "schema_fingerprint": None,
+            "request_route": request_route,
+            "warnings": [],
+            "verification": {"template_url_resolved": False},
+            "message": message,
+        }
+
+    def _failed_verify_result(self, *, app_key: str, file_path: str, error_code: str, message: str) -> dict[str, Any]:
+        return {
+            "ok": True,
+            "status": "failed",
+            "error_code": error_code,
+            "app_key": app_key,
+            "can_import": False,
+            "verification_id": None,
+            "file_path": str(Path(file_path).expanduser()) if file_path else file_path,
+            "file_name": Path(file_path).name if file_path else None,
+            "file_sha256": None,
+            "file_size": None,
+            "schema_fingerprint": None,
+            "apply_rows": None,
+            "issues": [_issue(error_code, message, severity="error")],
+            "repair_suggestions": [],
+            "warnings": [],
+            "verification": {
+                "local_precheck_passed": False,
+                "backend_verification_passed": False,
+            },
+            "message": message,
+        }
+
+    def _failed_repair_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,
+            "source_file_path": None,
+            "repaired_file_path": None,
+            "applied_repairs": [],
+            "skipped_repairs": [],
+            "new_verification_id": None,
+            "can_import_after_repair": False,
+            "post_repair_issues": [_issue(error_code, message, severity="error")],
+            "warnings": [],
+            "verification": {
+                "repair_authorized": False,
+                "reverified": False,
+            },
+            "message": message,
+        }
+        if extra:
+            payload.update(extra)
+        return payload
+
+    def _failed_start_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,
+            "accepted": False,
+            "import_id": None,
+            "process_id_str": None,
+            "source_file_name": None,
+            "file_url": None,
+            "warnings": [],
+            "verification": {
+                "verification_id_valid": False,
+                "file_hash_verified": False,
+                "schema_fingerprint_verified": False,
+                "upload_staged": False,
+                "import_acknowledged": False,
+            },
+            "message": message,
+        }
+        if extra:
+            payload.update(extra)
+        return payload
+
+    def _failed_status_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,
+            "import_id": None,
+            "process_id_str": None,
+            "matched_by": None,
+            "source_file_name": None,
+            "total_rows": None,
+            "success_rows": None,
+            "failed_rows": None,
+            "progress": None,
+            "error_file_urls": [],
+            "operate_time": None,
+            "operate_user": None,
+            "warnings": [],
+            "verification": {
+                "status_lookup_completed": False,
+                "process_id_verified": False,
+            },
+            "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 = {
+            "ok": False,
+            "status": "failed",
+            "error_code": payload.get("details", {}).get("error_code") or error_code,
+            "warnings": [],
+            "verification": {},
+            "message": payload.get("message") or str(error),
+        }
+        if extra:
+            response.update(extra)
+        return response
+
+
+def _pick_template_url(payload: Any) -> str | None:
+    if isinstance(payload, dict):
+        for key in ("excelUrl", "url", "downloadUrl"):
+            value = payload.get(key)
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+    return None
+
+
+def _resolve_template_download_path(raw_path: str, *, app_key: str) -> Path:
+    path = Path(raw_path).expanduser()
+    if path.exists() and path.is_dir():
+        return path / f"{app_key}_import_template.xlsx"
+    if path.suffix:
+        return path
+    return path / f"{app_key}_import_template.xlsx"
+
+
+def _resolve_repaired_output_path(source_path: Path, *, output_path: str | None) -> Path:
+    if output_path:
+        path = Path(output_path).expanduser()
+        if path.exists() and path.is_dir():
+            return path / f"{source_path.stem}.repaired{source_path.suffix}"
+        if path.suffix:
+            return path
+        return path / f"{source_path.stem}.repaired{source_path.suffix}"
+    return source_path.with_name(f"{source_path.stem}.repaired{source_path.suffix}")
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _normalize_optional_text(value: Any) -> str | None:
+    if value is None:
+        return None
+    normalized = str(value).strip()
+    return normalized or None
+
+
+def _normalize_header_key(value: Any) -> str:
+    text = _normalize_optional_text(value)
+    return (text or "").casefold()
+
+
+def _issue(code: str, message: str, *, severity: str, repairable: bool = False, repair_code: str | None = None) -> JSONObject:
+    payload: JSONObject = {
+        "code": code,
+        "message": message,
+        "severity": severity,
+        "repairable": repairable,
+    }
+    if repair_code:
+        payload["repair_code"] = repair_code
+    return payload
+
+
+def _analyze_headers(header_row: list[Any], expected_columns: list[JSONObject]) -> dict[str, Any]:
+    expected_by_key = {_normalize_header_key(item["title"]): item for item in expected_columns}
+    seen: dict[str, int] = {}
+    actual_headers: list[str] = []
+    for item in header_row:
+        text = _normalize_optional_text(item)
+        if text is None:
+            actual_headers.append("")
+            continue
+        actual_headers.append(text)
+        key = _normalize_header_key(text)
+        seen[key] = seen.get(key, 0) + 1
+    actual_keys = {key for key, count in seen.items() if key and count > 0}
+    missing = [item["title"] for key, item in expected_by_key.items() if key not in actual_keys]
+    extra = [text for text in actual_headers if text and _normalize_header_key(text) not in expected_by_key]
+    duplicates = [text for text in actual_headers if text and seen.get(_normalize_header_key(text), 0) > 1]
+    issues: list[JSONObject] = []
+    repair_suggestions: list[str] = []
+    if missing:
+        issues.append(_issue("MISSING_COLUMNS", f"Missing expected columns: {', '.join(missing)}", severity="error"))
+    if extra:
+        issues.append(_issue("EXTRA_COLUMNS", f"Unexpected columns: {', '.join(extra)}", severity="error"))
+    if duplicates:
+        issues.append(_issue("DUPLICATE_COLUMNS", f"Duplicate columns: {', '.join(sorted(set(duplicates)))}", severity="error"))
+    normalized_changes = []
+    for text in actual_headers:
+        if not text:
+            continue
+        matched = expected_by_key.get(_normalize_header_key(text))
+        if matched and matched["title"] != text:
+            normalized_changes.append((text, matched["title"]))
+    if normalized_changes:
+        repair_suggestions.append("normalize_headers")
+    return {"issues": issues, "repair_suggestions": repair_suggestions}
+
+
+def _count_trailing_blank_rows(sheet) -> int:  # type: ignore[no-untyped-def]
+    count = 0
+    for row_index in range(sheet.max_row, 1, -1):
+        values = [cell.value for cell in sheet[row_index]]
+        if any(value not in (None, "") for value in values):
+            break
+        count += 1
+    return count
+
+
+def _find_enum_repairs(sheet, expected_columns: list[JSONObject]) -> list[str]:  # type: ignore[no-untyped-def]
+    header_map = _sheet_header_map(sheet)
+    found: list[str] = []
+    for column in expected_columns:
+        options = [str(item).strip() for item in column.get("options", []) if str(item).strip()]
+        if not options:
+            continue
+        column_index = header_map.get(_normalize_header_key(column["title"]))
+        if column_index is None:
+            continue
+        option_map = {_normalize_header_key(item): item for item in options}
+        for row in range(2, min(sheet.max_row, 50) + 1):
+            value = sheet.cell(row=row, column=column_index).value
+            text = _normalize_optional_text(value)
+            if text is None:
+                continue
+            exact = option_map.get(_normalize_header_key(text))
+            if exact and exact != text:
+                found.append(column["title"])
+                break
+    return found
+
+
+def _sheet_header_map(sheet) -> dict[str, int]:  # type: ignore[no-untyped-def]
+    mapping: dict[str, int] = {}
+    for index, cell in enumerate(next(sheet.iter_rows(min_row=1, max_row=1), []), start=1):
+        key = _normalize_header_key(cell.value)
+        if key and key not in mapping:
+            mapping[key] = index
+    return mapping
+
+
+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}
+    for cell in next(sheet.iter_rows(min_row=1, max_row=1), []):
+        text = _normalize_optional_text(cell.value)
+        if text is None:
+            continue
+        canonical = expected_by_key.get(_normalize_header_key(text))
+        if canonical and canonical != text:
+            cell.value = canonical
+            changed = True
+    return changed
+
+
+def _trim_trailing_blank_rows(sheet) -> bool:  # type: ignore[no-untyped-def]
+    removed = 0
+    while sheet.max_row > 1:
+        values = [cell.value for cell in sheet[sheet.max_row]]
+        if any(value not in (None, "") for value in values):
+            break
+        sheet.delete_rows(sheet.max_row, 1)
+        removed += 1
+    return removed > 0
+
+
+def _normalize_enum_values(sheet, expected_columns: list[JSONObject]) -> bool:  # type: ignore[no-untyped-def]
+    changed = False
+    header_map = _sheet_header_map(sheet)
+    for column in expected_columns:
+        options = [str(item).strip() for item in column.get("options", []) if str(item).strip()]
+        if not options:
+            continue
+        column_index = header_map.get(_normalize_header_key(column["title"]))
+        if column_index is None:
+            continue
+        option_map = {_normalize_header_key(item): item for item in options}
+        for row in range(2, sheet.max_row + 1):
+            cell = sheet.cell(row=row, column=column_index)
+            text = _normalize_optional_text(cell.value)
+            if text is None:
+                continue
+            canonical = option_map.get(_normalize_header_key(text))
+            if canonical and canonical != text:
+                cell.value = canonical
+                changed = True
+    return changed
+
+
+def _normalize_date_formats(sheet) -> bool:  # type: ignore[no-untyped-def]
+    changed = False
+    for row in sheet.iter_rows(min_row=2):
+        for cell in row:
+            if getattr(cell, "is_date", False):
+                if cell.number_format != "yyyy-mm-dd hh:mm:ss":
+                    cell.number_format = "yyyy-mm-dd hh:mm:ss"
+                    changed = True
+    return changed
+
+
+def _normalize_number_formats(sheet) -> bool:  # type: ignore[no-untyped-def]
+    changed = False
+    for row in sheet.iter_rows(min_row=2):
+        for cell in row:
+            if isinstance(cell.value, (int, float)) and not getattr(cell, "is_date", False):
+                if cell.number_format == "General":
+                    cell.number_format = "0.00" if isinstance(cell.value, float) else "0"
+                    changed = True
+    return changed
+
+
+def _normalize_url_cells(sheet) -> bool:  # type: ignore[no-untyped-def]
+    changed = False
+    for row in sheet.iter_rows(min_row=2):
+        for cell in row:
+            text = _normalize_optional_text(cell.value)
+            if text and (text.startswith("http://") or text.startswith("https://")) and text != cell.value:
+                cell.value = text
+                changed = True
+    return changed
+
+
+def _extract_import_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_import_record(
+    records: list[JSONObject],
+    *,
+    local_job: dict[str, Any] | None,
+    process_id_str: str | None,
+) -> tuple[JSONObject | None, str | None]:
+    if process_id_str:
+        exact = [
+            item
+            for item in records
+            if _normalize_optional_text(item.get("processIdStr") or item.get("processId") or item.get("process_id_str")) == process_id_str
+        ]
+        if len(exact) == 1:
+            return exact[0], "process_id_str"
+        if len(exact) > 1:
+            return None, "process_id_str"
+    if isinstance(local_job, dict):
+        source_file_name = _normalize_optional_text(local_job.get("source_file_name"))
+        started_at = _parse_utc(local_job.get("started_at"))
+        candidates = records
+        if source_file_name:
+            candidates = [
+                item
+                for item in candidates
+                if _normalize_optional_text(item.get("sourceFileName") or item.get("source_file_name")) == source_file_name
+            ]
+        if started_at is not None:
+            window_end = started_at + timedelta(minutes=10)
+            timed = []
+            for item in candidates:
+                operate_time = _parse_utc(item.get("operateTime"))
+                if operate_time is None:
+                    continue
+                if started_at - timedelta(minutes=1) <= operate_time <= window_end:
+                    timed.append(item)
+            if len(timed) == 1:
+                return timed[0], "local_job_window"
+            if len(timed) > 1:
+                return None, "local_job_window"
+        if len(candidates) == 1:
+            return candidates[0], "source_file_name"
+        if len(candidates) > 1:
+            return None, "source_file_name"
+    return None, None
+
+
+def _parse_utc(value: Any) -> datetime | None:
+    text = _normalize_optional_text(value)
+    if text is None:
+        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=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 _normalize_error_file_urls(value: Any) -> list[str]:
+    if isinstance(value, list):
+        return [str(item).strip() for item in value if str(item).strip()]
+    return []