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

package/src/qingflow_mcp/builder_facade/schemas/portals/v1alpha1/complete.json

@@ -0,0 +1,1397 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qingflow.com/schemas/builder/portals/v1alpha1/complete.json",
+  "title": "Qingflow Builder Portals Declaration · complete (v1alpha1)",
+  "portalCompleteDescription": "门户完整声明(详细版 spec):summary 的超集,覆盖门户全局配置(图标/颜色/版权/自动刷新)、九类组件明细(chart/view/grid/filter/text/link/carousel/task/favourite)、组件级样式与可见性授权。字段集 = portal_apply 真正可写的字段集(以 ws40013 dataset 实测形态校准);后端读面运行态字段(收藏/编辑权限/水印等)不属于声明。PC 为 24 列网格、mobile 为 6 列网格。组件引用使用后端唯一键。schema 校验在别名归一之后执行,JSON Schema 只约束规范名(别名见各字段说明)。",
+  "$defs": {
+    "PortalDeclaration": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "sections"
+      ],
+      "portalCompleteTopDescription": "完整门户声明。sections 提交即整体替换(replace 语义);不带 sections 的 base-info 更新(仅名称/图标/授权/归属)走 edit 模式。",
+      "properties": {
+        "dash_key": {
+          "type": "string",
+          "dashKeyCompleteDescription": "门户唯一键;upsert 锁定已有门户。别名 dashKey。",
+          "x-backend": "dash.dashKey"
+        },
+        "name": {
+          "type": "string",
+          "portalNameCompleteDescription": "门户名称。别名 dash_name/dashName。 可为空串(后端无非空校验,生产存量存在空名门户;提取产物空名透传)。",
+          "x-backend": "dash.dashName"
+        },
+        "package_tag_id": {
+          "type": "integer",
+          "minimum": 1,
+          "packageTagIdCompleteDescription": "归属应用包 tagId;创建必填,更新缺省沿用读面归属。别名 packageTagId/package_id/packageId。 创建(无 dash_key)时必填——由 portal_apply 实现层校验(PACKAGE_TAG_REQUIRED + 包新增权限守卫);更新(带 dash_key)缺省沿用读面归属,无所属包的门户提取产物合法缺省本字段。",
+          "x-backend": "dash.tags[0].tagId(POST /dash/{dashKey}/baseInfo)"
+        },
+        "sections": {
+          "type": "array",
+          "sectionsCompleteDescription": "组件清单,replace 语义,数组顺序即渲染顺序。 空数组合法(空门户:updateDash 对空组件列表仅跳过组件重建,全局配置仍生效)。",
+          "items": {
+            "$ref": "#/$defs/Section"
+          },
+          "x-backend": "DashDetailInfo.components"
+        },
+        "layout_preset": {
+          "type": "string",
+          "enum": [
+            "auto",
+            "dashboard_2col",
+            "dashboard_3col"
+          ],
+          "layoutPresetCompleteDescription": "布局预设;与显式 position 二选一。别名 layoutPreset。",
+          "x-backend": "(编排层,不落库)"
+        },
+        "publish": {
+          "type": "boolean",
+          "default": true,
+          "publishCompleteDescription": "apply 后是否发布;幂等重放时用 false。"
+        },
+        "icon": {
+          "type": "string",
+          "portalIconCompleteDescription": "门户图标名(workspace icon 目录,如 view-grid);与 color 一起编码为 dashIcon。省略时按名称生成稳定默认图标。",
+          "x-backend": "dash.dashIcon(编码)"
+        },
+        "color": {
+          "type": "string",
+          "portalColorCompleteDescription": "门户图标底色(如 #2468F2);与 icon 一起编码为 dashIcon。",
+          "x-backend": "dash.dashIcon(编码)"
+        },
+        "hide_copyright": {
+          "type": "boolean",
+          "default": false,
+          "hideCopyrightCompleteDescription": "是否隐藏轻流 vi 版权标识。别名 hideCopyright。",
+          "x-backend": "dash.hideCopyright"
+        },
+        "global_config": {
+          "$ref": "#/$defs/GlobalConfig",
+          "globalConfigCompleteDescription": "门户全局功能配置(自动刷新/导出)。别名收敛 dash_global_config/dashGlobalConfig。"
+        },
+        "style_template_id": {
+          "type": "integer",
+          "styleTemplateIdCompleteDescription": "门户样式模板 id(样式模板体系,详见 DashStyleTemplateCtrl)。",
+          "x-backend": "dash.styleTemplateId"
+        },
+        "overall_style": {
+          "type": "object",
+          "overallStyleCompleteDescription": "门户全局样式(受控键集;键白名单以 ws40013 dataset 实测形态校准,未经校准的键会被拒绝)。别名 overallConfigBO。",
+          "x-backend": "DashDetailInfo.overallConfigBO(DashStyleConfigBO)"
+        },
+        "visibility": {
+          "$ref": "#/$defs/Visibility",
+          "visibilityCompleteDescription": "门户可见性与授权(对内可见范围 + 外部成员授权)。与 auth(裸后端形状)互斥;声明面统一走 visibility。"
+        }
+      }
+    },
+    "GlobalConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "globalConfigShapeDescription": "门户全局功能配置。省略整段时创建路径按 auto_refresh=false + interval=60。",
+      "properties": {
+        "auto_refresh": {
+          "type": "boolean",
+          "default": false,
+          "autoRefreshDescription": "门户是否自动刷新。别名 beingAutoRefresh。",
+          "x-backend": "dashGlobalConfig.beingAutoRefresh"
+        },
+        "interval": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 60,
+          "intervalDescription": "自动刷新间隔(分钟),默认 60。",
+          "x-backend": "dashGlobalConfig.interval"
+        },
+        "export": {
+          "type": "boolean",
+          "exportDescription": "是否支持导出。别名 beingExport。",
+          "x-backend": "dashGlobalConfig.beingExport"
+        }
+      },
+      "x-backend": "DashGlobalConfigInfo"
+    },
+    "Section": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "source_type"
+      ],
+      "sectionCompleteDescription": "门户组件(complete 档开放九类:chart/view/grid/filter/text/link/carousel/task/favourite)。filter 语义 raw/unstable,skill 不建议作为主自动化路径。",
+      "properties": {
+        "title": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "sectionTitleDescription": "组件显示标题。空标题(null)是合法存量形态(显示标题开但标题空,读链渲染时回退图表名/视图名);创建语义缺省建议显式命名。",
+          "x-backend": "组件标题(DashChartInfo.title / DashChartInfo.chartComponentTitle / gridConfig.gridTitle / componentTaskTitle 等;null 落库 NULL)"
+        },
+        "source_type": {
+          "type": "string",
+          "enum": [
+            "chart",
+            "view",
+            "grid",
+            "filter",
+            "text",
+            "link",
+            "carousel",
+            "task",
+            "favourite"
+          ],
+          "sourceTypeCompleteDescription": "组件类型(complete 档开放九类)。每种类型的详细配置经专项 Schema 获取(CLI: qingflow builder portal schema --schema-kind <类型>;MCP: portal_schema(schema_kind=...)),不要凭枚举名猜配置键:chart=1(--schema-kind chart)、grid=2(--schema-kind grid)、carousel=3(--schema-kind carousel)、link=4(--schema-kind link)、text=5(--schema-kind text)、filter=6(--schema-kind filter,语义 raw/unstable)、favourite=7(--schema-kind favourite)、task=8(--schema-kind task)、view=10(--schema-kind view)。",
+          "x-backend": "DashComponentInfo.type"
+        },
+        "role": {
+          "type": "string",
+          "roleCompleteDescription": "组件角色标注(编排辅助,如 metric)。别名 zone/section_role。"
+        },
+        "position": {
+          "$ref": "#/$defs/Position",
+          "positionCompleteDescription": "网格位置(pc 24 列/mobile 6 列)。"
+        },
+        "style_config": {
+          "type": "object",
+          "styleConfigCompleteDescription": "组件级样式(受控键集;键白名单以 dataset 实测形态校准)。别名 dash_style_config/dashStyleConfigBO。",
+          "x-backend": "DashComponentInfo.dashStyleConfigBO(DashStyleConfigBO)"
+        },
+        "chart_ref": {
+          "$ref": "#/$defs/ChartRef",
+          "chartRefCompleteDescription": "已有图表引用(chart 类型:chart_ref 或 chart 二选一)。"
+        },
+        "chart": {
+          "$ref": "#/$defs/InlineChart",
+          "chartInlineCompleteDescription": "内联创建 QingBI 图表(chart 类型)。"
+        },
+        "view_ref": {
+          "$ref": "#/$defs/ViewRef",
+          "viewRefCompleteDescription": "业务视图引用(view 类型必填)。"
+        },
+        "view_display": {
+          "$ref": "#/$defs/ViewDisplayConfig",
+          "viewDisplayCompleteDescription": "视图组件展示配置(view 类型可选)。"
+        },
+        "config": {
+          "configCompleteDescription": "类型化配置:grid→GridConfig;filter→FilterConfig;其余类型不使用本键(各类型有专用键)。",
+          "oneOf": [
+            {
+              "$ref": "#/$defs/GridConfig"
+            },
+            {
+              "$ref": "#/$defs/FilterConfig"
+            }
+          ]
+        },
+        "carousel": {
+          "$ref": "#/$defs/CarouselConfig",
+          "carouselCompleteDescription": "轮播组件配置(carousel 类型必填):绑定应用的图片轮播。"
+        },
+        "task": {
+          "$ref": "#/$defs/TaskConfig",
+          "taskCompleteDescription": "待办组件配置(task 类型必填)。"
+        },
+        "favourite": {
+          "$ref": "#/$defs/FavouriteConfig",
+          "favouriteCompleteDescription": "收藏组件配置(favourite 类型必填)。"
+        },
+        "text": {
+          "type": "string",
+          "textCompleteDescription": "文本内容(text 类型必填)。",
+          "x-backend": "ComponentTextConfig.content"
+        },
+        "url": {
+          "type": "string",
+          "maxLength": 500,
+          "urlCompleteDescription": "链接地址(link 类型必填),上限 500。",
+          "x-backend": "ComponentLinkConfig.linkUrl"
+        },
+        "login_auth": {
+          "type": "boolean",
+          "default": false,
+          "loginAuthCompleteDescription": "链接是否需要登录鉴权(link 类型可选)。别名 beingLoginAuth/being_login_auth。",
+          "x-backend": "ComponentLinkConfig.beingLoginAuth"
+        },
+        "show_title": {
+          "type": "boolean",
+          "showTitleShapeDescription": "显示标题开关(draft_dash_chart.being_show_title 落库列)。提取侧读面必有值;存量 false 必须保真(渲染语义依赖)。声明缺省时编译回落产品默认 true。",
+          "x-backend": "DashChart.beingShowTitle(chart/view 组件)"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "source_type": {
+                "const": "chart"
+              }
+            },
+            "required": [
+              "source_type"
+            ]
+          },
+          "then": {
+            "anyOf": [
+              {
+                "required": [
+                  "chart_ref"
+                ]
+              },
+              {
+                "required": [
+                  "chart"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "source_type": {
+                "const": "view"
+              }
+            },
+            "required": [
+              "source_type"
+            ]
+          },
+          "then": {
+            "required": [
+              "view_ref"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "source_type": {
+                "const": "grid"
+              }
+            },
+            "required": [
+              "source_type"
+            ]
+          },
+          "then": {
+            "required": [
+              "config"
+            ],
+            "properties": {
+              "config": {
+                "required": [
+                  "items"
+                ],
+                "properties": {
+                  "items": {}
+                }
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "source_type": {
+                "const": "filter"
+              }
+            },
+            "required": [
+              "source_type"
+            ]
+          },
+          "then": {
+            "required": [
+              "config"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "source_type": {
+                "const": "text"
+              }
+            },
+            "required": [
+              "source_type"
+            ]
+          },
+          "then": {
+            "required": [
+              "text"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "source_type": {
+                "const": "link"
+              }
+            },
+            "required": [
+              "source_type"
+            ]
+          },
+          "then": {
+            "required": [
+              "url"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "source_type": {
+                "const": "carousel"
+              }
+            },
+            "required": [
+              "source_type"
+            ]
+          },
+          "then": {
+            "required": [
+              "carousel"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "source_type": {
+                "const": "task"
+              }
+            },
+            "required": [
+              "source_type"
+            ]
+          },
+          "then": {
+            "required": [
+              "task"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "source_type": {
+                "const": "favourite"
+              }
+            },
+            "required": [
+              "source_type"
+            ]
+          },
+          "then": {
+            "required": [
+              "favourite"
+            ]
+          }
+        }
+      ]
+    },
+    "Position": {
+      "type": "object",
+      "additionalProperties": false,
+      "positionShapeCompleteDescription": "网格位置。PC 是 24 列网格(cols≤24),mobile 是 6 列网格(cols≤6);mobile 可省略。平铺别名 pc_x/pc_y/pc_w/pc_h、mobile_* 也接受。",
+      "properties": {
+        "pc": {
+          "$ref": "#/$defs/PositionDetail"
+        },
+        "mobile": {
+          "$ref": "#/$defs/PositionDetail"
+        }
+      }
+    },
+    "PositionDetail": {
+      "type": "object",
+      "additionalProperties": false,
+      "positionDetailCompleteDescription": "单端位置:x=列偏移、y=行偏移、cols=占宽、rows=占高。",
+      "properties": {
+        "x": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "y": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "cols": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 1
+        },
+        "rows": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 1
+        }
+      },
+      "x-backend": "DashPosition.pc / DashPosition.mobile"
+    },
+    "Visibility": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "mode"
+      ],
+      "visibilityShapeDescription": "门户可见性与授权(与视图 visibility 同源编译)。写出 visibility 时 mode 必填。mode=specific 时必须带 selectors;mode=everyone 时 external_mode 必须为 workspace;external_mode=specific 时必须带 external_selectors。整段省略时创建路径按 workspace + external_mode=not。",
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "mode": {
+                "const": "specific"
+              }
+            },
+            "required": [
+              "mode"
+            ]
+          },
+          "then": {
+            "required": [
+              "selectors"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "mode": {
+                "const": "everyone"
+              }
+            },
+            "required": [
+              "mode"
+            ]
+          },
+          "then": {
+            "required": [
+              "external_mode"
+            ],
+            "properties": {
+              "external_mode": {
+                "const": "workspace"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "external_mode": {
+                "const": "specific"
+              }
+            },
+            "required": [
+              "external_mode"
+            ]
+          },
+          "then": {
+            "required": [
+              "external_selectors"
+            ]
+          }
+        }
+      ],
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": [
+            "workspace",
+            "everyone",
+            "specific"
+          ],
+          "visibilityModeDescription": "对内可见:workspace=工作区可见,everyone=互联网公开(要求 external_mode=workspace),specific=指定成员/部门/角色。",
+          "x-backend": "dash.dashAuth(1/2/3)"
+        },
+        "selectors": {
+          "$ref": "#/$defs/VisibilitySelectors"
+        },
+        "external_mode": {
+          "type": "string",
+          "enum": [
+            "not",
+            "workspace",
+            "specific"
+          ],
+          "externalModeCompleteDescription": "外部成员授权:not=不开放,workspace=共享工作区全部外部联系人,specific=指定外部成员。别名 externalMode。",
+          "x-backend": "dash.externalAuth(NOT|WORKSPACE_ALL|SPECIFIC)"
+        },
+        "external_selectors": {
+          "$ref": "#/$defs/ExternalSelectors"
+        }
+      },
+      "x-backend": "MemberAuthInfoVO(DashDetailInfo.auth)"
+    },
+    "VisibilitySelectors": {
+      "type": "object",
+      "additionalProperties": false,
+      "selectorsCompleteDescription": "指定成员/部门/角色选择器;各列表都不是单独必填,空对象表示指定范围但尚未配置成员(合法形态)。与 views 声明的 selectors 键集同构。",
+      "properties": {
+        "member_uids": {
+          "type": "array",
+          "items": {
+            "type": "integer"
+          },
+          "memberUidsDescription": "成员 uid 列表(数字)。"
+        },
+        "member_emails": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "memberEmailsDescription": "成员邮箱列表。"
+        },
+        "member_names": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "memberNamesDescription": "成员姓名列表(重名有歧义风险,优先 uid/email)。"
+        },
+        "dept_ids": {
+          "type": "array",
+          "items": {
+            "type": "integer"
+          },
+          "deptIdsDescription": "部门 id 列表。"
+        },
+        "dept_names": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "deptNamesDescription": "部门名称列表。"
+        },
+        "role_ids": {
+          "type": "array",
+          "items": {
+            "type": "integer"
+          },
+          "roleIdsDescription": "角色 id 列表。"
+        },
+        "role_names": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "roleNamesDescription": "角色名称列表。"
+        },
+        "include_sub_departs": {
+          "type": "boolean",
+          "default": false,
+          "includeSubDepartsDescription": "dept 指定时是否包含子部门。"
+        }
+      }
+    },
+    "ExternalSelectors": {
+      "type": "object",
+      "additionalProperties": false,
+      "externalSelectorsCompleteDescription": "指定外部成员选择器(与 views 声明键集同构)。",
+      "properties": {
+        "member_ids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "externalMemberIdsDescription": "外部成员 id 列表。"
+        },
+        "member_emails": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "externalMemberEmailsDescription": "外部成员邮箱列表。"
+        },
+        "dept_ids": {
+          "type": "array",
+          "items": {
+            "type": "integer"
+          },
+          "externalDeptIdsDescription": "外部部门 id 列表。"
+        }
+      }
+    },
+    "ChartRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "chartRefShapeCompleteDescription": "已有图表引用。chart_id 或 chart_name 至少一个;按 chart_name 解析时必须给 app_key。别名 chartId/chart_key/chartKey。",
+      "properties": {
+        "app_key": {
+          "type": "string",
+          "chartRefAppKeyCompleteDescription": "图表所属应用 key。"
+        },
+        "ref_kind": {
+          "type": "string",
+          "enum": [
+            "chart",
+            "bi_chart"
+          ],
+          "chartRefKindDescription": "引用面判别:chart=轻流报表(chart 表唯一键 chartKey,后端组件 type=1,写链 addChartInfos 按 chartKey 解析);bi_chart=轻析 BI 报表(bi_chart 表整型 chart_id,后端组件 type=9)。缺省 bi_chart(向后兼容)。别名 refKind/kind。",
+          "x-backend": "DashComponentInfo.type ∈ {1, 9}"
+        },
+        "chart_id": {
+          "type": "string",
+          "chartRefIdCompleteDescription": "图表 id(后端唯一键,回读优先携带)。 ref_kind=chart 时为 chart 表唯一键 chartKey;ref_kind=bi_chart 时为 bi_chart 整型 chart_id。"
+        },
+        "chart_name": {
+          "type": "string",
+          "chartRefNameCompleteDescription": "图表名称。"
+        }
+      }
+    },
+    "ViewRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "app_key"
+      ],
+      "viewRefShapeCompleteDescription": "业务视图引用。view_key 或 view_name 至少一个。",
+      "properties": {
+        "app_key": {
+          "type": "string",
+          "viewRefAppKeyCompleteDescription": "视图所属应用 key。"
+        },
+        "view_key": {
+          "type": "string",
+          "viewRefKeyCompleteDescription": "视图唯一键(viewgraphKey)。"
+        },
+        "view_name": {
+          "type": "string",
+          "viewRefNameCompleteDescription": "视图名称(按名解析)。"
+        }
+      },
+      "x-backend": "ComponentViewConfig(appKey/viewgraphKey)"
+    },
+    "ViewDisplayConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "viewDisplayShapeDescription": "视图组件展示配置。",
+      "properties": {
+        "show_title": {
+          "type": "boolean",
+          "default": true,
+          "viewShowTitleDescription": "是否显示组件标题。别名 beingShowTitle。",
+          "x-backend": "ComponentViewConfig.beingShowTitle"
+        },
+        "component_title": {
+          "type": "string",
+          "componentTitleDescription": "组件标题文案;缺省沿用组件引用名。别名 componentTitle。",
+          "x-backend": "ComponentViewConfig.componentTitle"
+        }
+      }
+    },
+    "InlineChart": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "app_key",
+        "name",
+        "chart_type"
+      ],
+      "inlineChartShapeCompleteDescription": "内联创建的 QingBI 图表(与 builder chart apply 同一公开契约的子集)。",
+      "properties": {
+        "app_key": {
+          "type": "string",
+          "inlineChartAppKeyCompleteDescription": "图表所属应用 key。"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "inlineChartNameCompleteDescription": "图表名称。"
+        },
+        "chart_type": {
+          "type": "string",
+          "enum": [
+            "target",
+            "indicator",
+            "summary",
+            "pie",
+            "bar",
+            "columnar",
+            "line",
+            "table",
+            "detail",
+            "area",
+            "stacked_area",
+            "pct_stack_area",
+            "funnel",
+            "waterfall",
+            "gauge",
+            "heatmap",
+            "histogram",
+            "treemap",
+            "radar",
+            "stacked_bar",
+            "pct_stack_bar",
+            "stacked_column",
+            "pct_stack_col",
+            "scatter",
+            "ring",
+            "rose",
+            "dualaxes",
+            "map",
+            "timeline"
+          ],
+          "inlineChartTypeCompleteDescription": "图表类型。"
+        },
+        "metric": {
+          "$ref": "#/$defs/ChartMetric"
+        },
+        "metrics": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ChartMetric"
+          }
+        },
+        "group_by": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "filters": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ChartFilterRule"
+          }
+        },
+        "dimension_field_ids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "indicator_field_ids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "visibility": {
+          "$ref": "#/$defs/Visibility",
+          "inlineChartVisibilityCompleteDescription": "图表自身可见性(可选)。"
+        },
+        "chart_id": {
+          "type": "string",
+          "inlineChartChartIdDescription": "已有图表 id(引用形态;等价 chart_ref.chart_id)。"
+        },
+        "rows": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "inlineChartRowsDescription": "行字段(交叉表)。",
+          "x-backend": "ChartUpsertPatch.rows"
+        },
+        "columns": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "inlineChartColumnsDescription": "列字段(交叉表)。",
+          "x-backend": "ChartUpsertPatch.columns"
+        },
+        "question_config": {
+          "type": "array",
+          "inlineChartQuestionConfigDescription": "图表字段配置透传(chart apply 受控面)。",
+          "x-backend": "ChartUpsertPatch.questionConfig"
+        },
+        "user_config": {
+          "type": "array",
+          "inlineChartUserConfigDescription": "图表用户配置透传(chart apply 受控面)。",
+          "x-backend": "ChartUpsertPatch.userConfig"
+        },
+        "config": {
+          "type": "object",
+          "inlineChartConfigDescription": "图表 raw 配置透传(chart apply 受控面)。",
+          "x-backend": "ChartUpsertPatch.config"
+        },
+        "x_metric": {
+          "$ref": "#/$defs/ChartMetric",
+          "inlineChartXMetricDescription": "X 轴指标(散点等)。"
+        },
+        "y_metric": {
+          "$ref": "#/$defs/ChartMetric",
+          "inlineChartYMetricDescription": "Y 轴指标(散点等)。"
+        },
+        "left_metric": {
+          "$ref": "#/$defs/ChartMetric",
+          "inlineChartLeftMetricDescription": "左轴指标(双轴图)。"
+        },
+        "right_metric": {
+          "$ref": "#/$defs/ChartMetric",
+          "inlineChartRightMetricDescription": "右轴指标(双轴图)。"
+        },
+        "value_metric": {
+          "$ref": "#/$defs/ChartMetric",
+          "inlineChartValueMetricDescription": "值指标。"
+        },
+        "target_metric": {
+          "$ref": "#/$defs/ChartMetric",
+          "inlineChartTargetMetricDescription": "目标值指标。"
+        }
+      }
+    },
+    "ChartMetric": {
+      "chartMetricShapeCompleteDescription": "聚合指标:字符串形态(如 \"count(*)\"、\"sum(金额)\",裸字段名默认 sum)或对象 {op, field_name, alias}。",
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "op"
+          ],
+          "properties": {
+            "op": {
+              "type": "string"
+            },
+            "field_name": {
+              "type": "string"
+            },
+            "alias": {
+              "type": "string"
+            }
+          }
+        }
+      ]
+    },
+    "ChartFilterRule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "field_name"
+      ],
+      "chartFilterRuleCompleteDescription": "图表过滤规则;is_empty/not_empty 不带 values,其余必须带非空 values。",
+      "properties": {
+        "field_name": {
+          "type": "string"
+        },
+        "operator": {
+          "type": "string",
+          "enum": [
+            "eq",
+            "neq",
+            "in",
+            "contains",
+            "gte",
+            "lte",
+            "is_empty",
+            "not_empty",
+            "belongs_to"
+          ],
+          "default": "eq"
+        },
+        "values": {
+          "type": "array"
+        }
+      }
+    },
+    "GridConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "items"
+      ],
+      "gridConfigShapeDescription": "业务入口宫格配置;items 必须含真实条目,不接受空宫格。声明键与后端 ComponentGridInfo 键一致(camelCase):gridTitle/beingShowTitle/items。",
+      "properties": {
+        "gridTitle": {
+          "type": "string",
+          "gridTitleShapeDescription": "宫格标题(缺省用 section.title)。",
+          "x-backend": "ComponentGridInfo.gridTitle"
+        },
+        "beingShowTitle": {
+          "type": "boolean",
+          "default": true,
+          "gridShowTitleShapeDescription": "是否显示宫格标题。",
+          "x-backend": "ComponentGridInfo.beingShowTitle"
+        },
+        "items": {
+          "type": "array",
+          "gridItemsShapeDescription": "入口条目列表(ordinal 缺省按数组顺序)。 空数组合法(空入口宫格:后端建 grid 行、0 item 行,round-trip 保真)。",
+          "items": {
+            "$ref": "#/$defs/GridItem"
+          }
+        }
+      },
+      "x-backend": "ComponentGridInfo"
+    },
+    "FilterConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "filterConfigShapeDescription": "筛选组件配置(受控键集;filter 组件语义 raw/unstable,不建议作为主自动化路径)。graphs 为受影响的图表引用,rules 为筛选规则组(键集以 ws40013 dataset 实测形态定稿)。",
+      "properties": {
+        "graphs": {
+          "type": "array",
+          "filterGraphsDescription": "筛选作用的图表引用列表(chart_key/chart_name)。",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "chart_key": {
+                "type": "string"
+              },
+              "chart_name": {
+                "type": "string"
+              }
+            }
+          },
+          "x-backend": "ComponentFilter.graphList(GraphVO.graphKey/graphName)"
+        },
+        "rules": {
+          "type": "array",
+          "filterRulesDescription": "筛选规则组(受控透传;dataset 校准后开放规范键)。",
+          "x-backend": "ComponentFilter.filterConfig(List<FilterConfig>)"
+        }
+      }
+    },
+    "CarouselConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [],
+      "carouselShapeDescription": "轮播组件配置:绑定一个应用的记录流,按标题/图片/链接字段轮播展示。",
+      "properties": {
+        "source_app_key": {
+          "type": "string",
+          "carouselSourceAppDescription": "轮播数据源应用 key。 悬空轮播(源表已删,related_form_id NULL 存量形态)缺省合法:后端写链不写 relatedFormId,读面回空 sourceApp。",
+          "x-backend": "ComponentCarouselConfig.sourceApp(ComponentFormBaseInfo)"
+        },
+        "source_form_title": {
+          "type": "string",
+          "sourceFormTitleDescription": "源表标题(读面派生回填,写链不落库)。别名 sourceFormTitle。",
+          "x-backend": "ComponentCarouselConfig.sourceApp.formTitle(读面派生)"
+        },
+        "title_field": {
+          "type": "string",
+          "carouselTitleFieldDescription": "标题字段(显示名)。",
+          "x-backend": "ComponentCarouselConfig.titleQue(ComponentQueBaseInfo)"
+        },
+        "image_field": {
+          "type": "string",
+          "carouselImageFieldDescription": "图片字段(显示名,附件/图片类字段)。",
+          "x-backend": "ComponentCarouselConfig.imageQue"
+        },
+        "link_field": {
+          "type": "string",
+          "carouselLinkFieldDescription": "链接字段(显示名,点击轮播项跳转)。",
+          "x-backend": "ComponentCarouselConfig.linkQue"
+        },
+        "jump_mode": {
+          "type": "integer",
+          "carouselJumpModeDescription": "跳转方式。",
+          "x-backend": "ComponentCarouselConfig.jumpMode"
+        },
+        "scaling": {
+          "type": "boolean",
+          "carouselScalingDescription": "图片是否缩放填充。别名 beingScaling。",
+          "x-backend": "ComponentCarouselConfig.beingScaling"
+        },
+        "show_latest_limit": {
+          "type": "integer",
+          "minimum": 1,
+          "carouselShowLatestDescription": "只展示最新 N 条记录。",
+          "x-backend": "ComponentCarouselConfig.showLatestLimit"
+        },
+        "scroll_interval": {
+          "type": "integer",
+          "minimum": 1,
+          "carouselScrollIntervalDescription": "轮播滚动间隔(秒)。",
+          "x-backend": "ComponentCarouselConfig.scrollInterval"
+        },
+        "filters": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ChartFilterRule"
+          },
+          "carouselFiltersDescription": "数据源过滤条件(单组 AND)。",
+          "x-backend": "ComponentCarouselConfig.filterConfig(List<List<MatchRule>>)"
+        }
+      }
+    },
+    "TaskConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "taskShapeDescription": "待办组件配置。",
+      "properties": {
+        "show_title": {
+          "type": "boolean",
+          "default": true,
+          "taskShowTitleDescription": "是否显示待办标题。别名 beingShowTitle。",
+          "x-backend": "ComponentTaskConfig.beingShowTitle"
+        },
+        "hint": {
+          "type": "string",
+          "taskHintDescription": "待办提示文案。别名 componentTaskHint。",
+          "x-backend": "ComponentTaskConfig.componentTaskHint"
+        },
+        "show_hint": {
+          "type": "boolean",
+          "taskShowHintDescription": "是否显示提示。别名 beingShowHint。",
+          "x-backend": "ComponentTaskConfig.beingShowHint"
+        },
+        "enabled": {
+          "type": "boolean",
+          "taskEnabledDescription": "待办组件是否启用。别名 beingUsing。",
+          "x-backend": "ComponentTaskConfig.beingUsing"
+        },
+        "tasks": {
+          "type": "array",
+          "taskItemsDescription": "待办任务条目(键集以 dataset 实测形态定稿)。",
+          "x-backend": "ComponentTaskConfig.dashTaskConfigList(DashTaskConfig)"
+        }
+      }
+    },
+    "FavouriteConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "favouriteShapeDescription": "收藏组件配置。",
+      "properties": {
+        "show_title": {
+          "type": "boolean",
+          "default": true,
+          "favouriteShowTitleDescription": "是否显示收藏标题。别名 beingShowTitle。",
+          "x-backend": "ComponentFavouriteConfig.beingShowTitle"
+        },
+        "enabled": {
+          "type": "boolean",
+          "favouriteEnabledDescription": "收藏组件是否启用。别名 beingUsing。",
+          "x-backend": "ComponentFavouriteConfig.beingUsing"
+        },
+        "items": {
+          "type": "array",
+          "favouriteItemsDescription": "收藏条目(键集以 dataset 实测形态定稿)。",
+          "x-backend": "ComponentFavouriteConfig.items(ComponentFavouriteItemInfo)"
+        }
+      }
+    },
+    "GridItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "jumpMode",
+        "title"
+      ],
+      "gridItemShapeDescription": "单个入口条目。grid 的 config 声明键与后端 ComponentGridItemInfo 键一致(camelCase);Python 端 section.config 直接透传。",
+      "properties": {
+        "type": {
+          "type": "integer",
+          "gridItemTypeDescription": "入口类型:1=应用,2=门户,3=应用包,4=外链。",
+          "x-backend": "ComponentGridItemInfo.type"
+        },
+        "jumpMode": {
+          "type": "integer",
+          "gridJumpModeDescription": "跳转方式:1=应用内页,2=新页面。",
+          "x-backend": "ComponentGridItemInfo.jumpMode"
+        },
+        "linkAppKey": {
+          "type": "string",
+          "gridItemAppKeyDescription": "目标应用 key(type=1 时使用)。",
+          "x-backend": "ComponentGridItemInfo.linkAppKey"
+        },
+        "linkFormType": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "gridItemFormTypeDescription": "目标应用页面形态(type=1 时使用)。",
+          "x-backend": "ComponentGridItemInfo.linkFormType"
+        },
+        "linkDashKey": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "gridItemDashKeyDescription": "目标门户 key(type=2 时使用)。",
+          "x-backend": "ComponentGridItemInfo.linkDashKey"
+        },
+        "linkTagId": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "gridItemTagIdDescription": "目标应用包 tagId(type=3 时使用)。",
+          "x-backend": "ComponentGridItemInfo.linkTagId"
+        },
+        "linkUrl": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "maxLength": 500,
+          "gridItemUrlDescription": "外链地址(type=4 时使用)。",
+          "x-backend": "ComponentGridItemInfo.linkUrl"
+        },
+        "title": {
+          "type": "string",
+          "gridItemTitleDescription": "入口标题。",
+          "x-backend": "ComponentGridItemInfo.title"
+        },
+        "customTitle": {
+          "type": "string",
+          "gridItemCustomTitleDescription": "自定义标题(beingCustomTitle=true 时生效)。",
+          "x-backend": "ComponentGridItemInfo.customTitle"
+        },
+        "beingCustomTitle": {
+          "type": "boolean",
+          "default": false,
+          "gridItemCustomTitleSwitchDescription": "是否启用自定义标题。",
+          "x-backend": "ComponentGridItemInfo.beingCustomTitle"
+        },
+        "iconUrl": {
+          "type": "string",
+          "gridItemIconDescription": "入口图标 URL(可选,缺省按目标解析)。",
+          "x-backend": "ComponentGridItemInfo.iconUrl"
+        },
+        "ordinal": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "gridItemOrdinalDescription": "排序(缺省按数组顺序)。",
+          "x-backend": "ComponentGridItemInfo.ordinal"
+        }
+      }
+    }
+  },
+  "$ref": "#/$defs/PortalDeclaration",
+  "x-qingflow-config-sections": {
+    "sectionsDescription": "complete 声明按配置域组织;各域可整体省略,省略片段的语义见 x-qingflow-write-semantics。",
+    "sections": {
+      "identity": "name/package_tag_id/dash_key/publish。",
+      "layout": "sections[].position / layout_preset。",
+      "global": "icon/color/hide_copyright/global_config/style_template_id/overall_style。",
+      "components": "sections[](九类组件与类型化 config/style_config)。",
+      "authorization": "visibility(对内 + 外部成员授权)。"
+    }
+  },
+  "x-qingflow-related-schemas": {
+    "summary": "builder portal schema --schema-kind summary(CLI)/portal_schema(schema_kind=summary)。",
+    "views": "视图声明契约 builder views schema(视图组件引用的视图本体配置)。",
+    "charts": "图表声明契约 builder chart 面(内联图表引用的图表完整可写面)。"
+  },
+  "x-qingflow-write-semantics": {
+    "create": "省略的配置片段由 builder 组装创建默认值;JSON Schema 的 default 只是注解。",
+    "sections_replace": "提交 sections 即整体替换组件清单(replace);不带 sections 的 apply 为 base-info 更新(名称/图标/授权/归属)。",
+    "patch_compat": "局部更新走 CLI 兼容参数 --patch-sections-file(order/chart_ref.chart_id/view_ref.view_key 选择器 + set/unset);声明面收敛后由 complete 档承载。",
+    "readback": "apply 后自动回读草稿态(发布时另回读线上态)并做元数据校验;回读失败记 partial,不算成功也不算失败。",
+    "backend_warning": "底层 DashDetailInfo 更新接口对部分省略字段会执行默认初始化,不得把后端请求中的省略统一理解为保留。"
+  },
+  "x-qingflow-capability-boundary": {
+    "contract": "仅列出 portal_apply 真正可写的字段;键集以 ws40013 dataset 实测形态校准。",
+    "backendKnownUnsupported": {
+      "watermark": "工作区水印(beingWatermark/watermarkConfig)是工作区级配置,不属于门户写入契约。",
+      "publish_state": "publishStatus 由发布动作管理,不作为声明字段。",
+      "runtime_flags": "beingFavorite/editItemStatus/deleteItemStatus/componentStatus/dashCount 为读面运行态。",
+      "deprecated": "favouriteTagId 后端已 @Deprecated,不进契约。",
+      "filter_semantics": "filter 组件的语义化筛选 DSL(v1alpha2 候选);当前受控键集见 qingflow builder portal schema --schema-kind filter。",
+      "carousel_media": "轮播媒体明细超集(v1alpha2 候选,dataset 校准);当前键集见 qingflow builder portal schema --schema-kind carousel。"
+    }
+  },
+  "examples": [
+    {
+      "name": "运营门户",
+      "package_tag_id": 2030703,
+      "icon": "view-grid",
+      "color": "#2468F2",
+      "hide_copyright": true,
+      "global_config": {
+        "auto_refresh": true,
+        "interval": 120,
+        "export": true
+      },
+      "visibility": {
+        "mode": "specific",
+        "selectors": {
+          "member_names": [
+            "张三"
+          ],
+          "dept_names": [
+            "运维部"
+          ]
+        },
+        "external_mode": "not"
+      },
+      "sections": [
+        {
+          "title": "业务入口",
+          "source_type": "grid",
+          "position": {
+            "pc": {
+              "x": 0,
+              "y": 0,
+              "cols": 24,
+              "rows": 4
+            }
+          },
+          "config": {
+            "gridTitle": "业务入口",
+            "beingShowTitle": true,
+            "items": [
+              {
+                "type": 1,
+                "jumpMode": 1,
+                "linkAppKey": "APP_KEY_OPS",
+                "linkFormType": 1,
+                "title": "运维台账"
+              }
+            ]
+          }
+        },
+        {
+          "title": "告警趋势",
+          "source_type": "chart",
+          "position": {
+            "pc": {
+              "x": 0,
+              "y": 4,
+              "cols": 12,
+              "rows": 7
+            }
+          },
+          "chart": {
+            "app_key": "APP_KEY_OPS",
+            "name": "告警趋势",
+            "chart_type": "line",
+            "metric": "count(*)",
+            "group_by": [
+              "告警日期"
+            ]
+          }
+        },
+        {
+          "title": "最新公告",
+          "source_type": "carousel",
+          "position": {
+            "pc": {
+              "x": 12,
+              "y": 4,
+              "cols": 12,
+              "rows": 7
+            }
+          },
+          "carousel": {
+            "source_app_key": "APP_KEY_NOTICE",
+            "title_field": "公告标题",
+            "image_field": "封面图",
+            "link_field": "详情链接",
+            "show_latest_limit": 5,
+            "scroll_interval": 8
+          }
+        },
+        {
+          "title": "我的待办",
+          "source_type": "task",
+          "position": {
+            "pc": {
+              "x": 0,
+              "y": 11,
+              "cols": 12,
+              "rows": 8
+            }
+          },
+          "task": {
+            "show_title": true,
+            "enabled": true
+          }
+        },
+        {
+          "title": "处理工单",
+          "source_type": "view",
+          "position": {
+            "pc": {
+              "x": 0,
+              "y": 19,
+              "cols": 24,
+              "rows": 11
+            }
+          },
+          "view_ref": {
+            "app_key": "APP_KEY_OPS",
+            "view_key": "VIEW_KEY_PENDING"
+          },
+          "view_display": {
+            "show_title": true
+          }
+        },
+        {
+          "title": "帮助中心",
+          "source_type": "link",
+          "position": {
+            "pc": {
+              "x": 0,
+              "y": 30,
+              "cols": 24,
+              "rows": 4
+            }
+          },
+          "url": "https://help.example.com",
+          "login_auth": false
+        }
+      ]
+    }
+  ],
+  "x-qingflow-detail-query": {
+    "currentKind": "complete",
+    "tool": "portal_schema",
+    "cli": "qingflow builder portal schema --schema-kind KIND",
+    "argument": "schema_kind",
+    "kinds": [
+      "summary",
+      "complete",
+      "chart",
+      "view",
+      "grid",
+      "filter",
+      "text",
+      "link",
+      "carousel",
+      "task",
+      "favourite"
+    ],
+    "kindDescriptions": {
+      "summary": "门户名称 + 布局 + 组件清单(五类稳定组件类型)。",
+      "complete": "完整门户声明:全局配置 + 九类组件明细 + 可见性授权;summary 是它的最小子集。",
+      "chart": "报表组件:chart_ref 已有图表引用 / chart 内联创建(QingBI 全类型、指标、过滤、双轴)。",
+      "view": "数据视图组件:视图引用(view_key 优先)与组件展示配置。",
+      "grid": "业务入口宫格:入口条目(应用/门户/外链)、图标、自定义标题、排序。",
+      "filter": "筛选组件:作用图表与筛选规则组(语义 raw/unstable,不建议主自动化路径)。",
+      "text": "文本组件:富文本内容。",
+      "link": "链接组件:地址(≤500)与登录鉴权。",
+      "carousel": "轮播组件:数据源应用 + 标题/图片/链接字段绑定 + 滚动配置。",
+      "task": "待办组件:提示文案与任务条目。",
+      "favourite": "收藏组件:预置收藏条目。"
+    },
+    "detailQueryDescription": "每种组件类型的详细配置都有自包含专项 Schema:按需调用 portal_schema 传对应 schema_kind(CLI: qingflow builder portal schema --schema-kind chart|view|grid|filter|text|link|carousel|task|favourite);专项已内联其引用的定义,可独立交给 JSON Schema 校验器。",
+    "readSources": {
+      "chartIds": "已有图表用 chart 面读取 chart_id;内联创建则直接在 section.chart 声明。",
+      "viewKeys": "视图唯一键用 qingflow builder views get --app-key APP 回读。",
+      "existingPortal": "既有门户声明用 qingflow builder portal get --dash-key K --schema-kind summary|complete 回读。"
+    }
+  }
+}