@qingflow-tech/qingflow-cli 1.1.61-beta.3 → 1.1.61-beta.5

package/src/qingflow_mcp/builder_facade/app_form.py

@@ -54,6 +54,24 @@ QUE_TYPE_TO_CANONICAL = {
     22: "department",
     25: "relation",
     26: "code_block",
+    # 透传型字段(r10 读面 65 app 缺口):声明层 EmptyConfig,round-trip 经后端
+    # 模板保真(选项/技能配置列随模板透传);语义 = QuestionTypeEnum 14/15/17/23
+    # 与 Constants QUE_TYPE_EMBED_FIELD(27)、AI 系 30-37(AI_CONTENT_GENERATION
+    # /EXTRACTION/CLASSIFICATION、AI_MACHINE_TRANSLATION、AI_IMAGE_RECOGNITION
+    # /GENERATION、AI_DOCUMENT_PARSING、AI_TEXT_SUMMARY)
+    14: "date_duration",
+    15: "image_select",
+    17: "location",
+    23: "ocr",
+    27: "embed_field",
+    30: "ai_content_generation",
+    31: "ai_content_extraction",
+    32: "ai_content_classification",
+    33: "ai_machine_translation",
+    34: "ai_image_recognition",
+    35: "ai_image_generation",
+    36: "ai_document_parsing",
+    37: "ai_text_summary",
 }
 CANONICAL_TO_QUE_TYPE = {
     "text": 2,
@@ -78,6 +96,20 @@ CANONICAL_TO_QUE_TYPE = {
     "data_relation": 19,
     "relation": 25,
     "subtable": 18,
+
+    "date_duration": 14,
+    "image_select": 15,
+    "location": 17,
+    "ocr": 23,
+    "embed_field": 27,
+    "ai_content_generation": 30,
+    "ai_content_extraction": 31,
+    "ai_content_classification": 32,
+    "ai_machine_translation": 33,
+    "ai_image_recognition": 34,
+    "ai_image_generation": 35,
+    "ai_document_parsing": 36,
+    "ai_text_summary": 37,
 }
 SUBFIELD_TYPES = {
     "text",
@@ -1227,11 +1259,20 @@ class AppFormNormalizer:
                 name = match.group("name").strip()
                 if name:
                     token = match.group("token").strip()
+                    # 名字两侧 strip 匹配:存量字段名带尾随空格(如 am4oh08v2401
+                    # 「答:Answer 」),模板引用名无空格——严格相等会丢 queId 锚定
                     matching_ids = [
                         que_id
                         for que_id, field_name in field_names.items()
-                        if field_name == name and _encrypt_question_id(que_id) == token
+                        if str(field_name).strip() == name and _encrypt_question_id(que_id) == token
                     ]
+                    if not matching_ids:
+                        # 悬空引用(字段已删/改名,模板仍留旧引用):原文透传——占位符
+                        # 化会丢 token 无法复原(加密不可逆),后端写链对模板原样落库;
+                        # 不注册 input(声明无此输入,写回与 B0 模板逐字一致,
+                        # r10 实测 9gtommb3ng01 等 6 app「inputs[N].field could not
+                        # be resolved」即此形态)
+                        return match.group(0)
                     json_path_inputs.setdefault(
                         name,
                         {
@@ -1244,11 +1285,21 @@ class AppFormNormalizer:
 
             request_values[request_key] = Q_LINKER_VALUE_REFERENCE_RE.sub(replace_reference, raw_value)
         inputs.extend(json_path_inputs.values())
-        request_url = _required_text(
-            request_values["url"],
-            message="Q-Linker request URL is empty",
-            details={"queId": source_id, "path": "/config/qLinkerBinding/request/url"},
-        )
+        # URL 空容忍边界(#208③):后端写链仅 configMode=1(自定义)校验 url/method/
+        # resultType 非空(FormQuestionSvcImpl.createQuestionRemoteLookUp:444 抛
+        # REMOTE_LOOK_UP_SETTING_WRONG);configMode=2 插件模板 / 3 连接中心 /
+        # 4 轻翼智能体的 URL 由模板侧提供,本表 url 空 是合法存量形态——非自定义
+        # 模式放行空 URL 透传(写回走模板透传,round-trip 保真;r12 归因 27 app;
+        # 自定义模式 url 空的 2 app 脓数据仍拒绝,入排除账本)。
+        config_mode = _positive_int(config.get("configMode")) or 1
+        if config_mode == 1:
+            request_url = _required_text(
+                request_values["url"],
+                message="Q-Linker request URL is empty",
+                details={"queId": source_id, "path": "/config/qLinkerBinding/request/url"},
+            )
+        else:
+            request_url = str(request_values["url"] or "")
         request = _without_none(
             {
                 "url": request_url,
@@ -1771,7 +1822,9 @@ class AppFormCompiler:
                     if not isinstance(item, dict) or item.get("source") != "json_path":
                         continue
                     selected = _resolve_internal_selector(item.get("field") or {}, internal_fields, f"qLinkerBinding.inputs[{index}].field")
-                    if str(item.get("key") or "") != str(selected.get("name") or ""):
+                    # 两侧 strip:模板引用名提取时已 strip(存量字段名带尾随空格,
+                    # 如 r10 am4oh08v2401「答:Answer 」),严格相等误报 key 不一致
+                    if str(item.get("key") or "").strip() != str(selected.get("name") or "").strip():
                         raise AppFormFailure(
                             "UNSUPPORTED_FIELD_CONFIG",
                             "json_path input key must equal the selected field name for lossless readback",
@@ -2449,7 +2502,18 @@ class AppFormCompiler:
     def _question(self, profile: str, app_key: str, field: JSONObject, internal: JSONObject, temp_id: int, relations: list[JSONObject]) -> JSONObject:
         field_type = _field_type(field)
         que_type = CANONICAL_TO_QUE_TYPE[field_type]
-        build_type = "boolean" if field_type == "single_choice" else "text" if field_type in {"link", "data_relation", "rich_text"} else field_type
+        build_type = (
+            "boolean" if field_type == "single_choice"
+            else "text" if field_type in {
+                "link", "data_relation", "rich_text",
+                # 透传型新类型(r10 读面覆盖):build 走 text 兜底,类型/配置经模板保真
+                "date_duration", "image_select", "location", "ocr", "embed_field",
+                "ai_content_generation", "ai_content_extraction", "ai_content_classification",
+                "ai_machine_translation", "ai_image_recognition", "ai_image_generation",
+                "ai_document_parsing", "ai_text_summary",
+            }
+            else field_type
+        )
         built_internal = deepcopy(internal)
         built_internal["type"] = build_type
         if build_type == "subtable":
@@ -2821,7 +2885,21 @@ class AppFormCompiler:
             if source.get("kind") == "app":
                 source_fields, _target_form = self._target_form_candidates(profile, str(source.get("appKey") or ""))
                 source_fields_are_backend = True
-                target = _resolve_backend_selector(source.get("field") or {}, source_fields, "source.field")
+                # 展示字段同样按后端语义透传:写链对 displayedQueId 无存在性校验
+                # 原样落库(fillMatchRulesList 读链按全局 question∪draft_question
+                # 解析)。解析不到时 queType=None → 写侧 origin_type 回退 current
+                # 模板值(见 data_relation relatedQueId/queOriginType 组装)。
+                try:
+                    target = _resolve_backend_selector(source.get("field") or {}, source_fields, "source.field")
+                except AppFormFailure as error:
+                    if error.error_code != "INVALID_FIELD_SELECTOR" or _positive_int((source.get("field") or {}).get("queId")) is None:
+                        raise
+                    target = {
+                        "queId": _positive_int(source["field"].get("queId")),
+                        "queTitle": str(source["field"].get("name") or "").strip() or None,
+                        "queType": None,
+                        "_app_form_unresolved": True,
+                    }
                 relation.update(
                     {
                         "displayedQueId": target["queId"],
@@ -3070,7 +3148,23 @@ class AppFormCompiler:
         location: str,
     ) -> JSONObject:
         if source_fields_are_backend:
-            return _resolve_backend_selector(selector, source_fields, location)
+            try:
+                return _resolve_backend_selector(selector, source_fields, location)
+            except AppFormFailure as error:
+                # 目标表单候选集(草稿∪发布 formQues)解析不到、但 selector 带正
+                # queId:按后端语义透传——读链 fillMatchRulesList 按 queId 查
+                # question∪draft_question 全局表,查不到容忍置空(new Question());
+                # 写链 updateFormInfo 对 matchRules/sortConfig 源 queId 无存在性
+                # 校验、原样落库。存量里该形态 = 引用指向目标表单 GET 响应之外
+                # 的字段(跨表/已删,如 r8 实测 00e0e0d8 筛选源),严格拒绝即
+                # round-trip 断裂。queType 置 None 与后端「查不到置空」同构。
+                if error.error_code == "INVALID_FIELD_SELECTOR" and _positive_int(selector.get("queId")) is not None:
+                    return {
+                        "queId": _positive_int(selector.get("queId")),
+                        "queTitle": str(selector.get("name") or "").strip() or None,
+                        "_app_form_unresolved": True,
+                    }
+                raise
         return _resolve_internal_selector(selector, source_fields, location)
 
     @staticmethod
@@ -3088,7 +3182,11 @@ class AppFormCompiler:
         return title
 
     @staticmethod
-    def _data_relation_que_type(field: JSONObject) -> int:
+    def _data_relation_que_type(field: JSONObject) -> int | None:
+        if field.get("_app_form_unresolved"):
+            # 透传形态(目标表单候选集解析不到):后端 fillMatchRulesList 对查
+            # 不到的 queId 置空 queType 继续出参,写链不校验——同构置 None。
+            return None
         backend_type = _positive_int(field.get("queType"))
         if backend_type is not None:
             return backend_type
@@ -3142,7 +3240,12 @@ class AppFormCompiler:
         ordered_ops = common | {"greater_than", "greater_or_equal", "less_than", "less_or_equal", "dynamic_range", "decimal_range"}
         organization_ops = common | {"belongs_to", "not_belongs_to", "subordinate_to", "not_subordinate_to", "subordinate_included", "subordinate_not_included", "contains_any", "contains_all"}
         field_type = _canonical_backend_field_type(source)
-        if field_type in {"number", "amount", "date", "datetime"}:
+        if source.get("_app_form_unresolved"):
+            # 透传形态:源字段类型不可知(后端读链查不到置空),后端写链对
+            # operator×源类型组合无校验——跳过类型白名单,仅保留 operand 形状
+            # 校验(下方),与「读面保留、写面透传」的存量形态处理同口径。
+            allowed = common | text_ops | ordered_ops | organization_ops
+        elif field_type in {"number", "amount", "date", "datetime"}:
             # date/datetime 补 belongs_to/not_belongs_to:后端 judgeType=13(JUDGE_BELONG_TO)
             # 对时间字段的存量语义是「属于时间范围」(judgeValues 形如
             # "2025-01-30 14:20:59~2026-01-30 14:20:59"),与组织字段的属于语义
@@ -3150,6 +3253,12 @@ class AppFormCompiler:
             allowed = ordered_ops | ({"belongs_to", "not_belongs_to"} if field_type in {"date", "datetime"} else set())
         elif field_type in {"member", "department"}:
             allowed = organization_ops
+        elif field_type in {"text", "multi_select"}:
+            # text/multi_select 补 belongs_to/not_belongs_to:judgeType=13 同为多态
+            # 语义(选项「属于」集合),后端写链对 operator×源类型无校验——存量
+            # 实证 r8:bjqj2bge2g02(multi_select 资产类型 belongs_to 当前字段)、
+            # e4f644fe(text 客户等级 belongs_to literal ["BC"])。
+            allowed = text_ops | {"belongs_to", "not_belongs_to"}
         else:
             allowed = text_ops
         if operator not in allowed:
@@ -3163,7 +3272,10 @@ class AppFormCompiler:
         if operator in EMPTY_OPERATORS:
             if operand.get("kind") != "literal" or values not in ([], None):
                 raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "empty-value operators require an empty literal operand", "CONTRACT_PRECHECK")
-        elif operand.get("kind") == "literal" and not values:
+        elif operand.get("kind") == "literal" and not values and operator not in {"subordinate_to", "not_subordinate_to"}:
+            # subordinate 两算子放行空 literal:存量「设置后清空」形态(r13 实证
+            # 41ce0ad8)——后端写链仅校验 dynamic_range(checkRelationMatchRules),
+            # formula 对空 judgeValueDetails 渲染 [],读回解析对称,往返保真
             raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "literal data_relation operands must contain at least one value", "CONTRACT_PRECHECK")
 
     @staticmethod
@@ -3279,11 +3391,19 @@ class AppFormCompiler:
         merged: list[JSONObject] = []
         seen: set[int] = set()
         for item in [*_backend_question_candidates(draft_form), *_backend_question_candidates(published_form)]:
-            que_id = _positive_int(item.get("queId"))
-            if que_id is not None:
-                if que_id in seen:
+            raw_id = item.get("queId")
+            if isinstance(raw_id, int) and not isinstance(raw_id, bool):
+                # queId 是字段身份,身份语义覆盖 0 与负数:0 是系统「编号」虚拟行
+                # (que_type=8,GET 草稿/发布两态各带一行)、负数是系统行(-1 数据来源
+                # 等,补导后物理在表)。只按正整数去重会让 queId=0 的「编号」在
+                # 并集里出现两次,by_name 引用恒定命中 2 个候选 → AMBIGUOUS_
+                # FIELD_SELECTOR(r13 103 app data_relation/relation 深层配置写回
+                # 全量失败根因)。同 queId 即同字段,草稿优先(与正整数身份同
+                # 语义);同名不同 queId 的真实用户字段仍双候选保留,by_name 歧义
+                # 照常显式拒绝(存量脏形态不消歧,禁止静默取第一个)。
+                if raw_id in seen:
                     continue
-                seen.add(que_id)
+                seen.add(raw_id)
             merged.append(item)
         return merged, (draft_form or published_form)
 

package/src/qingflow_mcp/builder_facade/models.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import re
 from enum import Enum
-from typing import Any, Union
+from typing import Any, Literal, Union
 
 from pydantic import AliasChoices, Field, model_validator
 
@@ -2508,14 +2508,17 @@ class PortalInlineChartPatch(ChartUpsertPatch):
 
 
 class PortalComponentPositionPatch(StrictModel):
-    pc_x: int = Field(default=0, validation_alias=AliasChoices("pc_x", "pcX", "x"))
-    pc_y: int = Field(default=0, validation_alias=AliasChoices("pc_y", "pcY", "y"))
-    pc_w: int = Field(default=12, validation_alias=AliasChoices("pc_w", "pcW", "w"))
-    pc_h: int = Field(default=8, validation_alias=AliasChoices("pc_h", "pcH", "h"))
-    mobile_x: int = Field(default=0, validation_alias=AliasChoices("mobile_x", "mobileX"))
-    mobile_y: int = Field(default=0, validation_alias=AliasChoices("mobile_y", "mobileY"))
-    mobile_w: int = Field(default=6, validation_alias=AliasChoices("mobile_w", "mobileW"))
-    mobile_h: int = Field(default=8, validation_alias=AliasChoices("mobile_h", "mobileH"))
+    # 后端语义(DashSvcImpl 读/写链):position 各坐标可为 null——生产数据中筛选组件
+    # (type=6)的 x/y/cols/rows 原生为 NULL,读面透传 null、写链 setPosition 直存 null。
+    # 因此显式 null 必须原样透传(round-trip 保真);仅键缺省时才回落布局默认值。
+    pc_x: int | None = Field(default=0, validation_alias=AliasChoices("pc_x", "pcX", "x"))
+    pc_y: int | None = Field(default=0, validation_alias=AliasChoices("pc_y", "pcY", "y"))
+    pc_w: int | None = Field(default=12, validation_alias=AliasChoices("pc_w", "pcW", "w"))
+    pc_h: int | None = Field(default=8, validation_alias=AliasChoices("pc_h", "pcH", "h"))
+    mobile_x: int | None = Field(default=0, validation_alias=AliasChoices("mobile_x", "mobileX"))
+    mobile_y: int | None = Field(default=0, validation_alias=AliasChoices("mobile_y", "mobileY"))
+    mobile_w: int | None = Field(default=6, validation_alias=AliasChoices("mobile_w", "mobileW"))
+    mobile_h: int | None = Field(default=8, validation_alias=AliasChoices("mobile_h", "mobileH"))
     mobile_provided: bool = Field(default=False, exclude=True)
 
     @model_validator(mode="before")
@@ -2554,6 +2557,10 @@ class PortalChartRefPatch(StrictModel):
     app_key: str | None = None
     chart_id: str | None = None
     chart_name: str | None = None
+    # 引用面判别:后端有两类图表组件——轻流报表(DASH_CONTENT_TYPE_CHART=1,chart 表唯一键
+    # chartKey,写链 addChartInfos 按 chartKey 解析)与轻析 BI 报表(DASH_CONTENT_TYPE_BICHART=9,
+    # bi_chart 表整型 chart_id,写链 addBiChartInfo 直存)。缺省 bi_chart(向后兼容既有声明)。
+    ref_kind: Literal["chart", "bi_chart"] | None = None
 
     @model_validator(mode="before")
     @classmethod
@@ -2573,12 +2580,18 @@ class PortalChartRefPatch(StrictModel):
             payload["chart_name"] = payload.pop("name")
         if "appKey" in payload and "app_key" not in payload:
             payload["app_key"] = payload.pop("appKey")
+        if "refKind" in payload and "ref_kind" not in payload:
+            payload["ref_kind"] = payload.pop("refKind")
+        if "kind" in payload and "ref_kind" not in payload:
+            payload["ref_kind"] = payload.pop("kind")
         return payload
 
     @model_validator(mode="after")
     def validate_target(self) -> "PortalChartRefPatch":
         if not (self.chart_id or self.chart_name):
             raise ValueError("chart_ref requires chart_id or chart_name")
+        if self.ref_kind == "chart" and not self.chart_id:
+            raise ValueError("chart_ref with ref_kind=chart requires chart_id (chart 表唯一键 chartKey)")
         if self.chart_name and not self.chart_id and not self.app_key:
             raise ValueError("chart_ref.app_key is required when resolving by chart_name")
         return self
@@ -2604,17 +2617,49 @@ class PortalViewRefPatch(StrictModel):
 
 
 class PortalSectionPatch(StrictModel):
-    title: str
+    # title 语义=组件显示标题(draft_dash_chart.component_title / grid_config.gridTitle 等),
+    # 生产存量存在空标题形态(显示标题开但标题空,读链回退视图名/图表名)——None=不设标题,
+    # 编译对 None 不落库(后端透传 NULL),round-trip 保真;手写声明缺省 title=None(不设)。
+    title: str | None = None
     source_type: str = Field(validation_alias=AliasChoices("source_type", "sourceType"))
     role: str | None = Field(default=None, validation_alias=AliasChoices("role", "zone", "section_role", "sectionRole"))
+    # 显示标题开关(draft_dash_chart.being_show_title):提取侧读面必有值(True/False);
+    # 声明缺省 None 时编译回落产品默认 True(与既有创建语义兼容)。
+    show_title: bool | None = Field(
+        default=None,
+        validation_alias=AliasChoices("show_title", "showTitle", "being_show_title", "beingShowTitle"),
+    )
     position: PortalComponentPositionPatch | None = None
-    dash_style_config: dict[str, Any] | None = Field(default=None, validation_alias=AliasChoices("dash_style_config", "dashStyleConfigBO"))
+    dash_style_config: dict[str, Any] | None = Field(
+        default=None,
+        validation_alias=AliasChoices("dash_style_config", "style_config", "dashStyleConfigBO", "dashStyleConfig"),
+    )
     config: dict[str, Any] = Field(default_factory=dict)
     chart_ref: PortalChartRefPatch | None = None
     chart: PortalInlineChartPatch | None = Field(default=None, validation_alias=AliasChoices("chart", "inline_chart", "inlineChart", "create_chart", "createChart"))
     view_ref: PortalViewRefPatch | None = None
+    view_display: dict[str, Any] | None = Field(
+        default=None,
+        validation_alias=AliasChoices("view_display", "viewDisplay"),
+    )
     text: str | None = None
     url: str | None = None
+    login_auth: bool | None = Field(
+        default=None,
+        validation_alias=AliasChoices("login_auth", "loginAuth", "being_login_auth", "beingLoginAuth"),
+    )
+    carousel: dict[str, Any] | None = Field(
+        default=None,
+        validation_alias=AliasChoices("carousel", "carousel_config", "carouselConfig"),
+    )
+    task: dict[str, Any] | None = Field(
+        default=None,
+        validation_alias=AliasChoices("task", "task_config", "taskConfig"),
+    )
+    favourite: dict[str, Any] | None = Field(
+        default=None,
+        validation_alias=AliasChoices("favourite", "favourite_config", "favouriteConfig"),
+    )
 
     @model_validator(mode="before")
     @classmethod
@@ -2659,7 +2704,7 @@ class PortalSectionPatch(StrictModel):
 
     @model_validator(mode="after")
     def validate_shape(self) -> "PortalSectionPatch":
-        supported = {"chart", "view", "grid", "filter", "text", "link"}
+        supported = {"chart", "view", "grid", "filter", "text", "link", "carousel", "task", "favourite"}
         if self.source_type not in supported:
             raise ValueError(f"unsupported portal source_type '{self.source_type}'")
         if self.source_type == "chart" and self.chart_ref is None and self.chart is None:
@@ -2670,6 +2715,12 @@ class PortalSectionPatch(StrictModel):
             raise ValueError("text section requires text")
         if self.source_type == "link" and self.url is None:
             raise ValueError("link section requires url")
+        if self.source_type == "carousel" and self.carousel is None:
+            raise ValueError("carousel section requires carousel")
+        if self.source_type == "task" and self.task is None:
+            raise ValueError("task section requires task")
+        if self.source_type == "favourite" and self.favourite is None:
+            raise ValueError("favourite section requires favourite")
         return self
 
 
@@ -2685,8 +2736,20 @@ class PortalApplyRequest(StrictModel):
     icon: str | None = None
     color: str | None = None
     hide_copyright: bool | None = Field(default=None, validation_alias=AliasChoices("hide_copyright", "hideCopyright"))
-    dash_global_config: dict[str, Any] | None = Field(default=None, validation_alias=AliasChoices("dash_global_config", "dashGlobalConfig"))
+    global_config: dict[str, Any] | None = Field(
+        default=None,
+        validation_alias=AliasChoices("global_config", "globalConfig", "dash_global_config", "dashGlobalConfig"),
+    )
+    style_template_id: int | None = Field(
+        default=None,
+        validation_alias=AliasChoices("style_template_id", "styleTemplateId"),
+    )
+    overall_style: dict[str, Any] | None = Field(
+        default=None,
+        validation_alias=AliasChoices("overall_style", "overallStyle", "overallConfigBO"),
+    )
     config: dict[str, Any] = Field(default_factory=dict)
+    schema_version: str | None = Field(default=None, validation_alias=AliasChoices("schema_version", "schemaVersion"))
 
     @model_validator(mode="before")
     @classmethod
@@ -2694,8 +2757,14 @@ class PortalApplyRequest(StrictModel):
         if not isinstance(value, dict):
             return value
         payload = dict(value)
+        payload.pop("schema_version", None)
+        payload.pop("schemaVersion", None)
         if "dash_name" not in payload and "dashName" not in payload and "name" in payload:
             payload["dash_name"] = payload.pop("name")
+        if "dash_global_config" in payload and "global_config" not in payload:
+            payload["global_config"] = payload.pop("dash_global_config")
+        elif "dashGlobalConfig" in payload and "global_config" not in payload:
+            payload["global_config"] = payload.pop("dashGlobalConfig")
         if "sections" not in payload and "pages" in payload:
             pages = payload.pop("pages")
             if not isinstance(pages, list):
@@ -2730,6 +2799,88 @@ class PortalApplyRequest(StrictModel):
         return self
 
 
+def _public_portal_section_payload(section: PortalSectionPatch) -> dict[str, Any]:
+    """Dump one portal section with canonical naming for schema validation."""
+    payload: dict[str, Any] = {
+        "title": section.title,
+        "source_type": section.source_type,
+    }
+    if section.role is not None:
+        payload["role"] = section.role
+    if section.position is not None:
+        payload["position"] = {
+            "pc": {
+                "x": section.position.pc_x,
+                "y": section.position.pc_y,
+                "cols": section.position.pc_w,
+                "rows": section.position.pc_h,
+            },
+        }
+        if section.position.mobile_provided:
+            payload["position"]["mobile"] = {
+                "x": section.position.mobile_x,
+                "y": section.position.mobile_y,
+                "cols": section.position.mobile_w,
+                "rows": section.position.mobile_h,
+            }
+    if section.dash_style_config is not None:
+        payload["style_config"] = section.dash_style_config
+    if section.chart_ref is not None:
+        payload["chart_ref"] = section.chart_ref.model_dump(mode="json", exclude_none=True)
+    if section.chart is not None:
+        payload["chart"] = section.chart.model_dump(mode="json", exclude_none=True)
+    if section.view_ref is not None:
+        payload["view_ref"] = section.view_ref.model_dump(mode="json", exclude_none=True)
+    if section.view_display is not None:
+        payload["view_display"] = section.view_display
+    if section.text is not None:
+        payload["text"] = section.text
+    if section.url is not None:
+        payload["url"] = section.url
+    if section.login_auth is not None:
+        payload["login_auth"] = section.login_auth
+    if section.carousel is not None:
+        payload["carousel"] = section.carousel
+    if section.task is not None:
+        payload["task"] = section.task
+    if section.favourite is not None:
+        payload["favourite"] = section.favourite
+    if section.config:
+        payload["config"] = section.config
+    return payload
+
+
+def public_portal_apply_payload(request: PortalApplyRequest) -> dict[str, Any]:
+    """Canonical-named portal declaration used for schema validation."""
+    payload: dict[str, Any] = {}
+    if request.dash_key:
+        payload["dash_key"] = request.dash_key
+    if request.dash_name is not None:
+        payload["name"] = request.dash_name
+    if request.package_tag_id is not None:
+        payload["package_tag_id"] = request.package_tag_id
+    payload["publish"] = request.publish
+    if request.sections is not None:
+        payload["sections"] = [_public_portal_section_payload(section) for section in request.sections]
+    if request.layout_preset is not None:
+        payload["layout_preset"] = request.layout_preset
+    if request.visibility is not None:
+        payload["visibility"] = request.visibility.model_dump(mode="json", exclude_none=True)
+    if request.icon is not None:
+        payload["icon"] = request.icon
+    if request.color is not None:
+        payload["color"] = request.color
+    if request.hide_copyright is not None:
+        payload["hide_copyright"] = request.hide_copyright
+    if request.global_config is not None:
+        payload["global_config"] = request.global_config
+    if request.style_template_id is not None:
+        payload["style_template_id"] = request.style_template_id
+    if request.overall_style is not None:
+        payload["overall_style"] = request.overall_style
+    return payload
+
+
 FieldPatch.model_rebuild()
 FieldMutation.model_rebuild()
 FieldUpdatePatch.model_rebuild()