@qingflow-tech/qingflow-app-user-mcp 1.0.43 → 1.1.0

package/src/qingflow_mcp/builder_facade/service.py

@@ -33,12 +33,11 @@ from ..tools.qingbi_report_tools import QingbiReportTools
 from ..tools.role_tools import RoleTools
 from ..tools.solution_tools import SolutionTools
 from ..tools.view_tools import ViewTools
-from ..tools.workflow_tools import WorkflowTools
+from . import workflow_spec as workflow_spec_api
 from .button_style_catalog import button_style_catalog_payload
 from .models import (
     AppChartsReadResponse,
     AppFieldsReadResponse,
-    AppFlowReadResponse,
     ChartGetResponse,
     AppLayoutReadResponse,
     AppReadSummaryResponse,
@@ -64,8 +63,6 @@ from .models import (
     FieldRemovePatch,
     FieldSelector,
     FieldUpdatePatch,
-    FlowPlanRequest,
-    FlowAssigneePatch,
     LayoutApplyMode,
     LayoutPlanRequest,
     LayoutSectionPatch,
@@ -96,11 +93,10 @@ from .models import (
     ViewGetResponse,
     ViewsPlanRequest,
     ViewsPreset,
-    FlowPreset,
-    FlowNodePermissionsPatch,
 )
 
 BUILDER_PORTAL_LIST_DETAIL_VERIFY_LIMIT = 50
+CHART_APPLY_RECOMMENDED_UPSERT_BATCH_SIZE = 8
 
 
 QUESTION_TYPE_TO_FIELD_TYPE: dict[int, str] = {
@@ -186,6 +182,37 @@ QUERY_CONDITION_UNSUPPORTED_FIELD_TYPES = {
     FieldType.relation.value,
     FieldType.subtable.value,
 }
+QUERY_CONDITION_UNSUPPORTED_FIELD_TYPES_PUBLIC = sorted(
+    {
+        "address",
+        "attachment",
+        "code_block",
+        "q_linker",
+        "relation",
+        "subtable",
+    }
+)
+QUERY_CONDITION_SUPPORTED_FIELD_TYPES_PUBLIC = sorted(
+    {
+        "text",
+        "long_text",
+        "number",
+        "amount",
+        "date",
+        "datetime",
+        "single_select",
+        "multi_select",
+        "phone",
+        "email",
+        "boolean",
+        "member",
+        "department",
+    }
+)
+QUERY_CONDITION_FIX_HINT = (
+    "Remove this field from query_conditions. query_conditions only configures the frontend query panel for supported query fields. "
+    "Use filters for fixed saved filters, and use associated-resource match_mappings for current-record relation/report matching."
+)
 
 ASSOCIATED_RESOURCE_LIMIT_TYPE_ALL = 1
 ASSOCIATED_RESOURCE_LIMIT_TYPE_SELECT = 2
@@ -234,7 +261,6 @@ class AiBuilderFacade:
         buttons: CustomButtonTools,
         packages: PackageTools,
         views: ViewTools,
-        workflows: WorkflowTools,
         portals: PortalTools,
         charts: QingbiReportTools,
         roles: RoleTools,
@@ -245,13 +271,216 @@ class AiBuilderFacade:
         self.buttons = buttons
         self.packages = packages
         self.views = views
-        self.workflows = workflows
         self.portals = portals
         self.charts = charts
         self.roles = roles
         self.directory = directory
         self.solutions = solutions
 
+    def _with_backend_context(self, profile: str, handler):
+        return self.apps._run(profile, lambda _session_profile, context: handler(context))
+
+    def flow_get_schema(self, *, profile: str, schema_version: str | None = None) -> JSONObject:
+        normalized_args = {"schema_version": schema_version or workflow_spec_api.DEFAULT_SCHEMA_VERSION}
+        try:
+            payload = self._with_backend_context(
+                profile,
+                lambda context: workflow_spec_api.fetch_schema(
+                    self.apps.backend,
+                    context,
+                    schema_version=schema_version,
+                ),
+            )
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "FLOW_SPEC_SCHEMA_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={},
+                suggested_next_call={"tool_name": "app_flow_get_schema", "arguments": {"profile": profile, **normalized_args}},
+            )
+        return {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "read workflow spec schema",
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {"schema": payload},
+            "request_id": None,
+            "suggested_next_call": None,
+            "noop": False,
+            "warnings": [],
+            "verification": {"schema_loaded": True},
+            "verified": True,
+            "schema": payload,
+        }
+
+    def flow_get(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        version_id: str | None = None,
+    ) -> JSONObject:
+        normalized_args = {"app_key": app_key, "version_id": version_id}
+        permission_outcome = self._guard_app_permission(
+            profile=profile,
+            app_key=app_key,
+            required_permission="data_manage",
+            normalized_args=normalized_args,
+        )
+        if permission_outcome.block is not None:
+            return permission_outcome.block
+        try:
+            payload = self._with_backend_context(
+                profile,
+                lambda context: workflow_spec_api.fetch_spec(
+                    self.apps.backend,
+                    context,
+                    app_key=app_key,
+                    version_id=version_id,
+                ),
+            )
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "FLOW_SPEC_GET_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_flow_get", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        response = {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "read workflow spec",
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {},
+            "request_id": None,
+            "suggested_next_call": None,
+            "noop": False,
+            "warnings": list(permission_outcome.warnings),
+            "verification": {"spec_loaded": True},
+            "verified": True,
+            "app_key": app_key,
+        }
+        if isinstance(payload, dict):
+            response.update(payload)
+        else:
+            response["result"] = payload
+        return _apply_permission_outcomes(response, permission_outcome)
+
+    def flow_apply(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        spec: dict[str, Any],
+        publish: bool = True,
+        idempotency_key: str | None = None,
+        schema_version: str | None = None,
+    ) -> JSONObject:
+        normalized_args = {
+            "app_key": app_key,
+            "spec": spec,
+            "publish": publish,
+            "idempotency_key": idempotency_key,
+            "schema_version": schema_version or workflow_spec_api.DEFAULT_SCHEMA_VERSION,
+        }
+        permission_outcomes: list[PermissionCheckOutcome] = []
+        permission_outcome = self._guard_app_permission(
+            profile=profile,
+            app_key=app_key,
+            required_permission="data_manage",
+            normalized_args=normalized_args,
+        )
+        if permission_outcome.block is not None:
+            return permission_outcome.block
+        permission_outcomes.append(permission_outcome)
+
+        def finalize(response: JSONObject) -> JSONObject:
+            return _apply_permission_outcomes(response, *permission_outcomes)
+
+        if not isinstance(spec, dict) or not spec:
+            return finalize(
+                _failed(
+                    "FLOW_SPEC_REQUIRED",
+                    "spec must be a non-empty WorkflowSpecDTO object",
+                    normalized_args=normalized_args,
+                    suggested_next_call={"tool_name": "app_flow_get_schema", "arguments": {"profile": profile}},
+                )
+            )
+        apply_body = {
+            "appKey": app_key,
+            "idempotencyKey": idempotency_key or str(uuid4()),
+            "schemaVersion": schema_version or workflow_spec_api.DEFAULT_SCHEMA_VERSION,
+            "spec": spec,
+        }
+        try:
+            apply_result = self._with_backend_context(
+                profile,
+                lambda context: workflow_spec_api.post_apply(self.apps.backend, context, apply_body=apply_body),
+            )
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return finalize(
+                _failed_from_api_error(
+                    "FLOW_SPEC_APPLY_FAILED",
+                    api_error,
+                    normalized_args=normalized_args,
+                    details={"app_key": app_key},
+                    suggested_next_call={"tool_name": "app_flow_get", "arguments": {"profile": profile, "app_key": app_key}},
+                )
+            )
+        if not isinstance(apply_result, dict):
+            apply_result = {"result": apply_result}
+        verification, verify_warnings, verified = workflow_spec_api.verify_apply_response(
+            input_spec=spec,
+            apply_result=apply_result,
+        )
+        backend_status = str(apply_result.get("status") or "SUCCESS").upper()
+        if backend_status not in {"SUCCESS", "OK"}:
+            return finalize(
+                _failed(
+                    "FLOW_SPEC_APPLY_FAILED",
+                    str(apply_result.get("message") or "workflow spec apply failed"),
+                    normalized_args=normalized_args,
+                    details={"apply_result": apply_result},
+                    suggested_next_call={"tool_name": "app_flow_get", "arguments": {"profile": profile, "app_key": app_key}},
+                )
+            )
+        status = "success" if verified else "partial_success"
+        response = {
+            "status": status,
+            "error_code": None if verified else "FLOW_SPEC_VERIFY_FAILED",
+            "recoverable": not verified,
+            "message": "applied workflow spec" if verified else "applied workflow spec; verification reported issues",
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {
+                "apply_result": apply_result,
+                "appliedSpec": apply_result.get("appliedSpec"),
+                "diffSummary": apply_result.get("diffSummary"),
+                "semanticLint": apply_result.get("semanticLint"),
+            },
+            "request_id": None,
+            "suggested_next_call": None if verified else {"tool_name": "app_flow_get", "arguments": {"profile": profile, "app_key": app_key}},
+            "noop": False,
+            "warnings": verify_warnings,
+            "verification": verification,
+            "verified": verified,
+            "app_key": app_key,
+            "current_version_id": apply_result.get("currentVersionId"),
+        }
+        return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
+
     def package_resolve(self, *, profile: str, package_name: str) -> JSONObject:
         requested = str(package_name or "").strip()
         if not requested:
@@ -2058,83 +2287,6 @@ class AiBuilderFacade:
             },
         }
 
-    def _normalize_flow_nodes(
-        self,
-        *,
-        profile: str,
-        current_fields: list[dict[str, Any]],
-        nodes: list[dict[str, Any]],
-    ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
-        field_name_to_field = {
-            str(field.get("name") or ""): field
-            for field in current_fields
-            if str(field.get("name") or "")
-        }
-        field_name_to_que_id = {
-            str(field.get("name") or ""): int(field.get("que_id"))
-            for field in current_fields
-            if str(field.get("name") or "") and isinstance(field.get("que_id"), int)
-        }
-        normalized_nodes: list[dict[str, Any]] = []
-        issues: list[dict[str, Any]] = []
-        for node in nodes:
-            if not isinstance(node, dict):
-                continue
-            normalized_node = deepcopy(node)
-            assignees = FlowAssigneePatch.model_validate(node.get("assignees") or {})
-            permissions = FlowNodePermissionsPatch.model_validate(node.get("permissions") or {})
-            role_resolution = self._resolve_role_references(
-                profile=profile,
-                role_ids=assignees.role_ids,
-                role_names=assignees.role_names,
-            )
-            member_resolution = self._resolve_member_references(
-                profile=profile,
-                member_uids=assignees.member_uids,
-                member_emails=assignees.member_emails,
-                member_names=assignees.member_names,
-            )
-            issues.extend({**issue, "node_id": node.get("id")} for issue in [*role_resolution["issues"], *member_resolution["issues"]])
-            editable_que_ids: list[int] = []
-            missing_editable_fields: list[str] = []
-            for field_name in permissions.editable_fields:
-                if field_name not in field_name_to_que_id:
-                    missing_editable_fields.append(field_name)
-                else:
-                    editable_que_ids.append(field_name_to_que_id[field_name])
-            if missing_editable_fields:
-                issues.append(
-                    {
-                        "node_id": node.get("id"),
-                        "kind": "editable_fields",
-                        "error_code": "UNKNOWN_FLOW_FIELD",
-                        "missing_fields": missing_editable_fields,
-                    }
-                )
-            condition_matrix, condition_issues = _build_flow_condition_matrix(
-                current_fields_by_name=field_name_to_field,
-                node=normalized_node,
-            )
-            issues.extend({**issue, "node_id": node.get("id")} for issue in condition_issues)
-            config_payload = deepcopy(normalized_node.get("config") or {}) if isinstance(normalized_node.get("config"), dict) else {}
-            if condition_matrix:
-                # Backend judge nodes persist branch conditions from `autoJudges`.
-                # Keep the legacy mirror key for internal verification logic.
-                config_payload["autoJudges"] = condition_matrix
-                config_payload["conditionFormatMatrix"] = condition_matrix
-            normalized_node["assignees"] = {
-                "member_uids": member_resolution["member_uids"],
-                "role_entries": role_resolution["role_entries"],
-                "include_sub_departs": assignees.include_sub_departs,
-            }
-            normalized_node["permissions"] = {
-                "editable_fields": permissions.editable_fields,
-                "editable_que_ids": editable_que_ids,
-            }
-            if config_payload:
-                normalized_node["config"] = config_payload
-            normalized_nodes.append(normalized_node)
-        return normalized_nodes, issues
 
     def _unsupported_public_flow_nodes(self, *, nodes: list[dict[str, Any]]) -> list[dict[str, Any]]:
         unsupported: list[dict[str, Any]] = []
@@ -4378,7 +4530,7 @@ class AiBuilderFacade:
                 "details": {"edit_version_no": None, "associated_item_ids_by_client_key": client_key_to_id, "readback_failed": False},
                 "request_id": None,
                 "suggested_next_call": None,
-                "noop": True,
+                "noop": False,
                 "warnings": [],
                 "verification": {"associated_resources_verified": True, "associated_resource_view_configs_verified": True, "readback_loaded": True, "published": False},
                 "verified": True,
@@ -5236,36 +5388,13 @@ class AiBuilderFacade:
         except (QingflowApiError, RuntimeError) as error:
             custom_buttons_unavailable = True
             custom_buttons = []
-            readback_errors.append(
-                {
-                    "resource": "custom_buttons",
-                    "phase": "summary",
-                    "transport_error": _transport_error_payload(_coerce_api_error(error)),
-                }
-            )
-        workflow, workflow_unavailable, workflow_read_error = self._load_workflow_result(
+        workflow_spec, workflow_unavailable = self._load_workflow_spec_snapshot(
             profile=profile,
             app_key=app_key,
             tolerate_404=True,
             tolerate_permission_restricted=True,
-            include_error=True,
         )
-        if views_read_error is not None:
-            readback_errors.append(
-                {
-                    "resource": "views",
-                    "phase": "summary",
-                    "transport_error": _transport_error_payload(views_read_error),
-                }
-            )
-        if workflow_read_error is not None:
-            readback_errors.append(
-                {
-                    "resource": "workflow",
-                    "phase": "summary",
-                    "transport_error": _transport_error_payload(workflow_read_error),
-                }
-            )
+        workflow_nodes = _extract_workflow_spec_nodes(workflow_spec)
         verification_hints = _build_verification_hints(
             tag_ids=_coerce_int_list(base_result.get("tagIds")),
             fields=parsed["fields"],
@@ -5321,7 +5450,7 @@ class AiBuilderFacade:
             charts=chart_summaries,
             associated_resources=associated_resources,
             custom_buttons=custom_buttons,
-            workflow_enabled=bool(workflow),
+            workflow_enabled=bool(workflow_nodes),
             verification_hints=verification_hints,
             form_settings={} if schema_unavailable else _form_settings_from_schema(schema_result, parsed["fields"]),
         )
@@ -5731,7 +5860,7 @@ class AiBuilderFacade:
         return result
 
     def app_get_flow(self, *, profile: str, app_key: str) -> JSONObject:
-        result = self.app_read_flow_summary(profile=profile, app_key=app_key)
+        result = self.flow_get(profile=profile, app_key=app_key)
         if result.get("status") == "success":
             result["message"] = "read app flow config"
         return result
@@ -5912,41 +6041,6 @@ class AiBuilderFacade:
             **response.model_dump(mode="json"),
         }
 
-    def app_read_flow_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        try:
-            workflow, workflow_unavailable = self._load_workflow_result(profile=profile, app_key=app_key, tolerate_404=True)
-        except (QingflowApiError, RuntimeError) as error:
-            api_error = _coerce_api_error(error)
-            return _failed_from_api_error(
-                "FLOW_READ_FAILED",
-                api_error,
-                normalized_args={"app_key": app_key},
-                details={"app_key": app_key},
-                suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
-            )
-        response = AppFlowReadResponse(
-            app_key=app_key,
-            enabled=bool(workflow),
-            nodes=_summarize_workflow_nodes(workflow),
-            transitions=[],
-        )
-        return {
-            "status": "success",
-            "error_code": None,
-            "recoverable": False,
-            "message": "read app flow summary",
-            "normalized_args": {"app_key": app_key},
-            "missing_fields": [],
-            "allowed_values": {},
-            "details": {},
-            "request_id": None,
-            "suggested_next_call": None,
-            "noop": False,
-            "warnings": [_warning("WORKFLOW_READ_UNAVAILABLE", "workflow summary readback is unavailable")] if workflow_unavailable else [],
-            "verification": {"app_exists": True, "workflow_read_unavailable": workflow_unavailable},
-            "verified": not workflow_unavailable,
-            **response.model_dump(mode="json"),
-        }
 
     def app_read_charts_summary(self, *, profile: str, app_key: str) -> JSONObject:
         try:
@@ -7399,154 +7493,6 @@ class AiBuilderFacade:
             "verification": {"field_count": len(current_names)},
         }
 
-    def app_flow_plan(self, *, profile: str, request: FlowPlanRequest) -> JSONObject:
-        nodes = [node.model_dump(mode="json") for node in request.nodes]
-        transitions = [transition.model_dump(mode="json", by_alias=True) for transition in request.transitions]
-        if request.preset is not None:
-            preset_nodes, preset_transitions = _build_flow_preset(request.preset)
-            nodes, transitions = _merge_flow_graph(
-                base_nodes=preset_nodes,
-                base_transitions=preset_transitions,
-                override_nodes=nodes,
-                override_transitions=transitions,
-            )
-        fields_result = self.app_read_fields(profile=profile, app_key=request.app_key)
-        if fields_result.get("status") == "failed":
-            return fields_result
-        current_fields = fields_result.get("fields", [])
-        normalized_nodes, resolution_issues = self._normalize_flow_nodes(profile=profile, current_fields=current_fields, nodes=nodes)
-        public_nodes = self._canonicalize_flow_nodes_for_public_output(normalized_nodes)
-        unsupported_nodes = self._unsupported_public_flow_nodes(nodes=public_nodes)
-        if unsupported_nodes:
-            return _failed(
-                "FLOW_NODE_TYPE_UNSUPPORTED",
-                "app_flow_apply currently supports only linear workflows; branch and condition nodes are disabled because the backend workflow route is not front-end stable for these node types.",
-                normalized_args={
-                    "app_key": request.app_key,
-                    "mode": str(request.mode or "replace"),
-                    "preset": request.preset.value if request.preset else None,
-                    "nodes": public_nodes,
-                    "transitions": transitions,
-                },
-                details={
-                    "unsupported_nodes": unsupported_nodes,
-                    "supported_node_types": sorted(STABLE_PUBLIC_FLOW_NODE_TYPES),
-                    "disabled_node_types": sorted(DISABLED_PUBLIC_FLOW_NODE_TYPES),
-                },
-                suggested_next_call={"tool_name": "builder_tool_contract", "arguments": {"tool_name": "app_flow_apply"}},
-            )
-        if resolution_issues:
-            first_issue = resolution_issues[0]
-            suggested_call = None
-            if first_issue.get("kind", "").startswith("role"):
-                suggested_call = {"tool_name": "role_search", "arguments": {"profile": profile, "keyword": first_issue.get("value") or ""}}
-            elif first_issue.get("kind", "").startswith("member"):
-                suggested_call = {"tool_name": "member_search", "arguments": {"profile": profile, "query": first_issue.get("value") or ""}}
-            elif first_issue.get("kind") in {"editable_fields", "condition_fields"}:
-                suggested_call = {"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": request.app_key}}
-            return _failed(
-                first_issue.get("error_code") or "FLOW_ASSIGNEE_UNRESOLVED",
-                "workflow contains unresolved assignees or field permissions",
-                normalized_args={
-                    "app_key": request.app_key,
-                    "mode": str(request.mode or "replace"),
-                    "preset": request.preset.value if request.preset else None,
-                    "nodes": public_nodes,
-                    "transitions": transitions,
-                },
-                details={"issues": resolution_issues},
-                suggested_next_call=suggested_call,
-            )
-        status_field_present = _infer_status_field_id(current_fields) is not None
-        node_types = {str(node.get("type") or "") for node in normalized_nodes}
-        assignee_required_nodes = [
-            node.get("id")
-            for node in normalized_nodes
-            if str(node.get("type") or "") in {"approve", "fill", "copy"}
-            and not (
-                (node.get("assignees") or {}).get("role_entries")
-                or (node.get("assignees") or {}).get("member_uids")
-            )
-        ]
-        if assignee_required_nodes:
-            return _failed(
-                "FLOW_ASSIGNEE_REQUIRED",
-                "workflow approval/fill/copy nodes must declare at least one role or member assignee",
-                normalized_args={
-                    "app_key": request.app_key,
-                    "mode": str(request.mode or "replace"),
-                    "preset": request.preset.value if request.preset else None,
-                    "nodes": public_nodes,
-                    "transitions": transitions,
-                },
-                details={"node_ids": assignee_required_nodes, "policy": "prefer role assignees; explicit members are also supported"},
-                suggested_next_call={"tool_name": "role_search", "arguments": {"profile": profile, "keyword": ""}},
-            )
-        workflow = _build_public_workflow_spec(nodes=normalized_nodes, transitions=transitions)
-        if workflow.get("status") == "failed":
-            workflow["normalized_args"] = {
-                "app_key": request.app_key,
-                "mode": str(request.mode or "replace"),
-                "nodes": public_nodes,
-                "transitions": transitions,
-            }
-            workflow["suggested_next_call"] = {
-                "tool_name": "app_flow_plan",
-                "arguments": {
-                    "profile": profile,
-                    "app_key": request.app_key,
-                    "mode": "replace",
-                    "nodes": public_nodes,
-                    "transitions": transitions,
-                },
-            }
-            return workflow
-        if ("approve" in node_types or request.preset in {FlowPreset.basic_approval, FlowPreset.basic_fill_then_approve}) and not status_field_present:
-            return _failed(
-                "FLOW_DEPENDENCY_MISSING",
-                "workflow requires an explicit status field",
-                normalized_args={
-                    "app_key": request.app_key,
-                    "mode": str(request.mode or "replace"),
-                    "nodes": public_nodes,
-                    "transitions": transitions,
-                },
-                details={"missing_dependencies": ["status field"]},
-                missing_fields=["status"],
-                suggested_next_call={
-                    "tool_name": "app_schema_apply",
-                    "arguments": {
-                        "profile": profile,
-                        "app_key": request.app_key,
-                        "create_if_missing": False,
-                        "add_fields": [{"name": "状态", "type": "single_select", "options": ["草稿", "进行中", "已完成"], "required": True}],
-                        "update_fields": [],
-                        "remove_fields": [],
-                    },
-                },
-            )
-        normalized_args = {
-            "app_key": request.app_key,
-            "mode": str(request.mode or "replace"),
-            "nodes": public_nodes,
-            "transitions": transitions,
-        }
-        return {
-            "status": "success",
-            "error_code": None,
-            "recoverable": False,
-            "message": "planned workflow patch",
-            "normalized_args": normalized_args,
-            "missing_fields": [],
-            "allowed_values": {"presets": [preset.value for preset in FlowPreset]},
-            "details": {},
-            "request_id": None,
-            "flow_diff_preview": {"mode": "replace", "node_count": len([node for node in nodes if node.get("type") != "end"])},
-            "dependency_issues": [],
-            "suggested_next_call": {"tool_name": "app_flow_apply", "arguments": {"profile": profile, **normalized_args}},
-            "noop": False,
-            "verification": {"status_field_present": status_field_present},
-        }
 
     def app_views_plan(self, *, profile: str, request: ViewsPlanRequest) -> JSONObject:
         fields_result = self.app_read_fields(profile=profile, app_key=request.app_key)
@@ -7839,8 +7785,9 @@ class AiBuilderFacade:
             "form_settings": _form_settings_from_schema(schema_result, parsed["fields"]),
             "layout": parsed["layout"],
             "flow_summary": {
-                "enabled": bool(state["workflow"]),
-                "nodes": _summarize_workflow_nodes(state["workflow"]),
+                "enabled": bool(_extract_workflow_spec_nodes(state["workflow_spec"])),
+                "nodes": _summarize_workflow_spec_nodes(_extract_workflow_spec_nodes(state["workflow_spec"])),
+                "source": "workflow_spec",
             },
             "views_summary": {
                 "views": _summarize_views(state["views"]),
@@ -7851,7 +7798,7 @@ class AiBuilderFacade:
                 "base": base_result,
                 "schema": schema_result,
                 "views": state["views"],
-                "workflow": state["workflow"],
+                "workflow_spec": state["workflow_spec"],
             }
         return response
 
@@ -8266,7 +8213,16 @@ class AiBuilderFacade:
         relation_field_count = _count_relation_fields(current_fields)
         relation_limit_verified = relation_field_count <= 1
         relation_warnings = (
-            [_warning("RELATION_FIELD_LIMIT_RISK", "multiple relation fields are not a stable backend capability", relation_field_count=relation_field_count)]
+            [
+                _warning(
+                    "RELATION_FIELD_LIMIT_RISK",
+                    "multiple relation fields were written and verified, but this backend capability can be unstable; do not downgrade to text unless the write fails or relation readback mismatches",
+                    severity="warning",
+                    relation_field_count=relation_field_count,
+                    relation_fields_created=True,
+                    do_not_downgrade_to_text_unless_apply_failed=True,
+                )
+            ]
             if not relation_limit_verified
             else []
         )
@@ -8397,6 +8353,8 @@ class AiBuilderFacade:
                         "app_key": target.app_key,
                         "field_diff": {"added": added, "updated": updated, "removed": removed},
                         "relation_field_count": relation_field_count,
+                        "relation_fields_created": False,
+                        "recommended_modeling_fallback": "Keep the primary relation field as relation; use text/reference summary fields only for secondary cross-object links, and report the downgrade as partial.",
                         "transport_error": {
                             "http_status": api_error.http_status,
                             "backend_code": api_error.backend_code,
@@ -9041,228 +8999,19 @@ class AiBuilderFacade:
         *,
         profile: str,
         app_key: str,
-        nodes: list[dict[str, Any]],
-        transitions: list[dict[str, Any]],
-        mode: str = "replace",
+        spec: dict[str, Any],
         publish: bool = True,
+        idempotency_key: str | None = None,
+        schema_version: str | None = None,
     ) -> JSONObject:
-        normalized_args = {
-            "app_key": app_key,
-            "mode": mode,
-            "nodes": nodes,
-            "transitions": transitions,
-            "publish": publish,
-        }
-        permission_outcomes: list[PermissionCheckOutcome] = []
-        permission_outcome = self._guard_app_permission(
+        return self.flow_apply(
             profile=profile,
             app_key=app_key,
-            required_permission="edit_app",
-            normalized_args=normalized_args,
+            spec=spec,
+            publish=publish,
+            idempotency_key=idempotency_key,
+            schema_version=schema_version,
         )
-        if permission_outcome.block is not None:
-            return permission_outcome.block
-        permission_outcomes.append(permission_outcome)
-
-        def finalize(response: JSONObject) -> JSONObject:
-            return _apply_permission_outcomes(response, *permission_outcomes)
-
-        if mode != "replace":
-            return finalize(_failed(
-                "UNSUPPORTED_FLOW_MODE",
-                "only mode='replace' is supported",
-                normalized_args=normalized_args,
-                allowed_values={"modes": ["replace"]},
-                suggested_next_call={"tool_name": "app_flow_apply", "arguments": {"profile": profile, **normalized_args}},
-            ))
-        try:
-            base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
-            schema, _schema_source = self._read_schema_with_fallback(profile=profile, app_key=app_key)
-        except (QingflowApiError, RuntimeError) as error:
-            api_error = _coerce_api_error(error)
-            return finalize(_failed_from_api_error(
-                "FLOW_READ_FAILED",
-                api_error,
-                normalized_args=normalized_args,
-                details=_with_state_read_blocked_details({"app_key": app_key}, resource="workflow", error=api_error),
-                suggested_next_call={"tool_name": "app_get_flow", "arguments": {"profile": profile, "app_key": app_key}},
-            ))
-        app_name = str(base.get("formTitle") or base.get("title") or base.get("appName") or app_key).strip() or app_key
-        entity = _entity_spec_from_app(base_info=base, schema=schema, views=None)
-        current_fields = _parse_schema(schema)["fields"]
-        normalized_nodes, resolution_issues = self._normalize_flow_nodes(profile=profile, current_fields=current_fields, nodes=nodes)
-        public_nodes = self._canonicalize_flow_nodes_for_public_output(normalized_nodes)
-        unsupported_nodes = self._unsupported_public_flow_nodes(nodes=public_nodes)
-        normalized_args["nodes"] = public_nodes
-        if unsupported_nodes:
-            return _failed(
-                "FLOW_NODE_TYPE_UNSUPPORTED",
-                "app_flow_apply currently supports only linear workflows; branch and condition nodes are disabled because the backend workflow route is not front-end stable for these node types.",
-                normalized_args=normalized_args,
-                details={
-                    "unsupported_nodes": unsupported_nodes,
-                    "supported_node_types": sorted(STABLE_PUBLIC_FLOW_NODE_TYPES),
-                    "disabled_node_types": sorted(DISABLED_PUBLIC_FLOW_NODE_TYPES),
-                },
-                suggested_next_call={"tool_name": "builder_tool_contract", "arguments": {"tool_name": "app_flow_apply"}},
-            )
-        if resolution_issues:
-            first_issue = resolution_issues[0]
-            suggested_call = None
-            if first_issue.get("kind", "").startswith("role"):
-                suggested_call = {"tool_name": "role_search", "arguments": {"profile": profile, "keyword": first_issue.get("value") or ""}}
-            elif first_issue.get("kind", "").startswith("member"):
-                suggested_call = {"tool_name": "member_search", "arguments": {"profile": profile, "query": first_issue.get("value") or ""}}
-            elif first_issue.get("kind") in {"editable_fields", "condition_fields"}:
-                suggested_call = {"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": app_key}}
-            return _failed(
-                first_issue.get("error_code") or "FLOW_ASSIGNEE_UNRESOLVED",
-                "workflow contains unresolved assignees or field permissions",
-                normalized_args=normalized_args,
-                details={"issues": resolution_issues},
-                suggested_next_call=suggested_call,
-            )
-        assignee_required_nodes = [
-            node.get("id")
-            for node in normalized_nodes
-            if str(node.get("type") or "") in {"approve", "fill", "copy"}
-            and not (
-                (node.get("assignees") or {}).get("role_entries")
-                or (node.get("assignees") or {}).get("member_uids")
-            )
-        ]
-        if assignee_required_nodes:
-            return _failed(
-                "FLOW_ASSIGNEE_REQUIRED",
-                "workflow approval/fill/copy nodes must declare at least one role or member assignee",
-                normalized_args=normalized_args,
-                details={"node_ids": assignee_required_nodes, "policy": "prefer role assignees; explicit members are also supported"},
-                suggested_next_call={"tool_name": "role_search", "arguments": {"profile": profile, "keyword": ""}},
-            )
-        workflow_spec = _build_public_workflow_spec(nodes=normalized_nodes, transitions=transitions)
-        if workflow_spec.get("status") == "failed":
-            workflow_spec["normalized_args"] = normalized_args
-            workflow_spec.setdefault("request_id", None)
-            workflow_spec["suggested_next_call"] = {"tool_name": "app_flow_apply", "arguments": {"profile": profile, **normalized_args}}
-            return workflow_spec
-        desired_node_count = len([node for node in normalized_nodes if node.get("type") != "end"])
-        build_id = f"facade-flow-{uuid4().hex[:12]}"
-        previous_build_home = os.getenv("QINGFLOW_MCP_BUILD_HOME")
-        temporary_build_home: str | None = None
-        if previous_build_home is None:
-            temporary_build_home = tempfile.mkdtemp(prefix="qingflow-mcp-build-", dir="/tmp")
-            os.environ["QINGFLOW_MCP_BUILD_HOME"] = temporary_build_home
-        try:
-            assembly = BuildAssemblyStore.open(build_id=build_id, create=True)
-            manifest = default_manifest()
-            manifest["solution_name"] = base.get("formTitle") or app_key
-            manifest["preferences"]["create_package"] = False
-            manifest["preferences"]["create_portal"] = False
-            manifest["preferences"]["create_navigation"] = False
-            manifest["entities"] = [entity]
-            assembly.set_manifest(manifest)
-            artifacts = default_artifacts()
-            artifacts["apps"][entity["entity_id"]] = {"app_key": app_key}
-            assembly.set_artifacts(artifacts)
-            flow_stage_spec = {
-                "solution_name": manifest["solution_name"],
-                "entities": [{"entity_id": entity["entity_id"], "workflow": workflow_spec["workflow"]}],
-            }
-            assembly.set_stage_spec("app_flow", flow_stage_spec)
-            stage = self.solutions.solution_build_flow(
-                profile=profile,
-                mode="apply",
-                build_id=build_id,
-                flow_spec=flow_stage_spec,
-                publish=False,
-                run_label=None,
-                repair_patch={},
-            )
-        finally:
-            if previous_build_home is None:
-                os.environ.pop("QINGFLOW_MCP_BUILD_HOME", None)
-        if stage.get("status") != "success":
-            failed = _normalize_flow_stage_failure(stage, profile=profile, app_key=app_key, entity=entity)
-            failed["normalized_args"] = normalized_args
-            suggested_next_call = failed.get("suggested_next_call")
-            if not isinstance(suggested_next_call, dict):
-                suggested_next_call = {"tool_name": "app_flow_apply", "arguments": {"profile": profile, **normalized_args}}
-            elif suggested_next_call.get("tool_name") == "app_flow_plan":
-                arguments = suggested_next_call.get("arguments")
-                if not isinstance(arguments, dict):
-                    arguments = {}
-                arguments.setdefault("profile", profile)
-                arguments.setdefault("app_key", app_key)
-                arguments.setdefault("mode", mode)
-                arguments.setdefault("nodes", public_nodes)
-                arguments.setdefault("transitions", transitions)
-                suggested_next_call["tool_name"] = "app_flow_apply"
-                suggested_next_call["arguments"] = arguments
-            failed["suggested_next_call"] = suggested_next_call
-            return finalize(failed)
-        verified_nodes, verified_nodes_unavailable = self._load_workflow_result(profile=profile, app_key=app_key, tolerate_404=True)
-        workflow_structure_verified = bool(verified_nodes) and _workflow_nodes_semantically_equal(
-            current_workflow=verified_nodes,
-            requested_nodes=normalized_nodes,
-        )
-        branch_structure_verified = bool(verified_nodes) and _workflow_branch_structure_verified(
-            current_workflow=verified_nodes,
-            requested_nodes=normalized_nodes,
-        )
-        workflow_verified = workflow_structure_verified and branch_structure_verified
-        warnings: list[dict[str, Any]] = []
-        if verified_nodes_unavailable:
-            status = "partial_success"
-            error_code = "FLOW_READBACK_PENDING"
-            recoverable = True
-            message = "applied workflow patch; flow readback pending"
-            suggested_next_call = {"tool_name": "app_get_flow", "arguments": {"profile": profile, "app_key": app_key}}
-        elif workflow_verified:
-            status = "success"
-            error_code = None
-            recoverable = False
-            message = "applied workflow patch"
-            suggested_next_call = None
-        else:
-            status = "partial_success"
-            error_code = "FLOW_BRANCH_VERIFICATION_FAILED" if workflow_structure_verified and not branch_structure_verified else "FLOW_VERIFICATION_FAILED"
-            recoverable = True
-            message = (
-                "applied workflow patch; branch or condition structure did not fully verify"
-                if workflow_structure_verified and not branch_structure_verified
-                else "applied workflow patch; flow readback did not confirm the requested workflow"
-            )
-            suggested_next_call = {"tool_name": "app_get_flow", "arguments": {"profile": profile, "app_key": app_key}}
-            if not branch_structure_verified:
-                warnings.append(_warning("WORKFLOW_BRANCH_STRUCTURE_UNVERIFIED", "branch or condition structure was written, but MCP could not fully verify downstream lane structure"))
-        response = {
-            "status": status,
-            "error_code": error_code,
-            "recoverable": recoverable,
-            "message": message,
-            "normalized_args": normalized_args,
-            "missing_fields": [],
-            "allowed_values": {"modes": ["replace"]},
-            "details": {},
-            "request_id": None,
-            "suggested_next_call": suggested_next_call,
-            "noop": False,
-            "warnings": warnings,
-            "verification": {
-                "workflow_verified": workflow_verified,
-                "workflow_structure_verified": workflow_structure_verified,
-                "branch_structure_verified": branch_structure_verified,
-                "workflow_read_unavailable": verified_nodes_unavailable,
-            },
-            "app_key": app_key,
-            "app_name": app_name,
-            "flow_diff": {"mode": "replace", "node_count": desired_node_count},
-            "verified": workflow_verified,
-            "write_executed": True,
-            "write_succeeded": True,
-            "safe_to_retry": False,
-        }
-        return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
 
     def app_views_apply(
         self,
@@ -10154,6 +9903,12 @@ class AiBuilderFacade:
                             "backend_code": api_error.backend_code,
                             "category": api_error.category,
                         },
+                        **_view_apply_failure_diagnostics(
+                            patch=patch,
+                            current_fields_by_name=current_fields_by_name,
+                            backend_code=api_error.backend_code,
+                            operation_phase=operation_phase,
+                        ),
                     },
                 }
                 failed_views.append(failure_entry)
@@ -11224,6 +10979,56 @@ class AiBuilderFacade:
             normalized_args["upsert_charts"] = [patch.model_dump(mode="json") for patch in upsert_charts]
             normalized_args["patch_results"] = patch_results
 
+        if len(upsert_charts) > CHART_APPLY_RECOMMENDED_UPSERT_BATCH_SIZE:
+            batching_context = _chart_apply_batching_context(
+                request=request,
+                upsert_charts=upsert_charts,
+                batch_size=CHART_APPLY_RECOMMENDED_UPSERT_BATCH_SIZE,
+            )
+            first_batch = batching_context["suggested_batch_payloads"][0]
+            return finalize({
+                "status": "failed",
+                "error_code": "CHART_UPSERT_BATCH_TOO_LARGE",
+                "recoverable": True,
+                "message": (
+                    f"upsert_charts contains {len(upsert_charts)} items; split into batches of "
+                    f"{CHART_APPLY_RECOMMENDED_UPSERT_BATCH_SIZE} or fewer before writing"
+                ),
+                "normalized_args": normalized_args,
+                "missing_fields": [],
+                "allowed_values": {"chart.chart_type": [member.value for member in PublicChartType], "chart.filter.operator": [member.value for member in ViewFilterOperator]},
+                "details": batching_context,
+                "request_id": None,
+                "suggested_next_call": {"tool_name": "app_charts_apply", "arguments": {"profile": profile, **first_batch}},
+                "backend_code": None,
+                "http_status": None,
+                "noop": False,
+                "warnings": [
+                    _warning(
+                        "CHART_UPSERT_BATCH_SIZE_BLOCKED",
+                        "large chart upsert batches are blocked before write to avoid timeout and unknown write state",
+                        upsert_count=len(upsert_charts),
+                        max_upsert_count=CHART_APPLY_RECOMMENDED_UPSERT_BATCH_SIZE,
+                    )
+                ],
+                "verification": {
+                    "charts_verified": False,
+                    "readback_unavailable": False,
+                    "readback_before_retry": False,
+                    "chart_delete_readback_results": [],
+                    "chart_order_verified": True,
+                    "chart_list_source": existing_chart_list_source,
+                },
+                "app_key": app_key,
+                "app_name": app_name,
+                "chart_results": [],
+                "verified": False,
+                "write_executed": False,
+                "write_succeeded": False,
+                "safe_to_retry": True,
+                "next_action": "split_upsert_charts_and_retry",
+            })
+
         chart_results: list[dict[str, Any]] = []
         created_ids: list[str] = []
         updated_ids: list[str] = []
@@ -11510,6 +11315,15 @@ class AiBuilderFacade:
             primary_failure = failed_items[0]
             primary_error_code = str(primary_failure.get("error_code") or "").strip()
             primary_message = str(primary_failure.get("message") or "").strip()
+            retry_context = _chart_apply_retry_context(
+                request=request,
+                failed_items=failed_items,
+                created_ids=created_ids,
+                updated_ids=updated_ids,
+                removed_ids=removed_ids,
+                reordered=reordered,
+                write_executed=write_executed,
+            )
             return finalize({
                 "status": "partial_success" if successful_changes else "failed",
                 "error_code": "CHART_APPLY_PARTIAL" if successful_changes else primary_error_code or "CHART_APPLY_FAILED",
@@ -11520,6 +11334,7 @@ class AiBuilderFacade:
                 "allowed_values": {"chart.chart_type": [member.value for member in PublicChartType], "chart.filter.operator": [member.value for member in ViewFilterOperator]},
                 "details": {
                     "per_chart_results": chart_results,
+                    **retry_context,
                     **({"readback_error": _transport_error_payload(readback_error)} if readback_error is not None else {}),
                 },
                 "request_id": failed_items[0].get("request_id") or (readback_error.request_id if readback_error is not None else None),
@@ -11536,6 +11351,7 @@ class AiBuilderFacade:
                 "verification": {
                     "charts_verified": False if failed_items else verified,
                     "readback_unavailable": any_readback_unavailable,
+                    "readback_before_retry": bool(write_executed),
                     "chart_delete_readback_results": [deepcopy(item) for item in chart_results if item.get("operation") == "delete"],
                     "chart_order_verified": False if request.reorder_chart_ids else True,
                     "chart_list_source": readback_list_source or existing_chart_list_source,
@@ -11546,6 +11362,7 @@ class AiBuilderFacade:
                 "verified": False if failed_items else verified,
                 "write_executed": write_executed,
                 "write_succeeded": write_succeeded,
+                **({"write_may_have_succeeded": True, "next_action": "readback_before_retry"} if write_executed else {}),
                 "safe_to_retry": not write_executed,
             })
         result_verified = verified or noop
@@ -12376,7 +12193,7 @@ class AiBuilderFacade:
         result = legacy_normalized or normalized_views
         return (result, False, None) if include_error else (result, False)
 
-    def _load_workflow_result(
+    def _load_workflow_spec_snapshot(
         self,
         *,
         profile: str,
@@ -12386,24 +12203,34 @@ class AiBuilderFacade:
         include_error: bool = False,
     ) -> tuple[Any, bool] | tuple[Any, bool, QingflowApiError | None]:
         try:
-            workflow = self.workflows.workflow_list_nodes(profile=profile, app_key=app_key)
+            payload = self._with_backend_context(
+                profile,
+                lambda context: workflow_spec_api.fetch_spec(
+                    self.apps.backend,
+                    context,
+                    app_key=app_key,
+                ),
+            )
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
             if tolerate_404 and (
                 api_error.http_status == 404
                 or (tolerate_permission_restricted and _is_permission_restricted_api_error(api_error))
             ):
-                return ([], True, api_error) if include_error else ([], True)
+                return {}, True
             raise
-        result = workflow.get("result")
-        return (result, False, None) if include_error else (result, False)
+        return payload if isinstance(payload, dict) else {}, False
 
     def _load_app_state(self, *, profile: str, app_key: str) -> dict[str, Any]:
         state = self._load_base_schema_state(profile=profile, app_key=app_key)
         views, views_unavailable = self._load_views_result(profile=profile, app_key=app_key, tolerate_404=True)
-        workflow, workflow_unavailable = self._load_workflow_result(profile=profile, app_key=app_key, tolerate_404=True)
+        workflow_spec, workflow_unavailable = self._load_workflow_spec_snapshot(
+            profile=profile,
+            app_key=app_key,
+            tolerate_404=True,
+        )
         state["views"] = views
-        state["workflow"] = workflow
+        state["workflow_spec"] = workflow_spec
         state["views_unavailable"] = views_unavailable
         state["workflow_unavailable"] = workflow_unavailable
         return state
@@ -15682,6 +15509,155 @@ def _public_chart_filter_groups_from_qingbi_config(config: dict[str, Any]) -> li
     return groups
 
 
+def _chart_apply_retry_context(
+    *,
+    request: ChartApplyRequest,
+    failed_items: list[dict[str, Any]],
+    created_ids: list[str],
+    updated_ids: list[str],
+    removed_ids: list[str],
+    reordered: bool,
+    write_executed: bool,
+) -> dict[str, Any]:
+    failed_chart_names = [
+        str(item.get("name") or "").strip()
+        for item in failed_items
+        if str(item.get("name") or "").strip()
+    ]
+    failed_delete_ids = [
+        str(item.get("chart_id") or "").strip()
+        for item in failed_items
+        if str(item.get("operation") or "") == "delete" and str(item.get("chart_id") or "").strip()
+    ]
+    reorder_failed = any(str(item.get("operation") or "") == "reorder" for item in failed_items)
+    failed_name_set = set(failed_chart_names)
+    retry_payload: dict[str, Any] = {"app_key": request.app_key}
+    retry_upserts = [
+        patch.model_dump(mode="json", exclude_none=True)
+        for patch in request.upsert_charts
+        if patch.name in failed_name_set
+    ]
+    if retry_upserts:
+        retry_payload["upsert_charts"] = retry_upserts
+    if failed_delete_ids:
+        retry_payload["remove_chart_ids"] = failed_delete_ids
+    if reorder_failed and request.reorder_chart_ids:
+        retry_payload["reorder_chart_ids"] = list(request.reorder_chart_ids)
+    has_retry_payload = any(key in retry_payload for key in ("upsert_charts", "remove_chart_ids", "reorder_chart_ids"))
+    context: dict[str, Any] = {
+        "created_chart_ids": list(created_ids),
+        "updated_chart_ids": list(updated_ids),
+        "removed_chart_ids": list(removed_ids),
+        "failed_chart_names": failed_chart_names,
+        "failed_delete_chart_ids": failed_delete_ids,
+        "readback_first": bool(write_executed),
+        "retry_rule": (
+            "read app charts before retrying; retry only the failed chart payloads if they are still missing or unverified"
+            if write_executed
+            else "fix the failed chart payloads and retry only those items"
+        ),
+    }
+    if has_retry_payload:
+        context["suggested_retry_payload"] = retry_payload
+    return context
+
+
+def _chart_apply_batching_context(
+    *,
+    request: ChartApplyRequest,
+    upsert_charts: list[ChartUpsertPatch],
+    batch_size: int,
+) -> dict[str, Any]:
+    suggested_batch_payloads: list[dict[str, Any]] = []
+    for start in range(0, len(upsert_charts), batch_size):
+        batch = upsert_charts[start : start + batch_size]
+        suggested_batch_payloads.append(
+            {
+                "app_key": request.app_key,
+                "upsert_charts": [patch.model_dump(mode="json", exclude_none=True) for patch in batch],
+            }
+        )
+
+    followup_payload: dict[str, Any] = {"app_key": request.app_key}
+    if request.remove_chart_ids:
+        followup_payload["remove_chart_ids"] = list(request.remove_chart_ids)
+    if request.reorder_chart_ids:
+        followup_payload["reorder_chart_ids"] = list(request.reorder_chart_ids)
+    if len(followup_payload) > 1:
+        suggested_batch_payloads.append(followup_payload)
+
+    return {
+        "upsert_count": len(upsert_charts),
+        "max_upsert_count": batch_size,
+        "write_executed": False,
+        "readback_first": False,
+        "retry_rule": "run suggested_batch_payloads one at a time; do not submit the original large upsert_charts array",
+        "suggested_batch_payloads": suggested_batch_payloads,
+    }
+
+
+def _view_apply_failure_diagnostics(
+    *,
+    patch: ViewUpsertPatch,
+    current_fields_by_name: dict[str, dict[str, Any]],
+    backend_code: Any,
+    operation_phase: str,
+) -> dict[str, Any]:
+    references: list[tuple[str, str]] = []
+
+    def add_reference(name: Any, source: str) -> None:
+        text = str(name or "").strip()
+        if text:
+            references.append((text, source))
+
+    for column in patch.columns:
+        add_reference(column, "columns")
+    add_reference(patch.group_by, "group_by")
+    add_reference(patch.start_field, "start_field")
+    add_reference(patch.end_field, "end_field")
+    add_reference(patch.title_field, "title_field")
+    for rule in patch.filters:
+        add_reference(rule.field_name, "filters")
+
+    seen: set[str] = set()
+    field_entries: list[dict[str, Any]] = []
+    for field_name, source in references:
+        key = f"{field_name}\0{source}"
+        if key in seen:
+            continue
+        seen.add(key)
+        field = current_fields_by_name.get(field_name) or {}
+        field_entries.append(
+            {
+                "field_name": field_name,
+                "source": source,
+                "field_id": field.get("field_id"),
+                "que_id": field.get("que_id"),
+                "field_type": field.get("type"),
+                "que_type": field.get("que_type"),
+                "exists_in_schema": bool(field),
+            }
+        )
+    diagnostics: dict[str, Any] = {
+        "operation_phase": operation_phase,
+        "field_level_diagnostics": field_entries,
+    }
+    if backend_code_value_int(backend_code) == 40038:
+        diagnostics.update(
+            {
+                "suspected_fields": field_entries,
+                "recovery_hint": "Do not delete app fields or recreate the app. First retry the view with the smallest required columns; then add non-critical columns back one by one.",
+                "recommended_minimal_retry": {
+                    "name": patch.name,
+                    "type": patch.type.value,
+                    "columns": [field_entries[0]["field_name"]] if field_entries else [],
+                    **({"filters": [rule.model_dump(mode="json", exclude_none=True) for rule in patch.filters]} if patch.filters else {}),
+                },
+            }
+        )
+    return diagnostics
+
+
 def _public_chart_group_by_from_qingbi_config(config: dict[str, Any]) -> list[str]:
     fields: list[dict[str, Any]] = []
     for key in ("selectedDimensions", "xDimensions", "yDimensions", "selectedTime"):
@@ -20236,30 +20212,6 @@ def _build_layout_preset_sections(*, preset: LayoutPreset, field_names: list[str
     return sections
 
 
-def _build_flow_preset(preset: FlowPreset) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
-    if preset == FlowPreset.basic_fill_then_approve:
-        nodes = [
-            {"id": "start", "type": "start", "name": "发起"},
-            {"id": "fill_1", "type": "fill", "name": "补充信息"},
-            {"id": "approve_1", "type": "approve", "name": "审批"},
-            {"id": "end", "type": "end", "name": "结束"},
-        ]
-        transitions = [
-            {"from": "start", "to": "fill_1"},
-            {"from": "fill_1", "to": "approve_1"},
-            {"from": "approve_1", "to": "end"},
-        ]
-        return nodes, transitions
-    nodes = [
-        {"id": "start", "type": "start", "name": "发起"},
-        {"id": "approve_1", "type": "approve", "name": "审批"},
-        {"id": "end", "type": "end", "name": "结束"},
-    ]
-    transitions = [
-        {"from": "start", "to": "approve_1"},
-        {"from": "approve_1", "to": "end"},
-    ]
-    return nodes, transitions
 
 
 def _merge_flow_graph(
@@ -22114,144 +22066,35 @@ def _apply_row_widths(row: list[dict[str, Any]]) -> None:
         question["queWidth"] = width + (1 if index < remainder else 0)
 
 
-def _summarize_workflow_nodes(result: Any) -> list[dict[str, Any]]:
-    nodes = []
-    if isinstance(result, dict):
-        iterable = result.values()
-    elif isinstance(result, list):
-        iterable = result
-    else:
-        iterable = []
-    for item in iterable:
-        if not isinstance(item, dict):
-            continue
-        node_id = _coerce_positive_int(item.get("auditNodeId"))
-        name = item.get("auditNodeName")
-        if node_id is None or not name:
-            continue
-        nodes.append({"id": node_id, "name": name, "type": item.get("type"), "deal_type": item.get("dealType")})
-    return nodes
-
-
-def _workflow_node_iterable(result: Any) -> list[dict[str, Any]]:
-    if isinstance(result, dict):
-        iterable = result.values()
-    elif isinstance(result, list):
-        iterable = result
-    else:
-        iterable = []
-    return [item for item in iterable if isinstance(item, dict)]
-
-
-def _workflow_condition_matrix_value(node: dict[str, Any]) -> list[Any]:
-    config = node.get("config")
-    if isinstance(config, dict):
-        matrix = config.get("autoJudges")
-        if isinstance(matrix, list):
-            return deepcopy(matrix)
-        matrix = config.get("conditionFormatMatrix")
-        if isinstance(matrix, list):
-            return deepcopy(matrix)
-    matrix = node.get("autoJudges")
-    if isinstance(matrix, list):
-        return deepcopy(matrix)
-    matrix = node.get("conditionFormatMatrix")
-    if isinstance(matrix, list):
-        return deepcopy(matrix)
+def _extract_workflow_spec_nodes(payload: Any) -> list[dict[str, Any]]:
+    if not isinstance(payload, dict):
+        return []
+    spec = payload.get("spec")
+    if isinstance(spec, dict):
+        nodes = spec.get("nodes")
+        if isinstance(nodes, list):
+            return [item for item in nodes if isinstance(item, dict)]
+    nodes = payload.get("nodes")
+    if isinstance(nodes, list):
+        return [item for item in nodes if isinstance(item, dict)]
     return []
 
 
-def _workflow_branch_structure_verified(*, current_workflow: Any, requested_nodes: list[dict[str, Any]]) -> bool:
-    requested_branch_like = [
-        node
-        for node in requested_nodes
-        if str(node.get("type") or "").strip().lower() in {"branch", "condition"}
-    ]
-    if not requested_branch_like:
-        return True
-    actual_nodes = _workflow_node_iterable(current_workflow)
-    actual_branch_like = [
-        node
-        for node in actual_nodes
-        if _normalize_existing_workflow_node_type(node.get("type"), node.get("dealType")) in {"branch", "condition"}
-    ]
-    if len(actual_branch_like) < len(requested_branch_like):
-        return False
-    actual_condition_nodes = [
-        node
-        for node in actual_nodes
-        if _normalize_existing_workflow_node_type(node.get("type"), node.get("dealType")) == "condition"
-    ]
-    for requested in requested_branch_like:
-        if str(requested.get("type") or "").strip().lower() != "condition":
-            continue
-        expected_matrix = _workflow_condition_matrix_value(requested)
-        if not expected_matrix:
+def _summarize_workflow_spec_nodes(spec_nodes: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    summaries: list[dict[str, Any]] = []
+    for item in spec_nodes:
+        node_id = str(item.get("id") or "").strip()
+        name = str(item.get("name") or "").strip()
+        if not node_id and not name:
             continue
-        requested_name = str(requested.get("name") or "").strip()
-        match = next(
-            (
-                node
-                for node in actual_condition_nodes
-                if str(node.get("auditNodeName") or node.get("nodeName") or "").strip() == requested_name
-            ),
-            None,
-        )
-        if match is None or not _workflow_condition_matrix_value(match):
-            return False
-    return True
-
-
-def _workflow_nodes_semantically_equal(*, current_workflow: Any, requested_nodes: list[dict[str, Any]]) -> bool:
-    current_nodes = _summarize_workflow_nodes(current_workflow)
-    current_effective = [
-        node
-        for node in current_nodes
-        if _normalize_existing_workflow_node_type(node.get("type"), node.get("deal_type")) not in {"start", "end"}
-    ]
-    requested_effective = [
-        node for node in requested_nodes if str(node.get("type") or "") not in {"start", "end"}
-    ]
-    if not current_effective or not requested_effective or len(current_effective) != len(requested_effective):
-        return False
-    current_signatures = sorted(
-        (
-            _normalize_existing_workflow_node_type(node.get("type"), node.get("deal_type")),
-            str(node.get("name") or "").strip(),
-        )
-        for node in current_effective
-    )
-    requested_signatures = sorted(
-        (
-            str(node.get("type") or "").strip().lower(),
-            str(node.get("name") or "").strip(),
+        summaries.append(
+            {
+                "id": node_id or None,
+                "name": name or None,
+                "type": item.get("type"),
+            }
         )
-        for node in requested_effective
-    )
-    return current_signatures == requested_signatures
-
-
-def _normalize_existing_workflow_node_type(raw_type: Any, deal_type: Any) -> str:
-    normalized = "" if raw_type is None else str(raw_type).strip().lower()
-    if normalized in {"audit", "approve"}:
-        return "approve"
-    if normalized in {"fill", "copy", "branch", "condition", "webhook", "start", "end"}:
-        return normalized
-    if normalized in {"1"}:
-        return "branch"
-    if normalized in {"2"}:
-        return "condition"
-    if normalized in {"3"} or deal_type == 10:
-        return "webhook"
-    if normalized in {"0"} and deal_type == 0:
-        return "approve"
-    if normalized in {"0"} and deal_type == 1:
-        return "fill"
-    if normalized in {"0"} and deal_type == 2:
-        return "copy"
-    if normalized in {"0"} or deal_type == 3:
-        return "start"
-    return normalized or "unknown"
+    return summaries
 
 
 def _summarize_views(result: Any) -> list[dict[str, Any]]:
@@ -23449,98 +23292,6 @@ def _field_id_for_name(fields: list[dict[str, Any]], name: str) -> str:
     raise KeyError(name)
 
 
-def _build_public_workflow_spec(*, nodes: list[dict[str, Any]], transitions: list[dict[str, Any]]) -> JSONObject:
-    node_map = {str(node.get("id") or ""): node for node in nodes if isinstance(node, dict) and node.get("id")}
-    if not node_map:
-        return _failed("INVALID_FLOW", "nodes must be a non-empty list", suggested_next_call=None)
-    start_nodes = [node_id for node_id, node in node_map.items() if node.get("type") == "start"]
-    if len(start_nodes) != 1:
-        return _failed("INVALID_FLOW", "flow must contain exactly one start node", suggested_next_call=None)
-    inbound: dict[str, list[str]] = {node_id: [] for node_id in node_map}
-    outbound: dict[str, list[str]] = {node_id: [] for node_id in node_map}
-    for transition in transitions:
-        if not isinstance(transition, dict):
-            continue
-        source = str(transition.get("from") or "")
-        target = str(transition.get("to") or "")
-        if source not in node_map or target not in node_map:
-            return _failed("INVALID_FLOW_EDGE", "transition references unknown node", details={"transition": transition}, suggested_next_call=None)
-        outbound[source].append(target)
-        inbound[target].append(source)
-    branch_lane_nodes: dict[str, dict[str, Any]] = {}
-    for node_id, node in node_map.items():
-        if str(node.get("type") or "") != "condition":
-            continue
-        if len(inbound[node_id]) != 1:
-            return _failed(
-                "INVALID_FLOW_EDGE",
-                f"condition lane '{node_id}' must have exactly one inbound transition",
-                details={"node_id": node_id, "inbound": inbound[node_id]},
-                suggested_next_call=None,
-            )
-        parent_id = inbound[node_id][0]
-        if node_map[parent_id].get("type") != "branch":
-            continue
-        branch_lane_nodes[node_id] = {
-            "branch_parent_id": parent_id,
-            "branch_index": outbound[parent_id].index(node_id) + 1,
-        }
-    internal_nodes = []
-    for node_id, node in node_map.items():
-        node_type = str(node.get("type") or "")
-        if node_type == "end":
-            continue
-        if node_type != "start" and len(inbound[node_id]) != 1:
-            return _failed(
-                "INVALID_FLOW_EDGE",
-                f"node '{node_id}' must have exactly one inbound transition",
-                details={"node_id": node_id, "inbound": inbound[node_id]},
-                suggested_next_call=None,
-            )
-        config_payload = deepcopy(node.get("config") or {}) if isinstance(node.get("config"), dict) else {}
-        assignees = node.get("assignees") or {}
-        if node_id in branch_lane_nodes:
-            lane_meta = branch_lane_nodes[node_id]
-            config_payload["__lane_only__"] = True
-            payload = {
-                "node_id": f"__branch_lane__{lane_meta['branch_parent_id']}__{lane_meta['branch_index']}",
-                "name": node.get("name") or node_id,
-                "node_type": "condition",
-                "parent_node_id": lane_meta["branch_parent_id"],
-                "branch_parent_id": lane_meta["branch_parent_id"],
-                "branch_index": lane_meta["branch_index"],
-            }
-        else:
-            payload = {
-                "node_id": node_id,
-                "name": node.get("name") or node_id,
-                "node_type": "audit" if node_type == "approve" else node_type,
-            }
-            if node_type != "start":
-                parent_id = inbound[node_id][0]
-                lane_parent = branch_lane_nodes.get(parent_id)
-                if lane_parent is not None:
-                    payload["parent_node_id"] = lane_parent["branch_parent_id"]
-                    payload["branch_parent_id"] = lane_parent["branch_parent_id"]
-                    payload["branch_index"] = lane_parent["branch_index"]
-                else:
-                    payload["parent_node_id"] = parent_id
-                    if node_map[parent_id].get("type") == "branch":
-                        payload["branch_parent_id"] = parent_id
-                        payload["branch_index"] = outbound[parent_id].index(node_id) + 1
-        permissions = node.get("permissions") or {}
-        editable_que_ids = permissions.get("editable_que_ids") or []
-        if editable_que_ids:
-            config_payload["editableQueIds"] = editable_que_ids
-        if config_payload:
-            payload["config"] = config_payload
-        if assignees:
-            payload["assignees"] = deepcopy(assignees)
-        internal_nodes.append(payload)
-    return {
-        "status": "success",
-        "workflow": {"enabled": True, "nodes": internal_nodes},
-    }
 
 
 def _build_flow_condition_matrix(
@@ -23737,6 +23488,9 @@ def _resolve_query_condition_field(
                 "field": raw,
                 "parent_field": subfield_parent.get("name"),
                 "message": "subtable subfields cannot be used as view query conditions",
+                "fix_hint": QUERY_CONDITION_FIX_HINT,
+                "supported_field_types": QUERY_CONDITION_SUPPORTED_FIELD_TYPES_PUBLIC,
+                "unsupported_field_types": QUERY_CONDITION_UNSUPPORTED_FIELD_TYPES_PUBLIC,
             }
         return {}, {
             "error_code": "QUERY_CONDITION_FIELD_NOT_FOUND",
@@ -23753,6 +23507,9 @@ def _resolve_query_condition_field(
             "field": field.get("name"),
             "field_type": field_type,
             "message": "this field type is not supported by the frontend query condition panel",
+            "fix_hint": QUERY_CONDITION_FIX_HINT,
+            "supported_field_types": QUERY_CONDITION_SUPPORTED_FIELD_TYPES_PUBLIC,
+            "unsupported_field_types": QUERY_CONDITION_UNSUPPORTED_FIELD_TYPES_PUBLIC,
         }
     que_id = _coerce_positive_int(field.get("que_id"))
     if que_id is None:
@@ -23762,6 +23519,8 @@ def _resolve_query_condition_field(
             "missing_fields": [],
             "field": field.get("name"),
             "message": "query condition field has no backend queId",
+            "fix_hint": QUERY_CONDITION_FIX_HINT,
+            "supported_field_types": QUERY_CONDITION_SUPPORTED_FIELD_TYPES_PUBLIC,
         }
     return field, None
 
@@ -25638,92 +25397,6 @@ def _infer_status_field_id(fields: list[dict[str, Any]]) -> str | None:
     return None
 
 
-def _normalize_flow_stage_failure(stage: JSONObject, *, profile: str, app_key: str, entity: dict[str, Any]) -> JSONObject:
-    stage_error_code = str(stage.get("error_code") or "FLOW_APPLY_FAILED")
-    detail_text = _extract_stage_failure_text(stage)
-    request_id = stage.get("request_id")
-    backend_code = stage.get("backend_code")
-    http_status = stage.get("http_status")
-    public_stage_result = _public_stage_result(stage)
-    if request_id is None and isinstance(public_stage_result.get("errors"), list) and public_stage_result["errors"]:
-        first_error = public_stage_result["errors"][0]
-        if isinstance(first_error, dict):
-            request_id = first_error.get("request_id")
-            backend_code = first_error.get("backend_code")
-            http_status = first_error.get("http_status")
-    lowered_detail = detail_text.lower()
-    if "must declare status field" in detail_text:
-        return _failed(
-            "STATUS_FIELD_REQUIRED",
-            detail_text,
-            details={
-                "app_key": app_key,
-                "entity_id": entity.get("entity_id"),
-                "existing_fields": entity.get("fields") or [],
-                "stage_result": public_stage_result,
-            },
-            suggested_next_call={
-                "tool_name": "app_schema_apply",
-                "arguments": {
-                    "profile": profile,
-                    "app_key": app_key,
-                    "create_if_missing": False,
-                    "add_fields": [
-                        {
-                            "name": "状态",
-                            "type": "single_select",
-                            "options": ["草稿", "进行中", "已完成"],
-                            "required": True,
-                        }
-                    ],
-                    "update_fields": [],
-                    "remove_fields": [],
-                },
-            },
-            request_id=request_id,
-            backend_code=backend_code,
-            http_status=http_status,
-        )
-    if (
-        "run solution_build_app first" in lowered_detail
-        or "run solution_build_app_flow first" in lowered_detail
-        or ("is not defined yet" in lowered_detail and "solution_build_" in lowered_detail)
-    ):
-        return _failed(
-            "FLOW_STAGE_CONTEXT_MISSING",
-            "workflow apply lost the app context required by the internal flow builder",
-            details={
-                "app_key": app_key,
-                "entity_id": entity.get("entity_id"),
-                "existing_fields": entity.get("fields") or [],
-                "internal_detail": detail_text,
-                "stage_result": public_stage_result,
-            },
-            suggested_next_call={"tool_name": "app_flow_plan", "arguments": {"profile": profile, "app_key": app_key}},
-            request_id=request_id,
-            backend_code=backend_code,
-            http_status=http_status,
-        )
-    message = detail_text or "failed to apply workflow patch"
-    details = {"app_key": app_key, "entity_id": entity.get("entity_id"), "stage_result": public_stage_result}
-    public_http_status = http_status
-    if http_status == 404:
-        message = "workflow write route is unavailable for this app in the current route"
-        details["transport_error"] = {
-            "http_status": http_status,
-            "backend_code": backend_code,
-            "category": "http",
-        }
-        public_http_status = None
-    return _failed(
-        stage_error_code,
-        message,
-        details=details,
-        suggested_next_call={"tool_name": "app_flow_plan", "arguments": {"profile": profile, "app_key": app_key}},
-        request_id=request_id,
-        backend_code=backend_code,
-        http_status=public_http_status,
-    )
 
 
 def _extract_stage_failure_text(stage: JSONObject) -> str: