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

package/src/qingflow_mcp/builder_facade/service.py

@@ -16,7 +16,7 @@ from ..list_type_labels import RECORD_LIST_TYPE_LABELS, SYSTEM_VIEW_ID_TO_LIST_T
 from ..solution.build_assembly_store import BuildAssemblyStore, default_artifacts, default_manifest
 from ..solution.compiler.chart_compiler import qingbi_workspace_visible_auth
 from ..solution.compiler.form_compiler import build_question, default_form_payload, default_member_auth
-from ..solution.compiler.icon_utils import encode_workspace_icon
+from ..solution.compiler.icon_utils import encode_workspace_icon_with_defaults
 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
@@ -1406,6 +1406,15 @@ class AiBuilderFacade:
         def finalize(response: JSONObject) -> JSONObject:
             return _apply_permission_outcomes(response, *permission_outcomes)
 
+        edit_version_no, edit_context_error = self._ensure_app_edit_context(
+            profile=profile,
+            app_key=app_key,
+            normalized_args=normalized_args,
+            failure_code="CUSTOM_BUTTON_CREATE_FAILED",
+        )
+        if edit_context_error is not None:
+            return finalize(edit_context_error)
+
         create_result = self.buttons.custom_button_create(
             profile=profile,
             app_key=app_key,
@@ -1419,7 +1428,7 @@ class AiBuilderFacade:
                     "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)},
+                    details={"app_key": app_key, "result": deepcopy(raw_result), "edit_version_no": edit_version_no},
                     suggested_next_call={"tool_name": "app_custom_button_list", "arguments": {"profile": profile, "app_key": app_key}},
                 )
             )
@@ -1444,6 +1453,7 @@ class AiBuilderFacade:
                 "details": {
                     "app_key": app_key,
                     "button_id": button_id,
+                    "edit_version_no": edit_version_no,
                     "transport_error": _transport_error_payload(api_error),
                 },
                 "request_id": api_error.request_id,
@@ -1487,6 +1497,7 @@ class AiBuilderFacade:
                 "verified": True,
                 "app_key": app_key,
                 "button_id": button_id,
+                "edit_version_no": edit_version_no,
                 "button": button,
             }
         )
@@ -1514,6 +1525,15 @@ class AiBuilderFacade:
         def finalize(response: JSONObject) -> JSONObject:
             return _apply_permission_outcomes(response, *permission_outcomes)
 
+        edit_version_no, edit_context_error = self._ensure_app_edit_context(
+            profile=profile,
+            app_key=app_key,
+            normalized_args=normalized_args,
+            failure_code="CUSTOM_BUTTON_UPDATE_FAILED",
+        )
+        if edit_context_error is not None:
+            return finalize(edit_context_error)
+
         self.buttons.custom_button_update(
             profile=profile,
             app_key=app_key,
@@ -1541,6 +1561,7 @@ class AiBuilderFacade:
                 "details": {
                     "app_key": app_key,
                     "button_id": button_id,
+                    "edit_version_no": edit_version_no,
                     "transport_error": _transport_error_payload(api_error),
                 },
                 "request_id": api_error.request_id,
@@ -1584,6 +1605,7 @@ class AiBuilderFacade:
                 "verified": True,
                 "app_key": app_key,
                 "button_id": button_id,
+                "edit_version_no": edit_version_no,
                 "button": button,
             }
         )
@@ -1946,6 +1968,7 @@ class AiBuilderFacade:
         response = AppReadSummaryResponse(
             app_key=app_key,
             title=state["base"].get("formTitle"),
+            app_icon=str(state["base"].get("appIcon") or "").strip() or None,
             tag_ids=_coerce_int_list(state["base"].get("tagIds")),
             publish_status=state["base"].get("appPublishStatus"),
             field_count=len(parsed["fields"]),
@@ -2567,7 +2590,17 @@ class AiBuilderFacade:
             upsert_views = _build_views_preset(request.preset, list(field_names))
         blocking_issues: list[dict[str, Any]] = []
         for patch in upsert_views:
-            columns = patch.get("columns") or []
+            raw_columns = [str(name or "").strip() for name in (patch.get("columns") or []) if str(name or "").strip()]
+            columns = _filter_known_system_view_columns(raw_columns)
+            if patch.get("type") in {"table", "card"} and raw_columns and not columns:
+                blocking_issues.append(
+                    {
+                        "error_code": "VALIDATION_ERROR",
+                        "view_name": patch.get("name"),
+                        "message": "view columns must include at least one real app field; system columns cannot be applied directly",
+                        "ignored_system_columns": [name for name in raw_columns if name in _KNOWN_SYSTEM_VIEW_COLUMNS],
+                    }
+                )
             missing_columns = [name for name in columns if name not in field_names]
             if missing_columns:
                 blocking_issues.append({"error_code": "UNKNOWN_VIEW_FIELD", "view_name": patch.get("name"), "missing_fields": missing_columns})
@@ -2642,6 +2675,7 @@ class AiBuilderFacade:
             "app": {
                 "app_key": app_key,
                 "title": base_result.get("formTitle"),
+                "app_icon": str(base_result.get("appIcon") or "").strip() or None,
                 "tag_ids": _coerce_int_list(base_result.get("tagIds")),
                 "publish_status": base_result.get("appPublishStatus"),
             },
@@ -2674,6 +2708,8 @@ class AiBuilderFacade:
         app_key: str = "",
         package_tag_id: int | None = None,
         app_name: str = "",
+        icon: str | None = None,
+        color: str | None = None,
         create_if_missing: bool = False,
         publish: bool = True,
         add_fields: list[FieldPatch],
@@ -2684,6 +2720,8 @@ class AiBuilderFacade:
             "app_key": app_key,
             "package_tag_id": package_tag_id,
             "app_name": app_name,
+            "icon": icon,
+            "color": color,
             "create_if_missing": create_if_missing,
             "publish": publish,
             "add_fields": [patch.model_dump(mode="json") for patch in add_fields],
@@ -2734,6 +2772,8 @@ class AiBuilderFacade:
                 profile=profile,
                 app_name=app_name,
                 package_tag_id=package_tag_id,
+                icon=icon,
+                color=color,
             )
             if resolved.get("status") == "failed":
                 if not isinstance(resolved.get("normalized_args"), dict) or not resolved.get("normalized_args"):
@@ -2757,6 +2797,23 @@ class AiBuilderFacade:
             if permission_outcome.block is not None:
                 return permission_outcome.block
             permission_outcomes.append(permission_outcome)
+            visual_result = self._ensure_app_base_visuals(
+                profile=profile,
+                app_key=target.app_key,
+                fallback_title=target.app_name,
+                icon=icon,
+                color=color,
+                normalized_args=normalized_args,
+            )
+            if visual_result.get("status") == "failed":
+                return finalize(visual_result)
+        else:
+            visual_result = {
+                "status": "success",
+                "updated": False,
+                "app_icon": str(resolved.get("app_icon") or "").strip() or None,
+                "request_id": None,
+            }
         if bool(resolved.get("created")) and not requested_field_changes:
             return finalize({
                 "status": "success",
@@ -2775,9 +2832,11 @@ class AiBuilderFacade:
                     "fields_verified": True,
                     "package_attached": None if package_tag_id is None else package_tag_id in target.tag_ids,
                     "relation_field_limit_verified": True,
+                    "app_visuals_verified": True,
                     "publish_skipped": True,
                 },
                 "app_key": target.app_key,
+                "app_icon": str(resolved.get("app_icon") or visual_result.get("app_icon") or "").strip() or None,
                 "created": True,
                 "field_diff": {"added": [], "updated": [], "removed": []},
                 "verified": True,
@@ -2899,17 +2958,22 @@ class AiBuilderFacade:
                 "status": "success",
                 "error_code": None,
                 "recoverable": False,
-                "message": "schema already matches requested state",
+                "message": "updated app visuals; schema already matches requested state" if bool(visual_result.get("updated")) else "schema already matches requested state",
                 "normalized_args": normalized_args,
                 "missing_fields": [],
                 "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}},
-                "noop": True,
+                "noop": not bool(visual_result.get("updated")),
                 "warnings": relation_warnings,
-                "verification": {"fields_verified": True, "relation_field_limit_verified": relation_limit_verified},
+                "verification": {
+                    "fields_verified": True,
+                    "relation_field_limit_verified": relation_limit_verified,
+                    "app_visuals_verified": True,
+                },
                 "app_key": target.app_key,
+                "app_icon": str(visual_result.get("app_icon") or "").strip() or None,
                 "created": False,
                 "field_diff": {"added": [], "updated": [], "removed": []},
                 "verified": True,
@@ -2981,9 +3045,11 @@ class AiBuilderFacade:
             "verification": {
                 "fields_verified": False,
                 "package_attached": None,
+                "app_visuals_verified": True,
                 "relation_field_limit_verified": relation_limit_verified,
             },
             "app_key": target.app_key,
+            "app_icon": str(visual_result.get("app_icon") or resolved.get("app_icon") or "").strip() or None,
             "created": bool(resolved.get("created")),
             "field_diff": {
                 "added": added,
@@ -3644,6 +3710,7 @@ class AiBuilderFacade:
             for patch in upsert_views
         )
         valid_custom_button_ids: set[int] = set()
+        custom_button_details_by_id: dict[int, dict[str, Any]] = {}
         if requires_custom_button_validation:
             try:
                 button_listing = self.buttons.custom_button_list(
@@ -3668,6 +3735,26 @@ class AiBuilderFacade:
                 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
             }
+            referenced_custom_button_ids = {
+                binding.button_id
+                for patch in upsert_views
+                for binding in (patch.buttons or [])
+                if binding.button_type == PublicViewButtonType.custom and binding.button_id in valid_custom_button_ids
+            }
+            for button_id in sorted(referenced_custom_button_ids):
+                try:
+                    detail = self.buttons.custom_button_get(
+                        profile=profile,
+                        app_key=app_key,
+                        button_id=button_id,
+                        being_draft=True,
+                        include_raw=False,
+                    )
+                except (QingflowApiError, RuntimeError):
+                    continue
+                detail_result = detail.get("result")
+                if isinstance(detail_result, dict):
+                    custom_button_details_by_id[button_id] = _normalize_custom_button_detail(detail_result)
         removed: list[str] = []
         view_results: list[dict[str, Any]] = []
         for name in remove_views:
@@ -3704,7 +3791,24 @@ class AiBuilderFacade:
             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]
+            apply_columns = _resolve_view_visible_field_names(patch)
+            ignored_system_columns = [
+                name
+                for name in [str(value or "").strip() for value in patch.columns]
+                if name in _KNOWN_SYSTEM_VIEW_COLUMNS
+            ]
+            if patch.type in {PublicViewType.table, PublicViewType.card} and patch.columns and not apply_columns:
+                return _failed(
+                    "VALIDATION_ERROR",
+                    "view columns must include at least one real app field; system columns cannot be applied directly",
+                    normalized_args=normalized_args,
+                    details={
+                        "app_key": app_key,
+                        "view_name": patch.name,
+                        "ignored_system_columns": ignored_system_columns,
+                    },
+                )
+            missing_columns = [name for name in apply_columns if name not in field_names]
             if missing_columns:
                 return _failed(
                     "UNKNOWN_VIEW_FIELD",
@@ -3714,6 +3818,7 @@ class AiBuilderFacade:
                         "app_key": app_key,
                         "view_name": patch.name,
                         "missing_fields": missing_columns,
+                        "ignored_system_columns": ignored_system_columns,
                     },
                     missing_fields=missing_columns,
                     suggested_next_call={"tool_name": "app_read_fields", "arguments": {"profile": profile, "app_key": app_key}},
@@ -3784,7 +3889,10 @@ 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_custom_button_list", "arguments": {"profile": profile, "app_key": app_key}},
                     )
-                expected_button_summary = _normalize_view_buttons_for_compare(explicit_button_dtos or [])
+                expected_button_summary = _normalize_expected_view_buttons_for_compare(
+                    explicit_button_dtos or [],
+                    custom_button_details_by_id=custom_button_details_by_id,
+                )
             matched_existing_view: dict[str, Any] | None = None
             existing_key: str | None = None
             if patch.view_key:
@@ -3837,12 +3945,14 @@ class AiBuilderFacade:
                     system_view_sync: dict[str, Any] | None = None
                     if system_view_list_type is not None and patch.type.value == "table":
                         operation_phase = "default_view_apply_config_sync"
-                        system_view_sync = self._sync_system_view_apply_config(
+                        system_view_sync = self._sync_system_view_and_restore_buttons(
                             profile=profile,
                             app_key=app_key,
+                            viewgraph_key=existing_key,
+                            payload=payload,
                             list_type=system_view_list_type,
                             schema=schema,
-                            visible_field_names=patch.columns,
+                            visible_field_names=apply_columns,
                         )
                         if not bool(system_view_sync.get("verified")):
                             failure_entry = {
@@ -3864,6 +3974,7 @@ class AiBuilderFacade:
                                     "list_type": system_view_list_type,
                                     "expected_visible_order": system_view_sync.get("expected_visible_order"),
                                     "actual_visible_order": system_view_sync.get("actual_visible_order"),
+                                    "apply_columns": apply_columns,
                                 },
                             }
                             failed_views.append(failure_entry)
@@ -3879,6 +3990,7 @@ class AiBuilderFacade:
                                 "expected_filters": deepcopy(translated_filters),
                                 "expected_buttons": deepcopy(expected_button_summary),
                                 "system_view_sync": system_view_sync,
+                                "apply_columns": deepcopy(apply_columns),
                             }
                         )
                 else:
@@ -3956,6 +4068,49 @@ class AiBuilderFacade:
                                 explicit_button_dtos=fallback_button_dtos,
                             )
                             self.views.view_update(profile=profile, viewgraph_key=target_key, payload=fallback_payload)
+                            system_view_sync: dict[str, Any] | None = None
+                            fallback_system_view_list_type = (
+                                _resolve_system_view_list_type(view_key=target_key, view_name=patch.name)
+                                if patch.type.value == "table" and target_key
+                                else None
+                            )
+                            if fallback_system_view_list_type is not None:
+                                operation_phase = "default_view_apply_config_sync"
+                                system_view_sync = self._sync_system_view_and_restore_buttons(
+                                    profile=profile,
+                                    app_key=app_key,
+                                    viewgraph_key=target_key,
+                                    payload=fallback_payload,
+                                    list_type=fallback_system_view_list_type,
+                                    schema=schema,
+                                    visible_field_names=apply_columns,
+                                )
+                                if not bool(system_view_sync.get("verified")):
+                                    failure_entry = {
+                                        "name": patch.name,
+                                        "view_key": target_key,
+                                        "type": patch.type.value,
+                                        "status": "failed",
+                                        "error_code": "SYSTEM_VIEW_ORDER_SYNC_FAILED",
+                                        "message": "default view column order did not verify through app apply/baseInfo readback",
+                                        "request_id": None,
+                                        "backend_code": None,
+                                        "http_status": None,
+                                        "operation": "sync_default_view",
+                                        "details": {
+                                            "app_key": app_key,
+                                            "view_name": patch.name,
+                                            "view_key": target_key,
+                                            "view_type": patch.type.value,
+                                            "list_type": fallback_system_view_list_type,
+                                            "expected_visible_order": system_view_sync.get("expected_visible_order"),
+                                            "actual_visible_order": system_view_sync.get("actual_visible_order"),
+                                            "apply_columns": apply_columns,
+                                        },
+                                    }
+                                    failed_views.append(failure_entry)
+                                    view_results.append(failure_entry)
+                                    continue
                             if existing_key:
                                 updated.append(patch.name)
                                 view_results.append(
@@ -3967,6 +4122,8 @@ class AiBuilderFacade:
                                         "fallback_applied": True,
                                         "expected_filters": deepcopy(translated_filters),
                                         "expected_buttons": deepcopy(expected_button_summary),
+                                        "system_view_sync": system_view_sync,
+                                        "apply_columns": deepcopy(apply_columns),
                                     }
                                 )
                             else:
@@ -3980,6 +4137,8 @@ class AiBuilderFacade:
                                         "fallback_applied": True,
                                         "expected_filters": deepcopy(translated_filters),
                                         "expected_buttons": deepcopy(expected_button_summary),
+                                        "system_view_sync": system_view_sync,
+                                        "apply_columns": deepcopy(apply_columns),
                                     }
                                 )
                             continue
@@ -4079,6 +4238,8 @@ class AiBuilderFacade:
         filter_mismatches: list[dict[str, Any]] = []
         button_readback_pending = False
         button_mismatches: list[dict[str, Any]] = []
+        custom_button_readback_pending = False
+        custom_button_readback_pending_entries: list[dict[str, Any]] = []
         for item in view_results:
             status = str(item.get("status") or "")
             name = str(item.get("name") or "")
@@ -4181,12 +4342,28 @@ class AiBuilderFacade:
                             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
+                            button_comparison = _compare_view_button_summaries(
+                                expected=expected_buttons,
+                                actual=actual_buttons,
+                            )
+                            buttons_verified = bool(button_comparison.get("verified"))
                             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:
+                            if button_comparison.get("custom_button_readback_pending"):
+                                verification_entry["custom_button_readback_pending"] = True
+                                verification_entry["pending_custom_buttons"] = deepcopy(button_comparison.get("pending_custom_buttons") or [])
+                                custom_button_readback_pending = True
+                                custom_button_readback_pending_entries.append(
+                                    {
+                                        "name": name,
+                                        "type": item.get("type"),
+                                        "view_key": verification_key,
+                                        "pending_custom_buttons": deepcopy(button_comparison.get("pending_custom_buttons") or []),
+                                    }
+                                )
+                            elif not buttons_verified:
                                 button_mismatches.append(
                                     {
                                         "name": name,
@@ -4249,6 +4426,11 @@ class AiBuilderFacade:
                     "per_view_results": view_results,
                     "filter_mismatches": filter_mismatches,
                     "button_mismatches": button_mismatches,
+                    **(
+                        {"custom_button_readback_pending": deepcopy(custom_button_readback_pending_entries)}
+                        if custom_button_readback_pending_entries
+                        else {}
+                    ),
                 },
                 "request_id": first_failure.get("request_id"),
                 "suggested_next_call": {"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
@@ -4256,10 +4438,21 @@ class AiBuilderFacade:
                 "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 []
-                )
-                + (
-                    [_warning("VIEW_BUTTONS_UNVERIFIED", "view definitions may exist, but saved button behavior is not fully verified")] if (button_readback_pending or button_mismatches) else []
+                    (
+                        [_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 []
+                    )
+                    + (
+                        [_warning("VIEW_CUSTOM_BUTTON_READBACK_PENDING", "system buttons verified, but draft custom button bindings are not fully visible through view readback yet")]
+                        if custom_button_readback_pending
+                        else []
+                    )
                 ),
                 "verification": {
                     "views_verified": verified,
@@ -4267,6 +4460,8 @@ class AiBuilderFacade:
                     "view_buttons_verified": view_buttons_verified,
                     "views_read_unavailable": verified_views_unavailable,
                     "by_view": verification_by_view,
+                    "custom_button_readback_pending": custom_button_readback_pending,
+                    "custom_button_readback_pending_entries": deepcopy(custom_button_readback_pending_entries),
                 },
                 "app_key": app_key,
                 "views_diff": {"created": created, "updated": updated, "removed": removed, "failed": failed_views},
@@ -4278,6 +4473,13 @@ class AiBuilderFacade:
             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"))
+        if custom_button_readback_pending:
+            warnings.append(
+                _warning(
+                    "VIEW_CUSTOM_BUTTON_READBACK_PENDING",
+                    "system buttons verified, but draft custom button bindings are not fully visible through view readback yet",
+                )
+            )
         response = {
             "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"),
@@ -4297,6 +4499,11 @@ class AiBuilderFacade:
             "details": {
                 **({"filter_mismatches": filter_mismatches} if filter_mismatches else {}),
                 **({"button_mismatches": button_mismatches} if button_mismatches else {}),
+                **(
+                    {"custom_button_readback_pending": deepcopy(custom_button_readback_pending_entries)}
+                    if custom_button_readback_pending_entries
+                    else {}
+                ),
             },
             "request_id": None,
             "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}},
@@ -4309,6 +4516,8 @@ class AiBuilderFacade:
                 "views_read_unavailable": verified_views_unavailable,
                 "filter_readback_pending": filter_readback_pending,
                 "button_readback_pending": button_readback_pending,
+                "custom_button_readback_pending": custom_button_readback_pending,
+                "custom_button_readback_pending_entries": deepcopy(custom_button_readback_pending_entries),
                 "by_view": verification_by_view,
             },
             "app_key": app_key,
@@ -5055,6 +5264,28 @@ class AiBuilderFacade:
             version_result = {}
         return _coerce_positive_int(version_result.get("editVersionNo") or version_result.get("versionNo")) or int(current_schema.get("editVersionNo") or 1)
 
+    def _ensure_app_edit_context(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        normalized_args: dict[str, Any],
+        failure_code: str,
+    ) -> tuple[int | None, JSONObject | 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 None, _failed_from_api_error(
+                failure_code,
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key, "phase": "prepare_edit_context"},
+                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
+        return edit_version_no, None
+
     def _append_publish_result(self, *, profile: str, app_key: str, publish: bool, response: JSONObject) -> JSONObject:
         verification = response.get("verification")
         if not isinstance(verification, dict):
@@ -5134,6 +5365,29 @@ class AiBuilderFacade:
             "verified": verified,
         }
 
+    def _sync_system_view_and_restore_buttons(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        viewgraph_key: str,
+        payload: dict[str, Any],
+        list_type: int,
+        schema: dict[str, Any],
+        visible_field_names: list[str],
+    ) -> dict[str, Any]:
+        sync_result = self._sync_system_view_apply_config(
+            profile=profile,
+            app_key=app_key,
+            list_type=list_type,
+            schema=schema,
+            visible_field_names=visible_field_names,
+        )
+        if bool(sync_result.get("verified")) and "buttonConfigDTOList" in payload:
+            self.views.view_update(profile=profile, viewgraph_key=viewgraph_key, payload=payload)
+            sync_result = {**sync_result, "button_config_restored": True}
+        return sync_result
+
     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)
@@ -5262,9 +5516,17 @@ class AiBuilderFacade:
         profile: str,
         app_name: str,
         package_tag_id: int | None,
+        icon: str | None,
+        color: str | None,
     ) -> JSONObject:
         payload: JSONObject = {
             "appName": app_name or "未命名应用",
+            "appIcon": encode_workspace_icon_with_defaults(
+                icon=icon,
+                color=color,
+                title=app_name or "未命名应用",
+                fallback_icon_name="template",
+            ),
             "auth": default_member_auth(),
             "tagIds": [package_tag_id] if package_tag_id and package_tag_id > 0 else [],
         }
@@ -5310,6 +5572,7 @@ class AiBuilderFacade:
                 "suggested_next_call": None,
                 "app_key": new_app_key,
                 "app_name": app_name or "未命名应用",
+                "app_icon": payload.get("appIcon"),
                 "tag_ids": [package_tag_id] if package_tag_id and package_tag_id > 0 else [],
                 "created": True,
             }
@@ -5321,10 +5584,103 @@ class AiBuilderFacade:
             "suggested_next_call": None,
             "app_key": new_app_key,
             "app_name": base.get("formTitle") or app_name or "未命名应用",
+            "app_icon": str(base.get("appIcon") or payload.get("appIcon") or "").strip() or None,
             "tag_ids": _coerce_int_list(base.get("tagIds")),
             "created": True,
         }
 
+    def _build_app_base_update_payload(
+        self,
+        *,
+        raw_base: dict[str, Any],
+        form_title: str,
+        app_icon: str,
+    ) -> JSONObject | None:
+        auth = deepcopy(raw_base.get("auth"))
+        if not isinstance(auth, dict):
+            return None
+        payload: JSONObject = {
+            "formTitle": form_title,
+            "auth": auth,
+            "appIcon": app_icon,
+        }
+        tag_ids = _coerce_int_list(raw_base.get("tagIds"))
+        if tag_ids:
+            payload["tagIds"] = tag_ids
+        return payload
+
+    def _ensure_app_base_visuals(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        fallback_title: str,
+        icon: str | None,
+        color: str | None,
+        normalized_args: dict[str, Any],
+    ) -> JSONObject:
+        if not icon and not color:
+            return {
+                "status": "success",
+                "updated": False,
+                "app_icon": None,
+                "request_id": None,
+            }
+        try:
+            base_result = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "APP_VISUAL_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}},
+            )
+        raw_base = base_result.get("result") if isinstance(base_result.get("result"), dict) else {}
+        effective_title = str(raw_base.get("formTitle") or fallback_title or "未命名应用").strip() or "未命名应用"
+        existing_icon = str(raw_base.get("appIcon") or "").strip() or None
+        desired_icon = encode_workspace_icon_with_defaults(
+            icon=icon,
+            color=color,
+            title=effective_title,
+            fallback_icon_name="template",
+            existing_icon=existing_icon,
+        )
+        if desired_icon == existing_icon:
+            return {
+                "status": "success",
+                "updated": False,
+                "app_icon": desired_icon,
+                "request_id": None,
+            }
+        payload = self._build_app_base_update_payload(raw_base=raw_base, form_title=effective_title, app_icon=desired_icon)
+        if payload is None:
+            return _failed(
+                "APP_VISUAL_UPDATE_UNSUPPORTED",
+                "app base info did not include editable auth payload required for icon update",
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        try:
+            update_result = self.apps.app_update_base(profile=profile, app_key=app_key, payload=payload)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "APP_VISUAL_UPDATE_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key, "app_icon": desired_icon},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        return {
+            "status": "success",
+            "updated": True,
+            "app_icon": desired_icon,
+            "request_id": update_result.get("request_id") if isinstance(update_result, dict) else None,
+        }
+
     def _current_request_route(self, profile: str) -> JSONObject:
         session_profile = self.apps.sessions.get_profile(profile)
         backend_session = self.apps.sessions.get_backend_session(profile)
@@ -5507,11 +5863,15 @@ def _serialize_custom_button_payload(payload: CustomButtonPatch) -> dict[str, An
         "buttonIcon": data["button_icon"],
         "triggerAction": data["trigger_action"],
     }
+    if str(data.get("icon_color") or "").strip():
+        serialized["iconColor"] = data["icon_color"]
     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)
+    else:
+        serialized["triggerAddDataConfig"] = _serialize_custom_button_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)
@@ -5594,6 +5954,7 @@ def _normalize_custom_button_summary(item: dict[str, Any]) -> dict[str, Any]:
         "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,
+        "icon_color": str(item.get("icon_color") or item.get("iconColor") 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")),
@@ -6350,11 +6711,12 @@ def _build_public_portal_base_payload(
     effective_name = str(dash_name or data.get("dashName") or "").strip() or "未命名门户"
     effective_hide_copyright = hide_copyright if hide_copyright is not None else bool(data.get("hideCopyright", False))
     if icon or color or not data.get("dashIcon"):
-        data["dashIcon"] = encode_workspace_icon(
+        data["dashIcon"] = encode_workspace_icon_with_defaults(
             icon=icon,
             color=color,
             title=effective_name,
             fallback_icon_name="view-grid",
+            existing_icon=str(data.get("dashIcon") or "").strip() or None,
         )
     data["dashName"] = effective_name
     data["auth"] = deepcopy(auth if auth is not None else data.get("auth") or default_member_auth())
@@ -8072,6 +8434,36 @@ def _merge_view_summary_with_config(base: dict[str, Any], *, config: dict[str, A
         for entry in display_entries
         if str(entry.get("name") or "").strip()
     ]
+    apply_entries = [
+        entry
+        for entry in display_entries
+        if _coerce_nonnegative_int(entry.get("field_id")) is not None
+        and str(entry.get("name") or "").strip()
+        and str(entry.get("name") or "").strip() not in _KNOWN_SYSTEM_VIEW_COLUMNS
+    ]
+    apply_column_ids = [
+        field_id
+        for field_id in (_coerce_nonnegative_int(entry.get("field_id")) for entry in apply_entries)
+        if field_id is not None
+    ]
+    apply_columns = [
+        str(entry.get("name") or "").strip()
+        for entry in apply_entries
+        if str(entry.get("name") or "").strip()
+    ]
+    if not apply_columns and configured_column_ids:
+        apply_columns = [
+            str((question_entries_by_id.get(field_id) or {}).get("name") or "").strip()
+            for field_id in configured_column_ids
+            if str((question_entries_by_id.get(field_id) or {}).get("name") or "").strip()
+            and str((question_entries_by_id.get(field_id) or {}).get("name") or "").strip() not in _KNOWN_SYSTEM_VIEW_COLUMNS
+        ]
+        apply_column_ids = [
+            field_id
+            for field_id in configured_column_ids
+            if str((question_entries_by_id.get(field_id) or {}).get("name") or "").strip()
+            and str((question_entries_by_id.get(field_id) or {}).get("name") or "").strip() not in _KNOWN_SYSTEM_VIEW_COLUMNS
+        ]
     if not display_columns and configured_columns:
         display_columns = configured_columns
         display_column_ids = list(configured_column_ids)
@@ -8087,6 +8479,10 @@ def _merge_view_summary_with_config(base: dict[str, Any], *, config: dict[str, A
         summary["configured_columns"] = configured_columns
         summary["configured_column_ids"] = configured_column_ids
         config_enriched = True
+    if apply_columns:
+        summary["apply_columns"] = apply_columns
+        summary["apply_column_ids"] = apply_column_ids
+        config_enriched = True
     if question_entries:
         summary["column_details"] = display_entries or _sort_view_question_entries(question_entries)
         config_enriched = True
@@ -8337,6 +8733,7 @@ def _normalize_view_button_entry(entry: dict[str, Any]) -> dict[str, Any]:
     for public_key, source_key in (
         ("default_button_text", "defaultButtonText"),
         ("button_icon", "buttonIcon"),
+        ("icon_color", "iconColor"),
         ("background_color", "backgroundColor"),
         ("text_color", "textColor"),
         ("trigger_link_url", "triggerLinkUrl"),
@@ -8366,17 +8763,21 @@ def _normalize_view_buttons_for_compare(value: Any) -> list[dict[str, Any]]:
     normalized_entries: list[dict[str, Any]] = []
     for entry in entries:
         normalized = _normalize_view_button_entry(entry)
+        is_custom = normalized.get("button_type") == "CUSTOM"
         normalized_entries.append(
             {
                 "button_type": normalized.get("button_type"),
                 "config_type": normalized.get("config_type"),
-                "button_id": normalized.get("button_id"),
+                "button_id": normalized.get("button_id") if is_custom else None,
                 "button_text": normalized.get("button_text"),
                 "button_icon": normalized.get("button_icon"),
+                "icon_color": normalized.get("icon_color"),
                 "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"),
+                # Custom button trigger details are verified by dedicated button CRUD readback.
+                # View binding verification should focus on binding/display semantics and tolerate resource-owned URLs.
+                "trigger_link_url": None if is_custom else 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 ""),
@@ -8387,12 +8788,127 @@ def _normalize_view_buttons_for_compare(value: Any) -> list[dict[str, Any]]:
     return normalized_entries
 
 
+_SYSTEM_VIEW_BUTTON_ID_BY_ACTION: dict[tuple[str, str], int] = {
+    ("TOP", "set"): 1,
+    ("TOP", "switchView"): 2,
+    ("TOP", "setRowHeight"): 3,
+    ("TOP", "search"): 6,
+    ("DETAIL", "share"): 7,
+    ("DETAIL", "edit"): 8,
+}
+
+_SYSTEM_VIEW_BUTTON_ID_BY_TEXT: dict[tuple[str, str], int] = {
+    ("TOP", "字段管理"): 1,
+    ("TOP", "视图类型"): 2,
+    ("TOP", "行高"): 3,
+    ("TOP", "搜索"): 6,
+    ("DETAIL", "分享"): 7,
+    ("DETAIL", "修改"): 8,
+    ("DETAIL", "修改记录"): 8,
+}
+
+
+def _resolve_system_view_button_logical_id(entry: dict[str, Any]) -> int | None:
+    config_type = _normalize_view_button_config_type(entry.get("configType") or entry.get("config_type")) or ""
+    trigger_action = str(entry.get("triggerAction") or entry.get("trigger_action") or "").strip()
+    if config_type and trigger_action:
+        mapped = _SYSTEM_VIEW_BUTTON_ID_BY_ACTION.get((config_type, trigger_action))
+        if mapped is not None:
+            return mapped
+    button_text = str(entry.get("buttonText") or entry.get("button_text") or "").strip()
+    default_button_text = str(entry.get("defaultButtonText") or entry.get("default_button_text") or "").strip()
+    for candidate in (button_text, default_button_text):
+        if config_type and candidate:
+            mapped = _SYSTEM_VIEW_BUTTON_ID_BY_TEXT.get((config_type, candidate))
+            if mapped is not None:
+                return mapped
+    button_id = _coerce_positive_int(entry.get("buttonId") or entry.get("button_id") or entry.get("id"))
+    if button_id is not None and button_id < 1000:
+        return button_id
+    return None
+
+
+def _normalize_expected_view_buttons_for_compare(
+    value: Any,
+    *,
+    custom_button_details_by_id: dict[int, dict[str, Any]] | None = None,
+) -> list[dict[str, Any]]:
+    normalized_entries = _normalize_view_buttons_for_compare(value)
+    if not custom_button_details_by_id:
+        return normalized_entries
+    enriched_entries: list[dict[str, Any]] = []
+    for item in normalized_entries:
+        enriched = deepcopy(item)
+        if enriched.get("button_type") == "CUSTOM":
+            button_id = _coerce_positive_int(enriched.get("button_id"))
+            detail = custom_button_details_by_id.get(button_id or -1)
+            if isinstance(detail, dict):
+                for key in (
+                    "button_text",
+                    "button_icon",
+                    "icon_color",
+                    "background_color",
+                    "text_color",
+                    "trigger_action",
+                ):
+                    value = detail.get(key)
+                    if enriched.get(key) in {None, ""} and value not in {None, ""}:
+                        enriched[key] = deepcopy(value)
+        enriched_entries.append(enriched)
+    return enriched_entries
+
+
+def _partition_view_button_summaries(
+    items: list[dict[str, Any]],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[dict[str, Any]]]:
+    system_buttons: list[dict[str, Any]] = []
+    custom_buttons: list[dict[str, Any]] = []
+    other_buttons: list[dict[str, Any]] = []
+    for item in items:
+        button_type = str(item.get("button_type") or "").strip().upper()
+        if button_type == "SYSTEM":
+            system_buttons.append(item)
+        elif button_type == "CUSTOM":
+            custom_buttons.append(item)
+        else:
+            other_buttons.append(item)
+    return system_buttons, custom_buttons, other_buttons
+
+
+def _compare_view_button_summaries(
+    *,
+    expected: list[dict[str, Any]],
+    actual: list[dict[str, Any]],
+) -> dict[str, Any]:
+    if actual == expected:
+        return {
+            "verified": True,
+            "custom_button_readback_pending": False,
+            "pending_custom_buttons": [],
+        }
+    expected_system, expected_custom, expected_other = _partition_view_button_summaries(expected)
+    actual_system, actual_custom, actual_other = _partition_view_button_summaries(actual)
+    custom_button_readback_pending = (
+        bool(expected_custom)
+        and not actual_custom
+        and actual_system == expected_system
+        and actual_other == expected_other
+    )
+    return {
+        "verified": custom_button_readback_pending,
+        "custom_button_readback_pending": custom_button_readback_pending,
+        "pending_custom_buttons": deepcopy(expected_custom) if custom_button_readback_pending else [],
+    }
+
+
 def _serialize_existing_view_button_entry(entry: dict[str, Any]) -> dict[str, Any]:
     dto: dict[str, Any] = {}
+    button_type = _normalize_view_button_type(entry.get("buttonType") or entry.get("button_type"))
     button_id = _coerce_positive_int(entry.get("buttonId") or entry.get("button_id") or entry.get("id"))
+    if button_type == "SYSTEM":
+        button_id = _resolve_system_view_button_logical_id(entry)
     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"))
@@ -8405,6 +8921,7 @@ def _serialize_existing_view_button_entry(entry: dict[str, Any]) -> dict[str, An
     dto["printTpls"] = _serialize_print_tpl_ids(entry.get("printTpls"))
     for source_key, target_key in (
         ("buttonText", "buttonText"),
+        ("defaultButtonText", "defaultButtonText"),
         ("buttonIcon", "buttonIcon"),
         ("backgroundColor", "backgroundColor"),
         ("textColor", "textColor"),
@@ -8423,10 +8940,9 @@ def _serialize_existing_view_button_entry(entry: dict[str, Any]) -> dict[str, An
 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)
+    entries, source = _extract_view_button_entries(config)
+    if source == "buttonConfigDTOList":
+        return [deepcopy(item) for item in entries if isinstance(item, dict)]
     return [_serialize_existing_view_button_entry(entry) for entry in entries if isinstance(entry, dict)]
 
 
@@ -8510,9 +9026,11 @@ def _serialize_view_button_binding(
         "buttonFormulaType": binding.button_formula_type,
         "printTpls": _serialize_print_tpl_ids(binding.print_tpls),
     }
-    if binding.button_type == PublicViewButtonType.system:
+    if binding.button_type in {PublicViewButtonType.system, PublicViewButtonType.custom}:
         dto["buttonText"] = binding.button_text
         dto["buttonIcon"] = binding.button_icon
+        if str(binding.icon_color or "").strip():
+            dto["iconColor"] = binding.icon_color
         dto["backgroundColor"] = binding.background_color
         dto["textColor"] = binding.text_color
         dto["triggerAction"] = binding.trigger_action
@@ -9171,6 +9689,22 @@ def _build_view_update_payload(
     )
 
 
+_KNOWN_SYSTEM_VIEW_COLUMNS = {
+    "编号",
+    "当前流程状态",
+    "申请人",
+    "申请时间",
+    "更新时间",
+    "流程标题",
+    "当前处理人",
+    "当前处理节点",
+}
+
+
+def _filter_known_system_view_columns(columns: list[str]) -> list[str]:
+    return [name for name in columns if str(name or "").strip() and str(name).strip() not in _KNOWN_SYSTEM_VIEW_COLUMNS]
+
+
 def _build_minimal_view_payload(
     *,
     app_key: str,
@@ -9299,7 +9833,7 @@ 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:
+        if name and name not in _KNOWN_SYSTEM_VIEW_COLUMNS and name not in ordered:
             ordered.append(name)
     return ordered