@josephyan/qingflow-cli 0.2.0-beta.61 → 0.2.0-beta.63

package/src/qingflow_mcp/builder_facade/service.py

@@ -21,6 +21,7 @@ from ..solution.compiler.view_compiler import VIEW_TYPE_MAP
 from ..solution.executor import _build_viewgraph_questions, _compact_dict, extract_field_map
 from ..solution.spec_models import FieldType, FormLayoutRowSpec, FormLayoutSectionSpec, ViewSpec
 from ..tools.app_tools import AppTools
+from ..tools.custom_button_tools import CustomButtonTools
 from ..tools.directory_tools import DirectoryTools
 from ..tools.package_tools import PackageTools
 from ..tools.portal_tools import PortalTools
@@ -39,6 +40,8 @@ from .models import (
     AppViewsReadResponse,
     ChartApplyRequest,
     ChartUpsertPatch,
+    CustomButtonMatchRulePatch,
+    CustomButtonPatch,
     FieldPatch,
     FieldRemovePatch,
     FieldSelector,
@@ -54,8 +57,12 @@ from .models import (
     PublicFieldType,
     PublicRelationMode,
     PublicChartType,
+    PublicButtonTriggerAction,
     PublicViewType,
+    PublicViewButtonConfigType,
+    PublicViewButtonType,
     SchemaPlanRequest,
+    ViewButtonBindingPatch,
     ViewUpsertPatch,
     ViewFilterOperator,
     ViewsPlanRequest,
@@ -142,6 +149,7 @@ class AiBuilderFacade:
         self,
         *,
         apps: AppTools,
+        buttons: CustomButtonTools,
         packages: PackageTools,
         views: ViewTools,
         workflows: WorkflowTools,
@@ -152,6 +160,7 @@ class AiBuilderFacade:
         solutions: SolutionTools,
     ) -> None:
         self.apps = apps
+        self.buttons = buttons
         self.packages = packages
         self.views = views
         self.workflows = workflows
@@ -1291,6 +1300,333 @@ class AiBuilderFacade:
             **match,
         }
 
+    def app_custom_button_list(self, *, profile: str, app_key: str) -> JSONObject:
+        normalized_args = {"app_key": app_key}
+        permission_outcomes: list[PermissionCheckOutcome] = []
+        permission_outcome = self._guard_app_permission(
+            profile=profile,
+            app_key=app_key,
+            required_permission="edit_app",
+            normalized_args=normalized_args,
+        )
+        if permission_outcome.block is not None:
+            return permission_outcome.block
+        permission_outcomes.append(permission_outcome)
+
+        def finalize(response: JSONObject) -> JSONObject:
+            return _apply_permission_outcomes(response, *permission_outcomes)
+
+        listing = self.buttons.custom_button_list(profile=profile, app_key=app_key, being_draft=True, include_raw=False)
+        items = [
+            _normalize_custom_button_summary(item)
+            for item in (listing.get("items") or [])
+            if isinstance(item, dict)
+        ]
+        return finalize(
+            {
+                "status": "success",
+                "error_code": None,
+                "recoverable": False,
+                "message": "read custom button summary",
+                "normalized_args": normalized_args,
+                "missing_fields": [],
+                "allowed_values": {},
+                "details": {},
+                "request_id": None,
+                "suggested_next_call": None,
+                "noop": False,
+                "warnings": [],
+                "verification": {"custom_buttons_verified": True},
+                "verified": True,
+                "app_key": app_key,
+                "count": len(items),
+                "buttons": items,
+            }
+        )
+
+    def app_custom_button_get(self, *, profile: str, app_key: str, button_id: int) -> JSONObject:
+        normalized_args = {"app_key": app_key, "button_id": button_id}
+        permission_outcomes: list[PermissionCheckOutcome] = []
+        permission_outcome = self._guard_app_permission(
+            profile=profile,
+            app_key=app_key,
+            required_permission="edit_app",
+            normalized_args=normalized_args,
+        )
+        if permission_outcome.block is not None:
+            return permission_outcome.block
+        permission_outcomes.append(permission_outcome)
+
+        def finalize(response: JSONObject) -> JSONObject:
+            return _apply_permission_outcomes(response, *permission_outcomes)
+
+        detail = self.buttons.custom_button_get(
+            profile=profile,
+            app_key=app_key,
+            button_id=button_id,
+            being_draft=True,
+            include_raw=False,
+        )
+        button = _normalize_custom_button_detail(detail.get("result") if isinstance(detail.get("result"), dict) else {})
+        return finalize(
+            {
+                "status": "success",
+                "error_code": None,
+                "recoverable": False,
+                "message": "read custom button detail",
+                "normalized_args": normalized_args,
+                "missing_fields": [],
+                "allowed_values": {},
+                "details": {},
+                "request_id": None,
+                "suggested_next_call": None,
+                "noop": False,
+                "warnings": [],
+                "verification": {"custom_button_verified": True},
+                "verified": True,
+                "app_key": app_key,
+                "button_id": button_id,
+                "button": button,
+            }
+        )
+
+    def app_custom_button_create(self, *, profile: str, app_key: str, payload: CustomButtonPatch) -> JSONObject:
+        normalized_args = {"app_key": app_key, "payload": payload.model_dump(mode="json")}
+        permission_outcomes: list[PermissionCheckOutcome] = []
+        permission_outcome = self._guard_app_permission(
+            profile=profile,
+            app_key=app_key,
+            required_permission="edit_app",
+            normalized_args=normalized_args,
+        )
+        if permission_outcome.block is not None:
+            return permission_outcome.block
+        permission_outcomes.append(permission_outcome)
+
+        def finalize(response: JSONObject) -> JSONObject:
+            return _apply_permission_outcomes(response, *permission_outcomes)
+
+        create_result = self.buttons.custom_button_create(
+            profile=profile,
+            app_key=app_key,
+            payload=_serialize_custom_button_payload(payload),
+        )
+        raw_result = create_result.get("result")
+        button_id = _extract_custom_button_id(raw_result)
+        if button_id is None:
+            return finalize(
+                _failed(
+                    "CUSTOM_BUTTON_CREATE_FAILED",
+                    "custom button create succeeded but no button_id was returned",
+                    normalized_args=normalized_args,
+                    details={"app_key": app_key, "result": deepcopy(raw_result)},
+                    suggested_next_call={"tool_name": "app_custom_button_list", "arguments": {"profile": profile, "app_key": app_key}},
+                )
+            )
+        try:
+            readback = self.buttons.custom_button_get(
+                profile=profile,
+                app_key=app_key,
+                button_id=button_id,
+                being_draft=True,
+                include_raw=False,
+            )
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            response = {
+                "status": "partial_success",
+                "error_code": "CUSTOM_BUTTON_READBACK_PENDING",
+                "recoverable": True,
+                "message": "created custom button; detail readback unavailable",
+                "normalized_args": normalized_args,
+                "missing_fields": [],
+                "allowed_values": {},
+                "details": {
+                    "app_key": app_key,
+                    "button_id": button_id,
+                    "transport_error": _transport_error_payload(api_error),
+                },
+                "request_id": api_error.request_id,
+                "suggested_next_call": {
+                    "tool_name": "app_custom_button_get",
+                    "arguments": {"profile": profile, "app_key": app_key, "button_id": button_id},
+                },
+                "noop": False,
+                "warnings": [_warning("CUSTOM_BUTTON_READBACK_PENDING", "custom button was created, but detail readback is not available")],
+                "verification": {"custom_button_verified": False},
+                "verified": False,
+                "app_key": app_key,
+                "button_id": button_id,
+            }
+            if _is_permission_restricted_api_error(api_error):
+                response = _apply_permission_outcomes(
+                    response,
+                    _verification_read_outcome(
+                        resource="custom_button",
+                        target={"app_key": app_key, "button_id": button_id},
+                        transport_error=api_error,
+                    ),
+                )
+            return finalize(response)
+        button = _normalize_custom_button_detail(readback.get("result") if isinstance(readback.get("result"), dict) else {})
+        return finalize(
+            {
+                "status": "success",
+                "error_code": None,
+                "recoverable": False,
+                "message": "created custom button",
+                "normalized_args": normalized_args,
+                "missing_fields": [],
+                "allowed_values": {},
+                "details": {},
+                "request_id": None,
+                "suggested_next_call": None,
+                "noop": False,
+                "warnings": [],
+                "verification": {"custom_button_verified": True},
+                "verified": True,
+                "app_key": app_key,
+                "button_id": button_id,
+                "button": button,
+            }
+        )
+
+    def app_custom_button_update(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        button_id: int,
+        payload: CustomButtonPatch,
+    ) -> JSONObject:
+        normalized_args = {"app_key": app_key, "button_id": button_id, "payload": payload.model_dump(mode="json")}
+        permission_outcomes: list[PermissionCheckOutcome] = []
+        permission_outcome = self._guard_app_permission(
+            profile=profile,
+            app_key=app_key,
+            required_permission="edit_app",
+            normalized_args=normalized_args,
+        )
+        if permission_outcome.block is not None:
+            return permission_outcome.block
+        permission_outcomes.append(permission_outcome)
+
+        def finalize(response: JSONObject) -> JSONObject:
+            return _apply_permission_outcomes(response, *permission_outcomes)
+
+        self.buttons.custom_button_update(
+            profile=profile,
+            app_key=app_key,
+            button_id=button_id,
+            payload=_serialize_custom_button_payload(payload),
+        )
+        try:
+            readback = self.buttons.custom_button_get(
+                profile=profile,
+                app_key=app_key,
+                button_id=button_id,
+                being_draft=True,
+                include_raw=False,
+            )
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            response = {
+                "status": "partial_success",
+                "error_code": "CUSTOM_BUTTON_READBACK_PENDING",
+                "recoverable": True,
+                "message": "updated custom button; detail readback unavailable",
+                "normalized_args": normalized_args,
+                "missing_fields": [],
+                "allowed_values": {},
+                "details": {
+                    "app_key": app_key,
+                    "button_id": button_id,
+                    "transport_error": _transport_error_payload(api_error),
+                },
+                "request_id": api_error.request_id,
+                "suggested_next_call": {
+                    "tool_name": "app_custom_button_get",
+                    "arguments": {"profile": profile, "app_key": app_key, "button_id": button_id},
+                },
+                "noop": False,
+                "warnings": [_warning("CUSTOM_BUTTON_READBACK_PENDING", "custom button was updated, but detail readback is not available")],
+                "verification": {"custom_button_verified": False},
+                "verified": False,
+                "app_key": app_key,
+                "button_id": button_id,
+            }
+            if _is_permission_restricted_api_error(api_error):
+                response = _apply_permission_outcomes(
+                    response,
+                    _verification_read_outcome(
+                        resource="custom_button",
+                        target={"app_key": app_key, "button_id": button_id},
+                        transport_error=api_error,
+                    ),
+                )
+            return finalize(response)
+        button = _normalize_custom_button_detail(readback.get("result") if isinstance(readback.get("result"), dict) else {})
+        return finalize(
+            {
+                "status": "success",
+                "error_code": None,
+                "recoverable": False,
+                "message": "updated custom button",
+                "normalized_args": normalized_args,
+                "missing_fields": [],
+                "allowed_values": {},
+                "details": {},
+                "request_id": None,
+                "suggested_next_call": None,
+                "noop": False,
+                "warnings": [],
+                "verification": {"custom_button_verified": True},
+                "verified": True,
+                "app_key": app_key,
+                "button_id": button_id,
+                "button": button,
+            }
+        )
+
+    def app_custom_button_delete(self, *, profile: str, app_key: str, button_id: int) -> JSONObject:
+        normalized_args = {"app_key": app_key, "button_id": button_id}
+        permission_outcomes: list[PermissionCheckOutcome] = []
+        permission_outcome = self._guard_app_permission(
+            profile=profile,
+            app_key=app_key,
+            required_permission="edit_app",
+            normalized_args=normalized_args,
+        )
+        if permission_outcome.block is not None:
+            return permission_outcome.block
+        permission_outcomes.append(permission_outcome)
+
+        def finalize(response: JSONObject) -> JSONObject:
+            return _apply_permission_outcomes(response, *permission_outcomes)
+
+        self.buttons.custom_button_delete(profile=profile, app_key=app_key, button_id=button_id)
+        return finalize(
+            {
+                "status": "success",
+                "error_code": None,
+                "recoverable": False,
+                "message": "deleted custom button",
+                "normalized_args": normalized_args,
+                "missing_fields": [],
+                "allowed_values": {},
+                "details": {},
+                "request_id": None,
+                "suggested_next_call": None,
+                "noop": False,
+                "warnings": [],
+                "verification": {"custom_button_deleted": True},
+                "verified": True,
+                "app_key": app_key,
+                "button_id": button_id,
+                "deleted": True,
+            }
+        )
+
     def _resolve_app_matches_in_visible_apps(
         self,
         *,
@@ -3303,6 +3639,35 @@ class AiBuilderFacade:
             for field in parsed_schema["fields"]
             if isinstance(field, dict) and str(field.get("name") or "")
         }
+        requires_custom_button_validation = any(
+            any(binding.button_type == PublicViewButtonType.custom for binding in (patch.buttons or []))
+            for patch in upsert_views
+        )
+        valid_custom_button_ids: set[int] = set()
+        if requires_custom_button_validation:
+            try:
+                button_listing = self.buttons.custom_button_list(
+                    profile=profile,
+                    app_key=app_key,
+                    being_draft=True,
+                    include_raw=False,
+                )
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                return finalize(
+                    _failed_from_api_error(
+                        "CUSTOM_BUTTON_LIST_FAILED",
+                        api_error,
+                        normalized_args=normalized_args,
+                        details=_with_state_read_blocked_details({"app_key": app_key}, resource="custom_button", error=api_error),
+                        suggested_next_call={"tool_name": "app_custom_button_list", "arguments": {"profile": profile, "app_key": app_key}},
+                    )
+                )
+            valid_custom_button_ids = {
+                button_id
+                for item in (button_listing.get("items") or [])
+                if isinstance(item, dict) and (button_id := _coerce_positive_int(item.get("button_id"))) is not None
+            }
         removed: list[str] = []
         view_results: list[dict[str, Any]] = []
         for name in remove_views:
@@ -3396,6 +3761,30 @@ class AiBuilderFacade:
                     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}},
                 )
+            explicit_button_dtos: list[dict[str, Any]] | None = None
+            expected_button_summary: list[dict[str, Any]] | None = None
+            if patch.buttons is not None:
+                explicit_button_dtos, button_issues = _build_view_button_dtos(
+                    current_fields_by_name=current_fields_by_name,
+                    bindings=patch.buttons,
+                    valid_custom_button_ids=valid_custom_button_ids,
+                )
+                if button_issues:
+                    first_issue = button_issues[0]
+                    return _failed(
+                        str(first_issue.get("error_code") or "INVALID_VIEW_BUTTON"),
+                        "view buttons reference invalid fields, values, or custom buttons",
+                        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_custom_button_list", "arguments": {"profile": profile, "app_key": app_key}},
+                    )
+                expected_button_summary = _normalize_view_buttons_for_compare(explicit_button_dtos or [])
             matched_existing_view: dict[str, Any] | None = None
             existing_key: str | None = None
             if patch.view_key:
@@ -3441,6 +3830,8 @@ class AiBuilderFacade:
                         schema=schema,
                         patch=patch,
                         view_filters=translated_filters,
+                        current_fields_by_name=current_fields_by_name,
+                        explicit_button_dtos=explicit_button_dtos,
                     )
                     self.views.view_update(profile=profile, viewgraph_key=existing_key, payload=payload)
                     system_view_sync: dict[str, Any] | None = None
@@ -3481,14 +3872,15 @@ class AiBuilderFacade:
                     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),
-                            "system_view_sync": system_view_sync,
-                        }
-                    )
+                                "name": patch.name,
+                                "view_key": existing_key,
+                                "type": patch.type.value,
+                                "status": "updated",
+                                "expected_filters": deepcopy(translated_filters),
+                                "expected_buttons": deepcopy(expected_button_summary),
+                                "system_view_sync": system_view_sync,
+                            }
+                        )
                 else:
                     template_key = _pick_view_template_key(existing_view_list, desired_type=patch.type.value)
                     should_copy_template = patch.type.value == "table" and template_key and not translated_filters
@@ -3502,6 +3894,8 @@ class AiBuilderFacade:
                             schema=schema,
                             patch=patch,
                             view_filters=translated_filters,
+                            current_fields_by_name=current_fields_by_name,
+                            explicit_button_dtos=explicit_button_dtos,
                         )
                         self.views.view_update(profile=profile, viewgraph_key=created_key, payload=payload)
                     else:
@@ -3512,6 +3906,8 @@ class AiBuilderFacade:
                             patch=patch,
                             ordinal=ordinal,
                             view_filters=translated_filters,
+                            current_fields_by_name=current_fields_by_name,
+                            explicit_button_dtos=explicit_button_dtos,
                         )
                         create_result = self.views.view_create(profile=profile, payload=payload)
                         raw_created = create_result.get("result")
@@ -3522,14 +3918,15 @@ class AiBuilderFacade:
                             created_key = raw_created.strip() or None
                     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),
-                        }
-                    )
+                            {
+                                "name": patch.name,
+                                "view_key": created_key,
+                                "type": patch.type.value,
+                                "status": "created",
+                                "expected_filters": deepcopy(translated_filters),
+                                "expected_buttons": deepcopy(expected_button_summary),
+                            }
+                        )
             except (QingflowApiError, RuntimeError) as error:
                 api_error = _coerce_api_error(error)
                 should_retry_minimal = operation_phase != "default_view_apply_config_sync" and (
@@ -3540,12 +3937,23 @@ class AiBuilderFacade:
                     try:
                         if existing_key or created_key:
                             target_key = created_key or existing_key or ""
+                            fallback_button_dtos = explicit_button_dtos
+                            if fallback_button_dtos is None:
+                                fallback_config_response = self.views.view_get_config(profile=profile, viewgraph_key=target_key)
+                                fallback_config = (
+                                    fallback_config_response.get("result")
+                                    if isinstance(fallback_config_response.get("result"), dict)
+                                    else {}
+                                )
+                                fallback_button_dtos = _extract_existing_view_button_dtos(fallback_config)
                             fallback_payload = _build_minimal_view_payload(
                                 app_key=app_key,
                                 schema=schema,
                                 patch=patch,
                                 ordinal=ordinal,
                                 view_filters=translated_filters,
+                                current_fields_by_name=current_fields_by_name,
+                                explicit_button_dtos=fallback_button_dtos,
                             )
                             self.views.view_update(profile=profile, viewgraph_key=target_key, payload=fallback_payload)
                             if existing_key:
@@ -3558,6 +3966,7 @@ class AiBuilderFacade:
                                         "status": "updated",
                                         "fallback_applied": True,
                                         "expected_filters": deepcopy(translated_filters),
+                                        "expected_buttons": deepcopy(expected_button_summary),
                                     }
                                 )
                             else:
@@ -3570,6 +3979,7 @@ class AiBuilderFacade:
                                         "status": "created",
                                         "fallback_applied": True,
                                         "expected_filters": deepcopy(translated_filters),
+                                        "expected_buttons": deepcopy(expected_button_summary),
                                     }
                                 )
                             continue
@@ -3579,6 +3989,8 @@ class AiBuilderFacade:
                             patch=patch,
                             ordinal=ordinal,
                             view_filters=translated_filters,
+                            current_fields_by_name=current_fields_by_name,
+                            explicit_button_dtos=explicit_button_dtos,
                         )
                         self.views.view_create(profile=profile, payload=fallback_payload)
                         created.append(patch.name)
@@ -3665,6 +4077,8 @@ class AiBuilderFacade:
         verification_by_view: list[dict[str, Any]] = []
         filter_readback_pending = False
         filter_mismatches: list[dict[str, Any]] = []
+        button_readback_pending = False
+        button_mismatches: list[dict[str, Any]] = []
         for item in view_results:
             status = str(item.get("status") or "")
             name = str(item.get("name") or "")
@@ -3688,6 +4102,7 @@ class AiBuilderFacade:
                 if isinstance(system_view_sync, dict):
                     verification_entry["system_view_sync"] = deepcopy(system_view_sync)
                 expected_filters = item.get("expected_filters") or []
+                expected_buttons = item.get("expected_buttons") if isinstance(item.get("expected_buttons"), list) else None
                 if expected_filters:
                     if verified_views_unavailable or not present_in_readback:
                         verification_entry["filters_verified"] = None
@@ -3743,6 +4158,54 @@ class AiBuilderFacade:
                                 "category": api_error.category,
                             }
                             filter_readback_pending = True
+                if expected_buttons is not None:
+                    if verified_views_unavailable or not present_in_readback:
+                        verification_entry["buttons_verified"] = None
+                        verification_entry["button_readback_pending"] = True
+                        button_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["buttons_verified"] = None
+                                verification_entry["button_readback_pending"] = True
+                                verification_entry["readback_ambiguous"] = True
+                                verification_entry["matching_view_keys"] = matched_keys
+                                button_readback_pending = True
+                                verification_by_view.append(verification_entry)
+                                continue
+                        try:
+                            config_response = self.views.view_get_config(profile=profile, viewgraph_key=verification_key)
+                            config_result = (config_response.get("result") or {}) if isinstance(config_response.get("result"), dict) else {}
+                            actual_buttons = _normalize_view_buttons_for_compare(config_result)
+                            buttons_verified = actual_buttons == expected_buttons
+                            verification_entry["buttons_verified"] = buttons_verified
+                            verification_entry["view_key"] = verification_key
+                            verification_entry["expected_buttons"] = deepcopy(expected_buttons)
+                            verification_entry["actual_buttons"] = actual_buttons
+                            if not buttons_verified:
+                                button_mismatches.append(
+                                    {
+                                        "name": name,
+                                        "type": item.get("type"),
+                                        "expected_buttons": deepcopy(expected_buttons),
+                                        "actual_buttons": actual_buttons,
+                                    }
+                                )
+                        except (QingflowApiError, RuntimeError) as error:
+                            api_error = _coerce_api_error(error)
+                            verification_entry["buttons_verified"] = None
+                            verification_entry["button_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,
+                            }
+                            button_readback_pending = True
                 verification_by_view.append(verification_entry)
             elif status == "removed":
                 verification_by_view.append(
@@ -3769,6 +4232,7 @@ class AiBuilderFacade:
             and all(name not in verified_names for name in removed)
         )
         view_filters_verified = verified and not filter_readback_pending and not filter_mismatches
+        view_buttons_verified = verified and not button_readback_pending and not button_mismatches
         noop = not created and not updated and not removed
         if failed_views:
             successful_changes = bool(created or updated or removed)
@@ -3781,34 +4245,48 @@ class AiBuilderFacade:
                 "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},
+                "details": {
+                    "per_view_results": view_results,
+                    "filter_mismatches": filter_mismatches,
+                    "button_mismatches": button_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,
-                "warnings": [_warning("VIEW_FILTERS_UNVERIFIED", "view definitions may exist, but saved filter behavior is not fully verified")] if (filter_readback_pending or filter_mismatches) else [],
+                "warnings": (
+                    [_warning("VIEW_FILTERS_UNVERIFIED", "view definitions may exist, but saved filter behavior is not fully verified")] if (filter_readback_pending or filter_mismatches) else []
+                )
+                + (
+                    [_warning("VIEW_BUTTONS_UNVERIFIED", "view definitions may exist, but saved button behavior is not fully verified")] if (button_readback_pending or button_mismatches) else []
+                ),
                 "verification": {
                     "views_verified": verified,
                     "view_filters_verified": view_filters_verified,
+                    "view_buttons_verified": view_buttons_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 and view_filters_verified,
+                "verified": verified and view_filters_verified and view_buttons_verified,
             }
             return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
         warnings: list[dict[str, Any]] = []
         if filter_readback_pending or filter_mismatches:
             warnings.append(_warning("VIEW_FILTERS_UNVERIFIED", "view definitions were applied, but saved filter behavior is not fully verified"))
+        if button_readback_pending or button_mismatches:
+            warnings.append(_warning("VIEW_BUTTONS_UNVERIFIED", "view definitions were applied, but saved button behavior is not fully verified"))
         response = {
-            "status": "success" if verified and view_filters_verified else "partial_success",
-            "error_code": None if verified and view_filters_verified else ("VIEW_FILTER_READBACK_MISMATCH" if filter_mismatches else "VIEWS_READBACK_PENDING"),
-            "recoverable": not (verified and view_filters_verified),
+            "status": "success" if verified and view_filters_verified and view_buttons_verified else "partial_success",
+            "error_code": None if verified and view_filters_verified and view_buttons_verified else ("VIEW_BUTTON_READBACK_MISMATCH" if button_mismatches else "VIEW_FILTER_READBACK_MISMATCH" if filter_mismatches else "VIEWS_READBACK_PENDING"),
+            "recoverable": not (verified and view_filters_verified and view_buttons_verified),
             "message": (
                 "applied view patch"
-                if verified and view_filters_verified
+                if verified and view_filters_verified and view_buttons_verified
+                else "applied view patch; buttons did not fully verify"
+                if button_mismatches
                 else "applied view patch; filters did not fully verify"
                 if filter_mismatches
                 else "applied view patch; views readback pending"
@@ -3816,21 +4294,26 @@ class AiBuilderFacade:
             "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": {"filter_mismatches": filter_mismatches} if filter_mismatches else {},
+            "details": {
+                **({"filter_mismatches": filter_mismatches} if filter_mismatches else {}),
+                **({"button_mismatches": button_mismatches} if button_mismatches else {}),
+            },
             "request_id": None,
-            "suggested_next_call": None if verified and view_filters_verified else {"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            "suggested_next_call": None if verified and view_filters_verified and view_buttons_verified else {"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
             "noop": noop,
             "warnings": warnings,
             "verification": {
                 "views_verified": verified,
                 "view_filters_verified": view_filters_verified,
+                "view_buttons_verified": view_buttons_verified,
                 "views_read_unavailable": verified_views_unavailable,
                 "filter_readback_pending": filter_readback_pending,
+                "button_readback_pending": button_readback_pending,
                 "by_view": verification_by_view,
             },
             "app_key": app_key,
             "views_diff": {"created": created, "updated": updated, "removed": removed, "failed": []},
-            "verified": verified and view_filters_verified,
+            "verified": verified and view_filters_verified and view_buttons_verified,
         }
         return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
 
@@ -5002,6 +5485,156 @@ class AiBuilderFacade:
             raise QingflowApiError(category="runtime", message="failed to attach app to package")
 
 
+def _extract_custom_button_id(value: Any) -> int | None:
+    if isinstance(value, dict):
+        for key in ("buttonId", "customButtonId", "id"):
+            button_id = _coerce_positive_int(value.get(key))
+            if button_id is not None:
+                return button_id
+        nested_result = value.get("result")
+        if nested_result is not value:
+            return _extract_custom_button_id(nested_result)
+        return None
+    return _coerce_positive_int(value)
+
+
+def _serialize_custom_button_payload(payload: CustomButtonPatch) -> dict[str, Any]:
+    data = payload.model_dump(mode="json", exclude_none=True)
+    serialized: dict[str, Any] = {
+        "buttonText": data["button_text"],
+        "backgroundColor": data["background_color"],
+        "textColor": data["text_color"],
+        "buttonIcon": data["button_icon"],
+        "triggerAction": data["trigger_action"],
+    }
+    if str(data.get("trigger_link_url") or "").strip():
+        serialized["triggerLinkUrl"] = data["trigger_link_url"]
+    trigger_add_data_config = data.get("trigger_add_data_config")
+    if isinstance(trigger_add_data_config, dict):
+        serialized["triggerAddDataConfig"] = _serialize_custom_button_add_data_config(trigger_add_data_config)
+    external_qrobot_config = data.get("external_qrobot_config")
+    if isinstance(external_qrobot_config, dict):
+        serialized["customButtonExternalQRobotRelationVO"] = _serialize_custom_button_external_qrobot_config(external_qrobot_config)
+    trigger_wings_config = data.get("trigger_wings_config")
+    if isinstance(trigger_wings_config, dict):
+        serialized["triggerWingsConfig"] = _serialize_custom_button_wings_config(trigger_wings_config)
+    return serialized
+
+
+def _serialize_custom_button_add_data_config(value: dict[str, Any]) -> dict[str, Any]:
+    relation_rules = value.get("que_relation") or []
+    return {
+        "relatedAppKey": value.get("related_app_key"),
+        "relatedAppName": value.get("related_app_name"),
+        "queRelation": [_serialize_custom_button_match_rule(rule) for rule in relation_rules if isinstance(rule, dict)],
+    }
+
+
+def _serialize_custom_button_external_qrobot_config(value: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "externalQRobotConfigId": value.get("external_qrobot_config_id"),
+        "triggeredText": value.get("triggered_text"),
+    }
+
+
+def _serialize_custom_button_wings_config(value: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "wingsAgentId": value.get("wings_agent_id"),
+        "wingsAgentName": value.get("wings_agent_name"),
+        "bindQueIdList": list(value.get("bind_que_id_list") or []),
+        "bindFileQueIdList": list(value.get("bind_file_que_id_list") or []),
+        "defaultPrompt": value.get("default_prompt"),
+        "beingAutoSend": value.get("being_auto_send"),
+    }
+
+
+def _serialize_custom_button_match_rule(value: dict[str, Any]) -> dict[str, Any]:
+    serialized = {
+        "queId": value.get("que_id"),
+        "queTitle": value.get("que_title"),
+        "queType": value.get("que_type"),
+        "dateType": value.get("date_type"),
+        "judgeType": value.get("judge_type"),
+        "matchType": value.get("match_type"),
+        "judgeValues": list(value.get("judge_values") or []),
+        "judgeQueType": value.get("judge_que_type"),
+        "judgeQueId": value.get("judge_que_id"),
+        "pathValue": value.get("path_value"),
+        "tableUpdateType": value.get("table_update_type"),
+        "multiValue": value.get("multi_value"),
+        "addRule": value.get("add_rule"),
+        "fieldIdPrefix": value.get("field_id_prefix"),
+    }
+    judge_que_detail = value.get("judge_que_detail")
+    if isinstance(judge_que_detail, dict):
+        serialized["judgeQueDetail"] = {
+            "queId": judge_que_detail.get("que_id"),
+            "queTitle": judge_que_detail.get("que_title"),
+            "queType": judge_que_detail.get("que_type"),
+        }
+    judge_value_details = value.get("judge_value_details")
+    if isinstance(judge_value_details, list):
+        serialized["judgeValueDetails"] = [
+            {"id": item.get("id"), "value": item.get("value")}
+            for item in judge_value_details
+            if isinstance(item, dict)
+        ]
+    filter_condition = value.get("filter_condition")
+    if isinstance(filter_condition, list):
+        serialized["filterCondition"] = [
+            [_serialize_custom_button_match_rule(item) for item in group if isinstance(item, dict)]
+            for group in filter_condition
+            if isinstance(group, list)
+        ]
+    return {key: deepcopy(item) for key, item in serialized.items() if item is not None}
+
+
+def _normalize_custom_button_summary(item: dict[str, Any]) -> dict[str, Any]:
+    normalized = {
+        "button_id": _coerce_positive_int(item.get("button_id") or item.get("buttonId") or item.get("id")),
+        "button_text": str(item.get("button_text") or item.get("buttonText") or "").strip() or None,
+        "button_icon": str(item.get("button_icon") or item.get("buttonIcon") or "").strip() or None,
+        "background_color": str(item.get("background_color") or item.get("backgroundColor") or "").strip() or None,
+        "text_color": str(item.get("text_color") or item.get("textColor") or "").strip() or None,
+        "used_in_chart_count": _coerce_nonnegative_int(item.get("used_in_chart_count") or item.get("userInChartCount")),
+        "being_effective_external_qrobot": bool(item.get("being_effective_external_qrobot") or item.get("beingEffectiveExternalQRobot")),
+    }
+    creator = item.get("creator_user_info") if isinstance(item.get("creator_user_info"), dict) else item.get("creatorUserInfo")
+    if isinstance(creator, dict):
+        normalized["creator_user_info"] = {
+            "uid": creator.get("uid"),
+            "name": creator.get("name"),
+            "email": creator.get("email"),
+        }
+    return normalized
+
+
+def _normalize_custom_button_detail(item: dict[str, Any]) -> dict[str, Any]:
+    normalized = _normalize_custom_button_summary(item)
+    normalized.update(
+        {
+            "trigger_action": str(item.get("trigger_action") or item.get("triggerAction") or "").strip() or None,
+            "trigger_link_url": str(item.get("trigger_link_url") or item.get("triggerLinkUrl") or "").strip() or None,
+        }
+    )
+    trigger_add_data_config = item.get("trigger_add_data_config")
+    if not isinstance(trigger_add_data_config, dict):
+        trigger_add_data_config = item.get("triggerAddDataConfig")
+    if isinstance(trigger_add_data_config, dict):
+        normalized["trigger_add_data_config"] = deepcopy(trigger_add_data_config)
+    external_qrobot_config = item.get("external_qrobot_config")
+    if not isinstance(external_qrobot_config, dict):
+        external_qrobot_config = item.get("customButtonExternalQRobotRelationVO")
+    if isinstance(external_qrobot_config, dict):
+        normalized["external_qrobot_config"] = deepcopy(external_qrobot_config)
+    trigger_wings_config = item.get("trigger_wings_config")
+    if not isinstance(trigger_wings_config, dict):
+        trigger_wings_config = item.get("triggerWingsConfig")
+    if isinstance(trigger_wings_config, dict):
+        normalized["trigger_wings_config"] = deepcopy(trigger_wings_config)
+    return normalized
+
+
 def _failed(
     error_code: str,
     message: str,
@@ -7467,6 +8100,18 @@ def _merge_view_summary_with_config(base: dict[str, Any], *, config: dict[str, A
         if not summary.get("group_by") and display_config.get("group_by"):
             summary["group_by"] = display_config.get("group_by")
         config_enriched = True
+    button_entries, button_source = _extract_view_button_entries(config)
+    if button_entries:
+        summary["buttons"] = [_normalize_view_button_entry(entry) for entry in button_entries]
+        summary["button_count"] = len(button_entries)
+        if button_source:
+            summary["button_read_source"] = button_source
+        config_enriched = True
+    elif button_source:
+        summary["buttons"] = []
+        summary["button_count"] = 0
+        summary["button_read_source"] = button_source
+        config_enriched = True
     if config_enriched:
         summary["read_source"] = "view_config"
     return summary
@@ -7580,6 +8225,339 @@ def _extract_view_display_config(
     return display_config
 
 
+def _normalize_view_button_type(value: Any) -> str | None:
+    normalized = str(value or "").strip().upper()
+    if normalized in {"SYSTEM", "CUSTOM"}:
+        return normalized
+    return None
+
+
+def _normalize_view_button_config_type(value: Any) -> str | None:
+    normalized = str(value or "").strip().upper()
+    if normalized in {"TOP", "DETAIL"}:
+        return normalized
+    return None
+
+
+def _normalize_print_tpls(value: Any) -> list[dict[str, Any]]:
+    if not isinstance(value, list):
+        return []
+    items: list[dict[str, Any]] = []
+    for item in value:
+        if isinstance(item, dict):
+            tpl_id = item.get("printTplId")
+            if tpl_id is None:
+                tpl_id = item.get("templateId")
+            if tpl_id is None:
+                tpl_id = item.get("id")
+            tpl_name = item.get("printTplName")
+            if tpl_name is None:
+                tpl_name = item.get("templateName")
+            if tpl_name is None:
+                tpl_name = item.get("name")
+            normalized: dict[str, Any] = {}
+            if tpl_id is not None:
+                normalized["id"] = str(tpl_id)
+            if str(tpl_name or "").strip():
+                normalized["name"] = str(tpl_name).strip()
+            if normalized:
+                items.append(normalized)
+            continue
+        scalar = str(item or "").strip()
+        if scalar:
+            items.append({"id": scalar})
+    return items
+
+
+def _normalize_print_tpls_for_compare(value: Any) -> list[str]:
+    normalized_items: list[str] = []
+    for item in _normalize_print_tpls(value):
+        item_id = str(item.get("id") or "").strip()
+        item_name = str(item.get("name") or "").strip()
+        normalized_items.append(item_id or item_name)
+    return normalized_items
+
+
+def _serialize_print_tpl_ids(value: Any) -> list[str]:
+    return [item for item in _normalize_print_tpls_for_compare(value) if item]
+
+
+def _extract_view_button_entries(config: dict[str, Any]) -> tuple[list[dict[str, Any]], str | None]:
+    if not isinstance(config, dict):
+        return [], None
+    raw_vo = config.get("buttonConfigVO")
+    if isinstance(raw_vo, list):
+        return [deepcopy(item) for item in raw_vo if isinstance(item, dict)], "buttonConfigVO"
+    raw_dtos = config.get("buttonConfigDTOList")
+    if isinstance(raw_dtos, list):
+        return [deepcopy(item) for item in raw_dtos if isinstance(item, dict)], "buttonConfigDTOList"
+    grouped = config.get("buttonConfig")
+    if not isinstance(grouped, dict):
+        return [], None
+    entries: list[dict[str, Any]] = []
+    for item in grouped.get("topButtonList") or []:
+        if not isinstance(item, dict):
+            continue
+        entry = deepcopy(item)
+        entry.setdefault("configType", "TOP")
+        entry.setdefault("beingMain", True)
+        entries.append(entry)
+    for item in grouped.get("mainButtonDetailList") or []:
+        if not isinstance(item, dict):
+            continue
+        entry = deepcopy(item)
+        entry.setdefault("configType", "DETAIL")
+        entry["beingMain"] = True
+        entries.append(entry)
+    for item in grouped.get("moreButtonDetailList") or []:
+        if not isinstance(item, dict):
+            continue
+        entry = deepcopy(item)
+        entry.setdefault("configType", "DETAIL")
+        entry["beingMain"] = False
+        entries.append(entry)
+    return entries, "buttonConfig"
+
+
+def _normalize_view_button_entry(entry: dict[str, Any]) -> dict[str, Any]:
+    button_id = _coerce_positive_int(entry.get("buttonId") or entry.get("button_id") or entry.get("id"))
+    button_text = str(entry.get("buttonText") or "").strip() or None
+    default_button_text = str(entry.get("defaultButtonText") or "").strip() or None
+    normalized: dict[str, Any] = {
+        "button_type": _normalize_view_button_type(entry.get("buttonType") or entry.get("button_type")),
+        "config_type": _normalize_view_button_config_type(entry.get("configType") or entry.get("config_type")),
+        "button_id": button_id,
+        "button_text": button_text or default_button_text,
+        "being_main": bool(entry.get("beingMain", False)),
+        "trigger_action": str(entry.get("triggerAction") or "").strip() or None,
+        "print_tpls": _normalize_print_tpls(entry.get("printTpls")),
+        "button_formula_type": _coerce_positive_int(entry.get("buttonFormulaType")) or 1,
+        "button_limit": _normalize_view_filter_groups_for_compare(entry.get("buttonLimit")),
+    }
+    for public_key, source_key in (
+        ("default_button_text", "defaultButtonText"),
+        ("button_icon", "buttonIcon"),
+        ("background_color", "backgroundColor"),
+        ("text_color", "textColor"),
+        ("trigger_link_url", "triggerLinkUrl"),
+        ("button_formula", "buttonFormula"),
+    ):
+        value = entry.get(source_key)
+        if isinstance(value, str):
+            value = value.strip() or None
+        if value not in {None, ""}:
+            normalized[public_key] = deepcopy(value)
+    trigger_add_data_config = entry.get("triggerAddDataConfig")
+    if isinstance(trigger_add_data_config, dict):
+        normalized["trigger_add_data_config"] = deepcopy(trigger_add_data_config)
+    trigger_wings_config = entry.get("triggerWingsConfig")
+    if isinstance(trigger_wings_config, dict):
+        normalized["trigger_wings_config"] = deepcopy(trigger_wings_config)
+    return normalized
+
+
+def _normalize_view_buttons_for_compare(value: Any) -> list[dict[str, Any]]:
+    if isinstance(value, dict):
+        entries, _ = _extract_view_button_entries(value)
+    elif isinstance(value, list):
+        entries = [item for item in value if isinstance(item, dict)]
+    else:
+        entries = []
+    normalized_entries: list[dict[str, Any]] = []
+    for entry in entries:
+        normalized = _normalize_view_button_entry(entry)
+        normalized_entries.append(
+            {
+                "button_type": normalized.get("button_type"),
+                "config_type": normalized.get("config_type"),
+                "button_id": normalized.get("button_id"),
+                "button_text": normalized.get("button_text"),
+                "button_icon": normalized.get("button_icon"),
+                "background_color": normalized.get("background_color"),
+                "text_color": normalized.get("text_color"),
+                "trigger_action": normalized.get("trigger_action"),
+                "trigger_link_url": normalized.get("trigger_link_url"),
+                "being_main": bool(normalized.get("being_main", False)),
+                "print_tpls": _normalize_print_tpls_for_compare(normalized.get("print_tpls")),
+                "button_formula": str(normalized.get("button_formula") or ""),
+                "button_formula_type": _coerce_positive_int(normalized.get("button_formula_type")) or 1,
+                "button_limit": deepcopy(normalized.get("button_limit") or []),
+            }
+        )
+    return normalized_entries
+
+
+def _serialize_existing_view_button_entry(entry: dict[str, Any]) -> dict[str, Any]:
+    dto: dict[str, Any] = {}
+    button_id = _coerce_positive_int(entry.get("buttonId") or entry.get("button_id") or entry.get("id"))
+    if button_id is not None:
+        dto["buttonId"] = button_id
+    button_type = _normalize_view_button_type(entry.get("buttonType") or entry.get("button_type"))
+    if button_type is not None:
+        dto["buttonType"] = button_type
+    config_type = _normalize_view_button_config_type(entry.get("configType") or entry.get("config_type"))
+    if config_type is not None:
+        dto["configType"] = config_type
+    dto["beingMain"] = bool(entry.get("beingMain", False))
+    dto["buttonLimit"] = deepcopy(entry.get("buttonLimit") or [])
+    dto["buttonFormula"] = str(entry.get("buttonFormula") or "")
+    dto["buttonFormulaType"] = _coerce_positive_int(entry.get("buttonFormulaType")) or 1
+    dto["printTpls"] = _serialize_print_tpl_ids(entry.get("printTpls"))
+    for source_key, target_key in (
+        ("buttonText", "buttonText"),
+        ("buttonIcon", "buttonIcon"),
+        ("backgroundColor", "backgroundColor"),
+        ("textColor", "textColor"),
+        ("triggerAction", "triggerAction"),
+        ("triggerLinkUrl", "triggerLinkUrl"),
+    ):
+        if source_key in entry:
+            dto[target_key] = deepcopy(entry.get(source_key))
+    if isinstance(entry.get("triggerAddDataConfig"), dict):
+        dto["triggerAddDataConfig"] = deepcopy(entry.get("triggerAddDataConfig"))
+    if isinstance(entry.get("triggerWingsConfig"), dict):
+        dto["triggerWingsConfig"] = deepcopy(entry.get("triggerWingsConfig"))
+    return dto
+
+
+def _extract_existing_view_button_dtos(config: dict[str, Any]) -> list[dict[str, Any]]:
+    if not isinstance(config, dict):
+        return []
+    button_config_dtos = config.get("buttonConfigDTOList")
+    if isinstance(button_config_dtos, list):
+        return [deepcopy(item) for item in button_config_dtos if isinstance(item, dict)]
+    entries, _ = _extract_view_button_entries(config)
+    return [_serialize_existing_view_button_entry(entry) for entry in entries if isinstance(entry, dict)]
+
+
+def _resolve_view_button_dtos_for_patch(
+    *,
+    config: dict[str, Any],
+    patch: ViewUpsertPatch,
+    explicit_button_dtos: list[dict[str, Any]] | None,
+) -> list[dict[str, Any]] | None:
+    if patch.buttons is None:
+        return _extract_existing_view_button_dtos(config)
+    return deepcopy(explicit_button_dtos or [])
+
+
+def _build_grouped_view_button_config(button_config_dtos: list[dict[str, Any]]) -> dict[str, list[dict[str, Any]]]:
+    grouped = {"topButtonList": [], "mainButtonDetailList": [], "moreButtonDetailList": []}
+    for raw_item in button_config_dtos:
+        if not isinstance(raw_item, dict):
+            continue
+        item = deepcopy(raw_item)
+        config_type = _normalize_view_button_config_type(item.get("configType"))
+        being_main = bool(item.get("beingMain", False))
+        if config_type == "TOP":
+            grouped["topButtonList"].append(item)
+        elif being_main:
+            grouped["mainButtonDetailList"].append(item)
+        else:
+            grouped["moreButtonDetailList"].append(item)
+    return grouped
+
+
+def _build_view_button_dtos(
+    *,
+    current_fields_by_name: dict[str, dict[str, Any]],
+    bindings: list[ViewButtonBindingPatch],
+    valid_custom_button_ids: set[int],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    dtos: list[dict[str, Any]] = []
+    issues: list[dict[str, Any]] = []
+    for binding in bindings:
+        dto, binding_issues = _serialize_view_button_binding(
+            binding=binding,
+            current_fields_by_name=current_fields_by_name,
+            valid_custom_button_ids=valid_custom_button_ids,
+        )
+        if binding_issues:
+            issues.extend(binding_issues)
+            continue
+        dtos.append(dto)
+    return dtos, issues
+
+
+def _serialize_view_button_binding(
+    *,
+    binding: ViewButtonBindingPatch,
+    current_fields_by_name: dict[str, dict[str, Any]],
+    valid_custom_button_ids: set[int],
+) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    if binding.button_type == PublicViewButtonType.custom and binding.button_id not in valid_custom_button_ids:
+        return {}, [
+            {
+                "error_code": "UNKNOWN_CUSTOM_BUTTON",
+                "reason_path": "buttons[].button_id",
+                "missing_fields": [],
+                "details": {"button_id": binding.button_id},
+            }
+        ]
+    translated_limits, limit_issues = _build_view_button_limit_groups(
+        current_fields_by_name=current_fields_by_name,
+        groups=binding.button_limit,
+    )
+    if limit_issues:
+        return {}, limit_issues
+    dto: dict[str, Any] = {
+        "buttonId": binding.button_id,
+        "buttonType": binding.button_type.value,
+        "configType": binding.config_type.value,
+        "beingMain": bool(binding.being_main),
+        "buttonLimit": translated_limits,
+        "buttonFormula": binding.button_formula or "",
+        "buttonFormulaType": binding.button_formula_type,
+        "printTpls": _serialize_print_tpl_ids(binding.print_tpls),
+    }
+    if binding.button_type == PublicViewButtonType.system:
+        dto["buttonText"] = binding.button_text
+        dto["buttonIcon"] = binding.button_icon
+        dto["backgroundColor"] = binding.background_color
+        dto["textColor"] = binding.text_color
+        dto["triggerAction"] = binding.trigger_action
+    return dto, []
+
+
+def _build_view_button_limit_groups(
+    *,
+    current_fields_by_name: dict[str, dict[str, Any]],
+    groups: list[list[ViewFilterRulePatch]],
+) -> tuple[list[list[dict[str, Any]]], list[dict[str, Any]]]:
+    translated_groups: list[list[dict[str, Any]]] = []
+    issues: list[dict[str, Any]] = []
+    for raw_group in groups:
+        if not isinstance(raw_group, list):
+            continue
+        translated_rules: list[dict[str, Any]] = []
+        for raw_rule in raw_group:
+            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": "buttons[].button_limit[].field_name",
+                    }
+                )
+                continue
+            translated_rule, issue = _translate_view_filter_rule(field=field, rule=raw_rule)
+            if issue:
+                issue = deepcopy(issue)
+                issue["reason_path"] = "buttons[].button_limit[].values"
+                issues.append(issue)
+                continue
+            translated_rules.append(translated_rule)
+        if translated_rules:
+            translated_groups.append(translated_rules)
+    return translated_groups, issues
+
+
 def _summarize_charts(result: Any) -> list[dict[str, Any]]:
     if not isinstance(result, list):
         return []
@@ -7929,6 +8907,8 @@ def _build_view_create_payload(
     patch: ViewUpsertPatch,
     ordinal: int,
     view_filters: list[list[dict[str, Any]]],
+    current_fields_by_name: dict[str, dict[str, Any]],
+    explicit_button_dtos: list[dict[str, Any]] | None = None,
 ) -> JSONObject:
     entity = _entity_spec_from_app(base_info=base_info, schema=schema, views=None)
     parsed_schema = _parse_schema(schema)
@@ -7969,6 +8949,7 @@ def _build_view_create_payload(
         group_que_id=field_map.get(patch.group_by or "") if patch.group_by else None,
         view_filters=view_filters,
         gantt_payload=gantt_config,
+        button_config_dtos=explicit_button_dtos,
     )
 
 
@@ -8111,6 +9092,8 @@ def _build_view_update_payload(
     schema: dict[str, Any],
     patch: ViewUpsertPatch,
     view_filters: list[list[dict[str, Any]]],
+    current_fields_by_name: dict[str, dict[str, Any]],
+    explicit_button_dtos: list[dict[str, Any]] | None = None,
 ) -> 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 {}
@@ -8149,7 +9132,11 @@ def _build_view_update_payload(
     payload.setdefault("defaultRowHigh", "compact")
     payload.setdefault("viewgraphLimitType", 1)
     payload.setdefault("viewgraphLimit", deepcopy(view_filters) if view_filters else [])
-    payload.setdefault("buttonConfigDTOList", [])
+    button_config_dtos = _resolve_view_button_dtos_for_patch(
+        config=config,
+        patch=patch,
+        explicit_button_dtos=explicit_button_dtos,
+    )
 
     normalized_type = patch.type.value
     existing_type = _normalize_view_type_name(payload.get("viewgraphType") or payload.get("type"))
@@ -8180,6 +9167,7 @@ def _build_view_update_payload(
         group_que_id=field_map.get(patch.group_by or "") if patch.group_by else None,
         view_filters=view_filters,
         gantt_payload=gantt_payload,
+        button_config_dtos=button_config_dtos,
     )
 
 
@@ -8190,6 +9178,8 @@ def _build_minimal_view_payload(
     patch: ViewUpsertPatch,
     ordinal: int,
     view_filters: list[list[dict[str, Any]]],
+    current_fields_by_name: dict[str, dict[str, Any]],
+    explicit_button_dtos: list[dict[str, Any]] | None = None,
 ) -> JSONObject:
     field_map = extract_field_map(schema)
     parsed_schema = _parse_schema(schema)
@@ -8222,6 +9212,7 @@ def _build_minimal_view_payload(
         group_que_id=field_map.get(patch.group_by or "") if patch.group_by else None,
         view_filters=view_filters,
         gantt_payload=gantt_payload,
+        button_config_dtos=explicit_button_dtos,
     )
 
 
@@ -8233,6 +9224,7 @@ def _hydrate_view_backend_payload(
     group_que_id: int | None,
     view_filters: list[list[dict[str, Any]]] | None = None,
     gantt_payload: dict[str, Any] | None = None,
+    button_config_dtos: list[dict[str, Any]] | None = None,
 ) -> JSONObject:
     data = deepcopy(payload)
     data.setdefault("beingPinNavigate", True)
@@ -8268,9 +9260,11 @@ def _hydrate_view_backend_payload(
     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 button_config_dtos is not None:
+        data["buttonConfigDTOList"] = deepcopy(button_config_dtos)
+        data["buttonConfig"] = _build_grouped_view_button_config(button_config_dtos)
+    else:
+        data.pop("buttonConfigVO", None)
     if view_type == "table":
         data["viewgraphType"] = "tableView"
         data["beingShowTitleQue"] = False