@qingflow-tech/qingflow-cli 1.1.61-beta.4 → 1.1.61-beta.6

package/src/qingflow_mcp/builder_facade/service.py

@@ -26,7 +26,12 @@ from ..resource_uri import validate_positive_resource_id, validate_resource_iden
 from ..solution.build_assembly_store import BuildAssemblyStore, default_artifacts, default_manifest
 from ..solution.compiler.chart_compiler import qingbi_workspace_visible_auth
 from ..solution.compiler.form_compiler import build_question, default_form_payload, default_member_auth
-from ..solution.compiler.icon_utils import encode_workspace_icon_with_defaults, workspace_icon_config
+from ..solution.compiler.icon_utils import (
+    encode_workspace_icon_with_defaults,
+    update_workspace_icon_from_existing,
+    validate_workspace_icon_choice,
+    workspace_icon_config,
+)
 from ..solution.compiler.view_compiler import VIEW_TYPE_MAP
 from ..solution.executor import _build_viewgraph_questions, _compact_dict, _flatten_viewgraph_questions, extract_field_map
 from ..solution.spec_models import FieldType, FormLayoutRowSpec, FormLayoutSectionSpec, ViewSpec
@@ -35,6 +40,7 @@ from ..tools.custom_button_tools import CustomButtonTools
 from ..tools.directory_tools import DirectoryTools
 from ..tools.package_tools import PackageTools
 from ..tools.portal_tools import PortalTools
+from ..tools.portal_writer import PortalWriter
 from ..tools.qingbi_report_tools import QingbiReportTools
 from ..tools.role_tools import RoleTools
 from ..tools.solution_tools import SolutionTools
@@ -45,6 +51,7 @@ from . import workflow_spec as workflow_spec_api
 from .button_style_catalog import button_style_catalog_payload
 from ..tools.view_writer import ViewWriter
 from .views_schema import ViewsContractError, compact_none_values, views_schema_registry
+from .portals_schema import PortalsContractError, PortalsSchemaContext, portals_schema_registry
 from .models import (
     AppChartsReadResponse,
     AppFieldsReadResponse,
@@ -81,6 +88,7 @@ from .models import (
     LayoutSectionPatch,
     LayoutPreset,
     PortalApplyRequest,
+    public_portal_apply_payload,
     PortalGetResponse,
     PortalListResponse,
     PortalReadSummaryResponse,
@@ -167,6 +175,8 @@ FIELD_TYPE_TO_QUESTION_TYPE: dict[str, int] = {
 # 落库),运行时 DataSvcImpl.getAnswerValueByString:attachment 按拆分 URL 写入、
 # subtable 整表组装(均有专门分支),rich_text/data_relation 走 Question.canImport
 # 兜底按字符串写入(不报错)——四者为存量合法配置,与 validator 侧白名单同口径。
+# r10 再放行 link/member(存量实证:92nl6blfk402 link×2、ab9fjvj33001 member;
+# 运行时同为字符串写入路径)。
 INTEGRATION_OUTPUT_TARGET_FIELD_TYPES: tuple[str, ...] = (
     FieldType.text.value,
     FieldType.long_text.value,
@@ -181,6 +191,8 @@ INTEGRATION_OUTPUT_TARGET_FIELD_TYPES: tuple[str, ...] = (
     FieldType.attachment.value,
     "data_relation",
     FieldType.subtable.value,
+    "link",
+    "member",
 )
 
 MATCH_TYPE_ACCURACY = 1
@@ -191,6 +203,9 @@ JUDGE_INCLUDE = 2
 JUDGE_GREATER_OR_EQUAL = 5
 JUDGE_LESS_OR_EQUAL = 7
 JUDGE_EQUAL_ANY = 9
+# 成员/部门归属判定(Constants.JUDGE_BELONG_TO):轮播筛选存量数据出现,后端公式引擎
+# JUDGE_FUNCTION[13]="JUDGE_BELONG_TO" 全支持,声明侧以 belongs_to 表达保真回写。
+JUDGE_BELONG_TO = 13
 JUDGE_FUZZY_MATCH = 19
 JUDGE_INCLUDE_ANY = 20
 DEFAULT_TYPE_RELATION = 2
@@ -305,6 +320,7 @@ class AiBuilderFacade:
         self._view_writer = ViewWriter(views.sessions, views.backend)
         self.workflows = workflows
         self.portals = portals
+        self._portal_writer = PortalWriter(portals.sessions, portals.backend)
         self.charts = charts
         self.roles = roles
         self.directory = directory
@@ -3052,6 +3068,7 @@ class AiBuilderFacade:
         *,
         profile: str,
         visibility: VisibilityPatch | None,
+        degradation_warnings: list[dict[str, Any]] | None = None,
     ) -> dict[str, Any]:
         if visibility is None:
             return default_member_auth()
@@ -3085,27 +3102,116 @@ class AiBuilderFacade:
             member_ids=visibility.external_selectors.member_ids,
             member_emails=visibility.external_selectors.member_emails,
         )
-        # 冗余引用降级:提取器对同一成员同时产出 uid/email/name 三通道(uid 必有且直通解析,
-        # 保证成员不丢);email/name 走后端通讯录搜索,受数据/权限边界影响解析可能失败。
-        # 这类失败降级为非阻断——只有 uid/dept_id 直通也覆盖不了的引用才真正阻断。
+        # 冗余引用降级(review §2-1 逐主体锚定校验):提取器对同一成员同时产出
+        # uid/email/name 三通道(uid 必有且直通解析,保证成员不丢);email/name 走
+        # 后端通讯录搜索,受数据/权限边界影响解析可能失败。降级只在「该主体已被
+        # 直通锚覆盖」时成立,否则升级为阻断——关闭手写声明混用 uid 锚定 + 仅
+        # email/name 引用时,主体被静默丢弃的窗口。覆盖判定按失败类别的可验证面:
+        #   - AMBIGUOUS_*:目录命中多候选,候选(matches)与已解析直通锚 uid/deptId/
+        #     roleId 求交——交非空说明歧义主体之一已被锚定,主体集合不丢;
+        #   - *_NOT_FOUND:目录答「不存在」,失败值与已解析条目的真实属性(email/
+        #     name)比对(直通 stub 条目属性是 id 字符串,不会误匹配);
+        #   - *_SEARCH_FAILED:目录服务本身不可达,主体身份无从验证——保留全局
+        #     「直通锚非空」guard(eval 隔离环境外部登录资源不可达 → 搜索 49500
+        #     超时的确定性约束;纯手写声明仍阻断),降级明细经 degradation_warnings
+        #     回响应信封,不再静默。
         _SOFT_RESOLUTION_KINDS = {"member_email", "member_name", "department_name", "role", "external_member_email"}
         _NOT_FOUND_RESOLUTION_CODES = {"MEMBER_NOT_FOUND", "AMBIGUOUS_MEMBER", "ROLE_NOT_FOUND", "AMBIGUOUS_ROLE", "DEPARTMENT_NOT_FOUND", "AMBIGUOUS_DEPARTMENT"}
-        blocking_issues = [
-            issue
-            for issue in [
-                *member_resolution["issues"],
-                *role_resolution["issues"],
-                *department_resolution["issues"],
-                *external_member_resolution["issues"],
-            ]
-            # 冗余 email/name 引用「找不到」降级为非阻断(uid/id 直通已保主体不丢);
-            # 权限拒绝/查询失败类(LOOKUP_FAILED/PERMISSION_DENIED)仍阻断
-            if not (
-                str(issue.get("kind") or "") in _SOFT_RESOLUTION_KINDS
-                and str(issue.get("error_code") or "") in _NOT_FOUND_RESOLUTION_CODES
-            )
-        ]
+        member_entries = member_resolution.get("member_entries") or []
+        department_entries = department_resolution.get("department_entries") or []
+        role_entries = role_resolution.get("role_entries") or []
+        external_entries = external_member_resolution.get("member_entries") or []
+        uid_direct_count = len(member_entries) + len(department_entries)
+        resolved_anchor_ids = {
+            value
+            for value in (
+                _coerce_positive_int(entry.get("uid"))
+                for entry in [*member_entries, *external_entries]
+            )
+            if value is not None
+        } | {
+            value
+            for value in (
+                _coerce_positive_int(entry.get("deptId"))
+                for entry in department_entries
+            )
+            if value is not None
+        } | {
+            value
+            for value in (_coerce_positive_int(entry.get("roleId")) for entry in role_entries)
+            if value is not None
+        }
+
+        def _match_anchor_ids(issue: dict[str, Any]) -> set[int]:
+            matched: set[int] = set()
+            for candidate in issue.get("matches") or []:
+                if not isinstance(candidate, dict):
+                    continue
+                for key in ("uid", "id", "memberId", "deptId", "roleId"):
+                    value = _coerce_positive_int(candidate.get(key))
+                    if value is not None:
+                        matched.add(value)
+            return matched
+
+        def _matches_resolved_attribute(issue: dict[str, Any]) -> bool:
+            kind = str(issue.get("kind") or "")
+            raw = str(issue.get("value") or "").strip()
+            if not raw:
+                return False
+            if kind in {"member_email", "external_member_email"}:
+                entries = external_entries if kind.startswith("external") else member_entries
+                return any(raw.lower() == str(entry.get("email") or "").strip().lower() for entry in entries)
+            if kind == "member_name":
+                return any(raw == str(entry.get("name") or "").strip() for entry in member_entries)
+            if kind == "department_name":
+                return any(raw == str(entry.get("deptName") or "").strip() for entry in department_entries)
+            if kind == "role":
+                return any(raw == str(entry.get("roleName") or "").strip() for entry in role_entries)
+            return False
+
+        blocking_issues: list[dict[str, Any]] = []
+        degraded_issues: list[dict[str, Any]] = []
+        for issue in [
+            *member_resolution["issues"],
+            *role_resolution["issues"],
+            *department_resolution["issues"],
+            *external_member_resolution["issues"],
+        ]:
+            if str(issue.get("kind") or "") not in _SOFT_RESOLUTION_KINDS:
+                blocking_issues.append(issue)
+                continue
+            error_code = str(issue.get("error_code") or "")
+            if error_code.endswith("_SEARCH_FAILED"):
+                covered = uid_direct_count > 0
+            elif error_code.startswith("AMBIGUOUS_"):
+                covered = bool(_match_anchor_ids(issue) & resolved_anchor_ids)
+            elif error_code in _NOT_FOUND_RESOLUTION_CODES:
+                covered = _matches_resolved_attribute(issue)
+            else:
+                # PERMISSION_DENIED/未知失败类:不可归因为「主体已被锚定的冗余通道」,
+                # 维持阻断(master 语义)。
+                blocking_issues.append(issue)
+                continue
+            if covered:
+                degraded_issues.append(issue)
+            else:
+                blocking_issues.append(issue)
         self._raise_visibility_resolution_issues(blocking_issues)
+        if degraded_issues and degradation_warnings is not None:
+            for issue in degraded_issues:
+                degradation_warnings.append(
+                    _warning(
+                        "VISIBILITY_SOFT_REFERENCE_DEGRADED",
+                        (
+                            f"visibility {issue.get('kind')} '{issue.get('value')}' could not be resolved "
+                            f"({issue.get('error_code')}); the subject is dropped from visibility selectors "
+                            "unless it was also anchored by a direct id reference"
+                        ),
+                        kind=issue.get("kind"),
+                        value=issue.get("value"),
+                        error_code=issue.get("error_code"),
+                    )
+                )
 
         external_depart_entries: list[dict[str, Any]] = []
         for dept_id in visibility.external_selectors.dept_ids:
@@ -8761,7 +8867,25 @@ class AiBuilderFacade:
             "warnings": warnings,
         }
 
-    def portal_get(self, *, profile: str, dash_key: str, being_draft: bool = True) -> JSONObject:
+    def portal_get(
+        self,
+        *,
+        profile: str,
+        dash_key: str,
+        being_draft: bool = True,
+        schema_kind: str = "raw",
+        schema_version: str | None = None,
+    ) -> JSONObject:
+        """读取门户详情;schema_kind=summary|complete 时返回 canonical 声明投影,raw 为原始归一响应。"""
+        normalized_kind = str(schema_kind or "raw").strip().lower() or "raw"
+        if normalized_kind not in {"raw", "summary", "complete"}:
+            return _failed(
+                "UNSUPPORTED_SCHEMA_KIND",
+                f"unsupported portal get schema kind: {normalized_kind}",
+                normalized_args={"dash_key": dash_key, "being_draft": being_draft, "schema_kind": normalized_kind},
+                details={"supportedKinds": ["raw", "summary", "complete"]},
+                suggested_next_call={"tool_name": "portal_get", "arguments": {"profile": profile, "dash_key": dash_key, "schema_kind": "raw"}},
+            )
         try:
             result = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=being_draft).get("result") or {}
         except (QingflowApiError, RuntimeError) as error:
@@ -8769,10 +8893,52 @@ class AiBuilderFacade:
             return _failed_from_api_error(
                 "PORTAL_GET_FAILED",
                 api_error,
-                normalized_args={"dash_key": dash_key, "being_draft": being_draft},
+                normalized_args={"dash_key": dash_key, "being_draft": being_draft, "schema_kind": normalized_kind},
                 details={"dash_key": dash_key, "being_draft": being_draft},
                 suggested_next_call={"tool_name": "portal_get", "arguments": {"profile": profile, "dash_key": dash_key, "being_draft": being_draft}},
             )
+        if normalized_kind in {"summary", "complete"}:
+            schema_context = None
+            if schema_version is not None:
+                try:
+                    schema_context = portals_schema_registry().resolve_schema_version(schema_version)
+                except PortalsContractError as error:
+                    return _failed(
+                        error.error_code,
+                        str(error.message),
+                        normalized_args={"dash_key": dash_key, "being_draft": being_draft, "schema_kind": normalized_kind, "schema_version": schema_version},
+                        details={"reason_path": error.path or "", **(error.details or {})},
+                        suggested_next_call={"tool_name": "portal_schema", "arguments": {"schema_kind": "summary"}},
+                    )
+            declaration, read_gaps = _portal_declaration_from_dash_detail(result, schema_kind=normalized_kind)
+            response = {
+                "status": "success",
+                "error_code": None,
+                "recoverable": False,
+                "message": f"read portal declaration ({normalized_kind})",
+                "normalized_args": {
+                    "dash_key": dash_key,
+                    "being_draft": being_draft,
+                    "schema_kind": normalized_kind,
+                    "schema_version": schema_version,
+                },
+                "missing_fields": [],
+                "allowed_values": {"schema_kind": ["raw", "summary", "complete"]},
+                "details": {"read_gaps": read_gaps} if read_gaps else {},
+                "request_id": None,
+                "suggested_next_call": None,
+                "noop": False,
+                "warnings": [],
+                "verification": {"portal_exists": True, "being_draft": being_draft},
+                "verified": True,
+                "schemaVersion": schema_context.schema_version if schema_context is not None else portals_schema_registry().latest_version,
+                "latestVersion": portals_schema_registry().latest_version,
+                "apiVersion": schema_context.api_version if schema_context is not None else "builder.qingflow.com/v1alpha1",
+                "schemaKind": normalized_kind,
+                "declaration": declaration,
+                "read_gap_count": len(read_gaps),
+            }
+            return response
         dash_icon = str(result.get("dashIcon") or "").strip() or None
         response = PortalGetResponse(
             dash_key=dash_key,
@@ -8867,6 +9033,124 @@ class AiBuilderFacade:
             **response.model_dump(mode="json"),
         }
 
+    def portal_schema(
+        self,
+        *,
+        schema_version: str | None = None,
+        schema_kind: str | None = None,
+    ) -> JSONObject:
+        """读取版本化门户声明 schema;组件专项 kind 用于获取自包含专项配置定义。"""
+        normalized_args = {"schema_version": schema_version, "schema_kind": schema_kind}
+        try:
+            payload = portals_schema_registry().schema(schema_version=schema_version, schema_kind=schema_kind)
+        except PortalsContractError as error:
+            return _failed(
+                error.error_code,
+                str(error.message),
+                normalized_args=normalized_args,
+                details={"reason_path": error.path or "", **(error.details or {})},
+                suggested_next_call={"tool_name": "portal_schema", "arguments": {"schema_kind": "summary"}},
+            )
+        return {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "read portals declaration schema",
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {"schema_kind": payload["supportedSchemaKinds"]},
+            "details": {},
+            "request_id": None,
+            "suggested_next_call": None,
+            "warnings": [],
+            "verification": {"schema_loaded": True},
+            **payload,
+        }
+
+    def portal_validate(
+        self,
+        *,
+        declaration: JSONObject,
+        schema_version: str | None = None,
+    ) -> JSONObject:
+        """纯离线校验一条门户声明;不访问后端。"""
+        normalized_args = {"schema_version": schema_version}
+        resolved_version = (
+            str(schema_version or (declaration.get("schema_version") if isinstance(declaration, dict) else None) or "").strip() or None
+        )
+        try:
+            context = portals_schema_registry().resolve_schema_version(resolved_version)
+        except PortalsContractError as error:
+            return _failed(
+                error.error_code,
+                str(error.message),
+                normalized_args=normalized_args,
+                details={"reason_path": error.path or "", **(error.details or {})},
+                suggested_next_call={"tool_name": "portal_schema", "arguments": {"schema_kind": "complete"}},
+            )
+        issues: list[dict[str, Any]] = []
+        if not isinstance(declaration, dict):
+            issues.append({"path": "/", "code": "INVALID_SPEC", "message": "portals declaration must be a JSON object"})
+        else:
+            declaration_item = {
+                key: value
+                for key, value in declaration.items()
+                if key not in {"schema_version", "schemaVersion", "apiVersion"}
+            }
+            try:
+                parsed = PortalApplyRequest.model_validate(declaration_item)
+                context.validate_upsert(compact_none_values(public_portal_apply_payload(parsed)))
+            except ValidationError as exc:
+                first_error = exc.errors()[0]
+                issues.append(
+                    {
+                        "path": f"/{'/'.join(str(part) for part in first_error.get('loc', ()))}".rstrip("/"),
+                        "code": "INVALID_SPEC",
+                        "message": str(first_error.get("msg") or exc),
+                    }
+                )
+            except PortalsContractError as error:
+                issues.append({"path": error.path or "/", "code": error.error_code, "message": str(error.message)})
+            else:
+                # 创建语义(无 dash_key)的 icon/color 目录校验与 apply 同口径:离线
+                # jsonschema 不含目录枚举(更新语义须放行存量 hex 透传),不补这层
+                # 会出现「validate 通过、apply 拒绝」的校验信任断裂(实测反馈失败二
+                # 同型);更新语义不做目录校验(与 apply 更新分支一致)。
+                if not str(parsed.dash_key or "").strip():
+                    icon_ok, icon_error_code, icon_message, _icon_details = validate_workspace_icon_choice(
+                        icon=parsed.icon,
+                        color=parsed.color,
+                        require_explicit=True,
+                        disallow_generic=True,
+                    )
+                    if not icon_ok:
+                        issues.append(
+                            {
+                                "path": "/color" if str(icon_error_code or "").endswith("COLOR_NOT_FOUND") or icon_error_code == "WORKSPACE_ICON_COLOR_REQUIRED" else "/icon",
+                                "code": icon_error_code or "WORKSPACE_ICON_INVALID",
+                                "message": icon_message or "invalid workspace icon configuration",
+                            }
+                        )
+        ok = not issues
+        return {
+            "status": "success" if ok else "failed",
+            "error_code": None if ok else issues[0]["code"],
+            "recoverable": True,
+            "message": "portals declaration is valid" if ok else "portals declaration failed validation",
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {"issues": issues},
+            "request_id": None,
+            "suggested_next_call": None,
+            "warnings": [],
+            "verification": {"validated_entries": 1 if ok else 0},
+            "ok": ok,
+            "schemaVersion": context.schema_version,
+            "apiVersion": context.api_version,
+            "issues": issues,
+        }
+
     def view_get(self, *, profile: str, view_key: str) -> JSONObject:
         try:
             config = self.views.view_get_config(profile=profile, viewgraph_key=view_key).get("result") or {}
@@ -15086,7 +15370,13 @@ class AiBuilderFacade:
             "safe_to_retry": not write_executed,
         })
 
-    def portal_apply(self, *, profile: str, request: PortalApplyRequest) -> JSONObject:
+    def portal_apply(
+        self,
+        *,
+        profile: str,
+        request: PortalApplyRequest,
+        schema_version: str | None = None,
+    ) -> JSONObject:
         apply_started_at = time.perf_counter()
         portal_initial_read_ms: int | None = None
         portal_create_ms: int | None = None
@@ -15096,23 +15386,51 @@ class AiBuilderFacade:
         portal_draft_readback_ms: int | None = None
         portal_publish_ms: int | None = None
         portal_live_readback_ms: int | None = None
+        effective_schema_version = str(schema_version or request.schema_version or "").strip() or None
         normalized_args = request.model_dump(mode="json")
+        normalized_args["schema_version"] = effective_schema_version
+        schema_context: PortalsSchemaContext | None = None
+        if effective_schema_version is not None:
+            try:
+                schema_context = portals_schema_registry().resolve_schema_version(effective_schema_version)
+                schema_context.validate_upsert(
+                    compact_none_values(public_portal_apply_payload(request))
+                )
+            except PortalsContractError as error:
+                return _failed(
+                    error.error_code,
+                    str(error.message),
+                    normalized_args=normalized_args,
+                    details={"reason_path": error.path or "", **(error.details or {})},
+                    suggested_next_call={"tool_name": "portal_schema", "arguments": {"schema_version": effective_schema_version, "schema_kind": "complete"}},
+                )
         permission_outcomes: list[PermissionCheckOutcome] = []
         dash_key = str(request.dash_key or "").strip()
         creating = not dash_key
-        sections_requested = creating or bool(request.sections)
+        # sections_requested 语义:显式携带 sections 键(含空列表)即走组件重建链;
+        # 未传(不在 model_fields_set)才是纯 base-info 更新。模型缺省 sections=[] 与
+        # 显式空列表同值,只能用 fields_set 区分。空 sections=[] 是合法存量形态
+        # (无组件门户):后端 updateDash 对空组件列表=删全部后不重建(getComponents
+        # 非空才重建),createDash 不建组件——把空列表当「未传」会把携带
+        # global_config/hide_copyright 的空门户拒之门外。
+        sections_requested = creating or ("sections" in request.model_fields_set)
         verify_dash_name = creating or request.dash_name is not None
         verify_dash_icon = bool(request.icon or request.color)
         verify_auth = request.visibility is not None or request.auth is not None
         verify_hide_copyright = request.hide_copyright is not None and sections_requested
-        verify_dash_global_config = request.dash_global_config is not None and sections_requested
+        verify_dash_global_config = request.global_config is not None and sections_requested
         verify_tags = creating or request.package_tag_id is not None
         requested_visibility = request.visibility
         if requested_visibility is None and isinstance(request.auth, dict) and request.auth:
             requested_visibility = VisibilityPatch.model_validate(_public_visibility_from_member_auth(request.auth))
+        visibility_degradation_warnings: list[dict[str, Any]] = []
         try:
             desired_auth = (
-                self._compile_visibility_to_member_auth(profile=profile, visibility=requested_visibility)
+                self._compile_visibility_to_member_auth(
+                    profile=profile,
+                    visibility=requested_visibility,
+                    degradation_warnings=visibility_degradation_warnings,
+                )
                 if requested_visibility is not None
                 else None
             )
@@ -15155,6 +15473,14 @@ class AiBuilderFacade:
             permission_outcomes.append(portal_permission_outcome)
 
         def finalize(response: JSONObject) -> JSONObject:
+            if schema_context is not None:
+                response["schemaVersion"] = schema_context.schema_version
+            # 可见性冗余引用降级明细回信封(review §2-1:降级不再静默)
+            if visibility_degradation_warnings:
+                existing_warnings = response.get("warnings")
+                warnings = list(existing_warnings) if isinstance(existing_warnings, list) else []
+                warnings.extend(item for item in visibility_degradation_warnings if item not in warnings)
+                response["warnings"] = warnings
             _merge_duration_breakdown(
                 response,
                 portal_initial_read_ms=portal_initial_read_ms,
@@ -15192,8 +15518,8 @@ class AiBuilderFacade:
             unsupported_base_only_keys: list[str] = []
             if request.hide_copyright is not None:
                 unsupported_base_only_keys.append("hide_copyright")
-            if request.dash_global_config is not None:
-                unsupported_base_only_keys.append("dash_global_config")
+            if request.global_config is not None:
+                unsupported_base_only_keys.append("global_config")
             if request.config:
                 unsupported_base_only_keys.append("config")
             if unsupported_base_only_keys:
@@ -15216,18 +15542,20 @@ class AiBuilderFacade:
             layout_diagnostics: dict[str, Any] = _empty_portal_layout_diagnostics()
             if creating:
                 create_payload = _build_public_portal_base_payload(
-                    dash_name=request.dash_name or "未命名门户",
+                    dash_name=request.dash_name if request.dash_name is not None else "未命名门户",
                     package_tag_id=target_package_tag_id,
                     icon=request.icon,
                     color=request.color,
                     auth=desired_auth,
                     hide_copyright=request.hide_copyright,
-                    dash_global_config=request.dash_global_config,
+                    dash_global_config=request.global_config,
+                    style_template_id=request.style_template_id,
+                    overall_style=request.overall_style,
                     config=request.config,
                     base_payload=None,
                 )
                 portal_create_started_at = time.perf_counter()
-                create_result = self.portals.portal_create(profile=profile, payload=create_payload)
+                create_result = self._portal_writer.create_portal(profile=profile, payload=create_payload)
                 portal_create_ms = _duration_ms(portal_create_started_at)
                 write_executed = True
                 created = create_result.get("result") if isinstance(create_result.get("result"), dict) else {}
@@ -15250,13 +15578,15 @@ class AiBuilderFacade:
                     }
                     base_payload = {}
             update_payload = _build_public_portal_base_payload(
-                dash_name=request.dash_name or str(base_payload.get("dashName") or "").strip() or "未命名门户",
+                dash_name=request.dash_name if request.dash_name is not None else (str(base_payload.get("dashName") or "").strip() or "未命名门户"),
                 package_tag_id=target_package_tag_id,
                 icon=request.icon,
                 color=request.color,
                 auth=desired_auth,
                 hide_copyright=request.hide_copyright,
-                dash_global_config=request.dash_global_config,
+                dash_global_config=request.global_config,
+                style_template_id=request.style_template_id,
+                overall_style=request.overall_style,
                 config=request.config,
                 base_payload=base_payload,
             )
@@ -15272,7 +15602,7 @@ class AiBuilderFacade:
                 layout_diagnostics = _portal_layout_diagnostics(request.sections, component_payload, layout_metadata=layout_metadata)
                 update_payload["components"] = component_payload
                 portal_update_started_at = time.perf_counter()
-                self.portals.portal_update(profile=profile, dash_key=dash_key, payload=update_payload)
+                self._portal_writer.update_portal(profile=profile, dash_key=dash_key, payload=update_payload)
                 portal_update_ms = _duration_ms(portal_update_started_at)
                 write_executed = True
             else:
@@ -15289,15 +15619,22 @@ class AiBuilderFacade:
             )
             if base_info_update_requested:
                 portal_base_info_update_started_at = time.perf_counter()
-                self.portals.portal_update_base_info(
+                base_info_payload = {
+                    "dashName": update_payload.get("dashName"),
+                    "dashIcon": update_payload.get("dashIcon"),
+                    "auth": deepcopy(update_payload.get("auth")),
+                }
+                # tags 空列表省略键:后端 updateDashBaseInfo(DashSvcImpl)对非 null 的空 tags
+                # 按 ws 过滤后判空抛 PARAMS_ERROR → 整个 baseInfo 写失败(事务回滚,name/icon/auth
+                # 全部静默失效,r8 实测 16 门)。省略键 → getTags()==null → 后端跳过 tags 校验与更新,
+                # 其余字段正常写。声明显式给 package_tag_id 时 tags 非空,不受影响。
+                base_info_tags = deepcopy(update_payload.get("tags") or [])
+                if base_info_tags:
+                    base_info_payload["tags"] = base_info_tags
+                self._portal_writer.update_portal_base_info(
                     profile=profile,
                     dash_key=dash_key,
-                    payload={
-                        "dashName": update_payload.get("dashName"),
-                        "dashIcon": update_payload.get("dashIcon"),
-                        "auth": deepcopy(update_payload.get("auth")),
-                        "tags": deepcopy(update_payload.get("tags") or []),
-                    },
+                    payload=base_info_payload,
                 )
                 portal_base_info_update_ms = _duration_ms(portal_base_info_update_started_at)
                 write_executed = True
@@ -16612,25 +16949,58 @@ class AiBuilderFacade:
                     resolved_chart = inline_chart_resolutions.get(section_index)
                     if not isinstance(resolved_chart, dict):
                         raise ValueError(f"inline chart '{section.chart.name}' could not be created or updated for portal section '{section.title}'")
+                    chart_type = str(
+                        resolved_chart.get("chart_type")
+                        or _public_chart_type_from_backend(section.config.get("chartType") or section.config.get("chart_type"))
+                        or ""
+                    ).strip()
+                    chart_config = {
+                        "biChartId": resolved_chart["chart_id"],
+                        # title=None(存量空标题)不落库——_compact_dict 剔除,后端透传 NULL 保真;
+                        # beingShowTitle 以声明 show_title 为准(读面提取必有值),缺省回落产品默认 True。
+                        "chartComponentTitle": section.title,
+                        "beingShowTitle": section.show_title if section.show_title is not None else True,
+                        **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, "role": section.role})
+                elif section.chart_ref is not None and str(getattr(section.chart_ref, "ref_kind", "") or "") == "chart":
+                    # 轻流报表引用面(后端 DASH_CONTENT_TYPE_CHART=1):chart_id 携带的是
+                    # chart 表唯一键 chartKey,写链 addChartInfos 按 chartKey 解析,不走
+                    # BI 报表列表解析;不携带运行态派生键(chartId/chartName/formTitle 等读面回填)。
+                    chart_key = str(getattr(section.chart_ref, "chart_id", "") or "").strip()
+                    if not chart_key:
+                        raise ValueError(f"chart_ref with ref_kind=chart requires chart_id for portal section '{section.title}'")
+                    chart_config = {
+                        "chartKey": chart_key,
+                        # 同上:title=None 不落库、beingShowTitle 声明优先、缺省 True。
+                        "chartComponentTitle": section.title,
+                        "beingShowTitle": section.show_title if section.show_title is not None else True,
+                        **deepcopy(section.config),
+                    }
+                    component = {"type": 1, "position": position_payload, "chartConfig": _compact_dict(chart_config)}
+                    layout_metadata.append({"source_type": section.source_type, "chart_type": str(_public_chart_type_from_backend(section.config.get("chartType") or section.config.get("chart_type")) or "").strip(), "role": section.role})
                 else:
                     resolved_chart = _resolve_chart_reference(
                         charts=self.charts,
                         profile=profile,
                         ref=section.chart_ref,
                     )
-                chart_type = str(
-                    resolved_chart.get("chart_type")
-                    or _public_chart_type_from_backend(section.config.get("chartType") or section.config.get("chart_type"))
-                    or ""
-                ).strip()
-                chart_config = {
-                    "biChartId": resolved_chart["chart_id"],
-                    "chartComponentTitle": section.title,
-                    "beingShowTitle": True,
-                    **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, "role": section.role})
+                    chart_type = str(
+                        resolved_chart.get("chart_type")
+                        or _public_chart_type_from_backend(section.config.get("chartType") or section.config.get("chart_type"))
+                        or ""
+                    ).strip()
+                    chart_config = {
+                        "biChartId": resolved_chart["chart_id"],
+                        # title=None(存量空标题)不落库——_compact_dict 剔除,后端透传 NULL 保真;
+                        # beingShowTitle 以声明 show_title 为准(读面提取必有值),缺省回落产品默认 True。
+                        "chartComponentTitle": section.title,
+                        "beingShowTitle": section.show_title if section.show_title is not None else True,
+                        **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, "role": section.role})
             elif section.source_type == "view":
                 resolved_view = _resolve_view_reference(
                     facade=self,
@@ -16644,34 +17014,58 @@ class AiBuilderFacade:
                 view_config = {
                     "appKey": resolved_view["app_key"],
                     "viewgraphKey": resolved_view["view_key"],
-                    "viewgraphName": section.title,
+                    # viewgraphName=视图名(引用面锚,view_ref.view_name 优先);componentTitle=组件
+                    # 显示标题(title=None 的存量空标题形态经 _compact_dict 剔除,落库 NULL 保真,
+                    # 旧逻辑把视图名兑底进 componentTitle 会覆盖读链 chartName 派生分支)。
+                    "viewgraphName": getattr(section.view_ref, "view_name", None) or section.title,
                     "formTitle": app_title_cache[resolved_view["app_key"]],
                     "componentTitle": section.title,
                     "viewgraphType": resolved_view["view_type"],
-                    "beingShowTitle": True,
+                    # beingShowTitle 声明 show_title 优先(view_display.show_title 提取必有值;
+                    # 存量 false 被硬 True 覆写会漂移库表);缺省保持产品默认 True。
+                    "beingShowTitle": section.show_title if section.show_title is not None else True,
                     "dataManageStatus": True,
                     **deepcopy(section.config),
                 }
+                if section.view_display:
+                    display = _compile_portal_view_display(section.view_display)
+                    for key, value in display.items():
+                        view_config[key] = value
                 component = {"type": 10, "position": position_payload, "viewgraphConfig": _compact_dict(view_config)}
                 layout_metadata.append({"source_type": section.source_type, "role": section.role})
             elif section.source_type == "grid":
                 component = {
                     "type": 2,
                     "position": position_payload,
+                    # gridTitle=None(存量空标题)剔除不落库;beingShowTitle 缺省 True、声明 config 内
+                    # beingShowTitle 键后置覆盖(提取侧 grid config 保留该键,存量 false 保真)。
                     "gridConfig": _compact_dict({"gridTitle": section.title, "beingShowTitle": True, **deepcopy(section.config)}),
                 }
                 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)}
+                component = {"type": 6, "position": position_payload, "filterConfig": _compile_portal_filter_config(section.config)}
                 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, "role": section.role})
+            elif section.source_type == "carousel":
+                carousel_config = self._compile_portal_carousel_config(profile=profile, section=section)
+                component = {"type": 3, "position": position_payload, "carouselConfig": _compact_dict(carousel_config)}
+                layout_metadata.append({"source_type": section.source_type, "role": section.role})
+            elif section.source_type == "task":
+                task_config = _compile_portal_task_config(section.title, section.task or {})
+                component = {"type": 8, "position": position_payload, "taskConfig": _compact_dict(task_config)}
+                layout_metadata.append({"source_type": section.source_type, "role": section.role})
+            elif section.source_type == "favourite":
+                favourite_config = _compile_portal_favourite_config(section.title, section.favourite or {})
+                component = {"type": 7, "position": position_payload, "favouriteConfig": _compact_dict(favourite_config)}
+                layout_metadata.append({"source_type": section.source_type, "role": section.role})
             else:
+                link_config = {"url": section.url or "", "beingLoginAuth": bool(section.login_auth) if section.login_auth is not None else False, **deepcopy(section.config)}
                 component = {
                     "type": 4,
                     "position": position_payload,
-                    "linkConfig": {"url": section.url or "", "beingLoginAuth": False, **deepcopy(section.config)},
+                    "linkConfig": _compact_dict(link_config),
                 }
                 layout_metadata.append({"source_type": section.source_type, "role": section.role})
             if dash_style is not None:
@@ -16679,6 +17073,113 @@ class AiBuilderFacade:
             resolved_components.append(component)
         return resolved_components, layout_metadata, inline_chart_results
 
+    def _compile_portal_carousel_config(self, *, profile: str, section: PortalSectionPatch) -> dict[str, Any]:
+        """Compile a carousel section declaration into the backend carouselConfig shape."""
+        raw = section.carousel or {}
+        if not isinstance(raw, dict):
+            raise ValueError("carousel section config must be an object")
+        app_key = str(raw.get("source_app_key") or raw.get("sourceAppKey") or "").strip()
+        carousel_config: dict[str, Any] = {}
+        fields_by_que_id: dict[int, dict[str, Any]] = {}
+        field_name_to_field: dict[str, dict[str, Any]] = {}
+        if app_key:
+            carousel_config["sourceApp"] = {"appKey": app_key}
+            if raw.get("source_form_title") or raw.get("sourceFormTitle"):
+                carousel_config["sourceApp"]["formTitle"] = str(raw.get("source_form_title") or raw.get("sourceFormTitle"))
+            # 字段索引从原始 form schema 面构建(_read_schema_with_fallback + schema 分支,
+            # 与 views apply 同源):app_read_fields 解析面的字段不带 option_details,
+            # _resolve_view_filter_values 的选项文本→ID 解析分支不生效,选项文本被
+            # 原样透传进 formula,后端写后自读 Integer.parseInt("文本") 崩溃回滚
+            # (r6 实测 9b91e277;七条约束之四:两读面锚定同一数据源)。
+            schema, _schema_source = self._read_schema_with_fallback(profile=profile, app_key=app_key)
+            fields_by_que_id = _collect_fields_by_que_id([], schema=schema)
+            field_name_to_field = {
+                str(field.get("name") or ""): field
+                for field in fields_by_que_id.values()
+                if str(field.get("name") or "")
+            }
+        # 悬空轮播(存量形态:源表已删,related_form_id NULL,读面 sourceApp 空):后端写链
+        # DraftComponentCarousel 构造对 sourceApp 空/无 appKey 不写 relatedFormId,读面回空
+        # sourceApp——round-trip 保真;无源表则无从解析字段引用,仅保留运行参数(jump_mode 等)。
+
+        def _resolve_que_ref(field_name: Any, *, config_key: str) -> dict[str, Any] | None:
+            raw_name = str(field_name or "").strip()
+            if not raw_name:
+                return None
+            field: dict[str, Any] | None = None
+            if raw_name.isdigit():
+                que_id = _coerce_positive_int(raw_name)
+                field = fields_by_que_id.get(que_id) if que_id is not None else None
+            else:
+                field = field_name_to_field.get(raw_name)
+            if field is None:
+                raise ValueError(
+                    f"carousel section '{section.title}' references unknown {config_key} '{raw_name}' in app '{app_key}'"
+                )
+            que_id = _coerce_positive_int(field.get("que_id"))
+            if que_id is None:
+                raise ValueError(
+                    f"carousel section '{section.title}' {config_key} '{raw_name}' has no que_id in app '{app_key}'"
+                )
+            return {"queId": que_id}
+
+        title_que = _resolve_que_ref(raw.get("title_field") or raw.get("titleField"), config_key="title_field")
+        image_que = _resolve_que_ref(raw.get("image_field") or raw.get("imageField"), config_key="image_field")
+        link_que = _resolve_que_ref(raw.get("link_field") or raw.get("linkField"), config_key="link_field")
+        if title_que is not None:
+            carousel_config["titleQue"] = title_que
+        if image_que is not None:
+            carousel_config["imageQue"] = image_que
+        if link_que is not None:
+            carousel_config["linkQue"] = link_que
+        jump_mode = _coerce_positive_int(raw.get("jump_mode") or raw.get("jumpMode"))
+        if jump_mode is not None:
+            carousel_config["jumpMode"] = jump_mode
+        if "scaling" in raw or "beingScaling" in raw:
+            carousel_config["beingScaling"] = bool(raw.get("scaling", raw.get("beingScaling")))
+        show_latest_limit = _coerce_positive_int(raw.get("show_latest_limit") or raw.get("showLatestLimit"))
+        if show_latest_limit is not None:
+            carousel_config["showLatestLimit"] = show_latest_limit
+        scroll_interval = _coerce_positive_int(raw.get("scroll_interval") or raw.get("scrollInterval"))
+        if scroll_interval is not None:
+            carousel_config["scrollInterval"] = scroll_interval
+        raw_filters = raw.get("filters")
+        if isinstance(raw_filters, list) and raw_filters:
+            translated_rules: list[dict[str, Any]] = []
+            for raw_rule in raw_filters:
+                if hasattr(raw_rule, "model_dump"):
+                    raw_rule = raw_rule.model_dump(mode="json")
+                if not isinstance(raw_rule, dict):
+                    continue
+                field_name = str(raw_rule.get("field_name") or raw_rule.get("fieldName") or "").strip()
+                field: dict[str, Any] | None = None
+                if field_name.isdigit():
+                    # 与 _resolve_que_ref 同型：queId 数字串优先按稳定锚解析(提取器 canonical 形态)
+                    que_id = _coerce_positive_int(field_name)
+                    field = fields_by_que_id.get(que_id) if que_id is not None else None
+                if field is None:
+                    field = field_name_to_field.get(field_name)
+                if field is None:
+                    raise ValueError(
+                        f"carousel section '{section.title}' filters reference unknown field '{field_name}' in app '{app_key}'"
+                    )
+                rule_payload = {
+                    "que_id": field.get("que_id"),
+                    "operator": raw_rule.get("operator") or raw_rule.get("op") or "eq",
+                    "values": list(raw_rule.get("values") or []),
+                }
+                groups, filter_issues = _build_view_filter_groups(fields_by_que_id=fields_by_que_id, filters=[rule_payload])
+                blocking = [issue for issue in filter_issues if issue.get("error_code")]
+                if blocking:
+                    raise ValueError(
+                        f"carousel section '{section.title}' filters failed to compile: {blocking[0]}"
+                    )
+                if groups:
+                    translated_rules.extend(groups[0])
+            if translated_rules:
+                carousel_config["filterConfig"] = [translated_rules]
+        return carousel_config
+
     def _resolve_current_user_identity(self, *, profile: str) -> JSONObject:
         session_profile = self.apps.sessions.get_profile(profile)
         backend_session = self.apps.sessions.get_backend_session(profile)
@@ -20252,6 +20753,154 @@ def _chart_item_dataset_source_type(item: dict[str, Any]) -> str:
     return ""
 
 
+def _compile_portal_global_config(raw: dict[str, Any] | None) -> dict[str, Any]:
+    """Compile declaration-named global_config keys to backend dashGlobalConfig keys."""
+    config: dict[str, Any] = dict(raw or {})
+    if "auto_refresh" in config:
+        config["beingAutoRefresh"] = config.pop("auto_refresh")
+    if "export" in config:
+        config["beingExport"] = config.pop("export")
+    return config
+
+
+def _compile_portal_view_display(raw: dict[str, Any] | None) -> dict[str, Any]:
+    """Compile declaration view_display keys to backend viewgraphConfig keys."""
+    display: dict[str, Any] = {}
+    payload = raw or {}
+    if "show_title" in payload:
+        display["beingShowTitle"] = bool(payload["show_title"])
+    elif "beingShowTitle" in payload:
+        display["beingShowTitle"] = bool(payload["beingShowTitle"])
+    if payload.get("component_title") or payload.get("componentTitle"):
+        display["componentTitle"] = str(payload.get("component_title") or payload.get("componentTitle"))
+    return display
+
+
+def _compile_portal_task_config(section_title: str, raw: dict[str, Any]) -> dict[str, Any]:
+    """Compile a task section declaration into the backend taskConfig shape."""
+    payload = raw or {}
+    task_config: dict[str, Any] = {
+        "componentTaskTitle": section_title,
+    }
+    if "show_title" in payload:
+        task_config["beingShowTitle"] = bool(payload["show_title"])
+    elif "beingShowTitle" in payload:
+        task_config["beingShowTitle"] = bool(payload["beingShowTitle"])
+    if "hint" in payload or "componentTaskHint" in payload:
+        task_config["componentTaskHint"] = str(payload.get("hint") or payload.get("componentTaskHint") or "")
+    if "show_hint" in payload:
+        task_config["beingShowHint"] = bool(payload["show_hint"])
+    elif "beingShowHint" in payload:
+        task_config["beingShowHint"] = bool(payload["beingShowHint"])
+    if "enabled" in payload:
+        task_config["beingUsing"] = bool(payload["enabled"])
+    elif "beingUsing" in payload:
+        task_config["beingUsing"] = bool(payload["beingUsing"])
+    raw_tasks = payload.get("tasks")
+    if isinstance(raw_tasks, list) and raw_tasks:
+        task_items: list[dict[str, Any]] = []
+        for index, raw_item in enumerate(raw_tasks):
+            if not isinstance(raw_item, dict):
+                continue
+            item: dict[str, Any] = {
+                "title": str(raw_item.get("title") or ""),
+                "type": _coerce_positive_int(raw_item.get("task_type") or raw_item.get("type")) or 1,
+                "ordinal": _coerce_positive_int(raw_item.get("ordinal")) or index,
+                "beingCheck": bool(raw_item.get("checked", raw_item.get("beingCheck", False))),
+            }
+            task_items.append(item)
+        if task_items:
+            task_config["dashTaskConfigList"] = task_items
+    # dashTaskConfigList 必须始终携带:后端 DashTaskSvcImpl#addTaskInfos 对
+    # taskConfig.getDashTaskConfigList() 直接迭代(ComponentTaskConfig 字段无默认
+    # 初始化),键缺失 → null.size() NPE → 500(实测反馈「task 组件无论如何 500」
+    # 根因)。声明未表达 tasks 时按前端新建缺省补 4 类标准任务(title 用后端 i18n 键,
+    # 与存量/前端缺省一致);提取侧读面恒有条目,round-trip 不受影响。
+    if not task_config.get("dashTaskConfigList"):
+        task_config["dashTaskConfigList"] = [
+            {"title": "all.taskTodo", "type": 1, "ordinal": 0, "beingCheck": True},
+            {"title": "all.taskTimeout", "type": 2, "ordinal": 1, "beingCheck": True},
+            {"title": "all.taskUpcomingTimeout", "type": 3, "ordinal": 2, "beingCheck": True},
+            {"title": "all.taskRemind", "type": 4, "ordinal": 3, "beingCheck": True},
+        ]
+    return task_config
+
+
+def _compile_portal_filter_config(raw: dict[str, Any] | None) -> dict[str, Any]:
+    """Compile a filter section config into the backend ComponentFilter shape.
+
+    Declaration form: ``{graphs: [{chart_key, chart_name}], rules: [...]}``.
+    Legacy raw form (``{graphList: [...], filterConfig: [...]}`` 后端键) 透传兼容。
+    """
+    payload = raw or {}
+    compiled: dict[str, Any] = {}
+    raw_graphs = payload.get("graphs")
+    if isinstance(raw_graphs, list):
+        graph_list: list[dict[str, Any]] = []
+        for item in raw_graphs:
+            if not isinstance(item, dict):
+                continue
+            graph: dict[str, Any] = {
+                "graphKey": str(item.get("chart_key") or item.get("chartKey") or item.get("graphKey") or "").strip(),
+                "graphName": str(item.get("chart_name") or item.get("chartName") or item.get("graphName") or "").strip(),
+                "graphType": item.get("graph_type") or item.get("graphType") or "CHART",
+            }
+            if graph["graphKey"] or graph["graphName"]:
+                graph_list.append(graph)
+        compiled["graphList"] = graph_list
+    elif isinstance(payload.get("graphList"), list):
+        compiled["graphList"] = deepcopy(payload.get("graphList"))
+    raw_rules = payload.get("rules")
+    if isinstance(raw_rules, list):
+        compiled["filterConfig"] = deepcopy(raw_rules)
+    elif isinstance(payload.get("filterConfig"), list):
+        compiled["filterConfig"] = deepcopy(payload.get("filterConfig"))
+    return compiled
+
+
+def _compile_portal_favourite_config(section_title: str, raw: dict[str, Any]) -> dict[str, Any]:
+    """Compile a favourite section declaration into the backend favouriteConfig shape."""
+    payload = raw or {}
+    favourite_config: dict[str, Any] = {
+        "favouriteTitle": section_title,
+    }
+    if "show_title" in payload:
+        favourite_config["beingShowTitle"] = bool(payload["show_title"])
+    elif "beingShowTitle" in payload:
+        favourite_config["beingShowTitle"] = bool(payload["beingShowTitle"])
+    if "enabled" in payload:
+        favourite_config["beingUsing"] = bool(payload["enabled"])
+    elif "beingUsing" in payload:
+        favourite_config["beingUsing"] = bool(payload["beingUsing"])
+    raw_items = payload.get("items")
+    if isinstance(raw_items, list) and raw_items:
+        favourite_items: list[dict[str, Any]] = []
+        for index, raw_item in enumerate(raw_items):
+            if not isinstance(raw_item, dict):
+                continue
+            item: dict[str, Any] = {
+                "title": str(raw_item.get("title") or ""),
+                "type": _coerce_positive_int(raw_item.get("item_type") or raw_item.get("type")) or 1,
+                "ordinal": _coerce_positive_int(raw_item.get("ordinal")) or index,
+            }
+            link_key = str(raw_item.get("link_key") or raw_item.get("linkKey") or "").strip()
+            if link_key:
+                item["linkKey"] = link_key
+            link_id = _coerce_positive_int(raw_item.get("link_id") or raw_item.get("linkId"))
+            if link_id is not None:
+                item["linkId"] = link_id
+            icon_url = str(raw_item.get("icon_url") or raw_item.get("iconUrl") or "").strip()
+            if icon_url:
+                item["iconUrl"] = icon_url
+            jump_mode = _coerce_positive_int(raw_item.get("jump_mode") or raw_item.get("jumpMode"))
+            if jump_mode is not None:
+                item["jumpMode"] = jump_mode
+            favourite_items.append(item)
+        if favourite_items:
+            favourite_config["items"] = favourite_items
+    return favourite_config
+
+
 def _build_public_portal_base_payload(
     *,
     dash_name: str,
@@ -20261,19 +20910,49 @@ def _build_public_portal_base_payload(
     auth: dict[str, Any] | None,
     hide_copyright: bool | None,
     dash_global_config: dict[str, Any] | None,
+    style_template_id: int | None = None,
+    overall_style: dict[str, Any] | None = None,
     config: dict[str, Any] | None,
     base_payload: dict[str, Any] | None,
 ) -> dict[str, Any]:
     data = deepcopy(base_payload) if isinstance(base_payload, dict) else {}
-    effective_name = str(dash_name or data.get("dashName") or "").strip() or "未命名门户"
+    # dash_name 语义:None=未指定(沿用 base_payload 读面名,缺省再回落未命名门户);
+    # 空串=显式空名(后端 dash_name 允许空串,生产存量存在;round-trip 保真必须透传)。
+    if dash_name is not None:
+        effective_name = str(dash_name).strip()
+    else:
+        effective_name = str(data.get("dashName") or "").strip() or "未命名门户"
     effective_hide_copyright = hide_copyright if hide_copyright is not None else bool(data.get("hideCopyright", False))
-    if icon or color or not data.get("dashIcon"):
+    # dashIcon round-trip 保真(r4 全量实测「默认值补写」修复):
+    # - 声明显式给 icon/color → 重编码(存量形态走最小 patch);
+    # - 声明未指定 + 创建语义(base_payload 无) → 合成默认(创建行为不变);
+    # - 声明未指定 + 更新语义 → 不碰 dashIcon:存量有则保留原值,存量空则**不合成**。
+    #   后端 updateDashBaseInfo 对 dashIcon 无校验直接透传;合成默认会让「B0 无图标」
+    #   门户在 apply 后长出默认图标/默认色(r4 实测 50 处 color diff 根因)。
+    if icon or color:
+        if base_payload is not None and isinstance(base_payload.get("dashIcon"), str):
+            data["dashIcon"] = update_workspace_icon_from_existing(
+                icon=icon,
+                color=color,
+                title=effective_name,
+                existing_icon=str(data.get("dashIcon") or "").strip() or None,
+                fallback_icon_name="view-grid",
+            )
+        else:
+            data["dashIcon"] = encode_workspace_icon_with_defaults(
+                icon=icon,
+                color=color,
+                title=effective_name,
+                fallback_icon_name="view-grid",
+                existing_icon=str(data.get("dashIcon") or "").strip() or None,
+            )
+    elif base_payload is None:
         data["dashIcon"] = encode_workspace_icon_with_defaults(
-            icon=icon,
-            color=color,
+            icon=None,
+            color=None,
             title=effective_name,
             fallback_icon_name="view-grid",
-            existing_icon=str(data.get("dashIcon") or "").strip() or None,
+            existing_icon=None,
         )
     data["dashName"] = effective_name
     data["auth"] = deepcopy(auth if auth is not None else data.get("auth") or default_member_auth())
@@ -20283,10 +20962,15 @@ def _build_public_portal_base_payload(
     elif "tags" not in data:
         data["tags"] = []
     global_config = deepcopy(dash_global_config if isinstance(dash_global_config, dict) else data.get("dashGlobalConfig") or {})
+    global_config = _compile_portal_global_config(global_config)
     global_config.pop("layout", None)
     global_config["interval"] = global_config.get("interval") or 60
     global_config["beingAutoRefresh"] = bool(global_config.get("beingAutoRefresh", False))
     data["dashGlobalConfig"] = global_config
+    if style_template_id is not None:
+        data["styleTemplateId"] = style_template_id
+    if overall_style is not None:
+        data["overallConfigBO"] = deepcopy(overall_style)
     if isinstance(config, dict):
         data.update(deepcopy(config))
     return data
@@ -20392,18 +21076,37 @@ def _find_chart_by_name(items: Any, *, chart_name: str, chart_type: str | None =
 
 def _portal_position_payload(position: Any, *, inferred_mobile_y: int = 0) -> dict[str, Any]:
     mobile_provided = bool(getattr(position, "mobile_provided", False))
-    mobile_rows = int(getattr(position, "mobile_h", 8)) if mobile_provided else int(getattr(position, "pc_h", 8))
+
+    def _coord(raw: Any, *, explicit: bool, default: int) -> int | None:
+        # explicit=False(mobile 未提供):忽略模型默认值,沿用调用方 default(布局推断),
+        # 与旧实现 `int(v) if provided else default` 行为一致;
+        # explicit=True:显式 null 原样透传(后端 DashPosition null 语义,筛选组件等原生
+        # NULL 位置读写链双向透传),仅键缺省时才回落布局默认值。
+        if not explicit:
+            return default
+        if raw is None:
+            return None
+        return int(raw)
+
+    mobile_h_raw = getattr(position, "mobile_h", None) if mobile_provided else None
+    pc_h_raw = getattr(position, "pc_h", None)
+    if mobile_provided:
+        # mobile 显式提供:rows 以 mobile_h 为准,null 透传(后端语义)
+        mobile_rows = None if mobile_h_raw is None else int(mobile_h_raw)
+    else:
+        # mobile 未提供:rows 跟随 pc 高度(与旧实现一致);pc_h 显式 null 时回落布局默认 8
+        mobile_rows = int(pc_h_raw) if pc_h_raw is not None else 8
     return {
         "pc": {
-            "x": int(getattr(position, "pc_x", 0)),
-            "y": int(getattr(position, "pc_y", 0)),
-            "cols": int(getattr(position, "pc_w", 12)),
-            "rows": int(getattr(position, "pc_h", 8)),
+            "x": _coord(getattr(position, "pc_x", None), explicit=True, default=0),
+            "y": _coord(getattr(position, "pc_y", None), explicit=True, default=0),
+            "cols": _coord(getattr(position, "pc_w", None), explicit=True, default=12),
+            "rows": _coord(getattr(position, "pc_h", None), explicit=True, default=8),
         },
         "mobile": {
-            "x": int(getattr(position, "mobile_x", 0)) if mobile_provided else 0,
-            "y": int(getattr(position, "mobile_y", 0)) if mobile_provided else int(inferred_mobile_y),
-            "cols": int(getattr(position, "mobile_w", 6)) if mobile_provided else 6,
+            "x": _coord(getattr(position, "mobile_x", None), explicit=mobile_provided, default=0),
+            "y": _coord(getattr(position, "mobile_y", None), explicit=mobile_provided, default=inferred_mobile_y),
+            "cols": _coord(getattr(position, "mobile_w", None), explicit=mobile_provided, default=6),
             "rows": mobile_rows,
         },
     }
@@ -20434,6 +21137,15 @@ def _portal_component_position_public(
     elif source_name == "link":
         cols = 12
         rows = 2
+    elif source_name == "carousel":
+        cols = 24
+        rows = 7
+    elif source_name == "task":
+        cols = 12
+        rows = 8
+    elif source_name == "favourite":
+        cols = 12
+        rows = 6
     else:
         if layout_preset == "dashboard_2col":
             cols = 12
@@ -23584,6 +24296,24 @@ def _ensure_field_temp_ids(fields: list[dict[str, Any]]) -> None:
         temp_id -= 100
 
 
+def _field_index_by_ref(fields: list[dict[str, Any]]) -> dict[int, dict[str, Any]]:
+    """按稳定引用(que_id,新字段退化 que_temp_id)建索引——方案 A 同名场景
+    下 by_name 会把不同 queId 的同名字段折叠成一个,relation 目标错位(实测
+    a9lfp40imk02:两个同名 code_block 各自输出到同名不同 queId 的 text 字段,
+    by_name 把两条 relation 撞到同一目标,触发 multiple default-value relations)。
+    """
+    index: dict[int, dict[str, Any]] = {}
+    for field in fields:
+        if not isinstance(field, dict):
+            continue
+        ref = _coerce_positive_int(field.get("que_id"))
+        if ref is None:
+            ref = _coerce_any_int(field.get("que_temp_id"))
+        if ref is not None and ref not in index:
+            index[ref] = field
+    return index
+
+
 def _compile_code_block_binding_fields(
     *,
     fields: list[dict[str, Any]],
@@ -23596,6 +24326,7 @@ def _compile_code_block_binding_fields(
         for field in next_fields
         if isinstance(field, dict) and str(field.get("name") or "")
     }
+    by_ref = _field_index_by_ref(next_fields)
     existing_relations = current_schema.get("questionRelations") if isinstance(current_schema.get("questionRelations"), list) else []
     relation_specs: list[dict[str, Any]] = []
     affected_source_refs: set[int] = set()
@@ -23711,7 +24442,12 @@ def _compile_code_block_binding_fields(
             target_payload = output_item.get("target_field")
             if not isinstance(target_payload, dict):
                 continue
-            target_field = by_name.get(str(target_payload.get("name") or ""))
+            # 编译产物 target_field 已带按 queId 唯一解析出的 que_id(同名字段
+            # 不折叠);以 ref 定位目标,que_id 缺失(新字段 temp 形态)才退化
+            # by_name——by_name 对同名目标会错位到任意一个同名字段。
+            target_field = by_ref.get(_coerce_any_int(target_payload.get("que_id")) or -1)
+            if not isinstance(target_field, dict):
+                target_field = by_name.get(str(target_payload.get("name") or ""))
             if not isinstance(target_field, dict):
                 continue
             target_ref = _coerce_positive_int(target_field.get("que_id"))
@@ -23779,6 +24515,7 @@ def _materialize_code_block_question_relations(
     relation_specs: list[dict[str, Any]],
 ) -> list[dict[str, Any]]:
     by_name = {str(field.get("name") or ""): field for field in fields if isinstance(field, dict) and str(field.get("name") or "")}
+    by_ref = _field_index_by_ref(fields)
     materialized: list[dict[str, Any]] = []
     for relation in relation_specs:
         if not isinstance(relation, dict):
@@ -23786,8 +24523,15 @@ def _materialize_code_block_question_relations(
         if _coerce_positive_int(relation.get("relationType")) == RELATION_TYPE_CODE_BLOCK:
             materialized.append(deepcopy(relation))
             continue
-        source_field = by_name.get(str(relation.get("source_field_name") or ""))
-        target_field = by_name.get(str(relation.get("target_field_name") or ""))
+        # relation_spec 的 *_field_ref 来自编译期按 queId 唯一解析的结果,优先
+        # 以 ref 定位源/目标字段;ref 缺失(新字段 temp 形态)退化 by_name——
+        # 同名字段场景 by_name 会折叠错位(与 _compile_* 侧同口径)。
+        source_field = by_ref.get(_coerce_any_int(relation.get("source_field_ref")) or -1)
+        if not isinstance(source_field, dict):
+            source_field = by_name.get(str(relation.get("source_field_name") or ""))
+        target_field = by_ref.get(_coerce_any_int(relation.get("target_field_ref")) or -1)
+        if not isinstance(target_field, dict):
+            target_field = by_name.get(str(relation.get("target_field_name") or ""))
         if not isinstance(source_field, dict) or not isinstance(target_field, dict):
             continue
         source_ref = _coerce_positive_int(source_field.get("que_id"))
@@ -23911,6 +24655,7 @@ def _compile_q_linker_binding_fields(
         for field in next_fields
         if isinstance(field, dict) and str(field.get("name") or "")
     }
+    by_ref = _field_index_by_ref(next_fields)
     existing_relations = current_schema.get("questionRelations") if isinstance(current_schema.get("questionRelations"), list) else []
     relation_specs: list[dict[str, Any]] = []
     affected_source_refs: set[int] = set()
@@ -24007,21 +24752,39 @@ def _compile_q_linker_binding_fields(
         compiled_json_value = None if request.get("json_value") is None else str(request.get("json_value") or "")
         compiled_xml_value = None if request.get("xml_value") is None else str(request.get("xml_value") or "")
         for index, input_item in enumerate(cast(list[dict[str, Any]], binding.get("inputs") or [])):
-            source_field = _resolve_field_selector_with_uniqueness(
-                fields=next_fields,
-                selector_payload=cast(dict[str, Any], input_item.get("field") or {}),
-                location=f"q_linker_binding.inputs[{index}].field",
-            )
-            source_que_id = _coerce_positive_int(source_field.get("que_id"))
-            if source_que_id is None:
-                source_que_id = _coerce_any_int(source_field.get("que_temp_id"))
+            selector_payload = cast(dict[str, Any], input_item.get("field") or {})
+            declared_que_id = _coerce_positive_int(selector_payload.get("que_id"))
+            declared_name = str(selector_payload.get("name") or "").strip()
+            try:
+                source_field = _resolve_field_selector_with_uniqueness(
+                    fields=next_fields,
+                    selector_payload=selector_payload,
+                    location=f"q_linker_binding.inputs[{index}].field",
+                )
+            except AmbiguousFieldSelector:
+                raise
+            except ValueError:
+                if declared_que_id is None:
+                    raise
+                # 透传:queId 已锚定但字段不在当前表单(存量悬空/改名引用)——后端
+                # 写链对 params_que_id 无存在性校验,按声明 queId 直写,名称用声明名
+                source_field = None
+            if source_field is None:
+                source_que_id = declared_que_id
+            else:
+                source_que_id = _coerce_positive_int(source_field.get("que_id"))
+                if source_que_id is None:
+                    source_que_id = _coerce_any_int(source_field.get("que_temp_id"))
             if source_que_id is None:
-                raise ValueError(f"q_linker input field '{source_field.get('name')}' does not have a stable que_id")
+                raise ValueError(f"q_linker input field '{declared_name or (source_field or {}).get('name')}' does not have a stable que_id")
+            # 引用重组优先用声明名:B0 模板引用名与当前字段名可能不同(存量字段名
+            # 带尾随空格等,如 am4oh08v2401),按解析名重组会改写模板破坏 round-trip
+            compose_name = declared_name or str((source_field or {}).get("name") or "")
             key = str(input_item.get("key") or "").strip()
             source_kind = str(input_item.get("source") or "").strip().lower()
             compiled_inputs.append(
                 {
-                    "field": {"name": source_field.get("name"), "que_id": source_que_id},
+                    "field": {"name": compose_name, "que_id": source_que_id},
                     "key": key,
                     "source": source_kind,
                 }
@@ -24035,7 +24798,7 @@ def _compile_q_linker_binding_fields(
                 compiled_url_encoded.append(kv_item)
             elif source_kind == "json_path":
                 token = "{{" + key + "}}"
-                reference = _compose_qlinker_value_reference(field_name=str(source_field.get("name") or ""), que_id=source_que_id)
+                reference = _compose_qlinker_value_reference(field_name=compose_name, que_id=source_que_id)
                 compiled_url = compiled_url.replace(token, reference)
                 if compiled_json_value is not None:
                     compiled_json_value = compiled_json_value.replace(token, reference)
@@ -24121,7 +24884,12 @@ def _compile_q_linker_binding_fields(
             target_payload = output_item.get("target_field")
             if not isinstance(target_payload, dict):
                 continue
-            target_field = by_name.get(str(target_payload.get("name") or ""))
+            # 编译产物 target_field 已带按 queId 唯一解析出的 que_id(同名字段
+            # 不折叠);以 ref 定位目标,que_id 缺失(新字段 temp 形态)才退化
+            # by_name——by_name 对同名目标会错位到任意一个同名字段。
+            target_field = by_ref.get(_coerce_any_int(target_payload.get("que_id")) or -1)
+            if not isinstance(target_field, dict):
+                target_field = by_name.get(str(target_payload.get("name") or ""))
             if not isinstance(target_field, dict):
                 continue
             target_ref = _coerce_positive_int(target_field.get("que_id"))
@@ -24179,12 +24947,20 @@ def _materialize_q_linker_question_relations(
     relation_specs: list[dict[str, Any]],
 ) -> list[dict[str, Any]]:
     by_name = {str(field.get("name") or ""): field for field in fields if isinstance(field, dict) and str(field.get("name") or "")}
+    by_ref = _field_index_by_ref(fields)
     materialized: list[dict[str, Any]] = []
     for relation in relation_specs:
         if not isinstance(relation, dict):
             continue
-        source_field = by_name.get(str(relation.get("source_field_name") or ""))
-        target_field = by_name.get(str(relation.get("target_field_name") or ""))
+        # relation_spec 的 *_field_ref 来自编译期按 queId 唯一解析的结果,优先
+        # 以 ref 定位源/目标字段;ref 缺失(新字段 temp 形态)退化 by_name——
+        # 同名字段场景 by_name 会折叠错位(与 _compile_* 侧同口径)。
+        source_field = by_ref.get(_coerce_any_int(relation.get("source_field_ref")) or -1)
+        if not isinstance(source_field, dict):
+            source_field = by_name.get(str(relation.get("source_field_name") or ""))
+        target_field = by_ref.get(_coerce_any_int(relation.get("target_field_ref")) or -1)
+        if not isinstance(target_field, dict):
+            target_field = by_name.get(str(relation.get("target_field_name") or ""))
         if not isinstance(source_field, dict) or not isinstance(target_field, dict):
             continue
         source_ref = _coerce_positive_int(source_field.get("que_id"))
@@ -27814,6 +28590,385 @@ def _normalize_portal_components(components: Any) -> list[dict[str, Any]]:
     return items
 
 
+def _portal_component_source_type_by_backend(value: Any) -> str:
+    raw = value if isinstance(value, (int, str)) else str(value or "").strip()
+    mapping = {
+        1: "chart",
+        2: "grid",
+        3: "carousel",
+        4: "link",
+        5: "text",
+        6: "filter",
+        7: "favourite",
+        8: "task",
+        9: "chart",
+        10: "view",
+    }
+    if isinstance(raw, int):
+        return mapping.get(raw, "unknown")
+    raw_str = str(raw or "").strip()
+    if raw_str.isdigit():
+        return mapping.get(int(raw_str), "unknown")
+    return _normalize_portal_component_source_type(raw)
+
+
+def _portal_section_from_component(
+    component: dict[str, Any],
+    *,
+    index: int,
+    complete: bool,
+) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
+    """Reverse-compile one DashComponentInfo into a canonical section."""
+    source_type = _portal_component_source_type_by_backend(component.get("type"))
+    config_key_map = {
+        "grid": "gridConfig",
+        "link": "linkConfig",
+        "text": "textConfig",
+        "filter": "filterConfig",
+        "chart": "chartConfig",
+        "view": "viewgraphConfig",
+        "carousel": "carouselConfig",
+        "task": "taskConfig",
+        "favourite": "favouriteConfig",
+    }
+    if source_type == "unknown":
+        return None, {
+            "index": index,
+            "code": "UNKNOWN_COMPONENT_TYPE",
+            "message": f"component type {component.get('type')} is not part of the portals declaration contract",
+            "blocking_field": "source_type",
+        }
+    config = component.get(config_key_map.get(source_type, "")) if isinstance(component.get(config_key_map.get(source_type, "")), dict) else {}
+    section: dict[str, Any] = {"source_type": source_type}
+    title = _extract_portal_component_title(component, source_type=source_type)
+    gaps: list[dict[str, Any]] = []
+    if source_type == "carousel":
+        title = str(config.get("sourceApp", {}).get("formTitle") or "").strip() or f"轮播 {index + 1}"
+    elif source_type == "task":
+        title = str(config.get("componentTaskTitle") or f"待办 {index + 1}")
+    elif source_type == "favourite":
+        title = str(config.get("favouriteTitle") or f"收藏 {index + 1}")
+    # chart/grid/view 的 title 语义=组件显示标题(component_title/grid_title 落库列),
+    # 生产存量大量存在「显示标题开但标题空」形态(读链渲染时回退图表名/视图名):
+    # 合成「组件 N」会把不存在的标题落库(读链 chartName 派生被覆盖 + 库表漂移),
+    # 如实保留 None(编译不落库,round-trip 保真)。carousel/task/favourite 的
+    # 读面自有真名回填(formTitle/componentTaskTitle/favouriteTitle),其合成兑底保留。
+    # filter 同样不合成:后端 addComponentInfos 对筛选组件不落任何标题(无标题存储),
+    # 读面按代理键 HashMap 迭代序返回——合成「组件 {index+1}」的标签是列表序号的
+    # 函数,apply 删重建致代理键位移后标题跟着置换(r6 幂等差 3 的唯一根因)。
+    if source_type not in {"chart", "grid", "view", "filter"}:
+        title = title or f"组件 {index + 1}"
+    section["title"] = title
+    if source_type in {"chart", "view"} and complete:
+        # beingShowTitle 落库列(draft_dash_chart.being_show_title):读面必有值;
+        # 提取必须保真(存量 false 被「硬编码 True」覆写会漂移库表)。grid 的开关
+        # 在 grid_config.beingShowTitle 键内随 config 保留,无需单独建模。
+        if "beingShowTitle" in config:
+            section["show_title"] = bool(config.get("beingShowTitle"))
+    position = component.get("position")
+    if isinstance(position, dict) and position:
+        section["position"] = deepcopy(position)
+    if complete:
+        style = component.get("dashStyleConfigBO")
+        if isinstance(style, dict) and style:
+            section["style_config"] = deepcopy(style)
+    if source_type == "chart":
+        # 后端两类图表组件引用面不同(DashSvcImpl 写链):type=1 轻流报表锚 chart 表唯一键
+        # chartKey(addChartInfos);type=9 轻析 BI 报表锚 bi_chart 整型 chart_id(addBiChartInfo)。
+        # 提取时以读面 type 判别 ref_kind,保证 apply 回写同一引用面。
+        backend_type = component.get("type")
+        is_qingflow_chart = backend_type == 1 or (
+            backend_type != 9 and str(config.get("chartKey") or "").strip() and not config.get("biChartId")
+        )
+        if is_qingflow_chart:
+            chart_ref: dict[str, Any] = {
+                "ref_kind": "chart",
+                "chart_id": str(config.get("chartKey") or "").strip() or None,
+                "chart_name": str(config.get("chartName") or title or "").strip() or None,
+            }
+        else:
+            chart_ref = {
+                "chart_id": str(config.get("biChartId") or "").strip() or None,
+                "chart_name": str(config.get("chartComponentTitle") or title or "").strip() or None,
+            }
+        chart_ref = {key: value for key, value in chart_ref.items() if value is not None}
+        if not chart_ref.get("chart_id"):
+            gaps.append({
+                "index": index,
+                "code": "CHART_REF_MISSING",
+                "message": "chart component has no chartKey/biChartId in the read face",
+                "blocking_field": "chart_ref.chart_id",
+            })
+            return None, gaps[0]
+        section["chart_ref"] = chart_ref
+    elif source_type == "view":
+        view_ref: dict[str, Any] = {
+            "app_key": str(config.get("appKey") or "").strip() or None,
+            "view_key": str(config.get("viewgraphKey") or "").strip() or None,
+            "view_name": str(config.get("viewgraphName") or title or "").strip() or None,
+        }
+        view_ref = {key: value for key, value in view_ref.items() if value is not None}
+        if not view_ref.get("view_key"):
+            gaps.append({
+                "index": index,
+                "code": "VIEW_REF_MISSING",
+                "message": "view component has no viewgraphKey in the read face",
+                "blocking_field": "view_ref.view_key",
+            })
+            return None, gaps[0]
+        section["view_ref"] = view_ref
+        if complete and ("beingShowTitle" in config or config.get("componentTitle")):
+            display: dict[str, Any] = {}
+            if "beingShowTitle" in config:
+                display["show_title"] = bool(config.get("beingShowTitle"))
+            if config.get("componentTitle"):
+                display["component_title"] = str(config.get("componentTitle"))
+            if display:
+                section["view_display"] = display
+    elif source_type == "grid":
+        grid_config: dict[str, Any] = {}
+        for key in ("gridTitle", "beingShowTitle", "items"):
+            if key in config:
+                grid_config[key] = deepcopy(config.get(key))
+        if isinstance(grid_config.get("items"), list):
+            # 归一到声明规范键集(DraftComponentGridItem 落库列 + 读面派生 title):
+            # 丢弃运行态/代理键(id/gridId/beingShowTitle/beingTrial/trialExpireDate——
+            # 前者是自增代理键(比对器另剔),后两者读面运行态不入库,title/iconUrl 由
+            # setTitleAndIconByType 按引用派生);空 title 条目仍过滤(后端读面同型)。
+            kept_item_keys = {
+                "type", "jumpMode", "linkAppKey", "linkFormType", "linkDashKey",
+                "linkTagId", "linkUrl", "title", "customTitle", "beingCustomTitle",
+                "iconUrl", "ordinal",
+            }
+            normalized_items: list[dict[str, Any]] = []
+            for item in grid_config["items"]:
+                if not isinstance(item, dict) or not str(item.get("title") or "").strip():
+                    continue
+                normalized = {
+                    key: deepcopy(value)
+                    for key, value in item.items()
+                    if key in kept_item_keys and value is not None
+                }
+                # iconUrl 语义按条目类型分裂(Java ComponentGridItemInfo#setTitleAndIconByType):
+                # type 1/2/3(应用/门户/应用包)的 iconUrl 与 title 是读面按引用目标当前
+                # 图标实时派生的投影——门户声明不拥有也无法保真(写侧不回写生效值),
+                # 提取侧剔除;自定义条目 iconUrl 落库原样读回,保留 round-trip。
+                # 空串 iconUrl 统一剔除(与 favourite 提取对称,消 ""↔缺键不对称)。
+                if _coerce_positive_int(normalized.get("type")) in {1, 2, 3} or not str(normalized.get("iconUrl") or "").strip():
+                    normalized.pop("iconUrl", None)
+                normalized_items.append(normalized)
+            grid_config["items"] = normalized_items
+        section["config"] = grid_config
+    elif source_type == "text":
+        section["text"] = str(config.get("text") or "")
+        if complete and config:
+            extra_config = {key: deepcopy(value) for key, value in config.items() if key not in {"text"}}
+            if extra_config:
+                section["config"] = extra_config
+    elif source_type == "link":
+        section["url"] = str(config.get("url") or "")
+        if complete and "beingLoginAuth" in config:
+            section["login_auth"] = bool(config.get("beingLoginAuth"))
+    elif source_type == "filter":
+        graph_list = config.get("graphList") if isinstance(config.get("graphList"), list) else []
+        graphs = [
+            {
+                "chart_key": str(item.get("graphKey") or "").strip() or None,
+                "chart_name": str(item.get("graphName") or "").strip() or None,
+            }
+            for item in graph_list
+            if isinstance(item, dict)
+        ]
+        graphs = [
+            {key: value for key, value in item.items() if value is not None}
+            for item in graphs
+        ]
+        rules: list[dict[str, Any]] = []
+        for group in config.get("filterConfig") or []:
+            if not isinstance(group, dict):
+                continue
+            # 剔除后端删除重建的代理键(filterGroupId/filterItemId,自增 id 每次位移,七条约束之六):
+            # 声明级比以此归一,规则语义真源是 filterGroupName/filterItemName/judge 系内容列。
+            rules.append({
+                key: deepcopy(value)
+                for key, value in group.items()
+                if key not in {"filterGroupId"}
+            })
+        for group in rules:
+            for item in group.get("filterGroupConfig") or []:
+                if isinstance(item, dict):
+                    item.pop("filterItemId", None)
+        section["config"] = {"graphs": graphs, "rules": rules}
+    elif source_type == "carousel":
+        carousel: dict[str, Any] = {}
+        source_app = config.get("sourceApp") if isinstance(config.get("sourceApp"), dict) else {}
+        if source_app.get("appKey"):
+            carousel["source_app_key"] = str(source_app.get("appKey"))
+            if source_app.get("formTitle"):
+                carousel["source_form_title"] = str(source_app.get("formTitle"))
+        for raw_key, target_key in (("titleQue", "title_field"), ("imageQue", "image_field"), ("linkQue", "link_field")):
+            que = config.get(raw_key) if isinstance(config.get(raw_key), dict) else {}
+            if que.get("queId") is not None:
+                carousel[target_key] = str(que.get("queId"))
+        if "jumpMode" in config:
+            carousel["jump_mode"] = config.get("jumpMode")
+        if "beingScaling" in config:
+            carousel["scaling"] = bool(config.get("beingScaling"))
+        if "showLatestLimit" in config:
+            carousel["show_latest_limit"] = config.get("showLatestLimit")
+        if "scrollInterval" in config:
+            carousel["scroll_interval"] = config.get("scrollInterval")
+        filter_config = config.get("filterConfig")
+        if isinstance(filter_config, list) and filter_config:
+            # ComponentCarouselConfig.filterConfig 是单组 AND 的 MatchRule 列表。
+            # DashSvcImpl#getDashDetail 会补 judgeValueDetails/judgeType;复用门户既有
+            # match-rule 映射，优先以 details 作为选项值真源，避免只回传派生 judgeValues。
+            raw_rules = filter_config[0] if isinstance(filter_config[0], list) else filter_config
+            filters: list[dict[str, Any]] = []
+            for rule in raw_rules:
+                if not isinstance(rule, dict):
+                    continue
+                que_id = _coerce_positive_int(rule.get("queId"))
+                if que_id is None:
+                    gaps.append({
+                        "index": index,
+                        "code": "CAROUSEL_FILTER_FIELD_UNRESOLVED",
+                        "message": "carousel filter rule has no resolvable queId",
+                        "blocking_field": "carousel.filters",
+                    })
+                    continue
+                field = {"que_id": que_id, "name": str(rule.get("queTitle") or que_id)}
+                values = _public_view_filter_rule_values(rule, field=field)
+                operator = _public_view_filter_operator_from_judge_type(rule.get("judgeType"), values=values)
+                if operator.startswith("judge_type:"):
+                    gaps.append({
+                        "index": index,
+                        "code": "CAROUSEL_FILTER_OPERATOR_UNSUPPORTED",
+                        "message": "carousel filter rule judgeType is not expressible in v1alpha1",
+                        "blocking_field": "carousel.filters",
+                        "judge_type": rule.get("judgeType"),
+                    })
+                    continue
+                item: dict[str, Any] = {"field_name": str(que_id), "operator": operator}
+                if operator not in {"is_empty", "not_empty"}:
+                    item["values"] = values
+                filters.append(item)
+            if filters:
+                carousel["filters"] = filters
+        section["carousel"] = carousel
+    elif source_type == "task":
+        task: dict[str, Any] = {}
+        if "beingShowTitle" in config:
+            task["show_title"] = bool(config.get("beingShowTitle"))
+        if config.get("componentTaskHint") is not None:
+            task["hint"] = str(config.get("componentTaskHint") or "")
+        if "beingShowHint" in config:
+            task["show_hint"] = bool(config.get("beingShowHint"))
+        if "beingUsing" in config:
+            task["enabled"] = bool(config.get("beingUsing"))
+        raw_tasks = config.get("dashTaskConfigList")
+        if isinstance(raw_tasks, list) and raw_tasks:
+            task["tasks"] = [
+                {
+                    "title": str(item.get("title") or ""),
+                    "task_type": item.get("type"),
+                    "ordinal": item.get("ordinal"),
+                    "checked": bool(item.get("beingCheck")),
+                }
+                for item in raw_tasks
+                if isinstance(item, dict)
+            ]
+        section["task"] = task
+    elif source_type == "favourite":
+        favourite: dict[str, Any] = {}
+        if "beingShowTitle" in config:
+            favourite["show_title"] = bool(config.get("beingShowTitle"))
+        if "beingUsing" in config:
+            favourite["enabled"] = bool(config.get("beingUsing"))
+        raw_items = config.get("items")
+        if isinstance(raw_items, list) and raw_items:
+            favourite["items"] = [
+                {
+                    "title": str(item.get("title") or ""),
+                    "item_type": item.get("type"),
+                    "link_key": str(item.get("linkKey") or "") or None,
+                    "link_id": item.get("linkId"),
+                    "icon_url": str(item.get("iconUrl") or "") or None,
+                    "jump_mode": item.get("jumpMode"),
+                    "ordinal": item.get("ordinal"),
+                }
+                for item in raw_items
+                if isinstance(item, dict)
+            ]
+            favourite["items"] = [
+                {key: value for key, value in item.items() if value is not None}
+                for item in favourite["items"]
+            ]
+        section["favourite"] = favourite
+    return section, (gaps[0] if gaps else None)
+
+
+def _portal_declaration_from_dash_detail(
+    detail: dict[str, Any],
+    *,
+    schema_kind: str,
+) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    """Reverse-compile a DashDetailInfo read into a canonical portal declaration."""
+    complete = schema_kind == "complete"
+    gaps: list[dict[str, Any]] = []
+    sections: list[dict[str, Any]] = []
+    raw_components = detail.get("components") if isinstance(detail.get("components"), list) else []
+    for index, component in enumerate(raw_components):
+        if not isinstance(component, dict):
+            continue
+        section, gap = _portal_section_from_component(component, index=index, complete=complete)
+        if gap is not None:
+            gaps.append(gap)
+        if section is not None:
+            sections.append(section)
+    declaration: dict[str, Any] = {"sections": sections}
+    # 后端 dash_name 允许空串(生产存量存在,updateDashBaseInfo 无非空校验):
+    # 提取侧始终写出 name 键,空名透传(round-trip 保真),不再把空名当成缺省。
+    declaration["name"] = str(detail.get("dashName") or "").strip()
+    tags = detail.get("tags") if isinstance(detail.get("tags"), list) else []
+    first_tag = tags[0] if tags and isinstance(tags[0], dict) else {}
+    tag_id = _coerce_positive_int(first_tag.get("tagId"))
+    if tag_id is not None:
+        declaration["package_tag_id"] = tag_id
+    if not complete:
+        return declaration, gaps
+    dash_icon = str(detail.get("dashIcon") or "").strip() or None
+    if dash_icon:
+        icon_config = workspace_icon_config(dash_icon)
+        icon = str(icon_config.get("icon_name") or "").strip() or None
+        color = str(icon_config.get("icon_color") or "").strip() or None
+        if icon:
+            declaration["icon"] = icon
+        if color:
+            declaration["color"] = color
+    if "hideCopyright" in detail:
+        declaration["hide_copyright"] = bool(detail.get("hideCopyright"))
+    global_config = detail.get("dashGlobalConfig") if isinstance(detail.get("dashGlobalConfig"), dict) else {}
+    if global_config:
+        declaration["global_config"] = {}
+        if "interval" in global_config:
+            declaration["global_config"]["interval"] = global_config.get("interval")
+        if "beingAutoRefresh" in global_config:
+            declaration["global_config"]["auto_refresh"] = bool(global_config.get("beingAutoRefresh"))
+        if "beingExport" in global_config:
+            declaration["global_config"]["export"] = bool(global_config.get("beingExport"))
+    visibility = _public_visibility_from_member_auth(detail.get("auth"))
+    if isinstance(visibility, dict) and visibility:
+        declaration["visibility"] = visibility
+    style_template_id = _coerce_positive_int(detail.get("styleTemplateId"))
+    if style_template_id is not None:
+        declaration["style_template_id"] = style_template_id
+    overall = detail.get("overallConfigBO")
+    if isinstance(overall, dict) and overall:
+        declaration["overall_style"] = deepcopy(overall)
+    return declaration, gaps
+
+
 def _custom_button_view_configs_from_view_summaries(views: list[dict[str, Any]]) -> list[dict[str, Any]]:
     view_configs: list[dict[str, Any]] = []
     for view in views:
@@ -27967,7 +29122,10 @@ def _extract_portal_component_title(component: dict[str, Any], *, source_type: s
         "text": ["title", "textTitle"],
         "filter": ["title", "filterTitle"],
         "chart": ["chartComponentTitle", "componentTitle", "title"],
-        "view": ["componentTitle", "viewgraphName", "title"],
+        # view 的 title 语义=组件显示标题(component_title 落库列,可空);视图名
+        # (viewgraphName)是引用面锚进 view_ref.view_name,不再混入 title 候选
+        # (旧候选把它兑底进 title,编译时覆写 componentTitle 造成库表漂移)。
+        "view": ["componentTitle", "title"],
     }
     for key in title_candidates.get(source_type, []):
         title = str(config.get(key) or "").strip()
@@ -30529,6 +31687,9 @@ def _translate_view_filter_rule(*, field: dict[str, Any], rule: dict[str, Any])
     elif operator == "in":
         payload["judgeType"] = JUDGE_INCLUDE_ANY if field_type in INCLUDE_ANY_FLOW_FIELD_TYPES else JUDGE_EQUAL_ANY
         payload["judgeValues"] = judge_values
+    elif operator == "belongs_to":
+        payload["judgeType"] = JUDGE_BELONG_TO
+        payload["judgeValues"] = judge_values
     elif operator == "contains":
         payload["judgeType"] = JUDGE_INCLUDE
         payload["judgeValues"] = judge_values[:1] if judge_values else []
@@ -30850,6 +32011,8 @@ def _public_view_filter_operator_from_judge_type(judge_type: Any, *, values: lis
         # ANY 判型+空值 = "该字段未选任何值"的合法存量形态(judgeType 保真回写,
         # 转 is_empty 会丢判型——后端 9 与 0 是不同判定域,实测回读不同)
         return "in"
+    if normalized == JUDGE_BELONG_TO:
+        return "belongs_to"
     if normalized == JUDGE_GREATER_OR_EQUAL:
         return "gte"
     if normalized == JUDGE_LESS_OR_EQUAL: