@qingflow-tech/qingflow-app-user-mcp 1.0.40 → 1.0.42

package/src/qingflow_mcp/builder_facade/service.py

@@ -48,6 +48,7 @@ from .models import (
     AssociatedResourceUpsertPatch,
     AssociatedResourceViewConfigPatch,
     ChartApplyRequest,
+    ChartMetricPatch,
     ChartPartialPatch,
     ChartUpsertPatch,
     CustomButtonsApplyRequest,
@@ -649,6 +650,42 @@ class AiBuilderFacade:
                 normalized_args=normalized_args,
             )
             if layout_result.get("status") not in {"success", "partial_success"}:
+                prior_package_write_executed = bool(
+                    created
+                    or (
+                        metadata_requested
+                        and isinstance(update_result, dict)
+                        and update_result.get("status") in {"success", "partial_success"}
+                        and not bool(update_result.get("noop"))
+                    )
+                )
+                if prior_package_write_executed:
+                    layout_details = layout_result.get("details") if isinstance(layout_result.get("details"), dict) else {}
+                    partial = _post_write_readback_pending_result(
+                        error_code=str(layout_result.get("error_code") or "PACKAGE_APPLY_PARTIAL"),
+                        message="created or updated package, but package layout apply failed; read package before retrying",
+                        normalized_args=normalized_args,
+                        details={
+                            "package_id": effective_package_id,
+                            "layout_error_code": layout_result.get("error_code"),
+                            "layout_result": layout_result,
+                            **(
+                                {"layout_write_error": layout_details.get("write_error")}
+                                if isinstance(layout_details.get("write_error"), dict)
+                                else {}
+                            ),
+                        },
+                        suggested_next_call={
+                            "tool_name": "package_get",
+                            "arguments": {"profile": profile, "package_id": effective_package_id},
+                        },
+                        request_id=layout_result.get("request_id") if isinstance(layout_result.get("request_id"), str) else None,
+                        backend_code=layout_result.get("backend_code"),
+                        http_status=layout_result.get("http_status") if isinstance(layout_result.get("http_status"), int) else None,
+                    )
+                    partial["package_id"] = effective_package_id
+                    partial["layout_failed"] = True
+                    return _apply_permission_outcomes(partial, *permission_outcomes)
                 return _apply_permission_outcomes(layout_result, *permission_outcomes)
 
         write_executed = bool(
@@ -7185,6 +7222,8 @@ class AiBuilderFacade:
             base=deepcopy(base) if isinstance(base, dict) else {},
             visibility=_public_visibility_from_chart_visible_auth(base.get("visibleAuth")),
             filters=_public_chart_filter_groups_from_qingbi_config(config) if isinstance(config, dict) else [],
+            group_by=_public_chart_group_by_from_qingbi_config(config) if isinstance(config, dict) else [],
+            metrics=_public_chart_metrics_from_qingbi_config(config) if isinstance(config, dict) else [],
             config=deepcopy(config) if isinstance(config, dict) else {},
         )
         return {
@@ -7901,6 +7940,10 @@ class AiBuilderFacade:
                 if not isinstance(resolved.get("normalized_args"), dict) or not resolved.get("normalized_args"):
                     resolved["normalized_args"] = normalized_args
                 return finalize(resolved)
+            if resolved.get("status") == "partial_success" and not str(resolved.get("app_key") or "").strip():
+                if not isinstance(resolved.get("normalized_args"), dict) or not resolved.get("normalized_args"):
+                    resolved["normalized_args"] = normalized_args
+                return finalize(resolved)
         resolved_outcome = _permission_outcome_from_result(resolved)
         if resolved_outcome is not None:
             permission_outcomes.append(resolved_outcome)
@@ -7958,27 +8001,35 @@ class AiBuilderFacade:
                 "request_id": None,
             }
         if bool(resolved.get("created")) and not requested_field_changes:
-            return finalize({
-                "status": "success",
-                "error_code": None,
-                "recoverable": False,
-                "message": "created app shell",
+            shell_readback_pending = (
+                resolved.get("status") == "partial_success"
+                or bool((resolved.get("verification") if isinstance(resolved.get("verification"), dict) else {}).get("readback_unavailable"))
+                or str(resolved.get("next_action") or "") == "readback_before_retry"
+            )
+            shell_verification = {
+                "fields_verified": not shell_readback_pending,
+                "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": not shell_readback_pending,
+                "app_base_verified": not shell_readback_pending,
+                "publish_skipped": True,
+            }
+            if isinstance(resolved.get("verification"), dict):
+                shell_verification.update(deepcopy(resolved.get("verification") or {}))
+            created_shell_response = {
+                "status": "partial_success" if shell_readback_pending else "success",
+                "error_code": resolved.get("error_code") if shell_readback_pending else None,
+                "recoverable": bool(shell_readback_pending),
+                "message": str(resolved.get("message") or "created app shell") if shell_readback_pending else "created app shell",
                 "normalized_args": normalized_args,
                 "missing_fields": [],
                 "allowed_values": {"field_types": [item.value for item in PublicFieldType]},
                 "details": {"publish_skipped": True},
-                "request_id": None,
+                "request_id": resolved.get("request_id"),
                 "suggested_next_call": None,
                 "noop": False,
-                "warnings": [],
-                "verification": {
-                    "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,
-                    "app_base_verified": True,
-                    "publish_skipped": True,
-                },
+                "warnings": deepcopy(resolved.get("warnings") or []),
+                "verification": shell_verification,
                 "app_key": target.app_key,
                 "app_icon": str(resolved.get("app_icon") or visual_result.get("app_icon") or "").strip() or None,
                 "app_name": str(visual_result.get("app_name_after") or target.app_name),
@@ -7989,19 +8040,28 @@ class AiBuilderFacade:
                 "field_diff": {"added": [], "updated": [], "removed": []},
                 "verified": True,
                 "write_executed": True,
-                "write_succeeded": True,
+                "write_succeeded": not shell_readback_pending or bool(resolved.get("write_succeeded", True)),
                 "safe_to_retry": False,
                 "tag_ids_after": list(target.tag_ids),
                 "package_attached": None if package_tag_id is None else package_tag_id in target.tag_ids,
                 "publish_requested": False,
                 "published": False,
-            })
+            }
+            if shell_readback_pending:
+                created_shell_response["write_may_have_succeeded"] = True
+                created_shell_response["next_action"] = "readback_before_retry"
+                created_shell_response["suggested_next_call"] = resolved.get("suggested_next_call") or {
+                    "tool_name": "app_get",
+                    "arguments": {"profile": profile, "app_key": target.app_key},
+                }
+            return finalize(created_shell_response)
         schema_readback_delayed = False
+        schema_readback_delayed_error: JSONObject | None = None
         try:
             schema_result, _schema_source = self._read_schema_with_fallback(profile=profile, app_key=target.app_key)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
-            if not bool(resolved.get("created")) or api_error.http_status != 404:
+            if not bool(resolved.get("created")):
                 return finalize(_failed_from_api_error(
                     "SCHEMA_READBACK_FAILED",
                     api_error,
@@ -8013,6 +8073,10 @@ class AiBuilderFacade:
             schema_result = _empty_schema_result(effective_app_name)
             _schema_source = "synthetic_new_app"
             schema_readback_delayed = True
+            schema_readback_delayed_error = {
+                "message": api_error.message,
+                **_transport_error_payload(api_error),
+            }
         parsed = _parse_schema(schema_result)
         current_fields = parsed["fields"]
         original_fields = deepcopy(current_fields)
@@ -8344,6 +8408,47 @@ class AiBuilderFacade:
                     http_status=None if api_error.http_status == 404 else api_error.http_status,
                     suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": target.app_key}},
                 )
+            if _is_uncertain_write_transport_error(api_error):
+                uncertain = _post_write_may_have_succeeded_result(
+                    error_code="SCHEMA_WRITE_RESULT_UNCERTAIN",
+                    message="schema write request did not return a final result; read the app schema before retrying",
+                    normalized_args=normalized_args,
+                    details={
+                        "app_key": target.app_key,
+                        "app_name": effective_app_name,
+                        "created": bool(resolved.get("created")),
+                        "field_diff": {"added": added, "updated": updated, "removed": removed},
+                        "transport_error": _transport_error_payload(api_error),
+                    },
+                    suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": target.app_key}},
+                    request_id=api_error.request_id,
+                    backend_code=api_error.backend_code,
+                    http_status=api_error.http_status,
+                )
+                uncertain.update(
+                    {
+                        "app_key": target.app_key,
+                        "app_icon": str(visual_result.get("app_icon") or resolved.get("app_icon") or "").strip() or None,
+                        "app_name": effective_app_name,
+                        "app_name_before": str(visual_result.get("app_name_before") or target.app_name),
+                        "app_name_after": effective_app_name,
+                        "app_base_updated": bool(visual_result.get("updated")),
+                        "created": bool(resolved.get("created")),
+                        "field_diff": {"added": added, "updated": updated, "removed": removed},
+                        "field_diff_details": _schema_field_diff_details(
+                            added=added,
+                            updated=updated,
+                            removed=removed,
+                            before_fields=original_fields,
+                            after_fields=current_fields,
+                        ),
+                        "tag_ids_after": list(target.tag_ids),
+                        "package_attached": None if package_tag_id is None else package_tag_id in target.tag_ids,
+                        "publish_requested": False,
+                        "published": False,
+                    }
+                )
+                return finalize(uncertain)
             return _failed_from_api_error(
                 "SCHEMA_APPLY_FAILED",
                 api_error,
@@ -8508,6 +8613,8 @@ class AiBuilderFacade:
             response["normalized_code_block_fields"] = normalized_code_block_fields
         if schema_readback_delayed:
             response["verification"]["schema_readback_delayed"] = True
+            if schema_readback_delayed_error is not None:
+                response["details"]["schema_readback_delayed_error"] = schema_readback_delayed_error
         response = _apply_permission_outcomes(response, relation_permission_outcome)
         response = self._append_publish_result(profile=profile, app_key=target.app_key, publish=publish, response=response)
         verification_ok = False
@@ -8517,14 +8624,29 @@ class AiBuilderFacade:
         try:
             verified = self.app_read(profile=profile, app_key=target.app_key, include_raw=False)
             verified_field_names = {field["name"] for field in verified["schema"]["fields"]}
+            verified_fields = cast(list[dict[str, Any]], verified["schema"]["fields"])
             response["field_diff_details"] = _schema_field_diff_details(
                 added=added,
                 updated=updated,
                 removed=removed,
                 before_fields=original_fields,
-                after_fields=cast(list[dict[str, Any]], verified["schema"]["fields"]),
+                after_fields=verified_fields,
             )
             verification_ok = all(name in verified_field_names for name in added + updated) and all(name not in verified_field_names for name in removed)
+            relation_readback_matrix = _schema_relation_readback_matrix(
+                expected_fields=current_fields,
+                verified_fields=verified_fields,
+                changed_field_names=set(added + updated),
+                degraded_expectations=relation_degraded_expectations,
+            )
+            if relation_readback_matrix:
+                relation_matrix_verified = all(bool(item.get("readback_verified")) for item in relation_readback_matrix)
+                response["details"]["relation_readback_matrix"] = relation_readback_matrix
+                response["verification"]["relation_readback_matrix_verified"] = relation_matrix_verified
+                verification_ok = verification_ok and relation_matrix_verified
+                relation_repair_plan = _schema_relation_repair_plan(relation_readback_matrix)
+                if relation_repair_plan:
+                    response["details"]["relation_repair_plan"] = relation_repair_plan
             data_display_verification = _verify_data_display_readback(
                 form_settings=verified.get("form_settings"),
                 selection=data_display_selection,
@@ -8591,12 +8713,18 @@ class AiBuilderFacade:
             response["recoverable"] = True
             response["error_code"] = response.get("error_code") or "APP_BASE_READBACK_PENDING"
             response["message"] = f"{response.get('message') or 'apply succeeded'}; app base readback pending"
+            response["write_may_have_succeeded"] = True
+            response["next_action"] = "readback_before_retry"
+            response["verification"]["readback_before_retry"] = True
         if verification_error is not None:
             response["recoverable"] = True
             response["error_code"] = response.get("error_code") or (
                 "READBACK_PENDING" if verification_error.http_status == 404 else "READBACK_FAILED"
             )
             response["message"] = f"{response.get('message') or 'apply succeeded'}; readback pending"
+            response["write_may_have_succeeded"] = True
+            response["next_action"] = "readback_before_retry"
+            response["verification"]["readback_before_retry"] = True
             response["request_id"] = response.get("request_id") or verification_error.request_id
             details = response.get("details")
             if not isinstance(details, dict):
@@ -12374,6 +12502,28 @@ class AiBuilderFacade:
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
             request_route = self._current_request_route(profile)
+            if _is_uncertain_write_transport_error(api_error):
+                return _post_write_may_have_succeeded_result(
+                    error_code="APP_CREATE_WRITE_RESULT_UNCERTAIN",
+                    message="app create request did not return a final result; resolve the app in the package before retrying",
+                    details={
+                        "app_name": app_name,
+                        "package_tag_id": package_tag_id,
+                        "request_route": request_route,
+                        "transport_error": _transport_error_payload(api_error),
+                    },
+                    suggested_next_call={
+                        "tool_name": "app_resolve",
+                        "arguments": {
+                            "profile": profile,
+                            "app_name": app_name,
+                            "package_id": package_tag_id,
+                        },
+                    },
+                    request_id=api_error.request_id,
+                    backend_code=api_error.backend_code,
+                    http_status=api_error.http_status,
+                )
             return _failed_from_api_error(
                 "CREATE_APP_ROUTE_NOT_FOUND" if api_error.http_status == 404 else "APP_CREATE_FAILED",
                 api_error,
@@ -12397,12 +12547,29 @@ class AiBuilderFacade:
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
             if api_error.http_status != 404:
-                return _failed_from_api_error(
-                    "APP_CREATE_READBACK_FAILED",
-                    api_error,
+                pending = _post_write_readback_pending_result(
+                    error_code="APP_CREATE_READBACK_PENDING",
+                    message="created app; base readback is unavailable",
                     details={"app_key": new_app_key, "app_name": app_name, "package_tag_id": package_tag_id},
                     suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": new_app_key}},
+                    request_id=api_error.request_id,
+                    backend_code=api_error.backend_code,
+                    http_status=api_error.http_status,
+                )
+                pending.update(
+                    {
+                        "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,
+                    }
                 )
+                pending.setdefault("details", {})["readback_error"] = {
+                    "message": api_error.message,
+                    **_transport_error_payload(api_error),
+                }
+                return pending
             return {
                 "status": "success",
                 "error_code": None,
@@ -12610,7 +12777,7 @@ class AiBuilderFacade:
                     **deepcopy(section.config),
                 }
                 component = {"type": 9, "position": position_payload, "chartConfig": _compact_dict(chart_config)}
-                layout_metadata.append({"source_type": section.source_type, "chart_type": chart_type})
+                layout_metadata.append({"source_type": section.source_type, "chart_type": chart_type, "role": section.role})
             elif section.source_type == "view":
                 resolved_view = _resolve_view_reference(
                     facade=self,
@@ -12633,27 +12800,27 @@ class AiBuilderFacade:
                     **deepcopy(section.config),
                 }
                 component = {"type": 10, "position": position_payload, "viewgraphConfig": _compact_dict(view_config)}
-                layout_metadata.append({"source_type": section.source_type})
+                layout_metadata.append({"source_type": section.source_type, "role": section.role})
             elif section.source_type == "grid":
                 component = {
                     "type": 2,
                     "position": position_payload,
                     "gridConfig": _compact_dict({"gridTitle": section.title, "beingShowTitle": True, **deepcopy(section.config)}),
                 }
-                layout_metadata.append({"source_type": section.source_type})
+                layout_metadata.append({"source_type": section.source_type, "role": section.role})
             elif section.source_type == "filter":
                 component = {"type": 6, "position": position_payload, "filterConfig": deepcopy(section.config)}
-                layout_metadata.append({"source_type": section.source_type})
+                layout_metadata.append({"source_type": section.source_type, "role": section.role})
             elif section.source_type == "text":
                 component = {"type": 5, "position": position_payload, "textConfig": {"text": section.text or "", **deepcopy(section.config)}}
-                layout_metadata.append({"source_type": section.source_type})
+                layout_metadata.append({"source_type": section.source_type, "role": section.role})
             else:
                 component = {
                     "type": 4,
                     "position": position_payload,
                     "linkConfig": {"url": section.url or "", "beingLoginAuth": False, **deepcopy(section.config)},
                 }
-                layout_metadata.append({"source_type": section.source_type})
+                layout_metadata.append({"source_type": section.source_type, "role": section.role})
             if dash_style is not None:
                 component["dashStyleConfigBO"] = dash_style
             resolved_components.append(component)
@@ -13750,7 +13917,7 @@ def _failed_from_api_error(
                 "category": error.category,
             },
         )
-    return _failed(
+    result = _failed(
         effective_error_code,
         public_message,
         recoverable=recoverable,
@@ -13763,6 +13930,14 @@ def _failed_from_api_error(
         backend_code=error.backend_code,
         http_status=public_http_status,
     )
+    if _is_environment_quota_code(error.backend_code):
+        _mark_environment_quota_block(
+            result,
+            write_executed=False,
+            next_action="retry_after_quota_restored",
+            message="backend quota/AI assistant limit blocked this operation; retry after quota is restored",
+        )
+    return result
 
 
 def _post_write_readback_pending_result(
@@ -13789,7 +13964,7 @@ def _post_write_readback_pending_result(
     ):
         if value is not None:
             warning[key] = value
-    return {
+    result = {
         "status": "partial_success",
         "error_code": error_code,
         "recoverable": True,
@@ -13811,8 +13986,84 @@ def _post_write_readback_pending_result(
         "verified": False,
         "write_executed": True,
         "write_succeeded": True,
+        "write_may_have_succeeded": True,
         "safe_to_retry": False,
+        "next_action": "readback_before_retry",
     }
+    result["verification"]["readback_before_retry"] = True
+    if _is_environment_quota_code(effective_backend_code):
+        result["readback_blocked_by_environment"] = True
+        result["verification"]["readback_blocked_by_environment"] = True
+        _mark_environment_quota_block(
+            result,
+            write_executed=True,
+            next_action="retry_after_quota_restored",
+            message="post-write readback was blocked by backend quota/AI assistant limit; retry readback after quota is restored",
+        )
+    return result
+
+
+def _post_write_may_have_succeeded_result(
+    *,
+    error_code: str,
+    message: str,
+    normalized_args: JSONObject | None = None,
+    details: JSONObject | None = None,
+    suggested_next_call: JSONObject | None = None,
+    request_id: str | None = None,
+    backend_code: Any = None,
+    http_status: int | None = None,
+) -> JSONObject:
+    effective_details = details or {}
+    transport_error = _readback_transport_error_from_details(effective_details)
+    effective_backend_code = backend_code if backend_code is not None else (transport_error or {}).get("backend_code")
+    effective_http_status = http_status if http_status is not None else (transport_error or {}).get("http_status")
+    effective_request_id = request_id if request_id is not None else (transport_error or {}).get("request_id")
+    warning = _warning("WRITE_RESULT_UNCERTAIN", "write request may have succeeded but no final response was received")
+    for key, value in (
+        ("backend_code", effective_backend_code),
+        ("http_status", effective_http_status),
+        ("request_id", effective_request_id),
+    ):
+        if value is not None:
+            warning[key] = value
+    result = {
+        "status": "partial_success",
+        "error_code": error_code,
+        "recoverable": True,
+        "message": message,
+        "normalized_args": normalized_args or {},
+        "missing_fields": [],
+        "allowed_values": {},
+        "details": effective_details,
+        "suggested_next_call": suggested_next_call,
+        "request_id": effective_request_id,
+        "backend_code": effective_backend_code,
+        "http_status": effective_http_status,
+        "noop": False,
+        "warnings": [warning],
+        "verification": {
+            "readback_unavailable": True,
+            "metadata_unverified": True,
+            "readback_before_retry": True,
+        },
+        "verified": False,
+        "write_executed": True,
+        "write_succeeded": False,
+        "write_may_have_succeeded": True,
+        "safe_to_retry": False,
+        "next_action": "readback_before_retry",
+    }
+    if _is_environment_quota_code(effective_backend_code):
+        result["readback_blocked_by_environment"] = True
+        result["verification"]["readback_blocked_by_environment"] = True
+        _mark_environment_quota_block(
+            result,
+            write_executed=True,
+            next_action="retry_after_quota_restored",
+            message="write result or readback was blocked by backend quota/AI assistant limit; retry after quota is restored",
+        )
+    return result
 
 
 def _readback_transport_error_from_details(details: JSONObject) -> JSONObject | None:
@@ -13859,6 +14110,69 @@ def _transport_error_payload(error: QingflowApiError) -> JSONObject:
     }
 
 
+def _is_environment_quota_code(code: Any) -> bool:
+    return backend_code_value_int(code) == 59004
+
+
+def _mark_environment_quota_block(
+    payload: JSONObject,
+    *,
+    write_executed: bool,
+    next_action: str,
+    message: str,
+) -> None:
+    payload["environment_blocked"] = True
+    payload["blocker_type"] = "quota_limit"
+    payload["next_action"] = next_action
+    payload["safe_to_retry"] = False
+    payload["write_executed"] = bool(write_executed)
+    details = payload.get("details")
+    if not isinstance(details, dict):
+        details = {}
+        payload["details"] = details
+    details.setdefault("environment_blocked", True)
+    details.setdefault("blocker_type", "quota_limit")
+    details.setdefault("next_action", next_action)
+    details.setdefault("fix_hint", message)
+    warnings = payload.get("warnings")
+    if not isinstance(warnings, list):
+        warnings = []
+        payload["warnings"] = warnings
+    if not any(isinstance(item, dict) and item.get("code") == "ENVIRONMENT_QUOTA_LIMIT" for item in warnings):
+        warning = _warning("ENVIRONMENT_QUOTA_LIMIT", message)
+        for key in ("backend_code", "http_status", "request_id"):
+            value = payload.get(key)
+            if value is not None:
+                warning[key] = value
+        warnings.append(warning)
+
+
+def _is_uncertain_write_transport_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    category = str(error.category or "").strip().lower()
+    message = str(error.message or "").strip().lower()
+    if category == "timeout":
+        return True
+    if category != "network":
+        return False
+    return any(
+        marker in message
+        for marker in (
+            "timeout",
+            "timed out",
+            "read timed out",
+            "write timed out",
+            "readtimeout",
+            "writetimeout",
+            "server disconnected",
+            "connection reset",
+            "remote protocol error",
+            "response ended prematurely",
+        )
+    )
+
+
 def _is_permission_restricted_api_error(error: QingflowApiError) -> bool:
     if is_auth_like_error(error):
         return False
@@ -14317,7 +14631,29 @@ _CHART_PARTIAL_PATCH_KEY_ALIASES = {
     "indicator_field_ids": "indicator_field_ids",
     "indicatorFieldIds": "indicator_field_ids",
     "metric_field_ids": "indicator_field_ids",
+    "group_by": "group_by",
+    "groupBy": "group_by",
+    "dimensions": "group_by",
+    "rows": "rows",
+    "columns": "columns",
+    "metric": "metric",
+    "metrics": "metrics",
+    "x_metric": "x_metric",
+    "xMetric": "x_metric",
+    "y_metric": "y_metric",
+    "yMetric": "y_metric",
+    "left_metric": "left_metric",
+    "leftMetric": "left_metric",
+    "right_metric": "right_metric",
+    "rightMetric": "right_metric",
+    "value_metric": "value_metric",
+    "valueMetric": "value_metric",
+    "target_metric": "target_metric",
+    "targetMetric": "target_metric",
+    "where": "filters",
     "filters": "filters",
+    "filter_rules": "filters",
+    "filterRules": "filters",
     "question_config": "question_config",
     "questionConfig": "question_config",
     "user_config": "user_config",
@@ -14331,6 +14667,17 @@ _CHART_PARTIAL_SET_KEYS = {
     "chart_type",
     "dimension_field_ids",
     "indicator_field_ids",
+    "group_by",
+    "rows",
+    "columns",
+    "metric",
+    "metrics",
+    "x_metric",
+    "y_metric",
+    "left_metric",
+    "right_metric",
+    "value_metric",
+    "target_metric",
     "filters",
     "question_config",
     "user_config",
@@ -14717,12 +15064,43 @@ def _compact_public_chart_fields_read(
                     "field_type": field.get("fieldType") or field.get("field_type"),
                     "system_field": bool(que_id is not None and not isinstance(form_field, dict)),
                     "available_for_charts": True,
+                    "chart_apply_examples": _chart_apply_examples_for_field(
+                        title=title,
+                        field_type=field.get("fieldType") or field.get("field_type"),
+                    ),
                 }
             )
         )
     return compact_fields
 
 
+def _chart_apply_examples_for_field(*, title: str, field_type: Any) -> dict[str, Any]:
+    field_name = str(title or "").strip()
+    if not field_name:
+        return {}
+    examples: dict[str, Any] = {
+        "count_by_field": {
+            "name": f"按{field_name}分布",
+            "chart_type": "bar",
+            "group_by": [field_name],
+            "metric": "count(*)",
+        },
+        "filtered_count": {
+            "name": f"{field_name}筛选数量",
+            "chart_type": "target",
+            "metric": "count(*)",
+            "where": [{"field": field_name, "op": "eq", "value": "REPLACE_WITH_VALUE"}],
+        },
+    }
+    if str(field_type or "").strip().lower() in _QINGBI_DECIMAL_FIELD_TYPES:
+        examples["sum_metric"] = {
+            "name": f"{field_name}合计",
+            "chart_type": "target",
+            "metric": f"sum({field_name})",
+        }
+    return examples
+
+
 def _chart_field_candidates(
     selector: Any,
     *,
@@ -15031,37 +15409,80 @@ def _build_public_metric_fields(
     metrics: list[dict[str, Any]] = []
     for selector in selectors:
         qingbi_field = _resolve_qingbi_chart_field(selector, chart_field_lookup=chart_field_lookup, chart_type=chart_type, role="metric")
-        field_id = _chart_field_id(qingbi_field)
-        if field_id == _QINGBI_TOTAL_FIELD_ID:
-            metrics.append(qingbi_field)
+        metrics.append(_public_qingbi_metric_field(qingbi_field, aggregate=normalized_aggregate))
+    return metrics or [_default_public_total_metric()]
+
+
+def _public_qingbi_metric_field(qingbi_field: dict[str, Any], *, aggregate: str) -> dict[str, Any]:
+    field_id = _chart_field_id(qingbi_field)
+    if field_id == _QINGBI_TOTAL_FIELD_ID:
+        return deepcopy(qingbi_field)
+    form_field = qingbi_field.get("_public_form_field") if isinstance(qingbi_field.get("_public_form_field"), dict) else {}
+    normalized_aggregate = str(aggregate or "sum").strip().lower()
+    aggre_type = {"sum": "sum", "avg": "avg", "average": "avg", "max": "max", "min": "min"}.get(normalized_aggregate, "sum")
+    return {
+        "fieldId": field_id,
+        "fieldName": qingbi_field.get("fieldName") or form_field.get("name") or field_id,
+        "fieldType": qingbi_field.get("fieldType") or _qingbi_field_type_from_public_field(str(form_field.get("type") or "")),
+        "orderType": "default",
+        "alignType": "left",
+        "dateFormat": "yyyy-MM-dd",
+        "numberFormat": "default",
+        "numberConfig": {"format": "splitter", "unit": "DEFAULT", "prefix": "", "suffix": "", "digit": None},
+        "digit": None,
+        "aggreType": aggre_type,
+        "orderPriority": None,
+        "width": None,
+        "verticalAlign": "middle",
+        "formula": qingbi_field.get("formula"),
+        "fieldSource": qingbi_field.get("fieldSource") or "default",
+        "status": qingbi_field.get("status"),
+        "supId": qingbi_field.get("supId"),
+        "beingTable": bool(qingbi_field.get("beingTable", False)),
+        "returnType": qingbi_field.get("returnType"),
+        "biFormulaType": qingbi_field.get("biFormulaType"),
+        "aggreFieldId": qingbi_field.get("aggreFieldId"),
+    }
+
+
+def _build_public_semantic_metric_fields(
+    metrics: list[ChartMetricPatch],
+    *,
+    app_key: str,
+    field_lookup: dict[str, dict[str, Any]],
+    chart_field_lookup: dict[str, Any],
+    qingbi_fields_by_id: dict[str, dict[str, Any]],
+    chart_type: str = "chart",
+) -> list[dict[str, Any]]:
+    if not metrics:
+        return [_default_public_total_metric()]
+    selected_metrics: list[dict[str, Any]] = []
+    for metric in metrics:
+        op = str(metric.op or "count").strip().lower()
+        field_name = str(metric.field_name or "").strip()
+        if op == "count":
+            if field_name:
+                _raise_chart_rule(
+                    rule_code="CHART_COUNT_FIELD_UNSUPPORTED",
+                    chart_type=chart_type,
+                    message="count metric currently supports count(*) only",
+                    expected='Use metric: "count(*)" or {"op": "count"} for record count.',
+                    actual={"metric": metric.model_dump(mode="json")},
+                    next_action='Use count(*) for count cards; use sum(field), avg(field), max(field), or min(field) for field aggregation.',
+                )
+            selected_metrics.append(_default_public_total_metric())
             continue
-        form_field = qingbi_field.get("_public_form_field") if isinstance(qingbi_field.get("_public_form_field"), dict) else {}
-        metrics.append(
-            {
-                "fieldId": field_id,
-                "fieldName": qingbi_field.get("fieldName") or form_field.get("name") or field_id,
-                "fieldType": qingbi_field.get("fieldType") or _qingbi_field_type_from_public_field(str(form_field.get("type") or "")),
-                "orderType": "default",
-                "alignType": "left",
-                "dateFormat": "yyyy-MM-dd",
-                "numberFormat": "default",
-                "numberConfig": {"format": "splitter", "unit": "DEFAULT", "prefix": "", "suffix": "", "digit": None},
-                "digit": None,
-                "aggreType": {"sum": "sum", "avg": "avg", "average": "avg", "max": "max", "min": "min", "count": "sum", "distinct_count": "sum"}.get(normalized_aggregate, "sum"),
-                "orderPriority": None,
-                "width": None,
-                "verticalAlign": "middle",
-                "formula": qingbi_field.get("formula"),
-                "fieldSource": qingbi_field.get("fieldSource") or "default",
-                "status": qingbi_field.get("status"),
-                "supId": qingbi_field.get("supId"),
-                "beingTable": bool(qingbi_field.get("beingTable", False)),
-                "returnType": qingbi_field.get("returnType"),
-                "biFormulaType": qingbi_field.get("biFormulaType"),
-                "aggreFieldId": qingbi_field.get("aggreFieldId"),
-            }
+        qingbi_field = _resolve_qingbi_chart_field(
+            field_name,
+            chart_field_lookup=chart_field_lookup,
+            chart_type=chart_type,
+            role="metric",
         )
-    return metrics or [_default_public_total_metric()]
+        metric_payload = _public_qingbi_metric_field(qingbi_field, aggregate=op)
+        if metric.alias:
+            metric_payload["fieldName"] = metric.alias
+        selected_metrics.append(metric_payload)
+    return selected_metrics or [_default_public_total_metric()]
 
 
 def _split_axis_metric_fields(metrics: list[dict[str, Any]]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
@@ -15261,6 +15682,61 @@ def _public_chart_filter_groups_from_qingbi_config(config: dict[str, Any]) -> li
     return groups
 
 
+def _public_chart_group_by_from_qingbi_config(config: dict[str, Any]) -> list[str]:
+    fields: list[dict[str, Any]] = []
+    for key in ("selectedDimensions", "xDimensions", "yDimensions", "selectedTime"):
+        fields.extend(_chart_fields(config, key))
+    group_by: list[str] = []
+    seen: set[str] = set()
+    for field in fields:
+        name = _stringify_condition_value(
+            field.get("fieldName")
+            or field.get("field_name")
+            or field.get("queTitle")
+            or field.get("title")
+            or field.get("fieldId")
+            or field.get("field_id")
+        ).strip()
+        if not name or name in seen:
+            continue
+        seen.add(name)
+        group_by.append(name)
+    return group_by
+
+
+def _public_chart_metrics_from_qingbi_config(config: dict[str, Any]) -> list[dict[str, Any]]:
+    fields: list[dict[str, Any]] = []
+    for key in ("selectedMetrics", "xMetrics", "yMetrics", "leftMetrics", "rightMetrics"):
+        fields.extend(_chart_fields(config, key))
+    metrics: list[dict[str, Any]] = []
+    seen: set[tuple[str, str]] = set()
+    for field in fields:
+        field_id = _chart_field_id(field)
+        if field_id == _QINGBI_TOTAL_FIELD_ID:
+            metric = {"op": "count", "expr": "count(*)"}
+        else:
+            op = str(field.get("aggreType") or field.get("aggregate") or "sum").strip().lower()
+            if op == "average":
+                op = "avg"
+            field_name = _stringify_condition_value(
+                field.get("fieldName")
+                or field.get("field_name")
+                or field.get("queTitle")
+                or field.get("title")
+                or field_id
+            ).strip()
+            metric = {"op": op or "sum", "field_name": field_name}
+            if field_id:
+                metric["field_id"] = field_id
+            metric["expr"] = f"{metric['op']}({field_name})" if field_name else metric["op"]
+        identity = (str(metric.get("op") or ""), str(metric.get("field_id") or metric.get("field_name") or metric.get("expr") or ""))
+        if identity in seen:
+            continue
+        seen.add(identity)
+        metrics.append(metric)
+    return metrics
+
+
 def _public_chart_filter_operator_from_judge_type(judge_type: Any) -> str:
     normalized = _stringify_condition_value(judge_type).strip()
     mapping = {
@@ -15332,9 +15808,14 @@ def _build_public_chart_config_payload(
 ) -> dict[str, Any]:
     config = deepcopy(patch.config)
     explicit_fields = set(getattr(patch, "model_fields_set", set()) or set())
-    if "dimension_field_ids" in explicit_fields:
+    semantic_dimension_fields = bool({"dimension_field_ids", "group_by", "rows", "columns"} & explicit_fields)
+    semantic_metric_fields = bool(
+        {"indicator_field_ids", "metric", "metrics", "x_metric", "y_metric", "left_metric", "right_metric", "value_metric", "target_metric"}
+        & explicit_fields
+    )
+    if semantic_dimension_fields:
         config.pop("selectedDimensions", None)
-    if "indicator_field_ids" in explicit_fields:
+    if semantic_metric_fields:
         config.pop("selectedMetrics", None)
     if "filters" in explicit_fields:
         config.pop("beforeAggregationFilterMatrix", None)
@@ -15360,8 +15841,8 @@ def _build_public_chart_config_payload(
         )
         query_condition_field_ids.append(_chart_field_id(field))
     backend_chart_type = _map_public_chart_type_to_backend(patch.chart_type)
-    if backend_chart_type == "gauge" and not patch.indicator_field_ids and "selectedMetrics" not in config:
-        raise ValueError("gauge charts require at least one indicator_field_ids value; pass one metric and the CLI will pair it with 数据总量")
+    if backend_chart_type == "gauge" and not patch.indicator_field_ids and not patch.metrics and "selectedMetrics" not in config:
+        raise ValueError("gauge charts require at least one metric; pass value_metric or metric and the CLI will pair it with 数据总量")
     selected_dimensions = _build_public_dimension_fields(
         patch.dimension_field_ids,
         app_key=app_key,
@@ -15370,15 +15851,25 @@ def _build_public_chart_config_payload(
         qingbi_fields_by_id=qingbi_fields_by_id,
         chart_type=patch.chart_type.value,
     )
-    selected_metrics = _build_public_metric_fields(
-        patch.indicator_field_ids,
-        app_key=app_key,
-        field_lookup=field_lookup,
-        chart_field_lookup=chart_field_lookup,
-        qingbi_fields_by_id=qingbi_fields_by_id,
-        aggregate=aggregate,
-        chart_type=patch.chart_type.value,
-    )
+    if patch.metrics:
+        selected_metrics = _build_public_semantic_metric_fields(
+            patch.metrics,
+            app_key=app_key,
+            field_lookup=field_lookup,
+            chart_field_lookup=chart_field_lookup,
+            qingbi_fields_by_id=qingbi_fields_by_id,
+            chart_type=patch.chart_type.value,
+        )
+    else:
+        selected_metrics = _build_public_metric_fields(
+            patch.indicator_field_ids,
+            app_key=app_key,
+            field_lookup=field_lookup,
+            chart_field_lookup=chart_field_lookup,
+            qingbi_fields_by_id=qingbi_fields_by_id,
+            aggregate=aggregate,
+            chart_type=patch.chart_type.value,
+        )
     payload: dict[str, Any] = {
         "chartName": patch.name,
         "chartType": backend_chart_type,
@@ -15403,7 +15894,15 @@ def _build_public_chart_config_payload(
     if backend_chart_type == "summary":
         payload.pop("selectedDimensions", None)
         payload.setdefault("xDimensions", deepcopy(selected_dimensions))
-        payload.setdefault("yDimensions", [])
+        y_dimensions = _build_public_dimension_fields(
+            patch.columns,
+            app_key=app_key,
+            field_lookup=field_lookup,
+            chart_field_lookup=chart_field_lookup,
+            qingbi_fields_by_id=qingbi_fields_by_id,
+            chart_type=patch.chart_type.value,
+        )
+        payload.setdefault("yDimensions", y_dimensions)
     elif backend_chart_type == "scatter":
         x_metrics, y_metrics = _split_axis_metric_fields(selected_metrics)
         payload.pop("selectedMetrics", None)
@@ -15437,7 +15936,26 @@ def _build_public_chart_config_payload(
 
 def _chart_patch_updates_chart_config(patch: ChartUpsertPatch) -> bool:
     explicit_fields = set(getattr(patch, "model_fields_set", set()) or set())
-    return bool({"dimension_field_ids", "indicator_field_ids", "filters", "config"} & explicit_fields)
+    return bool(
+        {
+            "dimension_field_ids",
+            "indicator_field_ids",
+            "group_by",
+            "rows",
+            "columns",
+            "metric",
+            "metrics",
+            "x_metric",
+            "y_metric",
+            "left_metric",
+            "right_metric",
+            "value_metric",
+            "target_metric",
+            "filters",
+            "config",
+        }
+        & explicit_fields
+    )
 
 
 def _chart_patch_dataset_source_type(patch: ChartUpsertPatch) -> str:
@@ -15697,6 +16215,7 @@ def _empty_portal_layout_diagnostics() -> dict[str, Any]:
         "section_count": 0,
         "explicit_position_count": 0,
         "max_pc_right": None,
+        "standard_template_counts": {"metric_cards": 0, "bi_charts": 0, "views": 0},
         "safe_for_display": True,
         "warnings": [],
     }
@@ -15714,6 +16233,8 @@ def _portal_layout_diagnostics(
     diagnostics["explicit_position_count"] = explicit_count
     pc_positions: list[dict[str, Any]] = []
     warnings: list[dict[str, Any]] = []
+    standard_counts = {"metric_cards": 0, "bi_charts": 0, "views": 0}
+    has_business_grid = False
     for index, component in enumerate(components):
         if not isinstance(component, dict):
             continue
@@ -15728,9 +16249,28 @@ def _portal_layout_diagnostics(
         cols = int(pc.get("cols") or 0)
         rows = int(pc.get("rows") or 0)
         chart_type = str(metadata.get("chart_type") or "").strip().lower()
+        role = str(metadata.get("role") or getattr(section, "role", "") or "").strip().lower() if section is not None else ""
         is_metric_chart = chart_type in {"target", "indicator"}
+        if source_type == "chart" and (is_metric_chart or role in {"metric", "metrics", "indicator", "kpi"}):
+            standard_counts["metric_cards"] += 1
+        elif source_type == "chart":
+            standard_counts["bi_charts"] += 1
+        elif source_type == "view":
+            standard_counts["views"] += 1
         min_chart_cols = 6 if is_metric_chart else 8
         min_chart_rows = 5 if is_metric_chart else 7
+        if source_type == "grid":
+            has_business_grid = True
+            grid_config = component.get("gridConfig") if isinstance(component.get("gridConfig"), dict) else {}
+            grid_items = grid_config.get("items") if isinstance(grid_config, dict) else None
+            if not isinstance(grid_items, list) or not grid_items:
+                warnings.append(_warning(
+                    "PORTAL_GRID_ITEMS_EMPTY",
+                    "grid portal section has no config.items; frontend will show an empty entry container",
+                    section_index=index,
+                    title=title,
+                    fix_hint="Pass config.items with entries such as {type:1,jumpMode:1,linkAppKey,linkFormType,title}.",
+                ))
         if source_type == "chart" and (cols < min_chart_cols or rows < min_chart_rows):
             warnings.append(_warning(
                 "PORTAL_CHART_CARD_TOO_SMALL",
@@ -15744,6 +16284,16 @@ def _portal_layout_diagnostics(
                 chart_type=chart_type or None,
                 pc=deepcopy(pc),
             ))
+        if source_type == "chart" and role in {"metric", "metrics", "indicator", "kpi"} and not is_metric_chart:
+            warnings.append(_warning(
+                "PORTAL_METRIC_SECTION_CHART_TYPE_MISMATCH",
+                "metric portal section must reference a target/indicator chart; create the missing metric chart before assembling the portal",
+                section_index=index,
+                title=title,
+                role=role,
+                chart_type=chart_type or None,
+                fix_hint="Use app_charts_apply with chart_type=target and metric='count(*)' or another metric expression, then reference that chart.",
+            ))
         if section is not None and section.position is not None and not bool(getattr(section.position, "mobile_provided", False)):
             warnings.append(_warning(
                 "PORTAL_MOBILE_POSITION_MISSING",
@@ -15762,11 +16312,66 @@ def _portal_layout_diagnostics(
             max_pc_right=max_right,
             fix_hint="Use x=0/12 with cols=12 for two columns, x=0/8/16 with cols=8 for three columns, or omit position/use layout_preset.",
         ))
+    standard_categories_present = sum(1 for count in standard_counts.values() if int(count or 0) > 0)
+    _append_portal_standard_count_warnings(
+        warnings=warnings,
+        standard_counts=standard_counts,
+        require_complete_standard=has_business_grid or standard_categories_present == 3,
+    )
+    diagnostics["standard_template_counts"] = standard_counts
     diagnostics["warnings"] = warnings
-    diagnostics["safe_for_display"] = not any(item.get("code") in {"PORTAL_LAYOUT_HALF_WIDTH", "PORTAL_CHART_CARD_TOO_SMALL"} for item in warnings)
+    diagnostics["safe_for_display"] = not any(
+        item.get("code") in {
+            "PORTAL_LAYOUT_HALF_WIDTH",
+            "PORTAL_CHART_CARD_TOO_SMALL",
+            "PORTAL_GRID_ITEMS_EMPTY",
+            "PORTAL_METRIC_SECTION_CHART_TYPE_MISMATCH",
+            "PORTAL_STANDARD_METRIC_COUNT_OUT_OF_RANGE",
+            "PORTAL_STANDARD_BI_COUNT_OUT_OF_RANGE",
+            "PORTAL_STANDARD_VIEW_COUNT_OUT_OF_RANGE",
+        }
+        for item in warnings
+    )
     return diagnostics
 
 
+def _append_portal_standard_count_warnings(
+    *,
+    warnings: list[dict[str, Any]],
+    standard_counts: dict[str, int],
+    require_complete_standard: bool = False,
+) -> None:
+    metric_count = int(standard_counts.get("metric_cards") or 0)
+    bi_count = int(standard_counts.get("bi_charts") or 0)
+    view_count = int(standard_counts.get("views") or 0)
+    if not require_complete_standard:
+        return
+    if (metric_count or require_complete_standard) and not 4 <= metric_count <= 6:
+        warnings.append(_warning(
+            "PORTAL_STANDARD_METRIC_COUNT_OUT_OF_RANGE",
+            "standard portal metric area should contain 4-6 metric cards",
+            actual_count=metric_count,
+            expected_count="4-6",
+            fix_hint="Create missing target/indicator charts first, or keep 4 metric cards in one row with pc.cols=6, pc.rows=5.",
+        ))
+    if (bi_count or require_complete_standard) and not 2 <= bi_count <= 3:
+        warnings.append(_warning(
+            "PORTAL_STANDARD_BI_COUNT_OUT_OF_RANGE",
+            "standard portal BI area should contain 2-3 visualization charts",
+            actual_count=bi_count,
+            expected_count="2-3",
+            fix_hint="Use two half-width charts or three one-third-width charts with pc.rows=7.",
+        ))
+    if (view_count or require_complete_standard) and not 1 <= view_count <= 2:
+        warnings.append(_warning(
+            "PORTAL_STANDARD_VIEW_COUNT_OUT_OF_RANGE",
+            "standard portal data view area should contain 1-2 business views",
+            actual_count=view_count,
+            expected_count="1-2",
+            fix_hint="Reference 1-2 business views and avoid default 全部数据 / 我的数据 views as the main portal table.",
+        ))
+
+
 def _portal_layout_warning_items(layout_diagnostics: dict[str, Any]) -> list[dict[str, Any]]:
     warnings = layout_diagnostics.get("warnings") if isinstance(layout_diagnostics, dict) else None
     return [deepcopy(item) for item in warnings if isinstance(item, dict)] if isinstance(warnings, list) else []
@@ -16603,6 +17208,149 @@ def _verify_relation_readback_by_name(
     return True
 
 
+def _relation_field_names(values: object) -> list[str]:
+    names: list[str] = []
+    if not isinstance(values, list):
+        return names
+    for item in values:
+        if not isinstance(item, dict):
+            continue
+        name = str(item.get("name") or "").strip()
+        if name:
+            names.append(name)
+    return names
+
+
+def _relation_field_public_selector(value: object) -> dict[str, Any] | None:
+    if not isinstance(value, dict):
+        return None
+    return {
+        "name": str(value.get("name") or "").strip() or None,
+        "que_id": _coerce_nonnegative_int(value.get("que_id")),
+        "field_id": str(value.get("field_id") or "").strip() or None,
+    }
+
+
+def _schema_relation_readback_matrix(
+    *,
+    expected_fields: list[dict[str, Any]],
+    verified_fields: list[dict[str, Any]],
+    changed_field_names: set[str],
+    degraded_expectations: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    degraded_by_name = {
+        str(item.get("field_name") or "").strip(): item
+        for item in degraded_expectations
+        if isinstance(item, dict) and str(item.get("field_name") or "").strip()
+    }
+    relation_names = {
+        str(field.get("name") or "").strip()
+        for field in expected_fields
+        if isinstance(field, dict)
+        and str(field.get("type") or "") == FieldType.relation.value
+        and str(field.get("name") or "").strip() in changed_field_names
+    }
+    relation_names.update(name for name in degraded_by_name if name)
+    if not relation_names:
+        return []
+
+    expected_by_name = {
+        str(field.get("name") or "").strip(): field
+        for field in expected_fields
+        if isinstance(field, dict)
+        and str(field.get("type") or "") == FieldType.relation.value
+        and str(field.get("name") or "").strip()
+    }
+    verified_by_name = {
+        str(field.get("name") or "").strip(): field
+        for field in verified_fields
+        if isinstance(field, dict) and str(field.get("name") or "").strip()
+    }
+    rows: list[dict[str, Any]] = []
+    for field_name in sorted(relation_names):
+        expected = expected_by_name.get(field_name)
+        actual = verified_by_name.get(field_name)
+        degraded = degraded_by_name.get(field_name)
+        expected_target = str((expected or degraded or {}).get("target_app_key") or "").strip() or None
+        actual_target = str((actual or {}).get("target_app_key") or "").strip() or None
+        expected_mode = _normalize_relation_mode((expected or degraded or {}).get("relation_mode"))
+        actual_mode = _normalize_relation_mode((actual or {}).get("relation_mode"))
+        expected_display = _relation_field_public_selector((expected or degraded or {}).get("display_field"))
+        actual_display = _relation_field_public_selector((actual or {}).get("display_field"))
+        expected_visible_names = _relation_field_names((expected or degraded or {}).get("visible_fields"))
+        actual_visible_names = _relation_field_names((actual or {}).get("visible_fields"))
+
+        checks = {
+            "field_exists": isinstance(actual, dict),
+            "target_app_key": expected_target == actual_target,
+            "relation_mode": expected_mode == actual_mode,
+            "display_field": (expected_display or {}).get("name") == (actual_display or {}).get("name"),
+            "visible_fields": expected_visible_names == actual_visible_names,
+        }
+        readback_verified = all(checks.values())
+        if not isinstance(actual, dict):
+            status = "missing"
+        elif readback_verified and degraded is not None:
+            status = "matched_by_name"
+        elif readback_verified:
+            status = "matched"
+        else:
+            status = "mismatch"
+        rows.append(
+            {
+                "field_name": field_name,
+                "readback_status": status,
+                "readback_verified": readback_verified,
+                "metadata_verified": degraded is None,
+                "checks": checks,
+                "expected": {
+                    "target_app_key": expected_target,
+                    "relation_mode": expected_mode,
+                    "display_field": expected_display,
+                    "visible_fields": expected_visible_names,
+                },
+                "actual": {
+                    "target_app_key": actual_target,
+                    "relation_mode": actual_mode,
+                    "display_field": actual_display,
+                    "visible_fields": actual_visible_names,
+                },
+                "data_impact": (
+                    "none_detected"
+                    if readback_verified
+                    else "relation config mismatch can affect existing referenced values; inspect existing records before changing target_app_key or display fields"
+                ),
+            }
+        )
+    return rows
+
+
+def _schema_relation_repair_plan(relation_readback_matrix: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    plan: list[dict[str, Any]] = []
+    for row in relation_readback_matrix:
+        if bool(row.get("readback_verified")):
+            continue
+        expected = row.get("expected") if isinstance(row.get("expected"), dict) else {}
+        plan.append(
+            {
+                "field_name": row.get("field_name"),
+                "mode": "update_fields_relation_patch",
+                "next_action": "Use app_schema_apply update_fields with selector.name and set target_app_key/relation_mode/display_field/visible_fields, then read back relation_readback_matrix again.",
+                "suggested_patch": {
+                    "selector": {"name": row.get("field_name")},
+                    "set": {
+                        "target_app_key": expected.get("target_app_key"),
+                        "relation_mode": expected.get("relation_mode"),
+                        "display_field": expected.get("display_field"),
+                        "visible_fields": [{"name": name} for name in cast(list[Any], expected.get("visible_fields") or [])],
+                    },
+                },
+                "data_impact": row.get("data_impact"),
+            }
+        )
+    return plan
+
+
 def _relation_target_metadata_skip_outcome(*, degraded_entries: list[dict[str, Any]]) -> PermissionCheckOutcome | None:
     if not degraded_entries:
         return None