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

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

@@ -0,0 +1,800 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qingflow.com/schemas/builder/portals/v1alpha1/summary.json",
+  "title": "Qingflow Builder Portals Declaration · summary (v1alpha1)",
+  "portalSummaryDescription": "门户最小声明(最简版 spec):门户名称 + 布局 + 组件清单(sections)。创建一个可用门户的最小字段集;门户全局配置/组件明细/可见性授权通过 portal_schema 传 schema_kind=complete 获取完整声明(CLI: builder portal schema --schema-kind complete)。除必填项外全部可选,缺省走后端默认。PC 为 24 列网格、mobile 为 6 列网格。组件引用使用后端唯一键(chart_id/view_key),不依赖显示名。schema 校验在别名归一之后执行,JSON Schema 只约束规范名(别名见各字段说明)。",
+  "$defs": {
+    "PortalDeclaration": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "sections"
+      ],
+      "properties": {
+        "dash_key": {
+          "type": "string",
+          "dashKeyDescription": "门户唯一键;upsert 锁定已有门户(存在即更新)。缺省为创建模式,创建必须给 package_tag_id。别名 dashKey。",
+          "x-backend": "dash.dashKey"
+        },
+        "name": {
+          "type": "string",
+          "portalNameDescription": "门户名称。别名 dash_name/dashName。 可为空串(后端无非空校验,生产存量存在空名门户;提取产物空名透传)。",
+          "x-backend": "dash.dashName"
+        },
+        "package_tag_id": {
+          "type": "integer",
+          "minimum": 1,
+          "packageTagIdDescription": "归属应用包 tagId;创建必填(缺 dash_key 时),更新缺省沿用读面归属。别名 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",
+          "sectionsDescription": "组件清单;数组顺序即渲染顺序,提交即整体替换(replace 语义)。局部更新走 CLI 兼容参数 --patch-sections-file 或 complete 档。 空数组合法(空门户:updateDash 对空组件列表仅跳过组件重建,全局配置仍生效)。",
+          "items": {
+            "$ref": "#/$defs/Section"
+          },
+          "x-backend": "DashDetailInfo.components"
+        },
+        "layout_preset": {
+          "type": "string",
+          "enum": [
+            "auto",
+            "dashboard_2col",
+            "dashboard_3col"
+          ],
+          "layoutPresetDescription": "布局预设;sections 未显式给 position 时按预设自动排布(业务入口→指标卡→BI 图表→数据视图)。与显式 position 二选一,同用时 position 优先。别名 layoutPreset。",
+          "x-backend": "(编排层,不落库)"
+        },
+        "publish": {
+          "type": "boolean",
+          "default": true,
+          "publishDescription": "apply 后是否发布(true=写后发布并回读线上态;false=仅落草稿)。这是生命周期动作参数,不属于声明内容,幂等重放时用 false。",
+          "x-backend": "POST /dash/{dashKey}/publish"
+        }
+      }
+    },
+    "Section": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "source_type"
+      ],
+      "sectionSummaryDescription": "门户组件(summary 档限五类稳定类型:chart/view/grid/text/link)。carousel/task/favourite/filter 见 complete 档。",
+      "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",
+            "text",
+            "link"
+          ],
+          "sourceTypeSummaryDescription": "组件类型。每种类型的详细配置经专项 Schema 获取(CLI: qingflow builder portal schema --schema-kind <类型>;MCP: portal_schema(schema_kind=...)),不要凭枚举名猜配置键。summary 档限五类稳定类型:chart(报表,qingflow builder portal schema --schema-kind chart)、view(数据视图,--schema-kind view)、grid(业务入口宫格,--schema-kind grid)、text(文本,--schema-kind text)、link(链接,--schema-kind link);carousel/task/favourite/filter 见 complete 档与对应专项 Schema。别名归一:大小写不敏感。后端 type 整数:chart=1/view=10/grid=2/text=5/link=4。",
+          "x-backend": "DashComponentInfo.type"
+        },
+        "role": {
+          "type": "string",
+          "roleDescription": "组件角色标注(编排辅助,如 metric=指标卡);影响布局预设的排布与行高约定(指标卡 rows=5/BI 图表 rows=7/数据视图 rows=11)。别名 zone/section_role。"
+        },
+        "position": {
+          "$ref": "#/$defs/Position",
+          "positionSummaryDescription": "网格位置;省略时走 layout_preset 自动排布。"
+        },
+        "chart_ref": {
+          "$ref": "#/$defs/ChartRef",
+          "chartRefSummaryDescription": "引用已存在的 QingBI 图表(chart 类型必填 chart_ref 或 chart 二选一)。"
+        },
+        "chart": {
+          "$ref": "#/$defs/InlineChart",
+          "chartInlineSummaryDescription": "内联创建 QingBI 图表(chart 类型);同一 apply 内 app_key+name+chart_type 相同且配置一致的多个区块复用同一图表,配置不同则拒绝写入。别名 inline_chart/create_chart。"
+        },
+        "view_ref": {
+          "$ref": "#/$defs/ViewRef",
+          "viewRefSummaryDescription": "引用业务视图(view 类型必填)。优先用具体业务视图,不要用「全部数据/我的数据」系统视图。"
+        },
+        "config": {
+          "$ref": "#/$defs/GridConfig",
+          "configSummaryDescription": "grid 类型的宫格配置(必填且 items 非空);其余类型 summary 档不使用 config。"
+        },
+        "text": {
+          "type": "string",
+          "textSummaryDescription": "文本内容(text 类型必填)。",
+          "x-backend": "ComponentTextConfig.content"
+        },
+        "url": {
+          "type": "string",
+          "maxLength": 500,
+          "urlSummaryDescription": "链接地址(link 类型必填),长度上限 500。",
+          "x-backend": "ComponentLinkConfig.linkUrl"
+        }
+      },
+      "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": "text"
+              }
+            },
+            "required": [
+              "source_type"
+            ]
+          },
+          "then": {
+            "required": [
+              "text"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "source_type": {
+                "const": "link"
+              }
+            },
+            "required": [
+              "source_type"
+            ]
+          },
+          "then": {
+            "required": [
+              "url"
+            ]
+          }
+        }
+      ]
+    },
+    "Position": {
+      "type": "object",
+      "additionalProperties": false,
+      "positionDescription": "网格位置。PC 是 24 列网格(cols≤24),mobile 是 6 列网格(cols≤6);同行组件共享同一 y 与 rows,一行 cols 合计 24。mobile 可省略(缺省与 pc 同布局)。平铺别名 pc_x/pc_y/pc_w/pc_h、mobile_x/…/mobile_h 也接受,归一为本结构。标准行高:指标卡 rows=5、BI 图表 rows=7、数据视图 rows=11、业务入口 rows=4。",
+      "properties": {
+        "pc": {
+          "$ref": "#/$defs/PositionDetail"
+        },
+        "mobile": {
+          "$ref": "#/$defs/PositionDetail"
+        }
+      }
+    },
+    "PositionDetail": {
+      "type": "object",
+      "additionalProperties": false,
+      "positionDetailDescription": "单端位置: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"
+    },
+    "ChartRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "chartRefDescription": "已有图表引用。chart_id 或 chart_name 至少一个;按 chart_name 解析时必须给 app_key。别名 chartId/chart_key/chartKey。",
+      "properties": {
+        "app_key": {
+          "type": "string",
+          "chartRefAppKeyDescription": "图表所属应用 key。别名 appKey。",
+          "x-backend": "DashChartInfo(appKey 解析)"
+        },
+        "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",
+          "chartRefIdDescription": "图表 id(后端唯一键,回读优先携带)。别名 chartId/chart_key/chartKey。",
+          "x-backend": "DashComponentInfo.dashChartId"
+        },
+        "chart_name": {
+          "type": "string",
+          "chartRefNameDescription": "图表名称(按名解析时的定位键)。别名 chartName/name。"
+        }
+      }
+    },
+    "ViewRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "app_key"
+      ],
+      "viewRefDescription": "业务视图引用。view_key 或 view_name 至少一个;view_key 为后端唯一键,优先使用。",
+      "properties": {
+        "app_key": {
+          "type": "string",
+          "viewRefAppKeyDescription": "视图所属应用 key。别名 appKey。",
+          "x-backend": "ComponentViewConfig(viewgraphKey 解析)"
+        },
+        "view_key": {
+          "type": "string",
+          "viewRefKeyDescription": "视图唯一键(viewgraphKey)。别名 viewKey。"
+        },
+        "view_name": {
+          "type": "string",
+          "viewRefNameDescription": "视图名称(按名解析,重名有歧义风险)。别名 viewName。"
+        }
+      }
+    },
+    "InlineChart": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "app_key",
+        "name",
+        "chart_type"
+      ],
+      "inlineChartDescription": "内联创建的 QingBI 图表(创建后复用其 chart_id,等价于引用既有图表)。指标卡场景用 chart_type=target/indicator 且区块 rows=5。",
+      "properties": {
+        "app_key": {
+          "type": "string",
+          "inlineChartAppKeyDescription": "图表所属应用 key。"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "inlineChartNameDescription": "图表名称(同 apply 内去重键之一)。"
+        },
+        "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"
+          ],
+          "inlineChartTypeDescription": "图表类型(与 builder chart apply 同一公开枚举)。"
+        },
+        "metric": {
+          "$ref": "#/$defs/ChartMetric",
+          "inlineChartMetricDescription": "主指标;字符串形态如 \"count(*)\"/\"sum(金额)\" 或对象形态。"
+        },
+        "metrics": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ChartMetric"
+          },
+          "inlineChartMetricsDescription": "多指标列表(多轴/组合图)。"
+        },
+        "group_by": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "inlineChartGroupByDescription": "分组字段(显示名列表)。"
+        },
+        "filters": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ChartFilterRule"
+          },
+          "inlineChartFiltersDescription": "图表数据过滤条件(单组 AND)。"
+        },
+        "dimension_field_ids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "inlineChartDimensionDescription": "维度字段 id 列表(透传图表契约)。"
+        },
+        "indicator_field_ids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "inlineChartIndicatorDescription": "指标字段 id 列表(透传图表契约)。"
+        },
+        "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": {
+      "inlineChartMetricShapeDescription": "聚合指标:字符串形态(如 \"count(*)\"、\"sum(金额)\",裸字段名默认 sum)或对象 {op, field_name, alias}。op 常用 count/sum/avg/max/min。",
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "op"
+          ],
+          "properties": {
+            "op": {
+              "type": "string",
+              "inlineChartMetricOpDescription": "聚合方式(count/sum/avg/max/min…)。别名 operation/agg/aggregate/aggregation。"
+            },
+            "field_name": {
+              "type": "string",
+              "inlineChartMetricFieldDescription": "聚合字段显示名;count(*) 时省略。别名 field/fieldName/name。"
+            },
+            "alias": {
+              "type": "string",
+              "inlineChartMetricAliasDescription": "指标别名(图例显示)。"
+            }
+          }
+        }
+      ]
+    },
+    "ChartFilterRule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "field_name"
+      ],
+      "chartFilterRuleDescription": "图表过滤规则。is_empty/not_empty 不带 values,其余 operator 必须带非空 values。别名 field/fieldName/name。",
+      "properties": {
+        "field_name": {
+          "type": "string"
+        },
+        "operator": {
+          "type": "string",
+          "enum": [
+            "eq",
+            "neq",
+            "in",
+            "contains",
+            "gte",
+            "lte",
+            "is_empty",
+            "not_empty",
+            "belongs_to"
+          ],
+          "default": "eq",
+          "chartFilterOperatorDescription": "比较符。别名 op。 belongs_to=成员/部门归属(后端 JUDGE_BELONG_TO=13,公式引擎全支持)。"
+        },
+        "values": {
+          "type": "array",
+          "chartFilterValuesDescription": "比较值列表;单值也可写作 value(归一为单元素 values)。"
+        }
+      }
+    },
+    "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"
+    },
+    "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-detail-query": {
+    "currentKind": "summary",
+    "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 回读。"
+    }
+  },
+  "x-qingflow-create-defaults": {
+    "createDefaultsDescription": "以下是 portal_apply 当前创建路径在相应片段完全省略时组装的后端值。default 和 x-qingflow-* 是契约注解,通用 JSON Schema 校验器不会自动填值。更新已有门户时 sections 是 replace 语义,不要把创建默认值当作现有值。",
+    "name": "未命名门户(仅当创建且未给 name 时)",
+    "visibility": {
+      "mode": "workspace",
+      "external_mode": "not"
+    },
+    "hide_copyright": false,
+    "global_config": {
+      "auto_refresh": false,
+      "interval": 60
+    },
+    "publish": true
+  },
+  "x-qingflow-capability-boundary": {
+    "contract": "仅列出 portal_apply 当前可写字段。",
+    "backendKnownUnsupported": {
+      "carousel_task_favourite": "后端 DashComponentInfo 支持 carousel(3)/task(8)/favourite(7) 组件,summary 档不开放;详细配置经 qingflow builder portal schema --schema-kind carousel|task|favourite 获取(complete 档承载)。",
+      "filter_component": "filter(6) 组件后端语义 raw/unstable,不进 summary;详细配置经 qingflow builder portal schema --schema-kind filter 获取(complete 档受控承载)。",
+      "watermark": "工作区水印(beingWatermark/watermarkConfig)是工作区级配置,不属于门户声明。",
+      "overall_style": "overallConfigBO/styleTemplateId 全局样式,见 complete 档(键集以 dataset 实测形态校准)。"
+    }
+  },
+  "examples": [
+    {
+      "name": "业务工作台",
+      "package_tag_id": 2030703,
+      "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_DEVICE",
+                "linkFormType": 1,
+                "title": "设备台账"
+              }
+            ]
+          }
+        },
+        {
+          "title": "设备总数",
+          "source_type": "chart",
+          "role": "metric",
+          "position": {
+            "pc": {
+              "x": 0,
+              "y": 4,
+              "cols": 6,
+              "rows": 5
+            }
+          },
+          "chart": {
+            "app_key": "APP_KEY_DEVICE",
+            "name": "设备总数",
+            "chart_type": "target",
+            "metric": "count(*)"
+          }
+        },
+        {
+          "title": "异常设备",
+          "source_type": "view",
+          "position": {
+            "pc": {
+              "x": 0,
+              "y": 9,
+              "cols": 24,
+              "rows": 11
+            }
+          },
+          "view_ref": {
+            "app_key": "APP_KEY_DEVICE",
+            "view_key": "VIEW_KEY_ABNORMAL_DEVICES"
+          }
+        }
+      ]
+    }
+  ]
+}