@josephyan/qingflow-app-user-mcp 0.2.0-beta.2 → 0.2.0-beta.21

package/src/qingflow_mcp/builder_facade/service.py

@@ -4,6 +4,7 @@ from copy import deepcopy
 from dataclasses import dataclass
 import json
 import os
+import re
 import tempfile
 from typing import Any
 from uuid import uuid4
@@ -17,7 +18,9 @@ from ..solution.compiler.view_compiler import VIEW_TYPE_MAP
 from ..solution.executor import extract_field_map, _build_viewgraph_questions
 from ..solution.spec_models import FieldType, FormLayoutRowSpec, FormLayoutSectionSpec, ViewSpec
 from ..tools.app_tools import AppTools
+from ..tools.directory_tools import DirectoryTools
 from ..tools.package_tools import PackageTools
+from ..tools.role_tools import RoleTools
 from ..tools.solution_tools import SolutionTools
 from ..tools.view_tools import ViewTools
 from ..tools.workflow_tools import WorkflowTools
@@ -32,16 +35,20 @@ from .models import (
     FieldSelector,
     FieldUpdatePatch,
     FlowPlanRequest,
+    FlowAssigneePatch,
     LayoutApplyMode,
     LayoutPlanRequest,
     LayoutSectionPatch,
     LayoutPreset,
     PublicFieldType,
+    PublicViewType,
     SchemaPlanRequest,
     ViewUpsertPatch,
+    ViewFilterOperator,
     ViewsPlanRequest,
     ViewsPreset,
     FlowPreset,
+    FlowNodePermissionsPatch,
 )
 
 
@@ -63,6 +70,41 @@ QUESTION_TYPE_TO_FIELD_TYPE: dict[int, str] = {
     25: FieldType.relation.value,
 }
 
+FIELD_TYPE_TO_QUESTION_TYPE: dict[str, int] = {
+    FieldType.text.value: 2,
+    FieldType.long_text.value: 3,
+    FieldType.date.value: 4,
+    FieldType.datetime.value: 4,
+    FieldType.member.value: 5,
+    FieldType.email.value: 6,
+    FieldType.phone.value: 7,
+    FieldType.number.value: 8,
+    FieldType.amount.value: 8,
+    FieldType.boolean.value: 10,
+    FieldType.single_select.value: 11,
+    FieldType.multi_select.value: 12,
+    FieldType.attachment.value: 13,
+    FieldType.subtable.value: 18,
+    FieldType.address.value: 21,
+    FieldType.department.value: 22,
+    FieldType.relation.value: 25,
+}
+
+MATCH_TYPE_ACCURACY = 1
+JUDGE_EQUAL = 0
+JUDGE_UNEQUAL = 1
+JUDGE_GREATER_OR_EQUAL = 5
+JUDGE_LESS_OR_EQUAL = 7
+JUDGE_EQUAL_ANY = 9
+JUDGE_FUZZY_MATCH = 19
+JUDGE_INCLUDE_ANY = 20
+
+INCLUDE_ANY_FLOW_FIELD_TYPES = {
+    FieldType.multi_select.value,
+    FieldType.member.value,
+    FieldType.department.value,
+}
+
 
 @dataclass(slots=True)
 class ResolvedApp:
@@ -79,12 +121,16 @@ class AiBuilderFacade:
         packages: PackageTools,
         views: ViewTools,
         workflows: WorkflowTools,
+        roles: RoleTools,
+        directory: DirectoryTools,
         solutions: SolutionTools,
     ) -> None:
         self.apps = apps
         self.packages = packages
         self.views = views
         self.workflows = workflows
+        self.roles = roles
+        self.directory = directory
         self.solutions = solutions
 
     def package_resolve(self, *, profile: str, package_name: str) -> JSONObject:
@@ -135,6 +181,75 @@ class AiBuilderFacade:
             "match_mode": "exact",
         }
 
+    def package_create(self, *, profile: str, package_name: str) -> JSONObject:
+        requested = str(package_name or "").strip()
+        normalized_args = {"package_name": requested}
+        if not requested:
+            return _failed(
+                "PACKAGE_NAME_REQUIRED",
+                "package_name is required",
+                normalized_args=normalized_args,
+                suggested_next_call=None,
+            )
+        existing = self.package_resolve(profile=profile, package_name=requested)
+        if existing.get("status") == "success":
+            return {
+                "status": "success",
+                "error_code": None,
+                "recoverable": False,
+                "message": "package already exists",
+                "normalized_args": normalized_args,
+                "missing_fields": [],
+                "allowed_values": {},
+                "details": {},
+                "request_id": None,
+                "suggested_next_call": None,
+                "noop": True,
+                "verification": {"existing_package_reused": True},
+                "tag_id": existing.get("tag_id"),
+                "tag_name": existing.get("tag_name"),
+            }
+        if existing.get("error_code") == "AMBIGUOUS_PACKAGE":
+            return existing
+        try:
+            created = self.packages.package_create(profile=profile, payload={"tagName": requested})
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "PACKAGE_CREATE_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"package_name": requested},
+                suggested_next_call={"tool_name": "package_create", "arguments": {"profile": profile, "package_name": requested}},
+            )
+        result = created.get("result") if isinstance(created.get("result"), dict) else {}
+        tag_id = _coerce_positive_int(result.get("tagId"))
+        tag_name = str(result.get("tagName") or requested).strip() or requested
+        if tag_id is None:
+            resolved = self.package_resolve(profile=profile, package_name=requested)
+            if resolved.get("status") == "success":
+                tag_id = _coerce_positive_int(resolved.get("tag_id"))
+                tag_name = str(resolved.get("tag_name") or tag_name)
+        verified = tag_id is not None
+        return {
+            "status": "success" if verified else "partial_success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "created package" if verified else "created package but could not verify tag id",
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {},
+            "request_id": None,
+            "suggested_next_call": None
+            if verified
+            else {"tool_name": "package_resolve", "arguments": {"profile": profile, "package_name": requested}},
+            "noop": False,
+            "verification": {"tag_id_verified": verified},
+            "tag_id": tag_id,
+            "tag_name": tag_name,
+        }
+
     def package_list(self, *, profile: str, trial_status: str = "all") -> JSONObject:
         listed = self.packages.package_list(profile=profile, trial_status=trial_status, include_raw=False)
         return {
@@ -157,6 +272,465 @@ class AiBuilderFacade:
             "retried": bool(listed.get("retried", False)),
         }
 
+    def member_search(self, *, profile: str, query: str, page_num: int = 1, page_size: int = 20, contain_disable: bool = False) -> JSONObject:
+        requested = str(query or "").strip()
+        normalized_args = {
+            "query": requested,
+            "page_num": page_num,
+            "page_size": page_size,
+            "contain_disable": contain_disable,
+        }
+        if not requested:
+            return _failed("MEMBER_QUERY_REQUIRED", "query is required", normalized_args=normalized_args, suggested_next_call=None)
+        try:
+            listed = self.directory.directory_list_internal_users(
+                profile=profile,
+                keyword=requested,
+                dept_id=None,
+                role_id=None,
+                page_num=page_num,
+                page_size=page_size,
+                contain_disable=contain_disable,
+            )
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "MEMBER_SEARCH_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"query": requested},
+                suggested_next_call={"tool_name": "member_search", "arguments": {"profile": profile, **normalized_args}},
+            )
+        items = []
+        for item in _extract_directory_items(listed):
+            uid = _coerce_positive_int(item.get("uid") or item.get("id"))
+            if uid is None:
+                continue
+            items.append(
+                {
+                    "uid": uid,
+                    "name": item.get("nickName") or item.get("name") or item.get("value"),
+                    "email": item.get("email"),
+                    "dept_name": item.get("deptName") or item.get("departName"),
+                }
+            )
+        return {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "resolved members",
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {},
+            "request_id": None,
+            "suggested_next_call": None,
+            "noop": False,
+            "verification": {"count": len(items)},
+            "items": items,
+        }
+
+    def role_search(self, *, profile: str, keyword: str, page_num: int = 1, page_size: int = 20) -> JSONObject:
+        requested = str(keyword or "").strip()
+        normalized_args = {"keyword": requested, "page_num": page_num, "page_size": page_size}
+        if not requested:
+            return _failed("ROLE_QUERY_REQUIRED", "keyword is required", normalized_args=normalized_args, suggested_next_call=None)
+        try:
+            listed = self.roles.role_search(profile=profile, keyword=requested, page_num=page_num, page_size=page_size)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "ROLE_SEARCH_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"keyword": requested},
+                suggested_next_call={"tool_name": "role_search", "arguments": {"profile": profile, **normalized_args}},
+            )
+        page = listed.get("page") if isinstance(listed.get("page"), dict) else {}
+        raw_items = page.get("list") if isinstance(page.get("list"), list) else []
+        items = []
+        for item in raw_items:
+            if not isinstance(item, dict):
+                continue
+            role_id = _coerce_positive_int(item.get("roleId") or item.get("id"))
+            if role_id is None:
+                continue
+            items.append(
+                {
+                    "role_id": role_id,
+                    "role_name": item.get("roleName") or item.get("name"),
+                    "role_icon": item.get("roleIcon"),
+                }
+            )
+        return {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "resolved roles",
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {},
+            "request_id": None,
+            "suggested_next_call": None,
+            "noop": False,
+            "verification": {"count": len(items)},
+            "items": items,
+        }
+
+    def role_create(
+        self,
+        *,
+        profile: str,
+        role_name: str,
+        member_uids: list[int],
+        member_emails: list[str],
+        member_names: list[str],
+        role_icon: str = "ex-user-outlined",
+    ) -> JSONObject:
+        normalized_args = {
+            "role_name": str(role_name or "").strip(),
+            "member_uids": [uid for uid in member_uids if isinstance(uid, int) and uid > 0],
+            "member_emails": [str(email or "").strip() for email in member_emails if str(email or "").strip()],
+            "member_names": [str(name or "").strip() for name in member_names if str(name or "").strip()],
+            "role_icon": role_icon or "ex-user-outlined",
+        }
+        requested_name = normalized_args["role_name"]
+        if not requested_name:
+            return _failed("ROLE_NAME_REQUIRED", "role_name is required", normalized_args=normalized_args, suggested_next_call=None)
+        existing = self.role_search(profile=profile, keyword=requested_name, page_num=1, page_size=50)
+        if existing.get("status") == "success":
+            exact = [item for item in existing.get("items", []) if isinstance(item, dict) and item.get("role_name") == requested_name]
+            if len(exact) == 1:
+                return {
+                    "status": "success",
+                    "error_code": None,
+                    "recoverable": False,
+                    "message": "role already exists",
+                    "normalized_args": normalized_args,
+                    "missing_fields": [],
+                    "allowed_values": {},
+                    "details": {},
+                    "request_id": None,
+                    "suggested_next_call": None,
+                    "noop": True,
+                    "verification": {"existing_role_reused": True},
+                    "role_id": exact[0]["role_id"],
+                    "role_name": exact[0]["role_name"],
+                    "role_icon": exact[0].get("role_icon"),
+                }
+            if len(exact) > 1:
+                return _failed(
+                    "AMBIGUOUS_ROLE",
+                    f"multiple roles matched '{requested_name}'",
+                    normalized_args=normalized_args,
+                    details={"matches": exact},
+                    suggested_next_call={"tool_name": "role_search", "arguments": {"profile": profile, "keyword": requested_name}},
+                )
+        resolved_members = self._resolve_member_references(
+            profile=profile,
+            member_uids=normalized_args["member_uids"],
+            member_emails=normalized_args["member_emails"],
+            member_names=normalized_args["member_names"],
+        )
+        if resolved_members["issues"]:
+            first_issue = resolved_members["issues"][0]
+            return _failed(
+                "ROLE_MEMBERS_UNRESOLVED",
+                "one or more role members could not be resolved",
+                normalized_args=normalized_args,
+                details={"issues": resolved_members["issues"]},
+                suggested_next_call={"tool_name": "member_search", "arguments": {"profile": profile, "query": first_issue.get("value") or ""}},
+            )
+        try:
+            created = self.roles.role_create(
+                profile=profile,
+                payload={
+                    "roleName": requested_name,
+                    "roleIcon": normalized_args["role_icon"],
+                    "users": resolved_members["member_uids"],
+                },
+            )
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "ROLE_CREATE_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"role_name": requested_name},
+                suggested_next_call={"tool_name": "role_create", "arguments": {"profile": profile, **normalized_args}},
+            )
+        role_result = created.get("result") if isinstance(created.get("result"), dict) else {}
+        role_id = _coerce_positive_int(role_result.get("roleId") or role_result.get("id"))
+        return {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "created role",
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {},
+            "request_id": None,
+            "suggested_next_call": None,
+            "noop": False,
+            "verification": {"member_count": len(resolved_members["member_uids"])},
+            "role_id": role_id,
+            "role_name": requested_name,
+            "role_icon": normalized_args["role_icon"],
+        }
+
+    def _resolve_role_references(
+        self,
+        *,
+        profile: str,
+        role_ids: list[int],
+        role_names: list[str],
+    ) -> dict[str, Any]:
+        issues: list[dict[str, Any]] = []
+        resolved: list[dict[str, Any]] = []
+        seen_ids: set[int] = set()
+        for role_id in role_ids:
+            normalized_role_id = _coerce_positive_int(role_id)
+            if normalized_role_id is None or normalized_role_id in seen_ids:
+                continue
+            resolved.append(
+                {
+                    "roleId": normalized_role_id,
+                    "roleName": str(normalized_role_id),
+                    "roleIcon": "ex-user-outlined",
+                    "beingFrontendConfig": True,
+                }
+            )
+            seen_ids.add(normalized_role_id)
+        for role_name in role_names:
+            requested = str(role_name or "").strip()
+            if not requested:
+                continue
+            matches_result = self.role_search(profile=profile, keyword=requested, page_num=1, page_size=50)
+            items = matches_result.get("items", []) if matches_result.get("status") == "success" else []
+            exact = [item for item in items if isinstance(item, dict) and item.get("role_name") == requested]
+            if len(exact) != 1:
+                issues.append(
+                    {
+                        "kind": "role",
+                        "value": requested,
+                        "error_code": "AMBIGUOUS_ROLE" if len(exact) > 1 else "ROLE_NOT_FOUND",
+                        "matches": exact,
+                    }
+                )
+                continue
+            role_id = _coerce_positive_int(exact[0].get("role_id"))
+            if role_id is None or role_id in seen_ids:
+                continue
+            resolved.append(
+                {
+                    "roleId": role_id,
+                    "roleName": exact[0].get("role_name") or requested,
+                    "roleIcon": exact[0].get("role_icon") or "ex-user-outlined",
+                    "beingFrontendConfig": True,
+                }
+            )
+            seen_ids.add(role_id)
+        return {"role_entries": resolved, "issues": issues}
+
+    def _resolve_member_references(
+        self,
+        *,
+        profile: str,
+        member_uids: list[int],
+        member_emails: list[str],
+        member_names: list[str],
+    ) -> dict[str, Any]:
+        issues: list[dict[str, Any]] = []
+        resolved: list[dict[str, Any]] = []
+        seen_uids: set[int] = set()
+
+        def add_member(item: dict[str, Any], *, fallback_name: str | None = None) -> None:
+            uid = _coerce_positive_int(item.get("uid") or item.get("id"))
+            if uid is None or uid in seen_uids:
+                return
+            resolved.append(
+                {
+                    "uid": uid,
+                    "name": item.get("nickName") or item.get("name") or fallback_name or str(uid),
+                    "email": item.get("email"),
+                }
+            )
+            seen_uids.add(uid)
+
+        for uid in member_uids:
+            normalized_uid = _coerce_positive_int(uid)
+            if normalized_uid is not None and normalized_uid not in seen_uids:
+                add_member({"uid": normalized_uid}, fallback_name=str(normalized_uid))
+
+        for email in member_emails:
+            requested = str(email or "").strip()
+            if not requested:
+                continue
+            matches = self.member_search(profile=profile, query=requested, page_num=1, page_size=50, contain_disable=False)
+            items = matches.get("items", []) if matches.get("status") == "success" else []
+            exact = [item for item in items if isinstance(item, dict) and str(item.get("email") or "").strip().lower() == requested.lower()]
+            if len(exact) != 1:
+                issues.append(
+                    {
+                        "kind": "member_email",
+                        "value": requested,
+                        "error_code": "AMBIGUOUS_MEMBER" if len(exact) > 1 else "MEMBER_NOT_FOUND",
+                        "matches": exact,
+                    }
+                )
+                continue
+            add_member(exact[0])
+
+        for name in member_names:
+            requested = str(name or "").strip()
+            if not requested:
+                continue
+            matches = self.member_search(profile=profile, query=requested, page_num=1, page_size=50, contain_disable=False)
+            items = matches.get("items", []) if matches.get("status") == "success" else []
+            exact = [item for item in items if isinstance(item, dict) and str(item.get("name") or "").strip() == requested]
+            if len(exact) != 1:
+                issues.append(
+                    {
+                        "kind": "member_name",
+                        "value": requested,
+                        "error_code": "AMBIGUOUS_MEMBER" if len(exact) > 1 else "MEMBER_NOT_FOUND",
+                        "matches": exact,
+                    }
+                )
+                continue
+            add_member(exact[0])
+
+        return {"member_uids": [item["uid"] for item in resolved], "member_entries": resolved, "issues": issues}
+
+    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:
+                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 _canonicalize_flow_nodes_for_public_output(self, nodes: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        public_nodes: list[dict[str, Any]] = []
+        for node in nodes:
+            if not isinstance(node, dict):
+                continue
+            payload = deepcopy(node)
+            assignees = payload.get("assignees") if isinstance(payload.get("assignees"), dict) else {}
+            permissions = payload.get("permissions") if isinstance(payload.get("permissions"), dict) else {}
+            public_assignees: dict[str, Any] = {}
+            role_ids = [
+                role_id
+                for role_id in (
+                    _coerce_positive_int(entry.get("roleId"))
+                    for entry in (assignees.get("role_entries") or [])
+                    if isinstance(entry, dict)
+                )
+                if role_id is not None
+            ]
+            member_uids = [
+                member_uid
+                for member_uid in (_coerce_positive_int(value) for value in (assignees.get("member_uids") or []))
+                if member_uid is not None
+            ]
+            if role_ids:
+                public_assignees["role_ids"] = role_ids
+            if member_uids:
+                public_assignees["member_uids"] = member_uids
+            if bool(assignees.get("include_sub_departs")):
+                public_assignees["include_sub_departs"] = True
+            public_permissions: dict[str, Any] = {}
+            editable_fields = [str(name) for name in (permissions.get("editable_fields") or []) if str(name or "").strip()]
+            if editable_fields:
+                public_permissions["editable_fields"] = editable_fields
+            config_payload = payload.get("config") if isinstance(payload.get("config"), dict) else {}
+            if isinstance(config_payload, dict):
+                config_payload = deepcopy(config_payload)
+                config_payload.pop("conditionFormatMatrix", None)
+            if public_assignees:
+                payload["assignees"] = public_assignees
+            else:
+                payload.pop("assignees", None)
+            if public_permissions:
+                payload["permissions"] = public_permissions
+            else:
+                payload.pop("permissions", None)
+            if config_payload:
+                payload["config"] = config_payload
+            else:
+                payload.pop("config", None)
+            public_nodes.append(payload)
+        return public_nodes
+
     def package_attach_app(
         self,
         *,
@@ -210,6 +784,115 @@ class AiBuilderFacade:
             "attached": attached,
         }
 
+    def app_release_edit_lock_if_mine(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        lock_owner_email: str = "",
+        lock_owner_name: str = "",
+    ) -> JSONObject:
+        normalized_args = {
+            "app_key": app_key,
+            "lock_owner_email": lock_owner_email,
+            "lock_owner_name": lock_owner_name,
+        }
+        session_profile = self.apps.sessions.get_profile(profile)
+        if session_profile is None:
+            return _failed(
+                "AUTH_REQUIRED",
+                "auth profile is required before releasing an app edit lock",
+                normalized_args=normalized_args,
+                recoverable=False,
+                suggested_next_call={"tool_name": "auth_whoami", "arguments": {"profile": profile}},
+            )
+        identity = self._resolve_current_user_identity(profile=profile)
+        current_email = str(identity.get("email") or "").strip().lower()
+        current_name = str(identity.get("nick_name") or "").strip()
+        requested_owner_email = str(lock_owner_email or "").strip().lower()
+        requested_owner_name = str(lock_owner_name or "").strip()
+        if not requested_owner_email and not requested_owner_name:
+            return _failed(
+                "EDIT_LOCK_OWNER_UNKNOWN",
+                "lock owner could not be verified; refuse to release edit lock blindly",
+                normalized_args=normalized_args,
+                recoverable=False,
+                details={
+                    "current_user_email": identity.get("email"),
+                    "current_user_name": identity.get("nick_name"),
+                },
+                suggested_next_call=None,
+            )
+        owner_matches = True
+        if requested_owner_email:
+            owner_matches = bool(current_email) and current_email == requested_owner_email
+        elif requested_owner_name:
+            owner_matches = bool(current_name) and current_name == requested_owner_name
+        if not owner_matches:
+            return _failed(
+                "EDIT_LOCK_HELD_BY_OTHER_USER",
+                "edit lock is owned by another user; refusing to release it",
+                normalized_args=normalized_args,
+                recoverable=False,
+                details={
+                    "lock_owner_email": requested_owner_email or None,
+                    "lock_owner_name": requested_owner_name or None,
+                    "current_user_email": identity.get("email"),
+                    "current_user_name": identity.get("nick_name"),
+                },
+                suggested_next_call=None,
+            )
+        try:
+            version_result = self.apps.app_get_edit_version_no(profile=profile, app_key=app_key).get("result") or {}
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "EDIT_LOCK_RELEASE_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        edit_version_no = _coerce_positive_int(version_result.get("editVersionNo") or version_result.get("versionNo")) or 1
+        try:
+            self.apps.app_edit_finished(profile=profile, app_key=app_key, payload={"editVersionNo": edit_version_no})
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "EDIT_LOCK_RELEASE_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={
+                    "app_key": app_key,
+                    "edit_version_no": edit_version_no,
+                    "lock_owner_email": requested_owner_email or None,
+                    "lock_owner_name": requested_owner_name or None,
+                },
+                suggested_next_call={"tool_name": "app_release_edit_lock_if_mine", "arguments": {"profile": profile, **normalized_args}},
+            )
+        return {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "released app edit lock owned by current user",
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {
+                "lock_owner_email": requested_owner_email or None,
+                "lock_owner_name": requested_owner_name or None,
+                "current_user_email": identity.get("email"),
+                "current_user_name": identity.get("nick_name"),
+                "edit_version_no": edit_version_no,
+            },
+            "request_id": None,
+            "suggested_next_call": {"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            "noop": False,
+            "verification": {"released": True},
+            "app_key": app_key,
+            "released": True,
+        }
+
     def app_resolve(
         self,
         *,
@@ -221,8 +904,14 @@ class AiBuilderFacade:
         if app_key:
             try:
                 base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True)
-            except RuntimeError as exc:
-                return _failed("APP_NOT_FOUND", f"failed to resolve app_key '{app_key}'", details={"error": str(exc)})
+            except (QingflowApiError, RuntimeError) as exc:
+                api_error = _coerce_api_error(exc)
+                return _failed_from_api_error(
+                    "APP_NOT_FOUND" if api_error.http_status == 404 else "APP_RESOLVE_FAILED",
+                    api_error,
+                    details={"app_key": app_key},
+                    suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+                )
             result = base.get("result") if isinstance(base.get("result"), dict) else {}
             return {
                 "status": "success",
@@ -299,8 +988,30 @@ class AiBuilderFacade:
         }
 
     def app_read_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        state = self._load_app_state(profile=profile, app_key=app_key)
+        try:
+            state = self._load_base_schema_state(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "APP_READ_FAILED",
+                api_error,
+                normalized_args={"app_key": app_key},
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_resolve", "arguments": {"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)
         parsed = state["parsed"]
+        verification_hints = _build_verification_hints(
+            tag_ids=_coerce_int_list(state["base"].get("tagIds")),
+            fields=parsed["fields"],
+            layout=parsed["layout"],
+            views=_summarize_views(views),
+        )
+        if views_unavailable:
+            verification_hints.append("views_read_unavailable")
+        if workflow_unavailable:
+            verification_hints.append("workflow_read_unavailable")
         response = AppReadSummaryResponse(
             app_key=app_key,
             title=state["base"].get("formTitle"),
@@ -308,14 +1019,9 @@ class AiBuilderFacade:
             publish_status=state["base"].get("appPublishStatus"),
             field_count=len(parsed["fields"]),
             layout_section_count=len(parsed["layout"].get("sections", [])),
-            view_count=len(_summarize_views(state["views"])),
-            workflow_enabled=bool(state["workflow"]),
-            verification_hints=_build_verification_hints(
-                tag_ids=_coerce_int_list(state["base"].get("tagIds")),
-                fields=parsed["fields"],
-                layout=parsed["layout"],
-                views=_summarize_views(state["views"]),
-            ),
+            view_count=len(_summarize_views(views)),
+            workflow_enabled=bool(workflow),
+            verification_hints=verification_hints,
         )
         return {
             "status": "success",
@@ -334,7 +1040,17 @@ class AiBuilderFacade:
         }
 
     def app_read_fields(self, *, profile: str, app_key: str) -> JSONObject:
-        state = self._load_app_state(profile=profile, app_key=app_key)
+        try:
+            state = self._load_base_schema_state(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "FIELDS_READ_FAILED",
+                api_error,
+                normalized_args={"app_key": app_key},
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
         parsed = state["parsed"]
         response = AppFieldsReadResponse(
             app_key=app_key,
@@ -368,7 +1084,17 @@ class AiBuilderFacade:
         }
 
     def app_read_layout_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        state = self._load_app_state(profile=profile, app_key=app_key)
+        try:
+            state = self._load_base_schema_state(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "LAYOUT_READ_FAILED",
+                api_error,
+                normalized_args={"app_key": app_key},
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
         parsed = state["parsed"]
         layout = parsed["layout"]
         response = AppLayoutReadResponse(
@@ -394,10 +1120,20 @@ class AiBuilderFacade:
         }
 
     def app_read_views_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        state = self._load_app_state(profile=profile, app_key=app_key)
+        try:
+            views, _ = self._load_views_result(profile=profile, app_key=app_key, tolerate_404=False)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "VIEWS_READ_FAILED",
+                api_error,
+                normalized_args={"app_key": app_key},
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
         response = AppViewsReadResponse(
             app_key=app_key,
-            views=_summarize_views(state["views"]),
+            views=_summarize_views(views),
         )
         return {
             "status": "success",
@@ -416,11 +1152,21 @@ class AiBuilderFacade:
         }
 
     def app_read_flow_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        state = self._load_app_state(profile=profile, app_key=app_key)
+        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_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
         response = AppFlowReadResponse(
             app_key=app_key,
-            enabled=bool(state["workflow"]),
-            nodes=_summarize_workflow_nodes(state["workflow"]),
+            enabled=bool(workflow),
+            nodes=_summarize_workflow_nodes(workflow),
             transitions=[],
         )
         return {
@@ -435,7 +1181,7 @@ class AiBuilderFacade:
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
-            "verification": {"app_exists": True},
+            "verification": {"app_exists": True, "workflow_read_unavailable": workflow_unavailable},
             **response.model_dump(mode="json"),
         }
 
@@ -453,7 +1199,11 @@ class AiBuilderFacade:
             return target
         current_fields: list[dict[str, Any]] = []
         if not bool(target.get("would_create")):
-            current_fields = self.app_read_fields(profile=profile, app_key=str(target["app_key"])).get("fields", [])
+            fields_result = self.app_read_fields(profile=profile, app_key=str(target["app_key"]))
+            if fields_result.get("status") == "failed":
+                fields_result.setdefault("normalized_args", normalized_args)
+                return fields_result
+            current_fields = fields_result.get("fields", [])
         current_by_name = {str(field.get("name") or ""): field for field in current_fields}
         blocking_issues: list[dict[str, Any]] = []
         preview_added: list[str] = []
@@ -511,11 +1261,31 @@ class AiBuilderFacade:
 
     def app_layout_plan(self, *, profile: str, request: LayoutPlanRequest) -> JSONObject:
         read_fields = self.app_read_fields(profile=profile, app_key=request.app_key)
-        current_names = [str(field.get("name") or "") for field in read_fields.get("fields", []) if field.get("name")]
+        if read_fields.get("status") == "failed":
+            return read_fields
+        current_fields = [field for field in read_fields.get("fields", []) if isinstance(field, dict)]
+        current_names = [str(field.get("name") or "") for field in current_fields if field.get("name")]
         current_layout = self.app_read_layout_summary(profile=profile, app_key=request.app_key)
+        if current_layout.get("status") == "failed":
+            return current_layout
         requested_sections = [section.model_dump(mode="json") for section in request.sections]
         if request.preset is not None:
             requested_sections = _build_layout_preset_sections(preset=request.preset, field_names=current_names)
+        else:
+            requested_sections, missing_selectors = _resolve_layout_sections_to_names(requested_sections, current_fields)
+            if missing_selectors:
+                return _failed(
+                    "UNKNOWN_LAYOUT_FIELD",
+                    "layout references unknown field selectors",
+                    normalized_args={
+                        "app_key": request.app_key,
+                        "mode": request.mode.value,
+                        "sections": requested_sections,
+                    },
+                    details={"unknown_selectors": missing_selectors},
+                    missing_fields=[str(item) for item in missing_selectors],
+                    suggested_next_call={"tool_name": "app_read_fields", "arguments": {"profile": profile, "app_key": request.app_key}},
+                )
         merged = _merge_layout(
             current_layout={
                 "root_rows": [],
@@ -574,10 +1344,66 @@ class AiBuilderFacade:
         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:
-            nodes, transitions = _build_flow_preset(request.preset)
-        current_fields = self.app_read_fields(profile=profile, app_key=request.app_key).get("fields", [])
+            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)
+        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_read_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 nodes}
+        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": ""}},
+            )
         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",
@@ -585,7 +1411,7 @@ class AiBuilderFacade:
                 normalized_args={
                     "app_key": request.app_key,
                     "mode": str(request.mode or "replace"),
-                    "nodes": nodes,
+                    "nodes": public_nodes,
                     "transitions": transitions,
                 },
                 details={"missing_dependencies": ["status field"]},
@@ -602,12 +1428,12 @@ class AiBuilderFacade:
                     },
                 },
             )
-        workflow = _build_public_workflow_spec(nodes=nodes, transitions=transitions)
+        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": nodes,
+                "nodes": public_nodes,
                 "transitions": transitions,
             }
             workflow["suggested_next_call"] = {
@@ -616,7 +1442,7 @@ class AiBuilderFacade:
                     "profile": profile,
                     "app_key": request.app_key,
                     "mode": "replace",
-                    "nodes": nodes,
+                    "nodes": public_nodes,
                     "transitions": transitions,
                 },
             }
@@ -624,7 +1450,7 @@ class AiBuilderFacade:
         normalized_args = {
             "app_key": request.app_key,
             "mode": str(request.mode or "replace"),
-            "nodes": nodes,
+            "nodes": public_nodes,
             "transitions": transitions,
         }
         return {
@@ -645,8 +1471,16 @@ class AiBuilderFacade:
         }
 
     def app_views_plan(self, *, profile: str, request: ViewsPlanRequest) -> JSONObject:
-        current_fields = self.app_read_fields(profile=profile, app_key=request.app_key).get("fields", [])
+        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", [])
         field_names = {str(field.get("name") or "") for field in current_fields}
+        current_fields_by_name = {
+            str(field.get("name") or ""): field
+            for field in current_fields
+            if isinstance(field, dict) and str(field.get("name") or "")
+        }
         upsert_views = [view.model_dump(mode="json") for view in request.upsert_views]
         if request.preset is not None:
             upsert_views = _build_views_preset(request.preset, list(field_names))
@@ -659,6 +1493,31 @@ class AiBuilderFacade:
             group_by = patch.get("group_by")
             if group_by and group_by not in field_names:
                 blocking_issues.append({"error_code": "UNKNOWN_VIEW_FIELD", "view_name": patch.get("name"), "missing_fields": [group_by]})
+            start_field = str(patch.get("start_field") or "").strip()
+            end_field = str(patch.get("end_field") or "").strip()
+            title_field = str(patch.get("title_field") or "").strip()
+            if patch.get("type") == "gantt":
+                missing_required = []
+                if not start_field:
+                    missing_required.append("start_field")
+                if not end_field:
+                    missing_required.append("end_field")
+                if missing_required:
+                    blocking_issues.append({"error_code": "INVALID_GANTT_CONFIG", "view_name": patch.get("name"), "missing_fields": missing_required})
+                missing_gantt_fields = [name for name in (start_field, end_field, title_field) if name and name not in field_names]
+                if missing_gantt_fields:
+                    blocking_issues.append({"error_code": "UNKNOWN_VIEW_FIELD", "view_name": patch.get("name"), "missing_fields": missing_gantt_fields})
+            translated_filters, filter_issues = _build_view_filter_groups(current_fields_by_name=current_fields_by_name, filters=patch.get("filters") or [])
+            if filter_issues:
+                blocking_issues.extend(
+                    {
+                        **issue,
+                        "view_name": patch.get("name"),
+                    }
+                    for issue in filter_issues
+                )
+            if translated_filters:
+                patch["filters"] = [dict(rule) for rule in (patch.get("filters") or [])]
         normalized_args = {
             "app_key": request.app_key,
             "upsert_views": upsert_views,
@@ -671,7 +1530,11 @@ class AiBuilderFacade:
             "message": "view plan has blocking issues" if blocking_issues else "planned view patch",
             "normalized_args": normalized_args,
             "missing_fields": [],
-            "allowed_values": {"view_types": ["table", "card", "board"], "presets": [preset.value for preset in ViewsPreset]},
+            "allowed_values": {
+                "view_types": [member.value for member in PublicViewType],
+                "presets": [preset.value for preset in ViewsPreset],
+                "view.filter.operator": [member.value for member in ViewFilterOperator],
+            },
             "details": {},
             "request_id": None,
             "views_diff_preview": {
@@ -731,6 +1594,7 @@ class AiBuilderFacade:
         package_tag_id: int | None = None,
         app_name: str = "",
         create_if_missing: bool = False,
+        publish: bool = True,
         add_fields: list[FieldPatch],
         update_fields: list[FieldUpdatePatch],
         remove_fields: list[FieldRemovePatch],
@@ -740,6 +1604,7 @@ class AiBuilderFacade:
             "package_tag_id": package_tag_id,
             "app_name": app_name,
             "create_if_missing": create_if_missing,
+            "publish": publish,
             "add_fields": [patch.model_dump(mode="json") for patch in add_fields],
             "update_fields": [patch.model_dump(mode="json") for patch in update_fields],
             "remove_fields": [patch.model_dump(mode="json") for patch in remove_fields],
@@ -757,19 +1622,26 @@ class AiBuilderFacade:
             return resolved
         target = ResolvedApp(
             app_key=str(resolved["app_key"]),
-            app_name=str(resolved["app_name"]),
-            tag_ids=_coerce_int_list(resolved.get("tag_ids")),
-        )
-        schema = self.apps.app_get_form_schema(
-            profile=profile,
-            app_key=target.app_key,
-            form_type=1,
-            being_draft=True,
-            being_apply=None,
-            audit_node_id=None,
-            include_raw=True,
+            app_name=str(resolved["app_name"]),
+            tag_ids=_coerce_int_list(resolved.get("tag_ids")),
         )
-        schema_result = schema.get("result") if isinstance(schema.get("result"), dict) else {}
+        schema_readback_delayed = False
+        try:
+            schema_result, _schema_source = self._read_schema_with_fallback(profile=profile, app_key=target.app_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if not bool(resolved.get("created")) or api_error.http_status != 404:
+                return _failed_from_api_error(
+                    "SCHEMA_READBACK_FAILED",
+                    api_error,
+                    normalized_args=normalized_args,
+                    allowed_values={"field_types": [item.value for item in PublicFieldType]},
+                    details={"app_key": target.app_key},
+                    suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": target.app_key}},
+                )
+            schema_result = _empty_schema_result(target.app_name)
+            _schema_source = "synthetic_new_app"
+            schema_readback_delayed = True
         parsed = _parse_schema(schema_result)
         current_fields = parsed["fields"]
         layout = parsed["layout"]
@@ -834,7 +1706,7 @@ class AiBuilderFacade:
         if not added and not updated and not removed and not bool(resolved.get("created")):
             tag_ids_after = _coerce_int_list((self.apps.app_get_base(profile=profile, app_key=target.app_key, include_raw=True).get("result") or {}).get("tagIds"))
             package_attached = None if package_tag_id is None else package_tag_id in tag_ids_after
-            return {
+            response = {
                 "status": "success",
                 "error_code": None,
                 "recoverable": False,
@@ -854,6 +1726,7 @@ class AiBuilderFacade:
                 "tag_ids_after": tag_ids_after,
                 "package_attached": package_attached,
             }
+            return self._append_publish_result(profile=profile, app_key=target.app_key, publish=publish, response=response)
 
         payload = _build_form_payload_from_fields(
             title=schema_result.get("formTitle") or target.app_name,
@@ -861,6 +1734,11 @@ class AiBuilderFacade:
             fields=current_fields,
             layout=layout,
         )
+        payload["editVersionNo"] = self._resolve_form_edit_version(
+            profile=profile,
+            app_key=target.app_key,
+            current_schema=schema_result,
+        )
         try:
             self.apps.app_update_form_schema(profile=profile, app_key=target.app_key, payload=payload)
         except (QingflowApiError, RuntimeError) as error:
@@ -876,13 +1754,8 @@ class AiBuilderFacade:
                 },
                 suggested_next_call={"tool_name": "app_read_fields", "arguments": {"profile": profile, "app_key": target.app_key}},
             )
-        verified = self.app_read(profile=profile, app_key=target.app_key, include_raw=False)
-        verified_field_names = {field["name"] for field in verified["schema"]["fields"]}
-        tag_ids_after = _coerce_int_list((self.apps.app_get_base(profile=profile, app_key=target.app_key, include_raw=True).get("result") or {}).get("tagIds"))
-        verification_ok = all(name in verified_field_names for name in added + updated) and all(name not in verified_field_names for name in removed)
-        package_attached = None if package_tag_id is None else package_tag_id in tag_ids_after
-        return {
-            "status": "success" if verification_ok and (package_attached is not False) else "partial_success",
+        response = {
+            "status": "success",
             "error_code": None,
             "recoverable": False,
             "message": "applied schema patch",
@@ -891,21 +1764,11 @@ class AiBuilderFacade:
             "allowed_values": {"field_types": [item.value for item in PublicFieldType]},
             "details": {},
             "request_id": None,
-            "suggested_next_call": None
-            if package_attached is not False
-            else {
-                "tool_name": "package_attach_app",
-                "arguments": {
-                    "profile": profile,
-                    "tag_id": package_tag_id,
-                    "app_key": target.app_key,
-                    "app_title": app_name or target.app_name,
-                },
-            },
+            "suggested_next_call": None,
             "noop": False,
             "verification": {
-                "fields_verified": verification_ok,
-                "package_attached": package_attached,
+                "fields_verified": False,
+                "package_attached": None,
             },
             "app_key": target.app_key,
             "created": bool(resolved.get("created")),
@@ -914,10 +1777,71 @@ class AiBuilderFacade:
                 "updated": updated,
                 "removed": removed,
             },
-            "verified": verification_ok,
-            "tag_ids_after": tag_ids_after,
-            "package_attached": package_attached,
+            "verified": False,
+            "tag_ids_after": [],
+            "package_attached": None,
         }
+        if schema_readback_delayed:
+            response["verification"]["schema_readback_delayed"] = True
+        response = self._append_publish_result(profile=profile, app_key=target.app_key, publish=publish, response=response)
+        verification_ok = False
+        tag_ids_after: list[int] = []
+        package_attached: bool | None = None
+        verification_error: QingflowApiError | None = None
+        try:
+            verified = self.app_read(profile=profile, app_key=target.app_key, include_raw=False)
+            verified_field_names = {field["name"] for field in verified["schema"]["fields"]}
+            verification_ok = all(name in verified_field_names for name in added + updated) and all(name not in verified_field_names for name in removed)
+        except (QingflowApiError, RuntimeError) as error:
+            verification_error = _coerce_api_error(error)
+            verification_ok = False
+        try:
+            base_info = self.apps.app_get_base(profile=profile, app_key=target.app_key, include_raw=True).get("result") or {}
+            tag_ids_after = _coerce_int_list(base_info.get("tagIds"))
+            package_attached = None if package_tag_id is None else package_tag_id in tag_ids_after
+        except (QingflowApiError, RuntimeError) as error:
+            base_error = _coerce_api_error(error)
+            if verification_error is None:
+                verification_error = base_error
+            tag_ids_after = []
+            package_attached = None if package_tag_id is None else False
+        response["verification"]["fields_verified"] = verification_ok
+        response["verification"]["package_attached"] = package_attached
+        response["verified"] = verification_ok
+        response["tag_ids_after"] = tag_ids_after
+        response["package_attached"] = package_attached
+        if package_attached is False:
+            response["suggested_next_call"] = {
+                "tool_name": "package_attach_app",
+                "arguments": {
+                    "profile": profile,
+                    "tag_id": package_tag_id,
+                    "app_key": target.app_key,
+                    "app_title": app_name or target.app_name,
+                },
+            }
+        publish_failed = bool(response.get("publish_requested")) and not bool(response.get("published"))
+        if verification_ok and package_attached is not False and not publish_failed:
+            response["status"] = "success"
+        else:
+            response["status"] = "partial_success"
+        if verification_error is not None:
+            response["recoverable"] = True
+            response["error_code"] = response.get("error_code") or (
+                "READBACK_PENDING" if verification_error.http_status == 404 else "READBACK_FAILED"
+            )
+            response["message"] = f"{response.get('message') or 'apply succeeded'}; readback pending"
+            response["request_id"] = response.get("request_id") or verification_error.request_id
+            details = response.get("details")
+            if not isinstance(details, dict):
+                details = {}
+                response["details"] = details
+            details["verification_error"] = {
+                "message": verification_error.message,
+                "http_status": verification_error.http_status,
+                "backend_code": verification_error.backend_code,
+            }
+        return response
 
     def app_layout_apply(
         self,
@@ -926,28 +1850,47 @@ class AiBuilderFacade:
         app_key: str,
         mode: LayoutApplyMode = LayoutApplyMode.merge,
         sections: list[LayoutSectionPatch],
+        publish: bool = True,
     ) -> JSONObject:
+        requested_sections = [section.model_dump(mode="json") for section in sections]
+        try:
+            schema_result, _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 _failed_from_api_error(
+                "LAYOUT_READ_FAILED",
+                api_error,
+                normalized_args={
+                    "app_key": app_key,
+                    "mode": mode.value,
+                    "sections": requested_sections,
+                    "publish": publish,
+                },
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_layout_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        parsed = _parse_schema(schema_result)
+        current_fields = parsed["fields"]
+        requested_sections, missing_selectors = _resolve_layout_sections_to_names(requested_sections, current_fields)
         normalized_args = {
             "app_key": app_key,
             "mode": mode.value,
-            "sections": [section.model_dump(mode="json") for section in sections],
+            "sections": requested_sections,
+            "publish": publish,
         }
-        schema = self.apps.app_get_form_schema(
-            profile=profile,
-            app_key=app_key,
-            form_type=1,
-            being_draft=True,
-            being_apply=None,
-            audit_node_id=None,
-            include_raw=True,
-        )
-        schema_result = schema.get("result") if isinstance(schema.get("result"), dict) else {}
-        parsed = _parse_schema(schema_result)
-        current_fields = parsed["fields"]
+        if missing_selectors:
+            return _failed(
+                "UNKNOWN_LAYOUT_FIELD",
+                "layout references unknown field selectors",
+                normalized_args=normalized_args,
+                details={"unknown_selectors": missing_selectors},
+                missing_fields=[str(item) for item in missing_selectors],
+                suggested_next_call={"tool_name": "app_read_fields", "arguments": {"profile": profile, "app_key": app_key}},
+            )
         fields_by_name = {field["name"]: field for field in current_fields}
         seen: list[str] = []
-        for section in sections:
-            for row in section.rows:
+        for section in requested_sections:
+            for row in section.get("rows", []):
                 for field_name in row:
                     if field_name not in fields_by_name:
                         return _failed(
@@ -967,7 +1910,6 @@ class AiBuilderFacade:
                         )
                     seen.append(field_name)
         expected = {field["name"] for field in current_fields}
-        requested_sections = [section.model_dump(mode="json") for section in sections]
         if mode == LayoutApplyMode.replace and set(seen) != expected:
             missing = sorted(expected.difference(seen))
             return _failed(
@@ -999,7 +1941,7 @@ class AiBuilderFacade:
             else merged["layout"]
         )
         if _layouts_equal(parsed["layout"], target_layout):
-            return {
+            response = {
                 "status": "success",
                 "error_code": None,
                 "recoverable": False,
@@ -1022,10 +1964,16 @@ class AiBuilderFacade:
                 },
                 "verified": True,
             }
+            return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
         payload = _build_form_payload_from_existing_schema(
             current_schema=schema_result,
             layout=target_layout,
         )
+        payload["editVersionNo"] = self._resolve_form_edit_version(
+            profile=profile,
+            app_key=app_key,
+            current_schema=schema_result,
+        )
         applied_layout = target_layout
         fallback_applied = None
         try:
@@ -1038,6 +1986,11 @@ class AiBuilderFacade:
                     current_schema=schema_result,
                     layout=flattened_layout,
                 )
+                fallback_payload["editVersionNo"] = self._resolve_form_edit_version(
+                    profile=profile,
+                    app_key=app_key,
+                    current_schema=schema_result,
+                )
                 try:
                     self.apps.app_update_form_schema(profile=profile, app_key=app_key, payload=fallback_payload)
                     applied_layout = flattened_layout
@@ -1071,8 +2024,33 @@ class AiBuilderFacade:
                     },
                     suggested_next_call={"tool_name": "app_layout_plan", "arguments": {"profile": profile, **normalized_args}},
                 )
-        verified = self.app_read(profile=profile, app_key=app_key, include_raw=False)
-        return {
+        verified = self.app_read_layout_summary(profile=profile, app_key=app_key)
+        if verified.get("status") == "failed":
+            response = {
+                "status": "partial_success",
+                "error_code": "LAYOUT_READBACK_PENDING",
+                "recoverable": True,
+                "message": "applied app layout; layout readback pending",
+                "normalized_args": normalized_args,
+                "missing_fields": [],
+                "allowed_values": {"modes": ["merge", "replace"]},
+                "details": {},
+                "request_id": verified.get("request_id"),
+                "suggested_next_call": {"tool_name": "app_read_layout_summary", "arguments": {"profile": profile, "app_key": app_key}},
+                "noop": False,
+                "verification": {"layout_verified": False, "layout_read_unavailable": True},
+                "app_key": app_key,
+                "layout_diff": {
+                    "mode": mode.value,
+                    "replaced": mode == LayoutApplyMode.replace,
+                    "merged": mode == LayoutApplyMode.merge,
+                    "auto_added_fields": merged["auto_added_fields"] if mode == LayoutApplyMode.merge else [],
+                    "fallback_applied": fallback_applied,
+                },
+                "verified": False,
+            }
+            return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
+        response = {
             "status": "partial_success" if fallback_applied else "success",
             "error_code": None,
             "recoverable": False,
@@ -1084,7 +2062,7 @@ class AiBuilderFacade:
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
-            "verification": {"layout_verified": verified["layout"] == applied_layout},
+            "verification": {"layout_verified": verified["sections"] == applied_layout.get("sections", [])},
             "app_key": app_key,
             "layout_diff": {
                 "mode": mode.value,
@@ -1093,8 +2071,9 @@ class AiBuilderFacade:
                 "auto_added_fields": merged["auto_added_fields"] if mode == LayoutApplyMode.merge else [],
                 "fallback_applied": fallback_applied,
             },
-            "verified": verified["layout"] == applied_layout,
+            "verified": verified["sections"] == applied_layout.get("sections", []),
         }
+        return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
 
     def app_flow_apply(
         self,
@@ -1104,12 +2083,14 @@ class AiBuilderFacade:
         nodes: list[dict[str, Any]],
         transitions: list[dict[str, Any]],
         mode: str = "replace",
+        publish: bool = True,
     ) -> JSONObject:
         normalized_args = {
             "app_key": app_key,
             "mode": mode,
             "nodes": nodes,
             "transitions": transitions,
+            "publish": publish,
         }
         if mode != "replace":
             return _failed(
@@ -1119,25 +2100,65 @@ class AiBuilderFacade:
                 allowed_values={"modes": ["replace"]},
                 suggested_next_call={"tool_name": "app_flow_plan", "arguments": {"profile": profile, **normalized_args}},
             )
-        base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
-        schema = self.apps.app_get_form_schema(
-            profile=profile,
-            app_key=app_key,
-            form_type=1,
-            being_draft=True,
-            being_apply=None,
-            audit_node_id=None,
-            include_raw=True,
-        ).get("result") or {}
+        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 _failed_from_api_error(
+                "FLOW_READ_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_flow_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
         entity = _entity_spec_from_app(base_info=base, schema=schema, views=None)
-        workflow_spec = _build_public_workflow_spec(nodes=nodes, transitions=transitions)
+        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)
+        normalized_args["nodes"] = public_nodes
+        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_read_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_plan", "arguments": {"profile": profile, **normalized_args}}
             return workflow_spec
-        desired_node_count = len([node for node in nodes if node.get("type") != "end"])
-        current_node_count = len(_summarize_workflow_nodes(self.workflows.workflow_list_nodes(profile=profile, app_key=app_key).get("result")))
+        desired_node_count = len([node for node in normalized_nodes if node.get("type") != "end"])
+        current_workflow, _workflow_unavailable = self._load_workflow_result(profile=profile, app_key=app_key, tolerate_404=True)
+        current_node_count = len(_summarize_workflow_nodes(current_workflow))
         if current_node_count == desired_node_count and desired_node_count > 0:
             # Lightweight idempotency check for repeat submissions of same simple graph.
             pass
@@ -1149,42 +2170,57 @@ class AiBuilderFacade:
             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)
-        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)
-        stage = self.solutions.solution_build_flow(
-            profile=profile,
-            mode="apply",
-            build_id=build_id,
-            flow_spec={
-                "solution_name": manifest["solution_name"],
-                "entities": [{"entity_id": entity["entity_id"], "workflow": workflow_spec["workflow"]}],
-            },
-            publish=False,
-            run_label=None,
-            repair_patch={},
-        )
         if stage.get("status") != "success":
             failed = _normalize_flow_stage_failure(stage, profile=profile, app_key=app_key, entity=entity)
             failed["normalized_args"] = normalized_args
-            failed["suggested_next_call"] = failed.get("suggested_next_call") or {"tool_name": "app_flow_plan", "arguments": {"profile": profile, **normalized_args}}
+            suggested_next_call = failed.get("suggested_next_call")
+            if not isinstance(suggested_next_call, dict):
+                suggested_next_call = {"tool_name": "app_flow_plan", "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["arguments"] = arguments
+            failed["suggested_next_call"] = suggested_next_call
             return failed
-        verified_nodes = self.workflows.workflow_list_nodes(profile=profile, app_key=app_key).get("result")
-        return {
-            "status": "success",
+        verified_nodes, verified_nodes_unavailable = self._load_workflow_result(profile=profile, app_key=app_key, tolerate_404=True)
+        response = {
+            "status": "success" if bool(verified_nodes) or not verified_nodes_unavailable else "partial_success",
             "error_code": None,
-            "recoverable": False,
-            "message": "applied workflow patch",
+            "recoverable": bool(verified_nodes_unavailable),
+            "message": "applied workflow patch" if not verified_nodes_unavailable else "applied workflow patch; flow readback pending",
             "normalized_args": normalized_args,
             "missing_fields": [],
             "allowed_values": {"modes": ["replace"]},
@@ -1192,11 +2228,15 @@ class AiBuilderFacade:
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
-            "verification": {"workflow_verified": bool(verified_nodes)},
+            "verification": {"workflow_verified": bool(verified_nodes), "workflow_read_unavailable": verified_nodes_unavailable},
             "app_key": app_key,
             "flow_diff": {"mode": "replace", "node_count": desired_node_count},
             "verified": bool(verified_nodes),
         }
+        if verified_nodes_unavailable:
+            response["error_code"] = "FLOW_READBACK_PENDING"
+            response["suggested_next_call"] = {"tool_name": "app_read_flow_summary", "arguments": {"profile": profile, "app_key": app_key}}
+        return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
 
     def app_views_apply(
         self,
@@ -1205,21 +2245,23 @@ class AiBuilderFacade:
         app_key: str,
         upsert_views: list[ViewUpsertPatch],
         remove_views: list[str],
+        publish: bool = True,
     ) -> JSONObject:
         normalized_args = {
             "app_key": app_key,
             "upsert_views": [patch.model_dump(mode="json") for patch in upsert_views],
             "remove_views": list(remove_views),
+            "publish": publish,
         }
         if not upsert_views and not remove_views:
-            return {
+            response = {
                 "status": "success",
                 "error_code": None,
                 "recoverable": False,
                 "message": "no view changes requested",
                 "normalized_args": normalized_args,
                 "missing_fields": [],
-                "allowed_values": {"view_types": ["table", "card", "board"]},
+                "allowed_values": {"view_types": [member.value for member in PublicViewType], "view.filter.operator": [member.value for member in ViewFilterOperator]},
                 "details": {},
                 "request_id": None,
                 "suggested_next_call": None,
@@ -1229,41 +2271,72 @@ class AiBuilderFacade:
                 "views_diff": {"created": [], "updated": [], "removed": []},
                 "verified": True,
             }
-        base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
-        schema = self.apps.app_get_form_schema(
-            profile=profile,
-            app_key=app_key,
-            form_type=1,
-            being_draft=True,
-            being_apply=None,
-            audit_node_id=None,
-            include_raw=True,
-        ).get("result") or {}
-        existing_views = self.views.view_list_flat(profile=profile, app_key=app_key).get("result") or []
-        existing_by_name = {}
+            return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
+        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)
+            existing_views, _views_unavailable = self._load_views_result(profile=profile, app_key=app_key, tolerate_404=False)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "VIEWS_READ_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        existing_views = existing_views or []
+        existing_by_key: dict[str, dict[str, Any]] = {}
+        existing_by_name: dict[str, list[dict[str, Any]]] = {}
         for view in existing_views if isinstance(existing_views, list) else []:
             if not isinstance(view, dict):
                 continue
-            name = str(view.get("viewgraphName") or view.get("viewName") or view.get("title") or "").strip()
-            key = str(view.get("viewgraphKey") or view.get("viewKey") or "").strip()
+            name = _extract_view_name(view)
+            key = _extract_view_key(view)
             if name and key:
-                existing_by_name[name] = key
+                existing_by_key[key] = view
+                existing_by_name.setdefault(name, []).append(view)
         parsed_schema = _parse_schema(schema)
         field_names = {field["name"] for field in parsed_schema["fields"]}
+        current_fields_by_name = {
+            str(field.get("name") or ""): field
+            for field in parsed_schema["fields"]
+            if isinstance(field, dict) and str(field.get("name") or "")
+        }
         removed: list[str] = []
+        view_results: list[dict[str, Any]] = []
         for name in remove_views:
-            key = existing_by_name.get(name)
-            if key:
+            matches = existing_by_name.get(name, [])
+            if len(matches) > 1:
+                return _failed(
+                    "AMBIGUOUS_VIEW",
+                    "multiple views matched remove request; use app_read_views_summary and resolve duplicates before removing by name",
+                    normalized_args=normalized_args,
+                    details={
+                        "app_key": app_key,
+                        "view_name": name,
+                        "matches": [
+                            {"name": _extract_view_name(view), "view_key": _extract_view_key(view), "type": _normalize_view_type_name(view.get("viewgraphType") or view.get("type"))}
+                            for view in matches
+                        ],
+                    },
+                    suggested_next_call={"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
+                )
+            if len(matches) == 1:
+                key = _extract_view_key(matches[0])
                 self.views.view_delete(profile=profile, viewgraph_key=key)
                 removed.append(name)
                 existing_by_name.pop(name, None)
+                existing_by_key.pop(key, None)
+                view_results.append({"name": name, "view_key": key, "type": None, "status": "removed"})
         created: list[str] = []
         updated: list[str] = []
+        failed_views: list[dict[str, Any]] = []
         existing_view_list = [
             view
             for view in (existing_views if isinstance(existing_views, list) else [])
             if isinstance(view, dict)
-            and str(view.get("viewgraphName") or view.get("viewName") or view.get("title") or "").strip() not in remove_views
+            and _extract_view_name(view) not in remove_views
         ]
         for ordinal, patch in enumerate(upsert_views, start=1):
             missing_columns = [name for name in patch.columns if name not in field_names]
@@ -1293,7 +2366,69 @@ class AiBuilderFacade:
                     missing_fields=[patch.group_by],
                     suggested_next_call={"tool_name": "app_read_fields", "arguments": {"profile": profile, "app_key": app_key}},
                 )
-            existing_key = existing_by_name.get(patch.name)
+            for gantt_field_name in (patch.start_field, patch.end_field, patch.title_field):
+                if gantt_field_name and gantt_field_name not in field_names:
+                    return _failed(
+                        "UNKNOWN_VIEW_FIELD",
+                        f"gantt configuration references unknown field '{gantt_field_name}'",
+                        normalized_args=normalized_args,
+                        details={
+                            "app_key": app_key,
+                            "view_name": patch.name,
+                            "missing_fields": [gantt_field_name],
+                        },
+                        missing_fields=[gantt_field_name],
+                        suggested_next_call={"tool_name": "app_read_fields", "arguments": {"profile": profile, "app_key": app_key}},
+                    )
+            translated_filters, filter_issues = _build_view_filter_groups(current_fields_by_name=current_fields_by_name, filters=patch.filters)
+            if filter_issues:
+                first_issue = filter_issues[0]
+                return _failed(
+                    str(first_issue.get("error_code") or "UNKNOWN_VIEW_FIELD"),
+                    "view filters reference invalid fields or values",
+                    normalized_args=normalized_args,
+                    details={
+                        "app_key": app_key,
+                        "view_name": patch.name,
+                        **first_issue,
+                    },
+                    missing_fields=list(first_issue.get("missing_fields") or []),
+                    allowed_values=first_issue.get("allowed_values") or {"view_types": [member.value for member in PublicViewType], "view.filter.operator": [member.value for member in ViewFilterOperator]},
+                    suggested_next_call={"tool_name": "app_read_fields", "arguments": {"profile": profile, "app_key": app_key}},
+                )
+            matched_existing_view: dict[str, Any] | None = None
+            existing_key: str | None = None
+            if patch.view_key:
+                matched_existing_view = existing_by_key.get(patch.view_key)
+                if not matched_existing_view:
+                    return _failed(
+                        "UNKNOWN_VIEW",
+                        f"view_key '{patch.view_key}' does not exist on this app",
+                        normalized_args=normalized_args,
+                        details={"app_key": app_key, "view_key": patch.view_key, "view_name": patch.name},
+                        suggested_next_call={"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
+                    )
+                existing_key = patch.view_key
+            else:
+                name_matches = existing_by_name.get(patch.name, [])
+                if len(name_matches) > 1:
+                    return _failed(
+                        "AMBIGUOUS_VIEW",
+                        "multiple views share this name; supply view_key to update the exact target",
+                        normalized_args=normalized_args,
+                        details={
+                            "app_key": app_key,
+                            "view_name": patch.name,
+                            "matches": [
+                                {"name": _extract_view_name(view), "view_key": _extract_view_key(view), "type": _normalize_view_type_name(view.get("viewgraphType") or view.get("type"))}
+                                for view in name_matches
+                            ],
+                        },
+                        suggested_next_call={"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
+                    )
+                if len(name_matches) == 1:
+                    matched_existing_view = name_matches[0]
+                    existing_key = _extract_view_key(matched_existing_view)
             created_key: str | None = None
             try:
                 if existing_key:
@@ -1303,9 +2438,19 @@ class AiBuilderFacade:
                         source_viewgraph_key=existing_key,
                         schema=schema,
                         patch=patch,
+                        view_filters=translated_filters,
                     )
                     self.views.view_update(profile=profile, viewgraph_key=existing_key, payload=payload)
                     updated.append(patch.name)
+                    view_results.append(
+                        {
+                            "name": patch.name,
+                            "view_key": existing_key,
+                            "type": patch.type.value,
+                            "status": "updated",
+                            "expected_filters": deepcopy(translated_filters),
+                        }
+                    )
                 else:
                     template_key = _pick_view_template_key(existing_view_list, desired_type=patch.type.value)
                     if patch.type.value == "table" and template_key:
@@ -1317,6 +2462,7 @@ class AiBuilderFacade:
                             source_viewgraph_key=created_key,
                             schema=schema,
                             patch=patch,
+                            view_filters=translated_filters,
                         )
                         self.views.view_update(profile=profile, viewgraph_key=created_key, payload=payload)
                     else:
@@ -1326,52 +2472,304 @@ class AiBuilderFacade:
                             schema=schema,
                             patch=patch,
                             ordinal=ordinal,
+                            view_filters=translated_filters,
                         )
                         self.views.view_create(profile=profile, payload=payload)
                     created.append(patch.name)
+                    view_results.append(
+                        {
+                            "name": patch.name,
+                            "view_key": created_key,
+                            "type": patch.type.value,
+                            "status": "created",
+                            "expected_filters": deepcopy(translated_filters),
+                        }
+                    )
             except (QingflowApiError, RuntimeError) as error:
                 api_error = _coerce_api_error(error)
+                should_retry_minimal = api_error.backend_code == 48104 or (
+                    patch.type.value == "table" and bool(patch.filters) and api_error.http_status is not None and api_error.http_status >= 500
+                )
+                if should_retry_minimal:
+                    try:
+                        if existing_key or created_key:
+                            target_key = created_key or existing_key or ""
+                            fallback_payload = _build_minimal_view_payload(
+                                app_key=app_key,
+                                schema=schema,
+                                patch=patch,
+                                ordinal=ordinal,
+                                view_filters=translated_filters,
+                            )
+                            self.views.view_update(profile=profile, viewgraph_key=target_key, payload=fallback_payload)
+                            if existing_key:
+                                updated.append(patch.name)
+                                view_results.append(
+                                    {
+                                        "name": patch.name,
+                                        "view_key": existing_key,
+                                        "type": patch.type.value,
+                                        "status": "updated",
+                                        "fallback_applied": True,
+                                        "expected_filters": deepcopy(translated_filters),
+                                    }
+                                )
+                            else:
+                                created.append(patch.name)
+                                view_results.append(
+                                    {
+                                        "name": patch.name,
+                                        "view_key": created_key,
+                                        "type": patch.type.value,
+                                        "status": "created",
+                                        "fallback_applied": True,
+                                        "expected_filters": deepcopy(translated_filters),
+                                    }
+                                )
+                            continue
+                        fallback_payload = _build_minimal_view_payload(
+                            app_key=app_key,
+                            schema=schema,
+                            patch=patch,
+                            ordinal=ordinal,
+                            view_filters=translated_filters,
+                        )
+                        self.views.view_create(profile=profile, payload=fallback_payload)
+                        created.append(patch.name)
+                        view_results.append(
+                            {
+                                "name": patch.name,
+                                "view_key": created_key,
+                                "type": patch.type.value,
+                                "status": "created",
+                                "fallback_applied": True,
+                                "expected_filters": deepcopy(translated_filters),
+                            }
+                        )
+                        continue
+                    except (QingflowApiError, RuntimeError) as fallback_error:
+                        api_error = _coerce_api_error(fallback_error)
                 if created_key:
                     try:
                         self.views.view_delete(profile=profile, viewgraph_key=created_key)
                     except Exception:
                         pass
-                return _failed_from_api_error(
-                    "VIEW_APPLY_FAILED",
-                    api_error,
-                    normalized_args=normalized_args,
-                    details={
+                failure_entry = {
+                    "name": patch.name,
+                    "view_key": patch.view_key or existing_key or created_key,
+                    "type": patch.type.value,
+                    "status": "failed",
+                    "error_code": "VIEW_APPLY_FAILED",
+                    "message": _public_error_message("VIEW_APPLY_FAILED", api_error),
+                    "request_id": api_error.request_id,
+                    "backend_code": api_error.backend_code,
+                    "http_status": None if api_error.http_status == 404 else api_error.http_status,
+                    "operation": "update" if existing_key or created_key else "create",
+                    "details": {
                         "app_key": app_key,
                         "view_name": patch.name,
                         "view_type": patch.type.value,
                         "columns": patch.columns,
                         "group_by": patch.group_by,
+                        "filters": [item.model_dump(mode="json") for item in patch.filters],
+                        "start_field": patch.start_field,
+                        "end_field": patch.end_field,
+                        "title_field": patch.title_field,
+                        "operation": "update" if existing_key or created_key else "create",
+                        "transport_error": {
+                            "http_status": api_error.http_status,
+                            "backend_code": api_error.backend_code,
+                            "category": api_error.category,
+                        },
                     },
-                    suggested_next_call={
-                        "tool_name": "app_views_plan",
-                        "arguments": {"profile": profile, "app_key": app_key},
-                    },
+                }
+                failed_views.append(failure_entry)
+                view_results.append(failure_entry)
+                continue
+        try:
+            verified_view_result, verified_views_unavailable = self._load_views_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(
+                "VIEWS_READ_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        verified_names = {
+            _extract_view_name(item)
+            for item in (verified_view_result or [])
+            if isinstance(item, dict) and _extract_view_name(item)
+        }
+        verified_by_key = {
+            _extract_view_key(item): item
+            for item in (verified_view_result or [])
+            if isinstance(item, dict) and _extract_view_key(item)
+        }
+        verified_view_keys_by_name: dict[str, list[str]] = {}
+        for item in (verified_view_result or []):
+            if not isinstance(item, dict):
+                continue
+            name = _extract_view_name(item)
+            key = _extract_view_key(item)
+            if name and key:
+                verified_view_keys_by_name.setdefault(name, []).append(key)
+        verification_by_view: list[dict[str, Any]] = []
+        filter_readback_pending = False
+        filter_mismatches: list[dict[str, Any]] = []
+        for item in view_results:
+            status = str(item.get("status") or "")
+            name = str(item.get("name") or "")
+            item_view_key = str(item.get("view_key") or "").strip()
+            present_in_readback: bool | None
+            if status in {"created", "updated"}:
+                if verified_views_unavailable:
+                    present_in_readback = None
+                elif item_view_key:
+                    present_in_readback = item_view_key in verified_by_key
+                else:
+                    present_in_readback = name in verified_names
+                verification_entry: dict[str, Any] = {
+                    "name": name,
+                    "view_key": item_view_key or None,
+                    "type": item.get("type"),
+                    "status": status,
+                    "present_in_readback": present_in_readback,
+                }
+                expected_filters = item.get("expected_filters") or []
+                if expected_filters:
+                    if verified_views_unavailable or not present_in_readback:
+                        verification_entry["filters_verified"] = None
+                        verification_entry["filter_readback_pending"] = True
+                        filter_readback_pending = True
+                    else:
+                        verification_key = item_view_key
+                        if not verification_key:
+                            matched_keys = verified_view_keys_by_name.get(name) or []
+                            if len(matched_keys) == 1:
+                                verification_key = matched_keys[0]
+                            else:
+                                verification_entry["filters_verified"] = None
+                                verification_entry["filter_readback_pending"] = True
+                                verification_entry["readback_ambiguous"] = True
+                                verification_entry["matching_view_keys"] = matched_keys
+                                filter_readback_pending = True
+                                verification_by_view.append(verification_entry)
+                                continue
+                        try:
+                            config_response = self.views.view_get_config(profile=profile, viewgraph_key=verification_key)
+                            actual_filters = _normalize_view_filter_groups_for_compare((config_response.get("result") or {}).get("viewgraphLimit"))
+                            expected_filter_summary = _normalize_view_filter_groups_for_compare(expected_filters)
+                            filters_verified = actual_filters == expected_filter_summary
+                            verification_entry["filters_verified"] = filters_verified
+                            verification_entry["view_key"] = verification_key
+                            verification_entry["expected_filters"] = expected_filter_summary
+                            verification_entry["actual_filters"] = actual_filters
+                            if not filters_verified:
+                                filter_mismatches.append(
+                                    {
+                                        "name": name,
+                                        "type": item.get("type"),
+                                        "expected_filters": expected_filter_summary,
+                                        "actual_filters": actual_filters,
+                                    }
+                                )
+                        except (QingflowApiError, RuntimeError) as error:
+                            api_error = _coerce_api_error(error)
+                            verification_entry["filters_verified"] = None
+                            verification_entry["filter_readback_pending"] = True
+                            verification_entry["request_id"] = api_error.request_id
+                            verification_entry["transport_error"] = {
+                                "http_status": api_error.http_status,
+                                "backend_code": api_error.backend_code,
+                                "category": api_error.category,
+                            }
+                            filter_readback_pending = True
+                verification_by_view.append(verification_entry)
+            elif status == "removed":
+                verification_by_view.append(
+                    {
+                        "name": name,
+                        "type": item.get("type"),
+                        "status": "removed",
+                        "present_in_readback": None if verified_views_unavailable else name not in verified_names,
+                    }
+                )
+            else:
+                verification_by_view.append(
+                    {
+                        "name": item.get("name"),
+                        "type": item.get("type"),
+                        "status": "failed",
+                        "present_in_readback": None,
+                        "error_code": item.get("error_code"),
+                    }
                 )
-        verified_names = {item.get("viewgraphName") or item.get("viewName") or item.get("title") for item in (self.views.view_list_flat(profile=profile, app_key=app_key).get("result") or []) if isinstance(item, dict)}
-        verified = all(name in verified_names for name in created + updated) and all(name not in verified_names for name in removed)
+        verified = (
+            (not verified_views_unavailable)
+            and all(name in verified_names for name in created + updated)
+            and all(name not in verified_names for name in removed)
+            and not filter_readback_pending
+            and not filter_mismatches
+        )
         noop = not created and not updated and not removed
-        return {
+        if failed_views:
+            successful_changes = bool(created or updated or removed)
+            first_failure = failed_views[0]
+            response = {
+                "status": "partial_success" if successful_changes else "failed",
+                "error_code": "VIEW_APPLY_PARTIAL" if successful_changes else "VIEW_APPLY_FAILED",
+                "recoverable": True,
+                "message": "applied some view patches; at least one view failed" if successful_changes else "one or more view patches failed",
+                "normalized_args": normalized_args,
+                "missing_fields": [],
+                "allowed_values": {"view_types": [member.value for member in PublicViewType], "view.filter.operator": [member.value for member in ViewFilterOperator]},
+                "details": {"per_view_results": view_results, "filter_mismatches": filter_mismatches},
+                "request_id": first_failure.get("request_id"),
+                "suggested_next_call": {"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
+                "backend_code": first_failure.get("backend_code"),
+                "http_status": first_failure.get("http_status"),
+                "noop": noop,
+                "verification": {
+                    "views_verified": verified,
+                    "views_read_unavailable": verified_views_unavailable,
+                    "by_view": verification_by_view,
+                },
+                "app_key": app_key,
+                "views_diff": {"created": created, "updated": updated, "removed": removed, "failed": failed_views},
+                "verified": verified,
+            }
+            return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
+        response = {
             "status": "success" if verified else "partial_success",
-            "error_code": None,
-            "recoverable": False,
-            "message": "applied view patch",
+            "error_code": None if verified else ("VIEW_FILTER_READBACK_MISMATCH" if filter_mismatches else "VIEWS_READBACK_PENDING"),
+            "recoverable": not verified,
+            "message": (
+                "applied view patch"
+                if verified
+                else "applied view patch; filters did not fully verify"
+                if filter_mismatches
+                else "applied view patch; views readback pending"
+            ),
             "normalized_args": normalized_args,
             "missing_fields": [],
-            "allowed_values": {"view_types": ["table", "card", "board"]},
-            "details": {},
+            "allowed_values": {"view_types": [member.value for member in PublicViewType], "view.filter.operator": [member.value for member in ViewFilterOperator]},
+            "details": {"filter_mismatches": filter_mismatches} if filter_mismatches else {},
             "request_id": None,
-            "suggested_next_call": None,
+            "suggested_next_call": None if verified else {"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
             "noop": noop,
-            "verification": {"views_verified": verified},
+            "verification": {
+                "views_verified": verified,
+                "views_read_unavailable": verified_views_unavailable,
+                "filter_readback_pending": filter_readback_pending,
+                "by_view": verification_by_view,
+            },
             "app_key": app_key,
-            "views_diff": {"created": created, "updated": updated, "removed": removed},
+            "views_diff": {"created": created, "updated": updated, "removed": removed, "failed": []},
             "verified": verified,
         }
+        return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
 
     def app_publish_verify(
         self,
@@ -1381,12 +2779,33 @@ class AiBuilderFacade:
         expected_package_tag_id: int | None = None,
     ) -> JSONObject:
         normalized_args = {"app_key": app_key, "expected_package_tag_id": expected_package_tag_id}
-        base_before = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
+        try:
+            base_before = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "APP_READ_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
         tag_ids_before = _coerce_int_list(base_before.get("tagIds"))
         already_published = bool(base_before.get("appPublishStatus") in {1, 2})
         package_already_attached = None if not expected_package_tag_id else expected_package_tag_id in tag_ids_before
-        views_before = self.views.view_list_flat(profile=profile, app_key=app_key).get("result") or []
-        if already_published and package_already_attached is not False and isinstance(views_before, list):
+        try:
+            views_before, views_before_unavailable = self._load_views_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(
+                "VIEWS_READ_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        views_before = views_before or []
+        if already_published and package_already_attached is not False and isinstance(views_before, list) and not views_before_unavailable:
             return {
                 "status": "success",
                 "error_code": None,
@@ -1410,28 +2829,49 @@ class AiBuilderFacade:
         version_result = self.apps.app_get_edit_version_no(profile=profile, app_key=app_key).get("result") or {}
         edit_version_no = _coerce_positive_int(version_result.get("editVersionNo") or version_result.get("versionNo")) or 1
         try:
-            self.apps.app_publish(profile=profile, app_key=app_key, payload={"editVersionNo": edit_version_no})
-            self.apps.app_edit_finished(profile=profile, app_key=app_key, payload={"editVersionNo": edit_version_no})
+            self.apps.app_publish(profile=profile, app_key=app_key, payload={"editVersionNo": edit_version_no})
+            self.apps.app_edit_finished(profile=profile, app_key=app_key, payload={"editVersionNo": edit_version_no})
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "PUBLISH_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key, "edit_version_no": edit_version_no},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        try:
+            base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "APP_READ_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        tag_ids_after = _coerce_int_list(base.get("tagIds"))
+        package_attached = None if not expected_package_tag_id else expected_package_tag_id in tag_ids_after
+        try:
+            views, views_unavailable = self._load_views_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(
-                "PUBLISH_FAILED",
+                "VIEWS_READ_FAILED",
                 api_error,
                 normalized_args=normalized_args,
-                details={"app_key": app_key, "edit_version_no": edit_version_no},
-                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
             )
-        base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
-        tag_ids_after = _coerce_int_list(base.get("tagIds"))
-        package_attached = None if not expected_package_tag_id else expected_package_tag_id in tag_ids_after
-        views = self.views.view_list_flat(profile=profile, app_key=app_key).get("result") or []
-        views_ok = isinstance(views, list)
+        views = views or []
+        views_ok = isinstance(views, list) and not views_unavailable
         verified = bool(base.get("appPublishStatus") in {1, 2}) and (package_attached is not False) and views_ok
         return {
             "status": "success" if verified else "partial_success",
-            "error_code": None,
-            "recoverable": False,
-            "message": "published and verified app",
+            "error_code": None if not views_unavailable else "VIEWS_READBACK_PENDING",
+            "recoverable": bool(views_unavailable),
+            "message": "published and verified app" if not views_unavailable else "published app; views readback pending",
             "normalized_args": normalized_args,
             "missing_fields": [],
             "allowed_values": {},
@@ -1444,7 +2884,7 @@ class AiBuilderFacade:
                 "arguments": {"profile": profile, "tag_id": expected_package_tag_id, "app_key": app_key},
             },
             "noop": False,
-            "verification": {"published": bool(base.get("appPublishStatus") in {1, 2}), "package_attached": package_attached, "views_ok": views_ok},
+            "verification": {"published": bool(base.get("appPublishStatus") in {1, 2}), "package_attached": package_attached, "views_ok": views_ok, "views_read_unavailable": views_unavailable},
             "app_key": app_key,
             "published": bool(base.get("appPublishStatus") in {1, 2}),
             "package_attached": package_attached,
@@ -1453,29 +2893,163 @@ class AiBuilderFacade:
             "verified": verified,
         }
 
-    def _load_app_state(self, *, profile: str, app_key: str) -> dict[str, Any]:
+    def _publish_current_edit_version(self, *, profile: str, app_key: str) -> JSONObject:
+        normalized_args = {"app_key": app_key}
+        version_result = self.apps.app_get_edit_version_no(profile=profile, app_key=app_key).get("result") or {}
+        edit_version_no = _coerce_positive_int(version_result.get("editVersionNo") or version_result.get("versionNo")) or 1
+        try:
+            self.apps.app_publish(profile=profile, app_key=app_key, payload={"editVersionNo": edit_version_no})
+            self.apps.app_edit_finished(profile=profile, app_key=app_key, payload={"editVersionNo": edit_version_no})
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "PUBLISH_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key, "edit_version_no": edit_version_no},
+                suggested_next_call={"tool_name": "app_publish_verify", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        return {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "published current app draft",
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {"app_key": app_key, "edit_version_no": edit_version_no},
+            "request_id": None,
+            "suggested_next_call": None,
+            "noop": False,
+            "verification": {"published": True},
+            "app_key": app_key,
+            "published": True,
+        }
+
+    def _resolve_form_edit_version(self, *, profile: str, app_key: str, current_schema: dict[str, Any]) -> int:
+        try:
+            version_result = self.apps.app_get_edit_version_no(profile=profile, app_key=app_key).get("result") or {}
+        except (QingflowApiError, RuntimeError):
+            version_result = {}
+        return _coerce_positive_int(version_result.get("editVersionNo") or version_result.get("versionNo")) or int(current_schema.get("editVersionNo") or 1)
+
+    def _append_publish_result(self, *, profile: str, app_key: str, publish: bool, response: JSONObject) -> JSONObject:
+        response["publish_requested"] = publish
+        if not publish:
+            response["published"] = False
+            return response
+        publish_result = self._publish_current_edit_version(profile=profile, app_key=app_key)
+        response["publish_result"] = publish_result
+        response["published"] = bool(publish_result.get("published"))
+        verification = response.get("verification")
+        if not isinstance(verification, dict):
+            verification = {}
+            response["verification"] = verification
+        verification["published"] = bool(publish_result.get("published"))
+        if publish_result.get("status") == "failed":
+            response["status"] = "partial_success"
+            response["error_code"] = response.get("error_code") or publish_result.get("error_code")
+            response["recoverable"] = True
+            response["message"] = f"{response.get('message') or 'apply succeeded'}; publish failed"
+            if not response.get("suggested_next_call"):
+                response["suggested_next_call"] = publish_result.get("suggested_next_call")
+        return response
+
+    def _load_base_schema_state(self, *, profile: str, app_key: str) -> dict[str, Any]:
         base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True)
-        schema = self.apps.app_get_form_schema(
-            profile=profile,
-            app_key=app_key,
-            form_type=1,
-            being_draft=True,
-            being_apply=None,
-            audit_node_id=None,
-            include_raw=True,
-        )
-        views = self.views.view_list_flat(profile=profile, app_key=app_key)
-        workflow = self.workflows.workflow_list_nodes(profile=profile, app_key=app_key)
+        schema_result, schema_source = self._read_schema_with_fallback(profile=profile, app_key=app_key)
         base_result = base.get("result") if isinstance(base.get("result"), dict) else {}
-        schema_result = schema.get("result") if isinstance(schema.get("result"), dict) else {}
         return {
             "base": base_result,
             "schema": schema_result,
             "parsed": _parse_schema(schema_result),
-            "views": views.get("result"),
-            "workflow": workflow.get("result"),
+            "schema_source": schema_source,
         }
 
+    def _load_views_result(self, *, profile: str, app_key: str, tolerate_404: bool) -> tuple[Any, bool]:
+        try:
+            views = self.views.view_list_flat(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if api_error.http_status == 404:
+                try:
+                    legacy_views = self.views.view_list(profile=profile, app_key=app_key)
+                except (QingflowApiError, RuntimeError) as legacy_error:
+                    legacy_api_error = _coerce_api_error(legacy_error)
+                    if tolerate_404 and legacy_api_error.http_status == 404:
+                        return [], True
+                    raise
+                legacy_result = legacy_views.get("result")
+                if _is_view_collection_shape(legacy_result):
+                    return _normalize_view_collection(legacy_result), False
+                if tolerate_404:
+                    return [], True
+                raise error
+            raise
+        normalized_views = _normalize_view_collection(views.get("result"))
+        if normalized_views:
+            return normalized_views, False
+        try:
+            legacy_views = self.views.view_list(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as legacy_error:
+            legacy_api_error = _coerce_api_error(legacy_error)
+            if tolerate_404 and legacy_api_error.http_status == 404:
+                return normalized_views, False
+            raise
+        legacy_result = legacy_views.get("result")
+        legacy_normalized = _normalize_view_collection(legacy_result)
+        return legacy_normalized or normalized_views, False
+
+    def _load_workflow_result(self, *, profile: str, app_key: str, tolerate_404: bool) -> tuple[Any, bool]:
+        try:
+            workflow = self.workflows.workflow_list_nodes(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if tolerate_404 and api_error.http_status == 404:
+                return [], True
+            raise
+        return workflow.get("result"), 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)
+        state["views"] = views
+        state["workflow"] = workflow
+        state["views_unavailable"] = views_unavailable
+        state["workflow_unavailable"] = workflow_unavailable
+        return state
+
+    def _read_schema_with_fallback(self, *, profile: str, app_key: str) -> tuple[dict[str, Any], str]:
+        attempts = (
+            ("draft", True),
+            ("current", None),
+            ("published", False),
+        )
+        last_error: Exception | None = None
+        for label, being_draft in attempts:
+            try:
+                schema = self.apps.app_get_form_schema(
+                    profile=profile,
+                    app_key=app_key,
+                    form_type=1,
+                    being_draft=being_draft,
+                    being_apply=None,
+                    audit_node_id=None,
+                    include_raw=True,
+                )
+                result = schema.get("result")
+                return (result if isinstance(result, dict) else {}), label
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                last_error = error
+                if api_error.http_status == 404:
+                    continue
+                raise
+        if last_error is not None:
+            raise last_error
+        return {}, "unknown"
+
     def _preview_target_app(
         self,
         *,
@@ -1563,7 +3137,28 @@ class AiBuilderFacade:
         new_app_key = str(result.get("appKey") or (result.get("appKeys")[0] if isinstance(result.get("appKeys"), list) and result.get("appKeys") else ""))
         if not new_app_key:
             return _failed("APP_CREATE_FAILED", "failed to create app shell", details={"result": result}, suggested_next_call=None)
-        base = self.apps.app_get_base(profile=profile, app_key=new_app_key, include_raw=True).get("result") or {}
+        try:
+            base = self.apps.app_get_base(profile=profile, app_key=new_app_key, include_raw=True).get("result") or {}
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if api_error.http_status != 404:
+                return _failed_from_api_error(
+                    "APP_CREATE_READBACK_FAILED",
+                    api_error,
+                    details={"app_key": new_app_key, "app_name": app_name, "package_tag_id": package_tag_id},
+                    suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": new_app_key}},
+                )
+            return {
+                "status": "success",
+                "error_code": None,
+                "recoverable": False,
+                "message": "created app; base readback pending",
+                "suggested_next_call": None,
+                "app_key": new_app_key,
+                "app_name": app_name or "未命名应用",
+                "tag_ids": [],
+                "created": True,
+            }
         return {
             "status": "success",
             "error_code": None,
@@ -1594,6 +3189,33 @@ class AiBuilderFacade:
         payload.setdefault("ws_id", session_profile.selected_ws_id)
         return payload
 
+    def _resolve_current_user_identity(self, *, profile: str) -> JSONObject:
+        session_profile = self.apps.sessions.get_profile(profile)
+        backend_session = self.apps.sessions.get_backend_session(profile)
+        current_email = str((session_profile.email if session_profile else None) or "").strip()
+        current_name = str((session_profile.nick_name if session_profile else None) or "").strip()
+        if current_email or current_name or session_profile is None or backend_session is None:
+            return {"email": current_email or None, "nick_name": current_name or None}
+        try:
+            user_info = self.apps.backend.request(
+                "GET",
+                BackendRequestContext(
+                    base_url=backend_session.base_url,
+                    token=backend_session.token,
+                    ws_id=session_profile.selected_ws_id,
+                    qf_version=backend_session.qf_version,
+                    qf_version_source=backend_session.qf_version_source,
+                ),
+                "/user",
+            )
+        except (QingflowApiError, RuntimeError):
+            return {"email": current_email or None, "nick_name": current_name or None}
+        if not isinstance(user_info, dict):
+            return {"email": current_email or None, "nick_name": current_name or None}
+        resolved_email = str(user_info.get("email") or "").strip() or None
+        resolved_name = str(user_info.get("nickName") or user_info.get("displayName") or user_info.get("name") or "").strip() or None
+        return {"email": resolved_email, "nick_name": resolved_name}
+
     def _attach_app_to_package(self, *, profile: str, app_key: str, app_title: str, package_tag_id: int) -> None:
         detail = self.packages.package_get(profile=profile, tag_id=package_tag_id, include_raw=True)
         result = detail.get("result") if isinstance(detail.get("result"), dict) else {}
@@ -1658,18 +3280,49 @@ def _failed_from_api_error(
     suggested_next_call: JSONObject | None = None,
     recoverable: bool = True,
 ) -> JSONObject:
+    effective_error_code = "APP_EDIT_LOCKED" if error.backend_code == 40074 else error_code
+    public_message = _public_error_message(effective_error_code, error)
+    public_http_status = None if error.http_status == 404 else error.http_status
+    merged_details = dict(details or {})
+    if error.backend_code == 40074:
+        owner = _extract_edit_lock_owner(error.message)
+        merged_details.setdefault("lock_owner_name", owner.get("lock_owner_name"))
+        merged_details.setdefault("lock_owner_email", owner.get("lock_owner_email"))
+        app_key = None
+        if isinstance(normalized_args, dict):
+            app_key = normalized_args.get("app_key")
+        if not app_key and isinstance(details, dict):
+            app_key = details.get("app_key")
+        if isinstance(app_key, str) and app_key.strip():
+            suggested_next_call = {
+                "tool_name": "app_release_edit_lock_if_mine",
+                "arguments": {
+                    "app_key": app_key,
+                    "lock_owner_name": owner.get("lock_owner_name") or "",
+                    "lock_owner_email": owner.get("lock_owner_email") or "",
+                },
+            }
+    if error.http_status is not None or error.backend_code is not None:
+        merged_details.setdefault(
+            "transport_error",
+            {
+                "http_status": error.http_status,
+                "backend_code": error.backend_code,
+                "category": error.category,
+            },
+        )
     return _failed(
-        error_code,
-        error.message,
+        effective_error_code,
+        public_message,
         recoverable=recoverable,
         normalized_args=normalized_args,
         missing_fields=missing_fields,
         allowed_values=allowed_values,
-        details=details,
+        details=merged_details,
         suggested_next_call=suggested_next_call,
         request_id=error.request_id,
         backend_code=error.backend_code,
-        http_status=error.http_status,
+        http_status=public_http_status,
     )
 
 
@@ -1708,6 +3361,52 @@ def _coerce_api_error(error: Exception) -> QingflowApiError:
     return QingflowApiError(category="runtime", message=str(error))
 
 
+def _public_error_message(error_code: str, error: QingflowApiError) -> str:
+    if error.backend_code == 40074 or error_code == "APP_EDIT_LOCKED":
+        owner = _extract_edit_lock_owner(error.message)
+        owner_label = owner.get("lock_owner_email") or owner.get("lock_owner_name")
+        if owner_label:
+            return f"app is currently locked by active editor {owner_label}"
+        return "app is currently locked by another active editor session"
+    if error.http_status != 404:
+        return error.message
+    mapping = {
+        "APP_READ_FAILED": "app base or schema is unavailable in the current route",
+        "FIELDS_READ_FAILED": "app fields are unavailable in the current route",
+        "LAYOUT_READ_FAILED": "layout resource is unavailable for this app in the current route",
+        "VIEWS_READ_FAILED": "views resource is unavailable for this app in the current route",
+        "FLOW_READ_FAILED": "workflow resource is unavailable for this app in the current route",
+        "SCHEMA_READBACK_FAILED": "schema was written but schema readback is unavailable in the current route",
+        "CREATE_APP_ROUTE_NOT_FOUND": "create app route is unavailable in the current workspace route",
+        "APP_CREATE_READBACK_FAILED": "app was created but base readback is unavailable in the current route",
+        "PACKAGE_ATTACH_FAILED": "package attachment could not be verified in the current route",
+        "PUBLISH_FAILED": "publish route is unavailable in the current route",
+        "VIEW_APPLY_FAILED": "view resource rejected the operation or is unavailable in the current route",
+        "LAYOUT_APPLY_FAILED": "layout resource rejected the operation or is unavailable in the current route",
+        "SCHEMA_APPLY_FAILED": "schema resource rejected the operation or is unavailable in the current route",
+        "EDIT_LOCK_RELEASE_FAILED": "edit lock release route is unavailable in the current route",
+    }
+    return mapping.get(error_code, "requested builder resource is unavailable in the current route")
+
+
+def _extract_edit_lock_owner(message: str) -> JSONObject:
+    text = str(message or "").strip()
+    if not text:
+        return {"lock_owner_name": None, "lock_owner_email": None}
+    patterns = [
+        r"应用已被\s*(?P<name>[^（(]+?)\s*[（(](?P<email>[^）)]+)[）)]\s*编辑",
+        r"edited by\s*(?P<name>[^<(]+?)\s*<(?P<email>[^>]+)>",
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, text)
+        if match:
+            return {
+                "lock_owner_name": match.groupdict().get("name", "").strip() or None,
+                "lock_owner_email": match.groupdict().get("email", "").strip() or None,
+            }
+    return {"lock_owner_name": None, "lock_owner_email": None}
+
+
 def _coerce_positive_int(value: Any) -> int | None:
     if isinstance(value, bool) or value is None:
         return None
@@ -1735,6 +3434,51 @@ def _coerce_int_list(values: Any) -> list[int]:
     return result
 
 
+def _normalize_view_collection(values: Any) -> list[dict[str, Any]]:
+    if isinstance(values, list):
+        normalized: list[dict[str, Any]] = []
+        for item in values:
+            if not isinstance(item, dict):
+                continue
+            nested_view_list = item.get("viewList")
+            if isinstance(nested_view_list, list):
+                normalized.extend(view for view in nested_view_list if isinstance(view, dict))
+                continue
+            normalized.append(item)
+        return normalized
+    if isinstance(values, dict):
+        for key in ("list", "viewList", "views", "result"):
+            candidate = values.get(key)
+            if isinstance(candidate, list):
+                return _normalize_view_collection(candidate)
+    return []
+
+
+def _is_view_collection_shape(values: Any) -> bool:
+    if isinstance(values, list):
+        return True
+    if isinstance(values, dict):
+        return any(isinstance(values.get(key), list) for key in ("list", "viewList", "views", "result"))
+    return False
+
+
+def _extract_view_name(view: dict[str, Any]) -> str:
+    return str(view.get("viewgraphName") or view.get("viewName") or view.get("title") or "").strip()
+
+
+def _extract_view_key(view: dict[str, Any]) -> str:
+    return str(view.get("viewgraphKey") or view.get("viewKey") or "").strip()
+
+
+def _empty_schema_result(title: str) -> dict[str, Any]:
+    return {
+        "formTitle": title,
+        "editVersionNo": 1,
+        "formQues": [],
+        "questionRelations": [],
+    }
+
+
 def _slugify(text: str, *, default: str) -> str:
     normalized = "".join(ch.lower() if ch.isalnum() else "_" for ch in str(text or ""))
     collapsed = "_".join(part for part in normalized.split("_") if part)
@@ -1753,6 +3497,7 @@ def _infer_field_type(question: dict[str, Any]) -> str:
 def _parse_field(question: dict[str, Any], *, field_id_hint: str | None = None) -> dict[str, Any]:
     name = str(question.get("queTitle") or "").strip()
     que_id = _coerce_positive_int(question.get("queId"))
+    que_type = _coerce_positive_int(question.get("queType"))
     field_type = _infer_field_type(question)
     field_id = field_id_hint or f"field_{que_id or _slugify(name, default='x')}"
     field: dict[str, Any] = {
@@ -1762,14 +3507,30 @@ def _parse_field(question: dict[str, Any], *, field_id_hint: str | None = None)
         "required": bool(question.get("required")),
         "description": question.get("queHint") or None,
         "options": [],
+        "option_details": [],
         "target_app_key": None,
         "subfields": [],
         "que_id": que_id,
+        "que_type": que_type,
     }
     if field_type in {FieldType.single_select.value, FieldType.multi_select.value, FieldType.boolean.value}:
         options = question.get("options")
         if isinstance(options, list):
-            field["options"] = [str(item.get("optValue") or "") for item in options if isinstance(item, dict) and item.get("optValue")]
+            option_values: list[str] = []
+            option_details: list[dict[str, Any]] = []
+            for item in options:
+                if not isinstance(item, dict) or not item.get("optValue"):
+                    continue
+                option_value = str(item.get("optValue") or "")
+                option_values.append(option_value)
+                option_details.append(
+                    {
+                        "id": item.get("optId"),
+                        "value": option_value,
+                    }
+                )
+            field["options"] = option_values
+            field["option_details"] = option_details
     if field_type == FieldType.relation:
         reference = question.get("referenceConfig") if isinstance(question.get("referenceConfig"), dict) else {}
         field["target_app_key"] = reference.get("referAppKey")
@@ -1827,6 +3588,79 @@ def _parse_schema(schema: dict[str, Any]) -> dict[str, Any]:
     return {"fields": fields, "layout": {"root_rows": root_rows, "sections": sections}}
 
 
+def _resolve_layout_sections_to_names(
+    requested_sections: list[dict[str, Any]],
+    fields: list[dict[str, Any]],
+) -> tuple[list[dict[str, Any]], list[Any]]:
+    by_name = {str(field.get("name") or ""): str(field.get("name") or "") for field in fields if field.get("name")}
+    by_field_id = {
+        str(field.get("field_id") or ""): str(field.get("name") or "")
+        for field in fields
+        if field.get("field_id") and field.get("name")
+    }
+    by_que_id = {
+        int(field.get("que_id")): str(field.get("name") or "")
+        for field in fields
+        if _coerce_positive_int(field.get("que_id")) is not None and field.get("name")
+    }
+    normalized_sections: list[dict[str, Any]] = []
+    missing_selectors: list[Any] = []
+    for section in requested_sections:
+        if not isinstance(section, dict):
+            continue
+        normalized_rows: list[list[str]] = []
+        for row in section.get("rows", []) or []:
+            if not isinstance(row, list):
+                continue
+            normalized_row: list[str] = []
+            for selector in row:
+                resolved_name = _resolve_layout_field_name(selector, by_name=by_name, by_field_id=by_field_id, by_que_id=by_que_id)
+                if resolved_name is None:
+                    missing_selectors.append(selector)
+                    continue
+                normalized_row.append(resolved_name)
+            if normalized_row:
+                normalized_rows.append(normalized_row)
+        normalized_section = deepcopy(section)
+        normalized_section["rows"] = normalized_rows
+        normalized_sections.append(normalized_section)
+    return normalized_sections, missing_selectors
+
+
+def _resolve_layout_field_name(
+    selector: Any,
+    *,
+    by_name: dict[str, str],
+    by_field_id: dict[str, str],
+    by_que_id: dict[int, str],
+) -> str | None:
+    if isinstance(selector, str):
+        stripped = selector.strip()
+        if not stripped:
+            return None
+        if stripped in by_name:
+            return by_name[stripped]
+        if stripped in by_field_id:
+            return by_field_id[stripped]
+        if stripped.isdigit():
+            return by_que_id.get(int(stripped))
+        return None
+    if isinstance(selector, int) and not isinstance(selector, bool):
+        return by_que_id.get(selector)
+    if isinstance(selector, dict):
+        if selector.get("name"):
+            return _resolve_layout_field_name(selector.get("name"), by_name=by_name, by_field_id=by_field_id, by_que_id=by_que_id)
+        if selector.get("title"):
+            return _resolve_layout_field_name(selector.get("title"), by_name=by_name, by_field_id=by_field_id, by_que_id=by_que_id)
+        if selector.get("label"):
+            return _resolve_layout_field_name(selector.get("label"), by_name=by_name, by_field_id=by_field_id, by_que_id=by_que_id)
+        if selector.get("field_id"):
+            return _resolve_layout_field_name(selector.get("field_id"), by_name=by_name, by_field_id=by_field_id, by_que_id=by_que_id)
+        if selector.get("que_id") is not None:
+            return _resolve_layout_field_name(selector.get("que_id"), by_name=by_name, by_field_id=by_field_id, by_que_id=by_que_id)
+    return None
+
+
 def _build_selector_map(fields: list[dict[str, Any]]) -> dict[str, int]:
     mapping: dict[str, int] = {}
     for index, field in enumerate(fields):
@@ -2112,11 +3946,147 @@ def _build_flow_preset(preset: FlowPreset) -> tuple[list[dict[str, Any]], list[d
     return nodes, transitions
 
 
+def _merge_flow_graph(
+    *,
+    base_nodes: list[dict[str, Any]],
+    base_transitions: list[dict[str, Any]],
+    override_nodes: list[dict[str, Any]],
+    override_transitions: list[dict[str, Any]],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    if not override_nodes and not override_transitions:
+        return deepcopy(base_nodes), deepcopy(base_transitions)
+    override_nodes, override_transitions = _align_flow_preset_override_ids(
+        base_nodes=base_nodes,
+        override_nodes=override_nodes,
+        override_transitions=override_transitions,
+    )
+    merged_nodes: list[dict[str, Any]] = []
+    override_map = {
+        str(node.get("id") or ""): deepcopy(node)
+        for node in override_nodes
+        if isinstance(node, dict) and str(node.get("id") or "")
+    }
+    consumed: set[str] = set()
+    for node in base_nodes:
+        node_id = str(node.get("id") or "")
+        if node_id and node_id in override_map:
+            merged = deepcopy(node)
+            merged.update(override_map[node_id])
+            if isinstance(node.get("config"), dict) and isinstance(override_map[node_id].get("config"), dict):
+                merged["config"] = {**deepcopy(node["config"]), **deepcopy(override_map[node_id]["config"])}
+            if isinstance(node.get("assignees"), dict) and isinstance(override_map[node_id].get("assignees"), dict):
+                merged["assignees"] = {**deepcopy(node["assignees"]), **deepcopy(override_map[node_id]["assignees"])}
+            if isinstance(node.get("permissions"), dict) and isinstance(override_map[node_id].get("permissions"), dict):
+                merged["permissions"] = {**deepcopy(node["permissions"]), **deepcopy(override_map[node_id]["permissions"])}
+            merged_nodes.append(merged)
+            consumed.add(node_id)
+        else:
+            merged_nodes.append(deepcopy(node))
+    for node in override_nodes:
+        node_id = str(node.get("id") or "")
+        if node_id and node_id not in consumed:
+            merged_nodes.append(deepcopy(node))
+    merged_transitions = deepcopy(override_transitions) if override_transitions else deepcopy(base_transitions)
+    return merged_nodes, merged_transitions
+
+
+def _align_flow_preset_override_ids(
+    *,
+    base_nodes: list[dict[str, Any]],
+    override_nodes: list[dict[str, Any]],
+    override_transitions: list[dict[str, Any]],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Map simple preset skeleton overrides back onto canonical preset node ids.
+
+    This keeps preset-based plans stable when the caller customizes the single
+    approval/fill/copy step semantically but forgets to reuse ids such as
+    `approve_1` or `fill_1`.
+    """
+    patchable_types = {"approve", "fill", "copy"}
+    base_by_type: dict[str, list[str]] = {}
+    override_by_type: dict[str, list[str]] = {}
+    for node in base_nodes:
+        if not isinstance(node, dict):
+            continue
+        node_type = str(node.get("type") or "")
+        node_id = str(node.get("id") or "")
+        if node_type in patchable_types and node_id:
+            base_by_type.setdefault(node_type, []).append(node_id)
+    for node in override_nodes:
+        if not isinstance(node, dict):
+            continue
+        node_type = str(node.get("type") or "")
+        node_id = str(node.get("id") or "")
+        if node_type in patchable_types and node_id:
+            override_by_type.setdefault(node_type, []).append(node_id)
+    replacement_map: dict[str, str] = {}
+    for node_type in patchable_types:
+        base_ids = base_by_type.get(node_type) or []
+        override_ids = override_by_type.get(node_type) or []
+        if len(base_ids) != 1 or len(override_ids) != 1:
+            continue
+        base_id = base_ids[0]
+        override_id = override_ids[0]
+        if override_id == base_id:
+            continue
+        replacement_map[override_id] = base_id
+    if not replacement_map:
+        return deepcopy(override_nodes), deepcopy(override_transitions)
+    aligned_nodes: list[dict[str, Any]] = []
+    for node in override_nodes:
+        if not isinstance(node, dict):
+            continue
+        aligned = deepcopy(node)
+        node_id = str(aligned.get("id") or "")
+        if node_id in replacement_map:
+            aligned["id"] = replacement_map[node_id]
+        aligned_nodes.append(aligned)
+    aligned_transitions: list[dict[str, Any]] = []
+    for transition in override_transitions:
+        if not isinstance(transition, dict):
+            continue
+        aligned = deepcopy(transition)
+        source = str(aligned.get("from") or "")
+        target = str(aligned.get("to") or "")
+        if source in replacement_map:
+            aligned["from"] = replacement_map[source]
+        if target in replacement_map:
+            aligned["to"] = replacement_map[target]
+        aligned_transitions.append(aligned)
+    return aligned_nodes, aligned_transitions
+
+
+def _extract_directory_items(listed: JSONObject) -> list[dict[str, Any]]:
+    if isinstance(listed.get("items"), list):
+        return [item for item in listed["items"] if isinstance(item, dict)]
+    result = listed.get("result")
+    if isinstance(result, dict) and isinstance(result.get("result"), list):
+        return [item for item in result["result"] if isinstance(item, dict)]
+    if isinstance(result, list):
+        return [item for item in result if isinstance(item, dict)]
+    return []
+
+
 def _build_views_preset(preset: ViewsPreset, field_names: list[str]) -> list[dict[str, Any]]:
     ordered = [name for name in field_names if name]
     if preset == ViewsPreset.status_board:
         group_by = next((name for name in ordered if "状态" in name), ordered[0] if ordered else "")
         return [{"name": "按状态看板", "type": "board", "group_by": group_by, "columns": ordered[:3] or ([group_by] if group_by else [])}]
+    if preset == ViewsPreset.default_gantt:
+        title_like = next((name for name in ordered if "名称" in name or "标题" in name), ordered[0] if ordered else "")
+        start_like = next((name for name in ordered if "开始" in name or "起始" in name), "")
+        end_like = next((name for name in ordered if "结束" in name or "截止" in name or "完成" in name), "")
+        columns = [name for name in (title_like, start_like, end_like) if name]
+        return [
+            {
+                "name": "项目甘特图",
+                "type": "gantt",
+                "columns": columns,
+                "start_field": start_like or None,
+                "end_field": end_like or None,
+                "title_field": title_like or None,
+            }
+        ]
     return [{"name": "全部数据", "type": "table", "columns": ordered[: min(5, len(ordered))]}]
 
 
@@ -2263,13 +4233,20 @@ def _summarize_views(result: Any) -> list[dict[str, Any]]:
     for view in result:
         if not isinstance(view, dict):
             continue
+        name = view.get("viewgraphName") or view.get("viewName") or view.get("title")
+        view_key = view.get("viewgraphKey") or view.get("viewKey")
+        view_type = _normalize_view_type_name(view.get("viewgraphType") or view.get("type"))
+        columns = view.get("columnNames") or view.get("columns") or []
+        group_by = view.get("groupBy") or view.get("group_by")
+        if not any((name, view_key, view_type, columns, group_by)):
+            continue
         items.append(
             {
-                "name": view.get("viewgraphName") or view.get("viewName") or view.get("title"),
-                "view_key": view.get("viewgraphKey") or view.get("viewKey"),
-                "type": view.get("viewgraphType") or view.get("type"),
-                "column_names": view.get("columnNames") or view.get("columns") or [],
-                "group_by": view.get("groupBy") or view.get("group_by"),
+                "name": name,
+                "view_key": view_key,
+                "type": view_type,
+                "columns": columns,
+                "group_by": group_by,
             }
         )
     return items
@@ -2376,8 +4353,16 @@ def _build_public_workflow_spec(*, nodes: list[dict[str, Any]], transitions: lis
             if node_map[parent_id].get("type") == "branch":
                 payload["branch_parent_id"] = parent_id
                 payload["branch_index"] = outbound[parent_id].index(node_id) + 1
-        if isinstance(node.get("config"), dict) and node["config"]:
-            payload["config"] = deepcopy(node["config"])
+        config_payload = deepcopy(node.get("config") or {}) if isinstance(node.get("config"), dict) else {}
+        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
+        assignees = node.get("assignees") or {}
+        if assignees:
+            payload["assignees"] = deepcopy(assignees)
         internal_nodes.append(payload)
     return {
         "status": "success",
@@ -2385,6 +4370,91 @@ def _build_public_workflow_spec(*, nodes: list[dict[str, Any]], transitions: lis
     }
 
 
+def _build_flow_condition_matrix(
+    *,
+    current_fields_by_name: dict[str, dict[str, Any]],
+    node: dict[str, Any],
+) -> tuple[list[list[dict[str, Any]]], list[dict[str, Any]]]:
+    if str(node.get("type") or "") != "condition":
+        return [], []
+    raw_groups = node.get("condition_groups") or []
+    if not isinstance(raw_groups, list):
+        return [], []
+    groups: list[list[dict[str, Any]]] = []
+    issues: list[dict[str, Any]] = []
+    for raw_group in raw_groups:
+        if not isinstance(raw_group, list):
+            continue
+        translated_group: list[dict[str, Any]] = []
+        for raw_rule in raw_group:
+            if not isinstance(raw_rule, dict):
+                continue
+            field_name = str(raw_rule.get("field_name") or "").strip()
+            field = current_fields_by_name.get(field_name)
+            if field is None:
+                issues.append(
+                    {
+                        "kind": "condition_fields",
+                        "error_code": "UNKNOWN_FLOW_FIELD",
+                        "missing_fields": [field_name] if field_name else [],
+                    }
+                )
+                continue
+            translated_group.append(_translate_flow_condition_rule(field=field, rule=raw_rule))
+        if translated_group:
+            groups.append(translated_group)
+    return groups, issues
+
+
+def _translate_flow_condition_rule(*, field: dict[str, Any], rule: dict[str, Any]) -> dict[str, Any]:
+    operator = str(rule.get("operator") or "").strip().lower()
+    values = list(rule.get("values") or [])
+    field_type = str(field.get("type") or FieldType.text.value)
+    que_id = _coerce_positive_int(field.get("que_id")) or 0
+    que_type = _coerce_positive_int(field.get("que_type")) or FIELD_TYPE_TO_QUESTION_TYPE.get(field_type, 2)
+    base: dict[str, Any] = {
+        "queId": que_id,
+        "queTitle": str(field.get("name") or ""),
+        "queType": que_type,
+        "matchType": MATCH_TYPE_ACCURACY,
+    }
+    if operator == "eq":
+        base["judgeType"] = JUDGE_EQUAL
+        base["judgeValues"] = [_stringify_condition_value(values[0])]
+    elif operator == "neq":
+        base["judgeType"] = JUDGE_UNEQUAL
+        base["judgeValues"] = [_stringify_condition_value(values[0])]
+    elif operator == "in":
+        base["judgeType"] = JUDGE_INCLUDE_ANY if field_type in INCLUDE_ANY_FLOW_FIELD_TYPES else JUDGE_EQUAL_ANY
+        base["judgeValues"] = [_stringify_condition_value(value) for value in values]
+    elif operator == "contains":
+        base["judgeType"] = JUDGE_FUZZY_MATCH
+        base["judgeValues"] = [_stringify_condition_value(values[0])]
+    elif operator == "gte":
+        base["judgeType"] = JUDGE_GREATER_OR_EQUAL
+        base["judgeValues"] = [_stringify_condition_value(values[0])]
+    elif operator == "lte":
+        base["judgeType"] = JUDGE_LESS_OR_EQUAL
+        base["judgeValues"] = [_stringify_condition_value(values[0])]
+    elif operator == "is_empty":
+        base["judgeType"] = JUDGE_EQUAL
+        base["judgeValues"] = []
+    elif operator == "not_empty":
+        base["judgeType"] = JUDGE_UNEQUAL
+        base["judgeValues"] = []
+    return base
+
+
+def _stringify_condition_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if value is None:
+        return ""
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, ensure_ascii=False)
+    return str(value)
+
+
 def _build_view_create_payload(
     *,
     app_key: str,
@@ -2392,15 +4462,20 @@ def _build_view_create_payload(
     schema: dict[str, Any],
     patch: ViewUpsertPatch,
     ordinal: int,
+    view_filters: list[list[dict[str, Any]]],
 ) -> JSONObject:
     entity = _entity_spec_from_app(base_info=base_info, schema=schema, views=None)
-    field_ids = [_field_id_for_name(_parse_schema(schema)["fields"], name) for name in patch.columns]
+    parsed_schema = _parse_schema(schema)
+    visible_field_names = _resolve_view_visible_field_names(patch)
+    field_ids = [_field_id_for_name(parsed_schema["fields"], name) for name in visible_field_names]
+    gantt_config = _build_public_gantt_payload(parsed_schema["fields"], extract_field_map(schema), patch)
     view_spec = ViewSpec(
         view_id=_slugify(patch.name, default=f"view_{uuid4().hex[:6]}"),
         name=patch.name,
         type=patch.type.value,
         field_ids=field_ids,
         group_by_field_id=_field_id_for_name(_parse_schema(schema)["fields"], patch.group_by) if patch.group_by else None,
+        config=gantt_config,
     )
     from ..solution.spec_models import EntitySpec
     from ..solution.compiler.view_compiler import compile_views
@@ -2408,7 +4483,7 @@ def _build_view_create_payload(
     compiled = compile_views(EntitySpec.model_validate({**entity, "views": [view_spec.model_dump(mode="json")]}))[0]
     field_map = extract_field_map(schema)
     payload = deepcopy(compiled["create_payload"])
-    visible_que_ids = [field_map[field_name] for field_name in patch.columns if field_name in field_map]
+    visible_que_ids = [field_map[field_name] for field_name in visible_field_names if field_name in field_map]
     payload["appKey"] = app_key
     payload["ordinal"] = ordinal
     payload["viewgraphQueIds"] = visible_que_ids
@@ -2416,19 +4491,19 @@ def _build_view_create_payload(
     payload["auth"] = default_member_auth()
     payload.setdefault("sortType", "defaultSort")
     payload.setdefault("viewgraphSorts", [{"queId": 0, "beingSortAscend": True, "queType": 8}])
-    payload.setdefault("beingPinNavigate", True)
-    payload.setdefault("beingShowCover", False)
-    payload.setdefault("defaultRowHigh", "compact")
-    payload.setdefault("asosChartVisible", False)
-    payload.setdefault("viewgraphLimitType", 1)
-    payload.setdefault("viewgraphLimit", [])
-    payload.setdefault("buttonConfigDTOList", [])
-    if patch.type.value in {"card", "board"}:
+    if patch.type.value in {"card", "board", "gantt"}:
         payload["beingShowTitleQue"] = True
-        payload["titleQue"] = visible_que_ids[0] if visible_que_ids else None
+        payload["titleQue"] = gantt_config.get("titleQueId") or (visible_que_ids[0] if visible_que_ids else None)
     if patch.type.value == "board":
         payload["groupQueId"] = field_map.get(patch.group_by or "")
-    return payload
+    return _hydrate_view_backend_payload(
+        payload=payload,
+        view_type=patch.type.value,
+        visible_que_id_values=visible_que_ids,
+        group_que_id=field_map.get(patch.group_by or "") if patch.group_by else None,
+        view_filters=view_filters,
+        gantt_payload=gantt_config,
+    )
 
 
 def _build_form_payload_from_existing_schema(
@@ -2551,6 +4626,10 @@ def _pick_view_template_key(existing_views: list[dict[str, Any]], *, desired_typ
 
 def _normalize_view_type_name(value: Any) -> str:
     normalized = str(value or "").strip().lower()
+    if not normalized:
+        return ""
+    if "gantt" in normalized:
+        return "gantt"
     if "board" in normalized:
         return "board"
     if "card" in normalized:
@@ -2565,14 +4644,17 @@ def _build_view_update_payload(
     source_viewgraph_key: str,
     schema: dict[str, Any],
     patch: ViewUpsertPatch,
+    view_filters: list[list[dict[str, Any]]],
 ) -> JSONObject:
     config_response = views.view_get_config(profile=profile, viewgraph_key=source_viewgraph_key)
     config = config_response.get("result") if isinstance(config_response.get("result"), dict) else {}
     payload = deepcopy(config)
     parsed_schema = _parse_schema(schema)
     field_map = extract_field_map(schema)
-    visible_que_ids = [_field_id_for_name(parsed_schema["fields"], name) for name in patch.columns]
-    visible_que_id_values = [field_map[name] for name in patch.columns if name in field_map]
+    visible_field_names = _resolve_view_visible_field_names(patch)
+    visible_que_ids = [_field_id_for_name(parsed_schema["fields"], name) for name in visible_field_names]
+    visible_que_id_values = [field_map[name] for name in visible_field_names if name in field_map]
+    gantt_payload = _build_public_gantt_payload(parsed_schema["fields"], field_map, patch)
 
     for key in (
         "appKey",
@@ -2600,7 +4682,7 @@ def _build_view_update_payload(
     payload.setdefault("beingShowCover", False)
     payload.setdefault("defaultRowHigh", "compact")
     payload.setdefault("viewgraphLimitType", 1)
-    payload.setdefault("viewgraphLimit", [])
+    payload.setdefault("viewgraphLimit", deepcopy(view_filters) if view_filters else [])
     payload.setdefault("buttonConfigDTOList", [])
 
     normalized_type = patch.type.value
@@ -2620,7 +4702,385 @@ def _build_view_update_payload(
         payload["beingShowTitleQue"] = True
         payload["titleQue"] = visible_que_id_values[0] if visible_que_id_values else None
         payload["groupQueId"] = field_map.get(patch.group_by or "")
-    return payload
+    elif normalized_type == "gantt":
+        payload["viewgraphType"] = "ganttView"
+        payload["beingShowTitleQue"] = True
+        payload["titleQue"] = gantt_payload.get("titleQueId") or (visible_que_id_values[0] if visible_que_id_values else None)
+        payload.pop("groupQueId", None)
+    return _hydrate_view_backend_payload(
+        payload=payload,
+        view_type=normalized_type,
+        visible_que_id_values=visible_que_id_values,
+        group_que_id=field_map.get(patch.group_by or "") if patch.group_by else None,
+        view_filters=view_filters,
+        gantt_payload=gantt_payload,
+    )
+
+
+def _build_minimal_view_payload(
+    *,
+    app_key: str,
+    schema: dict[str, Any],
+    patch: ViewUpsertPatch,
+    ordinal: int,
+    view_filters: list[list[dict[str, Any]]],
+) -> JSONObject:
+    field_map = extract_field_map(schema)
+    parsed_schema = _parse_schema(schema)
+    visible_field_names = _resolve_view_visible_field_names(patch)
+    visible_que_id_values = [field_map[name] for name in visible_field_names if name in field_map]
+    gantt_payload = _build_public_gantt_payload(parsed_schema["fields"], field_map, patch)
+    payload: JSONObject = {
+        "appKey": app_key,
+        "viewgraphName": patch.name,
+        "viewgraphType": {
+            "table": "tableView",
+            "card": "cardView",
+            "board": "boardView",
+            "gantt": "ganttView",
+        }[patch.type.value],
+        "ordinal": ordinal,
+        "viewgraphQueIds": visible_que_id_values,
+        "viewgraphQuestions": _build_viewgraph_questions(schema, visible_que_id_values),
+        "auth": default_member_auth(),
+    }
+    if patch.type.value in {"card", "board", "gantt"}:
+        payload["beingShowTitleQue"] = True
+        payload["titleQue"] = gantt_payload.get("titleQueId") or (visible_que_id_values[0] if visible_que_id_values else None)
+    if patch.type.value == "board":
+        payload["groupQueId"] = field_map.get(patch.group_by or "")
+    return _hydrate_view_backend_payload(
+        payload=payload,
+        view_type=patch.type.value,
+        visible_que_id_values=visible_que_id_values,
+        group_que_id=field_map.get(patch.group_by or "") if patch.group_by else None,
+        view_filters=view_filters,
+        gantt_payload=gantt_payload,
+    )
+
+
+def _hydrate_view_backend_payload(
+    *,
+    payload: JSONObject,
+    view_type: str,
+    visible_que_id_values: list[int],
+    group_que_id: int | None,
+    view_filters: list[list[dict[str, Any]]] | None = None,
+    gantt_payload: dict[str, Any] | None = None,
+) -> JSONObject:
+    data = deepcopy(payload)
+    data.setdefault("beingPinNavigate", True)
+    data.setdefault("beingNeedPass", False)
+    data.setdefault("beingShowTitleQue", view_type in {"card", "board"})
+    data.setdefault("beingShowCover", False)
+    data.setdefault("defaultRowHigh", "compact")
+    data.setdefault("asosChartVisible", False)
+    data.setdefault("viewgraphPass", "")
+    data.setdefault("beingGroupColor", False)
+    data.setdefault("beingShowQueTitle", True)
+    data.setdefault("beingImageAdaption", False)
+    data.setdefault("clippingMode", "default")
+    data.setdefault("frontCoverQueId", None)
+    data.setdefault("viewgraphLimitType", 1)
+    data.setdefault("viewgraphLimit", deepcopy(view_filters) if view_filters else [])
+    data.setdefault("viewgraphLimitFormula", "")
+    data.setdefault("sortType", "defaultSort")
+    if not data.get("viewgraphSorts"):
+        sort_que_id = visible_que_id_values[0] if visible_que_id_values else 1
+        data["viewgraphSorts"] = [{"queId": sort_que_id, "beingSortAscend": True}]
+    data.setdefault("beingAuditRecordVisible", True)
+    data.setdefault("beingQrobotRecordVisible", False)
+    data.setdefault("beingPrintStatus", False)
+    data.setdefault("beingDefaultPrintTplStatus", False)
+    data.setdefault("printTpls", [])
+    data.setdefault("beingCommentStatus", False)
+    data.setdefault("usages", [])
+    data.setdefault("dataPermissionType", "CUSTOM")
+    data.setdefault("dataScope", "ALL")
+    data.setdefault("needPass", False)
+    data.setdefault("beingWorkflowNodeFutureListVisible", True)
+    data.setdefault("asosChartConfig", {"limitType": 1, "asosChartIdList": []})
+    data.setdefault("viewgraphGanttConfigVO", None)
+    data.setdefault("viewgraphHierarchyConfigVO", None)
+    data.setdefault("buttonConfigDTOList", [])
+    if "buttonConfig" not in data:
+        data["buttonConfig"] = {"topButtonList": [], "mainButtonDetailList": [], "moreButtonDetailList": []}
+    if view_type == "table":
+        data["viewgraphType"] = "tableView"
+        data["beingShowTitleQue"] = False
+        data["titleQue"] = None
+        data["groupQueId"] = None
+    elif view_type == "card":
+        data["viewgraphType"] = "cardView"
+        data["beingShowTitleQue"] = True
+        data["titleQue"] = visible_que_id_values[0] if visible_que_id_values else None
+        data["groupQueId"] = None
+    elif view_type == "board":
+        data["viewgraphType"] = "boardView"
+        data["beingShowTitleQue"] = True
+        data["titleQue"] = visible_que_id_values[0] if visible_que_id_values else None
+        data["groupQueId"] = group_que_id
+    elif view_type == "gantt":
+        data["viewgraphType"] = "ganttView"
+        data["beingShowTitleQue"] = True
+        data["titleQue"] = (gantt_payload or {}).get("titleQueId") or (visible_que_id_values[0] if visible_que_id_values else None)
+        data["groupQueId"] = None
+        data["viewgraphGanttConfigVO"] = deepcopy(gantt_payload) if gantt_payload else None
+    if view_filters is not None:
+        data["viewgraphLimit"] = deepcopy(view_filters)
+    return data
+
+
+def _resolve_view_visible_field_names(patch: ViewUpsertPatch) -> list[str]:
+    ordered: list[str] = []
+    for value in [*patch.columns, patch.title_field, patch.start_field, patch.end_field, patch.group_by]:
+        name = str(value or "").strip()
+        if name and name not in ordered:
+            ordered.append(name)
+    return ordered
+
+
+def _build_public_gantt_payload(
+    fields: list[dict[str, Any]],
+    field_map: dict[str, int],
+    patch: ViewUpsertPatch,
+) -> dict[str, Any]:
+    if patch.type.value != "gantt":
+        return {}
+    title_field_name = str((patch.title_field or (patch.columns[0] if patch.columns else "")) or "").strip()
+    start_field_name = str(patch.start_field or "").strip()
+    end_field_name = str(patch.end_field or "").strip()
+    return {
+        "titleQueId": field_map.get(title_field_name),
+        "startTimeQueId": field_map.get(start_field_name),
+        "endTimeQueId": field_map.get(end_field_name),
+        "defaultTimeDimension": "week",
+        "ganttGroupVOList": [],
+        "ganttDependencyVO": {
+            "dependencyQueId": None,
+            "predecessorTaskQueId": None,
+            "startEndOptionId": None,
+            "startStartOptionId": None,
+            "endEndOptionId": None,
+            "endStartOptionId": None,
+        },
+        "ganttAutoCalibrationVO": {
+            "autoCalibrationRuleVO": {
+                "startStartBegin": False,
+                "startEndBegin": False,
+                "startEndFinish": False,
+                "endStartBegin": True,
+                "endStartFinish": True,
+                "endEndFinish": False,
+            },
+            "beingAutoCalibration": False,
+            "userAutoCalibration": False,
+        },
+    }
+
+
+def _build_view_filter_groups(
+    *,
+    current_fields_by_name: dict[str, dict[str, Any]],
+    filters: list[Any],
+) -> tuple[list[list[dict[str, Any]]], list[dict[str, Any]]]:
+    translated_rules: list[dict[str, Any]] = []
+    issues: list[dict[str, Any]] = []
+    for raw_rule in filters:
+        if hasattr(raw_rule, "model_dump"):
+            raw_rule = raw_rule.model_dump(mode="json")
+        if not isinstance(raw_rule, dict):
+            continue
+        field_name = str(raw_rule.get("field_name") or "").strip()
+        field = current_fields_by_name.get(field_name)
+        if field is None:
+            issues.append(
+                {
+                    "error_code": "UNKNOWN_VIEW_FIELD",
+                    "missing_fields": [field_name] if field_name else [],
+                    "reason_path": "filters[].field_name",
+                }
+            )
+            continue
+        translated_rule, issue = _translate_view_filter_rule(field=field, rule=raw_rule)
+        if issue:
+            issues.append(issue)
+            continue
+        translated_rules.append(translated_rule)
+    return ([translated_rules] if translated_rules else []), issues
+
+
+def _translate_view_filter_rule(*, field: dict[str, Any], rule: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any] | None]:
+    operator = str(rule.get("operator") or "").strip().lower()
+    values = list(rule.get("values") or [])
+    field_type = str(field.get("type") or FieldType.text.value)
+    que_id = _coerce_positive_int(field.get("que_id")) or 0
+    que_type = _coerce_positive_int(field.get("que_type")) or FIELD_TYPE_TO_QUESTION_TYPE.get(field_type, 2)
+    judge_values, judge_value_details, issue = _resolve_view_filter_values(field=field, values=values)
+    if issue:
+        return {}, issue
+    payload: dict[str, Any] = {
+        "queId": que_id,
+        "queTitle": str(field.get("name") or ""),
+        "queType": que_type,
+        "matchType": MATCH_TYPE_ACCURACY,
+        "judgeValueDetails": judge_value_details,
+    }
+    if operator == "eq":
+        payload["judgeType"] = JUDGE_EQUAL
+        payload["judgeValues"] = judge_values[:1] if judge_values else []
+    elif operator == "neq":
+        payload["judgeType"] = JUDGE_UNEQUAL
+        payload["judgeValues"] = judge_values[:1] if judge_values else []
+    elif operator == "in":
+        payload["judgeType"] = JUDGE_INCLUDE_ANY if field_type in INCLUDE_ANY_FLOW_FIELD_TYPES else JUDGE_EQUAL_ANY
+        payload["judgeValues"] = judge_values
+    elif operator == "contains":
+        payload["judgeType"] = JUDGE_FUZZY_MATCH
+        payload["judgeValues"] = judge_values[:1] if judge_values else []
+    elif operator == "gte":
+        payload["judgeType"] = JUDGE_GREATER_OR_EQUAL
+        payload["judgeValues"] = judge_values[:1] if judge_values else []
+    elif operator == "lte":
+        payload["judgeType"] = JUDGE_LESS_OR_EQUAL
+        payload["judgeValues"] = judge_values[:1] if judge_values else []
+    elif operator == "is_empty":
+        payload["judgeType"] = JUDGE_EQUAL
+        payload["judgeValues"] = []
+    elif operator == "not_empty":
+        payload["judgeType"] = JUDGE_UNEQUAL
+        payload["judgeValues"] = []
+    return payload, None
+
+
+def _resolve_view_filter_values(
+    *,
+    field: dict[str, Any],
+    values: list[Any],
+) -> tuple[list[str], list[dict[str, Any]], dict[str, Any] | None]:
+    field_type = str(field.get("type") or FieldType.text.value)
+    if field_type not in {FieldType.single_select.value, FieldType.multi_select.value, FieldType.boolean.value}:
+        return [_stringify_condition_value(value) for value in values], _build_view_filter_value_details(values), None
+
+    option_details = [
+        item
+        for item in (field.get("option_details") or [])
+        if isinstance(item, dict) and item.get("id") is not None and item.get("value") is not None
+    ]
+    if not option_details:
+        return [_stringify_condition_value(value) for value in values], _build_view_filter_value_details(values), None
+
+    option_by_value = {str(item.get("value") or "").strip(): item for item in option_details if str(item.get("value") or "").strip()}
+    option_by_id = {str(item.get("id")): item for item in option_details if item.get("id") is not None}
+    resolved_details: list[dict[str, Any]] = []
+    unresolved_values: list[str] = []
+    for value in values:
+        resolved = _resolve_view_filter_option_detail(value=value, option_by_value=option_by_value, option_by_id=option_by_id)
+        if resolved is None:
+            unresolved_values.append(_stringify_condition_value(value))
+            continue
+        resolved_details.append({"id": resolved.get("id"), "value": str(resolved.get("value") or resolved.get("id"))})
+    if unresolved_values:
+        return (
+            [],
+            [],
+            {
+                "error_code": "UNKNOWN_VIEW_FILTER_VALUE",
+                "reason_path": "filters[].values",
+                "missing_fields": [],
+                "allowed_values": {"filter_values": sorted(option_by_value.keys())},
+                "details": {
+                    "field_name": str(field.get("name") or ""),
+                    "unresolved_values": unresolved_values,
+                },
+            },
+        )
+    return (
+        [str(detail["id"]) for detail in resolved_details if detail.get("id") is not None],
+        [_coerce_view_filter_value_detail(detail) for detail in resolved_details],
+        None,
+    )
+
+
+def _resolve_view_filter_option_detail(
+    *,
+    value: Any,
+    option_by_value: dict[str, dict[str, Any]],
+    option_by_id: dict[str, dict[str, Any]],
+) -> dict[str, Any] | None:
+    if isinstance(value, dict):
+        item_id = value.get("id")
+        if item_id is not None:
+            matched = option_by_id.get(str(item_id))
+            if matched is not None:
+                return matched
+        item_value = str(value.get("value") or "").strip()
+        if item_value:
+            return option_by_value.get(item_value)
+        return None
+    if isinstance(value, int):
+        return option_by_id.get(str(value))
+    normalized = str(value or "").strip()
+    if not normalized:
+        return None
+    return option_by_value.get(normalized) or option_by_id.get(normalized)
+
+
+def _build_view_filter_value_details(values: list[Any]) -> list[dict[str, Any]]:
+    details: list[dict[str, Any]] = []
+    for value in values:
+        if isinstance(value, dict):
+            item_id = value.get("id")
+            if item_id is None:
+                continue
+            item_value = value.get("value")
+            details.append(_coerce_view_filter_value_detail({"id": item_id, "value": item_value if item_value is not None else str(item_id)}))
+        elif isinstance(value, int):
+            details.append(_coerce_view_filter_value_detail({"id": value, "value": str(value)}))
+    return details
+
+
+def _coerce_view_filter_value_detail(value: dict[str, Any]) -> dict[str, Any]:
+    item_id = value.get("id")
+    item_value = value.get("value")
+    return {
+        "id": item_id,
+        "value": item_value if item_value is not None else (str(item_id) if item_id is not None else None),
+        "dataValue": value.get("dataValue"),
+        "email": value.get("email"),
+        "optionId": value.get("optionId"),
+        "ordinal": value.get("ordinal"),
+        "otherInfo": value.get("otherInfo"),
+        "pluginValue": value.get("pluginValue"),
+        "queId": value.get("queId"),
+    }
+
+
+def _normalize_view_filter_groups_for_compare(groups: Any) -> list[list[dict[str, Any]]]:
+    normalized_groups: list[list[dict[str, Any]]] = []
+    for raw_group in groups or []:
+        if not isinstance(raw_group, list):
+            continue
+        normalized_rules: list[dict[str, Any]] = []
+        for raw_rule in raw_group:
+            if not isinstance(raw_rule, dict):
+                continue
+            normalized_details = []
+            for detail in raw_rule.get("judgeValueDetails") or []:
+                if not isinstance(detail, dict) or detail.get("id") is None:
+                    continue
+                normalized_details.append({"id": detail.get("id"), "value": str(detail.get("value") or detail.get("id"))})
+            normalized_rules.append(
+                {
+                    "queId": _coerce_positive_int(raw_rule.get("queId")) or 0,
+                    "judgeType": _coerce_positive_int(raw_rule.get("judgeType")) or 0,
+                    "judgeValues": [str(value) for value in (raw_rule.get("judgeValues") or [])],
+                    "judgeValueDetails": normalized_details,
+                }
+            )
+        if normalized_rules:
+            normalized_groups.append(normalized_rules)
+    return normalized_groups
 
 
 def _infer_status_field_id(fields: list[dict[str, Any]]) -> str | None:
@@ -2654,6 +5114,7 @@ def _normalize_flow_stage_failure(stage: JSONObject, *, profile: str, app_key: s
             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",
@@ -2686,14 +5147,45 @@ def _normalize_flow_stage_failure(stage: JSONObject, *, profile: str, app_key: s
             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,
-        detail_text or "failed to apply workflow patch",
-        details={"app_key": app_key, "entity_id": entity.get("entity_id"), "stage_result": public_stage_result},
+        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=http_status,
+        http_status=public_http_status,
     )