@josephyan/qingflow-app-builder-mcp 1.1.26 → 1.1.27

package/src/qingflow_mcp/builder_facade/service.py

@@ -11,7 +11,7 @@ import re
 import string
 import time
 import tempfile
-from typing import Any, cast
+from typing import Any, NoReturn, cast
 from urllib.parse import quote_plus, unquote_plus
 from uuid import uuid4
 
@@ -49,6 +49,7 @@ from .models import (
     AssociatedResourceUpsertPatch,
     AssociatedResourceViewConfigPatch,
     ChartApplyRequest,
+    ChartMetricPatch,
     ChartPartialPatch,
     ChartUpsertPatch,
     CustomButtonsApplyRequest,
@@ -5238,6 +5239,20 @@ class AiBuilderFacade:
             result["message"] = "read app chart config"
         return result
 
+    def _chart_filter_field_names_by_id(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+    ) -> tuple[dict[str, str], dict[str, Any] | None]:
+        try:
+            state = self._load_base_schema_state(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return {}, _transport_error_payload(api_error)
+        fields = cast(list[dict[str, Any]], state["parsed"]["fields"])
+        return _chart_field_names_by_id_from_public_fields(app_key=app_key, fields=fields), None
+
     def app_get_buttons(self, *, profile: str, app_key: str) -> JSONObject:
         """Read custom buttons for a single app."""
         self.apps._require_app_key(app_key)
@@ -5796,6 +5811,8 @@ class AiBuilderFacade:
             )
         charts = _summarize_charts(items)
         chart_visibility_read_errors: list[dict[str, Any]] = []
+        chart_config_read_errors: list[dict[str, Any]] = []
+        field_name_by_id, field_name_read_error = self._chart_filter_field_names_by_id(profile=profile, app_key=resolved_app_key)
         for chart in charts:
             chart_id = str(chart.get("chart_id") or "").strip()
             if not chart_id:
@@ -5818,6 +5835,24 @@ class AiBuilderFacade:
                     base_info.get("visibleAuth") if isinstance(base_info, dict) else None
                 )
             )
+            try:
+                config_response = self.charts.qingbi_report_get_config(profile=profile, chart_id=chart_id)
+                config = config_response.get("result") or {}
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                chart_config_read_errors.append(
+                    {
+                        "chart_id": chart_id,
+                        "request_id": api_error.request_id,
+                        "http_status": api_error.http_status,
+                        "backend_code": api_error.backend_code,
+                    }
+                )
+                continue
+            if isinstance(config, dict):
+                chart["group_by"] = _public_chart_group_by_from_qingbi_config(config)
+                chart["metrics"] = _public_chart_metrics_from_qingbi_config(config)
+                chart["filters"] = _public_chart_filter_groups_from_qingbi_config(config, field_name_by_id=field_name_by_id)
         response = AppChartsReadResponse(
             app_key=resolved_app_key,
             charts=charts,
@@ -5831,7 +5866,11 @@ class AiBuilderFacade:
             "normalized_args": {"app_key": resolved_app_key},
             "missing_fields": [],
             "allowed_values": {},
-            "details": {"chart_visibility_read_errors": chart_visibility_read_errors} if chart_visibility_read_errors else {},
+            "details": {
+                **({"chart_visibility_read_errors": chart_visibility_read_errors} if chart_visibility_read_errors else {}),
+                **({"chart_config_read_errors": chart_config_read_errors} if chart_config_read_errors else {}),
+                **({"chart_filter_field_name_read_error": field_name_read_error} if field_name_read_error else {}),
+            },
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
@@ -5842,12 +5881,24 @@ class AiBuilderFacade:
                     if chart_visibility_read_errors
                     else []
                 )
+                + (
+                    [_warning("CHART_CONFIG_READ_PARTIAL", "some chart configs could not be read back; metrics/group_by/filters are incomplete for those charts")]
+                    if chart_config_read_errors
+                    else []
+                )
+                + (
+                    [_warning("CHART_FILTER_FIELD_NAMES_UNRESOLVED", "chart configs were read, but form fields could not be loaded to resolve filter field names")]
+                    if field_name_read_error
+                    else []
+                )
             ),
             "verification": {
                 "app_exists": True,
                 "chart_order_verified": list_source == "sorted",
                 "chart_list_source": list_source,
                 "chart_visibility_readback_complete": not chart_visibility_read_errors,
+                "chart_config_readback_complete": not chart_config_read_errors,
+                "chart_filter_field_names_resolved": field_name_read_error is None,
             },
             "verified": True,
             **response.model_dump(mode="json"),
@@ -6877,10 +6928,27 @@ class AiBuilderFacade:
                     suggested_next_call={"tool_name": "chart_get", "arguments": {"profile": profile, "chart_id": chart_id}},
                 )
 
+        field_name_by_id: dict[str, str] = {}
+        data_source = config.get("dataSource") if isinstance(config.get("dataSource"), dict) else {}
+        data_source_app_key = str(data_source.get("dataSourceId") or config.get("dataSourceId") or "").strip()
+        if data_source_app_key:
+            field_name_by_id, field_name_error = self._chart_filter_field_names_by_id(profile=profile, app_key=data_source_app_key)
+            if field_name_error:
+                warnings.append(
+                    _warning(
+                        "CHART_FILTER_FIELD_NAMES_UNRESOLVED",
+                        "chart config was read, but form fields could not be loaded to resolve filter field names",
+                        **field_name_error,
+                    )
+                )
+
         response = ChartGetResponse(
             chart_id=chart_id,
             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, field_name_by_id=field_name_by_id) 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 {
@@ -7380,6 +7448,8 @@ class AiBuilderFacade:
         add_fields: list[FieldPatch],
         update_fields: list[FieldUpdatePatch],
         remove_fields: list[FieldRemovePatch],
+        layout_mode: LayoutApplyMode = LayoutApplyMode.merge,
+        layout_sections: list[LayoutSectionPatch] | None = None,
     ) -> JSONObject:
         normalized_args = {
             "app_key": app_key,
@@ -7394,6 +7464,10 @@ class AiBuilderFacade:
             "update_fields": [patch.model_dump(mode="json") for patch in update_fields],
             "remove_fields": [patch.model_dump(mode="json") for patch in remove_fields],
         }
+        layout_requested = layout_sections is not None
+        requested_layout_sections = [section.model_dump(mode="json", exclude_none=True) for section in (layout_sections or [])]
+        if layout_requested:
+            normalized_args["form"] = {"mode": layout_mode.value, "sections": deepcopy(requested_layout_sections)}
         try:
             desired_auth = (
                 self._compile_visibility_to_member_auth(profile=profile, visibility=visibility)
@@ -7409,7 +7483,7 @@ class AiBuilderFacade:
                 suggested_next_call=None,
             )
         permission_outcomes: list[PermissionCheckOutcome] = []
-        requested_field_changes = bool(add_fields or update_fields or remove_fields)
+        requested_field_changes = bool(add_fields or update_fields or remove_fields or layout_requested)
         resolved: JSONObject
         if app_key:
             resolved = self.app_resolve(profile=profile, app_key=app_key)
@@ -7533,7 +7607,6 @@ class AiBuilderFacade:
                 "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,
@@ -7573,6 +7646,9 @@ class AiBuilderFacade:
         current_fields = parsed["fields"]
         original_fields = deepcopy(current_fields)
         layout = parsed["layout"]
+        original_layout = deepcopy(layout)
+        layout_write_requested = False
+        applied_layout = deepcopy(layout)
         existing_index = {field["field_id"]: index for index, field in enumerate(current_fields)}
         selector_map = _build_selector_map(current_fields)
         added: list[str] = []
@@ -7727,6 +7803,71 @@ class AiBuilderFacade:
                 suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": target.app_key}},
             )
 
+        if layout_requested:
+            resolved_sections, missing_selectors = _resolve_layout_sections_to_names(requested_layout_sections, current_fields)
+            normalized_args["form"] = {"mode": layout_mode.value, "sections": deepcopy(resolved_sections)}
+            if missing_selectors:
+                return _failed(
+                    "UNKNOWN_LAYOUT_FIELD",
+                    "form layout references unknown field selectors",
+                    normalized_args=normalized_args,
+                    details={"unknown_selectors": missing_selectors, "app_key": target.app_key},
+                    missing_fields=[str(item) for item in missing_selectors],
+                    suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": target.app_key}},
+                )
+            fields_by_name = {field["name"]: field for field in current_fields}
+            seen_layout_fields: list[str] = []
+            for section in resolved_sections:
+                for row in section.get("rows", []):
+                    for field_name in row:
+                        if field_name not in fields_by_name:
+                            return _failed(
+                                "UNKNOWN_LAYOUT_FIELD",
+                                f"form layout references unknown field '{field_name}'",
+                                normalized_args=normalized_args,
+                                details={"field_name": field_name, "app_key": target.app_key},
+                                suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": target.app_key}},
+                            )
+                        if field_name in seen_layout_fields:
+                            return _failed(
+                                "DUPLICATE_LAYOUT_FIELD",
+                                f"form layout references field '{field_name}' more than once",
+                                normalized_args=normalized_args,
+                                details={"field_name": field_name, "app_key": target.app_key},
+                                suggested_next_call={"tool_name": "app_schema_apply", "arguments": {"profile": profile, **normalized_args}},
+                            )
+                        seen_layout_fields.append(field_name)
+            expected_layout_fields = {field["name"] for field in current_fields}
+            if layout_mode == LayoutApplyMode.replace and set(seen_layout_fields) != expected_layout_fields:
+                missing = sorted(expected_layout_fields.difference(seen_layout_fields))
+                return _failed(
+                    "INCOMPLETE_LAYOUT",
+                    "form layout must reference every current field exactly once in replace mode",
+                    normalized_args=normalized_args,
+                    details={
+                        "missing_fields": missing,
+                        "auto_fill_preview": _merge_layout(
+                            current_layout=layout,
+                            requested_sections=resolved_sections,
+                            all_field_names=[field["name"] for field in current_fields],
+                        )["layout"],
+                    },
+                    missing_fields=missing,
+                    suggested_next_call={"tool_name": "app_schema_apply", "arguments": {"profile": profile, **normalized_args}},
+                )
+            merged_layout = _merge_layout(
+                current_layout=layout,
+                requested_sections=resolved_sections,
+                all_field_names=[field["name"] for field in current_fields],
+            )
+            applied_layout = (
+                {"root_rows": [], "sections": resolved_sections}
+                if layout_mode == LayoutApplyMode.replace
+                else merged_layout["layout"]
+            )
+            layout_write_requested = not _layouts_equal(layout, applied_layout)
+            layout = applied_layout
+
         schema_write_requested = bool(
             added
             or updated
@@ -7734,6 +7875,7 @@ class AiBuilderFacade:
             or normalized_code_block_fields
             or data_display_selection.has_any
             or bool(resolved.get("created"))
+            or layout_write_requested
         )
         if schema_write_requested:
             try:
@@ -7756,12 +7898,6 @@ class AiBuilderFacade:
                 )
 
         relation_field_count = _count_relation_fields(current_fields)
-        relation_limit_verified = relation_field_count <= 1
-        relation_warnings = (
-            [_warning("RELATION_FIELD_LIMIT_RISK", "multiple relation fields are not a stable backend capability", relation_field_count=relation_field_count)]
-            if not relation_limit_verified
-            else []
-        )
         code_block_normalization_warnings = (
             [
                 _warning(
@@ -7774,7 +7910,15 @@ class AiBuilderFacade:
             else []
         )
 
-        if not added and not updated and not removed and not normalized_code_block_fields and not data_display_selection.has_any and not bool(resolved.get("created")):
+        if (
+            not added
+            and not updated
+            and not removed
+            and not normalized_code_block_fields
+            and not data_display_selection.has_any
+            and not bool(resolved.get("created"))
+            and not layout_write_requested
+        ):
             base_info = self.apps.app_get_base(profile=profile, app_key=target.app_key, include_raw=True).get("result") or {}
             tag_ids_after = _coerce_int_list(base_info.get("tagIds"))
             package_attached = None if package_tag_id is None else package_tag_id in tag_ids_after
@@ -7796,10 +7940,10 @@ class AiBuilderFacade:
                 "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": not bool(visual_result.get("updated")),
-                "warnings": relation_warnings + code_block_normalization_warnings,
+                "warnings": code_block_normalization_warnings,
                 "verification": {
                     "fields_verified": True,
-                    "relation_field_limit_verified": relation_limit_verified,
+                    "form_layout_verified": True,
                     "app_visuals_verified": app_base_verified,
                     "app_base_verified": app_base_verified,
                     "relation_target_metadata_verified": relation_target_metadata_verified,
@@ -7817,6 +7961,12 @@ class AiBuilderFacade:
                 "package_attached": package_attached,
             }
             response["details"]["relation_field_count"] = relation_field_count
+            if layout_requested:
+                response["details"]["form_layout_diff"] = {
+                    "mode": layout_mode.value,
+                    "changed": False,
+                    "requested_section_count": len(requested_layout_sections),
+                }
             if normalized_code_block_fields:
                 response["normalized_code_block_output_assignment"] = True
                 response["normalized_code_block_fields"] = normalized_code_block_fields
@@ -7850,26 +8000,6 @@ class AiBuilderFacade:
             self.apps.app_update_form_schema(profile=profile, app_key=target.app_key, payload=payload)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
-            if api_error.backend_code == 49614:
-                return _failed(
-                    "MULTIPLE_RELATION_FIELDS_UNSUPPORTED",
-                    "backend currently rejects apps with more than one relation field; keep one real relation field and use text/reference summary fields for additional cross-object links.",
-                    normalized_args=normalized_args,
-                    details={
-                        "app_key": target.app_key,
-                        "field_diff": {"added": added, "updated": updated, "removed": removed},
-                        "relation_field_count": relation_field_count,
-                        "transport_error": {
-                            "http_status": api_error.http_status,
-                            "backend_code": api_error.backend_code,
-                            "category": api_error.category,
-                        },
-                    },
-                    request_id=api_error.request_id,
-                    backend_code=api_error.backend_code,
-                    http_status=None if api_error.http_status == 404 else api_error.http_status,
-                    suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": target.app_key}},
-                )
             return _failed_from_api_error(
                 "SCHEMA_APPLY_FAILED",
                 api_error,
@@ -7993,13 +8123,13 @@ class AiBuilderFacade:
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
-            "warnings": relation_warnings + code_block_normalization_warnings,
+            "warnings": code_block_normalization_warnings,
             "verification": {
                 "fields_verified": False,
                 "package_attached": None,
                 "app_visuals_verified": True,
                 "app_base_verified": True,
-                "relation_field_limit_verified": relation_limit_verified,
+                "form_layout_verified": not layout_requested,
                 "relation_target_metadata_verified": relation_target_metadata_verified,
             },
             "app_key": target.app_key,
@@ -8026,6 +8156,12 @@ class AiBuilderFacade:
             "package_attached": None,
         }
         response["details"]["relation_field_count"] = relation_field_count
+        if layout_requested:
+            response["details"]["form_layout_diff"] = {
+                "mode": layout_mode.value,
+                "changed": layout_write_requested,
+                "requested_section_count": len(requested_layout_sections),
+            }
         if normalized_code_block_fields:
             response["normalized_code_block_output_assignment"] = True
             response["normalized_code_block_fields"] = normalized_code_block_fields
@@ -8048,6 +8184,11 @@ class AiBuilderFacade:
                 after_fields=cast(list[dict[str, Any]], verified["schema"]["fields"]),
             )
             verification_ok = all(name in verified_field_names for name in added + updated) and all(name not in verified_field_names for name in removed)
+            if layout_requested:
+                verified_layout = cast(dict[str, Any], verified.get("layout") or {"root_rows": [], "sections": []})
+                layout_verified = _layouts_equal(verified_layout, applied_layout) or _layouts_semantically_equal(verified_layout, applied_layout)
+                response["verification"]["form_layout_verified"] = layout_verified
+                verification_ok = verification_ok and layout_verified
             data_display_verification = _verify_data_display_readback(
                 form_settings=verified.get("form_settings"),
                 selection=data_display_selection,
@@ -8091,7 +8232,6 @@ class AiBuilderFacade:
         response["verification"]["package_attached"] = package_attached
         response["verification"]["app_visuals_verified"] = app_base_verified
         response["verification"]["app_base_verified"] = app_base_verified
-        response["verification"]["relation_field_limit_verified"] = relation_limit_verified
         response["verified"] = verification_ok and app_base_verified
         response["tag_ids_after"] = tag_ids_after
         response["package_attached"] = package_attached
@@ -10304,6 +10444,7 @@ class AiBuilderFacade:
                     )
                 if existing is None:
                     temp_chart_id = str(patch.chart_id or f"mcp_{uuid4().hex[:16]}")
+                    chart_id = temp_chart_id
                     create_payload = {
                         "chartId": temp_chart_id,
                         "chartName": patch.name,
@@ -13693,7 +13834,18 @@ def _build_qingbi_chart_field_lookup(
     field_lookup: dict[str, dict[str, Any]],
 ) -> dict[str, Any]:
     by_selector: dict[str, list[dict[str, Any]]] = {}
-    form_by_que_id = field_lookup.get("by_que_id") or {}
+    form_by_que_id = dict(field_lookup.get("by_que_id") or {})
+    if not form_by_que_id:
+        for bucket_name in ("by_name", "by_field_id"):
+            bucket = field_lookup.get(bucket_name) or {}
+            if not isinstance(bucket, dict):
+                continue
+            for form_field in bucket.values():
+                if not isinstance(form_field, dict):
+                    continue
+                que_id = _coerce_any_int(form_field.get("que_id"))
+                if que_id is not None:
+                    form_by_que_id.setdefault(que_id, form_field)
 
     def add_selector(key: Any, field: dict[str, Any]) -> None:
         normalized = str(key or "").strip()
@@ -14082,37 +14234,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]]]:
@@ -14134,73 +14329,6 @@ def _two_gauge_metric_fields(metrics: list[dict[str, Any]], *, requested_metric_
     return [deepcopy(metrics[0]), deepcopy(metrics[1])]
 
 
-def _qingbi_filter_judge_type(operator: str) -> str:
-    return {
-        ViewFilterOperator.eq.value: "equal",
-        ViewFilterOperator.neq.value: "notEqual",
-        ViewFilterOperator.gte.value: "greaterOrEqual",
-        ViewFilterOperator.lte.value: "lessOrEqual",
-        ViewFilterOperator.in_.value: "anyMatch",
-        ViewFilterOperator.contains.value: "contains",
-        ViewFilterOperator.is_empty.value: "isNull",
-        ViewFilterOperator.not_empty.value: "isNotNull",
-    }.get(operator, "equal")
-
-
-def _qingbi_option_label_lookup(*, form_field: dict[str, Any], qingbi_field: dict[str, Any]) -> dict[str, str]:
-    labels: dict[str, str] = {}
-
-    def add_option(raw_option: Any) -> None:
-        if isinstance(raw_option, dict):
-            label = raw_option.get("value")
-            if label is None:
-                label = raw_option.get("label") or raw_option.get("name") or raw_option.get("title") or raw_option.get("optValue")
-            label_text = str(label).strip() if label is not None else ""
-            for key in ("id", "optionId", "option_id", "optId", "value", "label", "name", "title", "optValue"):
-                raw_key = raw_option.get(key)
-                if raw_key is not None and str(raw_key).strip() and label_text:
-                    labels[str(raw_key).strip()] = label_text
-        elif raw_option is not None:
-            label_text = str(raw_option).strip()
-            if label_text:
-                labels[label_text] = label_text
-
-    for option in form_field.get("option_details") or []:
-        add_option(option)
-    for option in form_field.get("options") or []:
-        add_option(option)
-    for option in qingbi_field.get("options") or qingbi_field.get("option_details") or []:
-        add_option(option)
-    return labels
-
-
-def _qingbi_filter_text_values(values: list[Any], *, form_field: dict[str, Any], qingbi_field: dict[str, Any]) -> list[str]:
-    labels = _qingbi_option_label_lookup(form_field=form_field, qingbi_field=qingbi_field)
-    normalized: list[str] = []
-    for value in values:
-        if isinstance(value, dict):
-            raw_label = value.get("value") or value.get("label") or value.get("name") or value.get("title") or value.get("optValue")
-            if raw_label is not None and str(raw_label).strip():
-                normalized.append(str(raw_label).strip())
-                continue
-            raw_id = value.get("id") or value.get("optionId") or value.get("option_id") or value.get("optId")
-            raw_text = str(raw_id).strip() if raw_id is not None else ""
-        else:
-            raw_text = str(value).strip()
-        if not raw_text:
-            continue
-        normalized.append(labels.get(raw_text, raw_text))
-    return normalized
-
-
-def _qingbi_filter_judge_value(values: list[str]) -> Any:
-    if not values:
-        return ""
-    if len(values) == 1:
-        return values[0]
-    return values
-
-
 def _build_public_chart_filter_matrix(
     rules: list[Any],
     *,
@@ -14213,6 +14341,16 @@ def _build_public_chart_filter_matrix(
     if not rules:
         return []
     group: list[dict[str, Any]] = []
+    judge_map = {
+        ViewFilterOperator.eq.value: "equal",
+        ViewFilterOperator.neq.value: "unequal",
+        ViewFilterOperator.gte.value: "greaterOrEqual",
+        ViewFilterOperator.lte.value: "lessOrEqual",
+        ViewFilterOperator.in_.value: "anyMatch",
+        ViewFilterOperator.contains.value: "include",
+        ViewFilterOperator.is_empty.value: "isNull",
+        ViewFilterOperator.not_empty.value: "notNull",
+    }
     for rule in rules:
         qingbi_field = _resolve_qingbi_chart_field(
             getattr(rule, "field_name", None),
@@ -14224,21 +14362,301 @@ def _build_public_chart_filter_matrix(
         form_field = qingbi_field.get("_public_form_field") if isinstance(qingbi_field.get("_public_form_field"), dict) else {}
         operator = str(getattr(rule, "operator", ViewFilterOperator.eq.value).value if hasattr(getattr(rule, "operator", None), "value") else getattr(rule, "operator", ViewFilterOperator.eq.value))
         values = list(getattr(rule, "values", []) or [])
-        text_values = _qingbi_filter_text_values(values, form_field=form_field, qingbi_field=qingbi_field)
         group.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 "")),
-                "judgeType": _qingbi_filter_judge_type(operator),
-                "judgeValue": _qingbi_filter_judge_value(text_values),
-                "judgeValues": text_values,
+                "judgeType": judge_map.get(operator, "equal"),
+                "judgeValue": _build_qingbi_chart_filter_judge_value(
+                    operator=operator,
+                    values=values,
+                    form_field=form_field,
+                    chart_type=chart_type,
+                ),
+                "judgeValueDetailList": [],
                 "matchType": 1,
             }
         )
     return [group] if group else []
 
 
+def _build_qingbi_chart_filter_judge_value(
+    *,
+    operator: str,
+    values: list[Any],
+    form_field: dict[str, Any],
+    chart_type: str,
+) -> str | None:
+    if operator in {ViewFilterOperator.is_empty.value, ViewFilterOperator.not_empty.value}:
+        return None
+    if operator == ViewFilterOperator.in_.value:
+        return "<&&>".join(
+            _qingbi_chart_filter_value_to_text(value=value, form_field=form_field, chart_type=chart_type) for value in values
+        )
+    if not values:
+        return ""
+    return _qingbi_chart_filter_value_to_text(value=values[0], form_field=form_field, chart_type=chart_type)
+
+
+def _qingbi_chart_filter_value_to_text(*, value: Any, form_field: dict[str, Any], chart_type: str) -> str:
+    option_details = [
+        item
+        for item in (form_field.get("option_details") or [])
+        if isinstance(item, dict) and item.get("id") is not None and item.get("value") is not None
+    ]
+    if not option_details:
+        if isinstance(value, dict):
+            for key in ("value", "label", "name", "title"):
+                raw = str(value.get(key) or "").strip()
+                if raw:
+                    return raw
+            if value.get("id") is not None:
+                return str(value.get("id"))
+        return _stringify_condition_value(value)
+
+    option_by_value = {str(item.get("value") or "").strip(): item for item in option_details if str(item.get("value") or "").strip()}
+    option_by_id = {str(item.get("id")): item for item in option_details if item.get("id") is not None}
+
+    def resolve(raw: Any) -> str | None:
+        text = _stringify_condition_value(raw).strip()
+        if not text:
+            return None
+        matched = option_by_value.get(text) or option_by_id.get(text)
+        if not matched:
+            return None
+        return str(matched.get("value") or "").strip()
+
+    def reject(raw: Any) -> NoReturn:
+        allowed = [
+            {"id": str(item.get("id")), "value": str(item.get("value"))}
+            for item in option_details
+        ]
+        _raise_chart_rule(
+            rule_code="CHART_FILTER_OPTION_VALUE_UNSUPPORTED",
+            chart_type=chart_type,
+            message="chart filter value is not in the field option list",
+            expected="Use an existing option label or option id from the target field schema.",
+            actual={
+                "field_name": form_field.get("name"),
+                "field_id": form_field.get("que_id"),
+                "value": raw,
+                "allowed_values": allowed,
+            },
+            offending_fields=[{"field_name": form_field.get("name"), "field_id": form_field.get("que_id"), "options": allowed}],
+            next_action="Read schema first, then pass one of the allowed option labels or option ids.",
+        )
+
+    if isinstance(value, dict):
+        for key in ("value", "label", "name", "title"):
+            if value.get(key) is not None:
+                resolved = resolve(value.get(key))
+                if resolved is not None:
+                    return resolved
+                reject(value.get(key))
+        if value.get("id") is not None:
+            resolved = resolve(value.get("id"))
+            if resolved is not None:
+                return resolved
+            reject(value.get("id"))
+        reject(value)
+    if isinstance(value, int):
+        resolved = resolve(value)
+        if resolved is not None:
+            return resolved
+        reject(value)
+    resolved = resolve(value)
+    if resolved is not None:
+        return resolved
+    reject(value)
+
+
+def _chart_field_names_by_id_from_public_fields(*, app_key: str, fields: list[dict[str, Any]]) -> dict[str, str]:
+    field_name_by_id: dict[str, str] = {}
+    for field in fields:
+        if not isinstance(field, dict):
+            continue
+        name = str(field.get("name") or "").strip()
+        if not name:
+            continue
+        que_id = field.get("que_id")
+        field_id = str(field.get("field_id") or "").strip()
+        for raw_key in (
+            que_id,
+            field_id,
+            f"{app_key}:{que_id}" if que_id is not None else None,
+            f"{app_key}:{field_id}" if field_id else None,
+        ):
+            key = str(raw_key or "").strip()
+            if key:
+                field_name_by_id.setdefault(key, name)
+    return field_name_by_id
+
+
+def _public_chart_filter_groups_from_qingbi_config(
+    config: dict[str, Any],
+    *,
+    field_name_by_id: dict[str, str] | None = None,
+) -> list[list[dict[str, Any]]]:
+    groups: list[list[dict[str, Any]]] = []
+    raw_groups = config.get("beforeAggregationFilterMatrix")
+    if not isinstance(raw_groups, list):
+        return groups
+    resolved_field_name_by_id = field_name_by_id or {}
+    for raw_group in raw_groups:
+        if not isinstance(raw_group, list):
+            continue
+        group: list[dict[str, Any]] = []
+        for raw_rule in raw_group:
+            if not isinstance(raw_rule, dict):
+                continue
+            operator = _public_chart_filter_operator_from_judge_type(raw_rule.get("judgeType"))
+            field_id = raw_rule.get("fieldId") or raw_rule.get("field_id")
+            field_id_text = _stringify_condition_value(field_id).strip() if field_id is not None else ""
+            raw_field_name = (
+                raw_rule.get("fieldName")
+                or raw_rule.get("field_name")
+                or raw_rule.get("queTitle")
+                or raw_rule.get("title")
+            )
+            raw_field_name_text = _stringify_condition_value(raw_field_name).strip()
+            field_name = (
+                resolved_field_name_by_id.get(raw_field_name_text)
+                or resolved_field_name_by_id.get(field_id_text)
+                or raw_field_name_text
+                or field_id_text
+            )
+            public_rule: dict[str, Any] = {
+                "field_name": field_name,
+                "operator": operator,
+            }
+            if field_id is not None:
+                public_rule["field_id"] = field_id_text
+            values = _public_chart_filter_values_from_rule(raw_rule, operator=operator)
+            if values:
+                public_rule["values"] = values
+            group.append(public_rule)
+        if group:
+            groups.append(group)
+    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 = {
+        "equal": "eq",
+        "equals": "eq",
+        "=": "eq",
+        "unequal": "neq",
+        "notEqual": "neq",
+        "!=": "neq",
+        "anyMatch": "in",
+        "oneOf": "in",
+        "include": "contains",
+        "contains": "contains",
+        "greaterOrEqual": "gte",
+        "gte": "gte",
+        "lessOrEqual": "lte",
+        "lte": "lte",
+        "isNull": "is_empty",
+        "empty": "is_empty",
+        "notNull": "not_empty",
+        "not_empty": "not_empty",
+    }
+    if normalized in mapping:
+        return mapping[normalized]
+    numeric = _coerce_nonnegative_int(judge_type)
+    if numeric is not None:
+        return _public_view_filter_operator_from_judge_type(numeric)
+    return f"judge_type:{judge_type}"
+
+
+def _public_chart_filter_values_from_rule(rule: dict[str, Any], *, operator: str) -> list[str]:
+    if operator in {"is_empty", "not_empty"}:
+        return []
+    raw_value = rule.get("judgeValue")
+    if raw_value is None and "judgeValues" in rule:
+        raw_value = rule.get("judgeValues")
+    values: list[str] = []
+    if isinstance(raw_value, list):
+        values = [_stringify_condition_value(value).strip() for value in raw_value]
+    elif isinstance(raw_value, str) and "<&&>" in raw_value:
+        values = [value.strip() for value in raw_value.split("<&&>")]
+    elif raw_value is not None:
+        values = [_stringify_condition_value(raw_value).strip()]
+    values = [value for value in values if value]
+    if values:
+        return values
+    for detail_key in ("judgeValueDetailList", "judgeValueDetails"):
+        details = rule.get(detail_key)
+        if not isinstance(details, list):
+            continue
+        for detail in details:
+            if not isinstance(detail, dict):
+                continue
+            for value_key in ("value", "label", "name", "title", "dataValue", "id"):
+                value = _stringify_condition_value(detail.get(value_key)).strip()
+                if value:
+                    values.append(value)
+                    break
+    return values
+
+
 def _build_public_chart_config_payload(
     *,
     patch: ChartUpsertPatch,
@@ -14249,9 +14667,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)
@@ -14277,8 +14700,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,
@@ -14287,15 +14710,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,
@@ -14320,7 +14753,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)
@@ -14354,7 +14795,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: