@qingflow-tech/qingflow-cli 1.1.51 → 1.1.54

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

@@ -0,0 +1,1245 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qingflow.com/schemas/builder/views/v1alpha1/complete.json",
+  "title": "Qingflow Builder Views Declaration · complete (v1alpha1)",
+  "viewCompleteDescription": "视图完整声明(完整版 spec):summary 的严格超集,覆盖 app_views_apply 当前支持的公开语义——数据权限/可见性授权/筛选/排序/查询条件/按钮配置/关联资源/类型特有配置(card/gantt/hierarchy/calendar)/展示与记录开关/分享安全。展示、排序、筛选和类型专属字段使用整数 queId;查询条件 rows 兼容字段名或 ID。打印模板明细、附件权限、列级权限和高级筛选公式尚未进入公开写入契约。schema 校验在别名归一之后执行,只约束规范名。各配置域的专项 Schema(含清空/替换语义)通过 app_views_schema 换 schema_kind 获取(见 x-qingflow-related-schemas)。",
+  "$defs": {
+    "ViewDeclaration": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "type"
+      ],
+      "properties": {
+        "view_key": {
+          "type": "string",
+          "x-backend": "viewgraph.viewgraphKey",
+          "viewKeyDescription": "视图唯一键;upsert 锁定已有视图。"
+        },
+        "pinned": {
+          "type": "boolean",
+          "pinnedDescription": "是否固定在应用的视图列表顶部。true=固定，false=取消固定；省略时保持当前状态。别名 fixed/is_pinned/isPinned。它与 display.pin_navigate（视图内导航固定）无关。",
+          "x-backend": "POST /app/{appKey}/view/ordinal (FIXED_VIEW_LIST|VIEW_LIST)"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "viewNameDescription": "视图名称;未提供 view_key 时按 name 唯一匹配决定更新或创建,重名报 AMBIGUOUS_VIEW。",
+          "x-backend": "viewgraphName"
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "table",
+            "card",
+            "board",
+            "gantt",
+            "hierarchy",
+            "calendar"
+          ],
+          "viewTypeDescription": "支持表格、卡片、看板、甘特、层级和日历视图。",
+          "x-backend": "viewgraphType(tableView/cardView/boardView/ganttView/hierarchyView/calendarView)"
+        },
+        "columns": {
+          "type": "array",
+          "items": {
+            "type": "integer"
+          },
+          "columnsDescription": "数据展示内容:业务字段或已存在系统字段的 queId 列表(table/card 必填)。别名 fields/column_names/columnNames。",
+          "x-backend": "viewgraphQuestion + viewgraphQueIds;已知系统字段允许原样透传"
+        },
+        "data_permission": {
+          "$ref": "#/$defs/DataPermission",
+          "dataPermissionDescription": "数据权限形状;scope=custom 时规则=本声明 filters(编译为 viewgraphLimit)。"
+        },
+        "visibility": {
+          "$ref": "#/$defs/Visibility",
+          "visibilityDescription": "操作权限·可见性授权(对内可见范围 + 外部成员授权)。",
+          "x-backend": "auth(MemberAuthInfoVO)+ viewgraph_member;external → viewgraph.externalAuth(NOT|WORKSPACE_ALL|SPECIFIC)"
+        },
+        "filters": {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              {
+                "$ref": "#/$defs/FilterRule"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "$ref": "#/$defs/FilterRule"
+                },
+                "filtersDescription": "OR 组(组内 AND)"
+              }
+            ]
+          },
+          "filtersDescription": "数据筛选。扁平 [rule,...]=单组 AND;嵌套 [[rule,...],...]=组间 OR、组内 AND(与 visible_when/root_filter 嵌组形态对齐)。",
+          "x-backend": "viewgraphLimitType=1 + viewgraphLimit(List<List<MatchRule>> 单组);公式形态(scope=custom 的 OR 组)列 v1alpha2"
+        },
+        "sort": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/SortRule"
+          },
+          "sortDescription": "排序规则(多级);空数组=恢复默认排序。",
+          "x-backend": "viewgraphSorts(ViewgraphSortQuestion[])+ sortType=customSort(空→defaultSort)"
+        },
+        "query_conditions": {
+          "$ref": "#/$defs/QueryConditions",
+          "queryConditionsDescription": "查询条件(搜索区)配置。",
+          "x-backend": "queryCondition + queryConditionStatus/queryConditionExact/hideBeforeQueryCondition/showConditionTitle"
+        },
+        "action_buttons": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ActionButton"
+          },
+          "actionButtonsDescription": "系统按钮配置(add_data/link/qrobot/wings 触发器);visible_when 为按钮级操作权限条件。别名 actionButtons。",
+          "x-backend": "buttonConfigDTOList(SYSTEM 分支)"
+        },
+        "action_buttons_mode": {
+          "type": "string",
+          "enum": [
+            "merge",
+            "replace"
+          ],
+          "default": "merge",
+          "actionButtonsModeDescription": "按钮应用模式:merge=与现有合并,replace=全量替换。别名 actionButtonsMode/buttonMode。"
+        },
+        "buttons": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ButtonBinding"
+          },
+          "buttonsDescription": "自定义按钮绑定(引用 app 级自定义按钮并配置位置/样式/权限)。",
+          "x-backend": "buttonConfigDTOList(CUSTOM 分支)+ custom_button/mtm 关联"
+        },
+        "associated_resources": {
+          "$ref": "#/$defs/AssociatedResources",
+          "associatedResourcesDescription": "关联报表/图表资源。别名 associatedResources/associated_reports/asosChartConfig。",
+          "x-backend": "asosChartConfig + asosChartVisible + viewgraph_asos_chart"
+        },
+        "card": {
+          "$ref": "#/$defs/CardConfig",
+          "cardDescription": "卡片视图特有配置(card 类型适用)。",
+          "x-backend": "titleQue/frontCoverQueId/clippingMode/beingImageAdaption/beingShowQueTitle/beingShowTitleQue/beingShowCover/groupQueId/beingGroupColor"
+        },
+        "gantt": {
+          "$ref": "#/$defs/GanttConfig",
+          "ganttDescription": "甘特视图特有配置(gantt 类型适用;start/end_field 与此处的同名字段等价,取其一)。",
+          "x-backend": "viewgraphGanttConfigVO(titleQueId/startTimeQueId/endTimeQueId/defaultTimeDimension/ganttGroupVOList/ganttDependencyVO/ganttAutoCalibrationVO)"
+        },
+        "hierarchy": {
+          "$ref": "#/$defs/HierarchyConfig",
+          "hierarchyDescription": "层级视图特有配置(hierarchy 类型适用,必填)。",
+          "x-backend": "viewgraphHierarchyConfigVO(titleQueId/childrenQueId/rootNodeFilter)"
+        },
+        "calendar": {
+          "$ref": "#/$defs/CalendarConfig",
+          "calendarDescription": "日历视图特有配置(calendar 类型适用,必填)。",
+          "x-backend": "viewgraphCalendarConfigVO(titleQueId/dateQueId/colorQueId)"
+        },
+        "display": {
+          "$ref": "#/$defs/DisplayConfig",
+          "displayDescription": "展示杂项:行高/固定导航/备注。",
+          "x-backend": "defaultRowHigh/beingPinNavigate/remark"
+        },
+        "record": {
+          "$ref": "#/$defs/RecordConfig",
+          "recordDescription": "记录可见性开关:操作记录/数据日志/机器人记录/流程未来节点/留言。",
+          "x-backend": "beingAuditRecordVisible/beingDataLogVisible/beingQrobotRecordVisible/beingWorkflowNodeFutureListVisible/beingCommentStatus"
+        },
+        "share": {
+          "$ref": "#/$defs/ShareConfig",
+          "shareDescription": "分享与安全:密码/强制登录/打印。",
+          "x-backend": "beingNeedPass/viewgraphPass/beingForceLogin/beingPrintStatus"
+        },
+        "partial_update": {
+          "type": "boolean",
+          "default": false,
+          "partialUpdateDescription": "patch 语义开关(编排层;仅声明语义,不编译进后端 payload)。别名 partialUpdate。"
+        },
+        "preserve_filters": {
+          "type": "boolean",
+          "default": false,
+          "preserveFiltersDescription": "更新时保留现有筛选(编排层)。别名 preserveFilters。"
+        },
+        "preserve_buttons": {
+          "type": "boolean",
+          "default": false,
+          "preserveButtonsDescription": "更新时保留现有按钮(编排层)。别名 preserveButtons。"
+        },
+        "preserve_query_conditions": {
+          "type": "boolean",
+          "default": false,
+          "preserveQueryConditionsDescription": "更新时保留现有查询条件(编排层)。别名 preserveQueryConditions。"
+        },
+        "preserve_associated_resources": {
+          "type": "boolean",
+          "default": false,
+          "preserveAssociatedResourcesDescription": "更新时保留现有关联资源(编排层)。别名 preserveAssociatedResources。"
+        },
+        "group_que_id": {
+          "type": "integer",
+          "x-backend": "groupQueId",
+          "groupQueIdDescription": "看板分组字段 queId(board 必填)。"
+        },
+        "start_que_id": {
+          "type": "integer",
+          "x-backend": "viewgraphGanttConfigVO.startTimeQueId",
+          "startQueIdDescription": "甘特开始时间字段 queId(gantt 必填)。"
+        },
+        "end_que_id": {
+          "type": "integer",
+          "x-backend": "viewgraphGanttConfigVO.endTimeQueId",
+          "endQueIdDescription": "甘特结束时间字段 queId(gantt 必填)。"
+        },
+        "title_que_id": {
+          "type": "integer",
+          "x-backend": "titleQue",
+          "titleQueIdDescription": "卡片/看板/甘特/层级标题字段 queId(可选)。"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "table"
+              }
+            },
+            "required": [
+              "type"
+            ]
+          },
+          "then": {
+            "required": [
+              "columns"
+            ],
+            "properties": {
+              "columns": {
+                "minItems": 1
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "card"
+              }
+            },
+            "required": [
+              "type"
+            ]
+          },
+          "then": {
+            "required": [
+              "columns"
+            ],
+            "properties": {
+              "columns": {
+                "minItems": 1
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "board"
+              }
+            },
+            "required": [
+              "type"
+            ]
+          },
+          "then": {
+            "required": [
+              "group_que_id"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "gantt"
+              }
+            },
+            "required": [
+              "type"
+            ]
+          },
+          "then": {
+            "required": [
+              "start_que_id",
+              "end_que_id"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "hierarchy"
+              }
+            },
+            "required": [
+              "type"
+            ]
+          },
+          "then": {
+            "required": [
+              "hierarchy"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "calendar" } },
+            "required": ["type"]
+          },
+          "then": { "required": ["calendar"] }
+        }
+      ]
+    },
+    "DataPermission": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "config",
+            "custom"
+          ],
+          "default": "custom",
+          "dataPermissionDescription": "数据权限生效类型:config=跟随应用配置,custom=视图自定义。别名 dataPermissionType(CONFIG/CUSTOM)。",
+          "x-backend": "dataPermissionType(CONFIG|CUSTOM)"
+        },
+        "scope": {
+          "type": "string",
+          "enum": [
+            "all",
+            "oneself",
+            "dept",
+            "subordinate",
+            "custom"
+          ],
+          "default": "all",
+          "dataScopeDescription": "数据范围:all=全部数据,oneself=自己发起的,dept=所在部门的,subordinate=下属的,custom=自定义(规则见 filters)。",
+          "x-backend": "dataScope(ALL|ONESELF|DEPT|SUBORDINATE|CUSTOM)"
+        }
+      }
+    },
+    "Visibility": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": [
+            "workspace",
+            "everyone",
+            "specific"
+          ],
+          "modeDescription": "对内可见:workspace=工作区可见,everyone=互联网公开(要求 external_mode=workspace),specific=指定成员/部门/角色。",
+          "x-backend": "viewgraph.viewgraphAuth(1/2/3)"
+        },
+        "selectors": {
+          "$ref": "#/$defs/VisibilitySelectors"
+        },
+        "external_mode": {
+          "type": "string",
+          "enum": [
+            "not",
+            "workspace",
+            "specific"
+          ],
+          "externalModeDescription": "外部成员授权:not=不开放,workspace=共享工作区全部外部联系人,specific=指定外部成员。别名 externalMode。",
+          "x-backend": "viewgraph.externalAuth(NOT|WORKSPACE_ALL|SPECIFIC)"
+        },
+        "external_selectors": {
+          "$ref": "#/$defs/ExternalSelectors"
+        }
+      }
+    },
+    "VisibilitySelectors": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "member_uids": {
+          "type": "array",
+          "items": {
+            "type": "integer"
+          },
+          "x-backend": "viewgraph_member(uid)",
+          "memberUidsDescription": "成员 uid 列表。别名 memberUids。"
+        },
+        "member_emails": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "x-backend": "viewgraph_member(uid 经邮箱解析)",
+          "memberEmailsDescription": "成员邮箱列表。别名 memberEmails。"
+        },
+        "member_names": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "x-backend": "viewgraph_member(uid 经姓名解析)",
+          "memberNamesDescription": "成员姓名列表(需唯一匹配)。别名 memberNames。"
+        },
+        "dept_ids": {
+          "type": "array",
+          "items": {
+            "type": "integer"
+          },
+          "x-backend": "viewgraph_member(dept_id)",
+          "deptIdsDescription": "部门 id 列表。别名 deptIds。"
+        },
+        "dept_names": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "x-backend": "viewgraph_member(dept_id 经部门名解析)",
+          "deptNamesDescription": "部门名称列表(需唯一匹配)。别名 deptNames。"
+        },
+        "role_ids": {
+          "type": "array",
+          "items": {
+            "type": "integer"
+          },
+          "x-backend": "viewgraph_member(role_id)",
+          "roleIdsDescription": "角色 id 列表。别名 roleIds。"
+        },
+        "role_names": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "x-backend": "viewgraph_member(role_id 经角色名解析)",
+          "roleNamesDescription": "角色名称列表(需唯一匹配)。别名 roleNames。"
+        },
+        "include_sub_departs": {
+          "type": "boolean",
+          "includeSubDepartsDescription": "部门选择是否含下级部门。别名 includeSubDeparts。",
+          "x-backend": "viewgraph_member(havingSubDept)"
+        }
+      }
+    },
+    "ExternalSelectors": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "member_ids": {
+          "type": "array",
+          "items": {
+            "type": "integer"
+          },
+          "x-backend": "external_member_auth",
+          "memberIdsDescription": "外部成员 id 列表。别名 memberIds。"
+        },
+        "member_emails": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "x-backend": "external_member_auth(经邮箱解析)",
+          "memberEmailsDescription": "外部成员邮箱列表。"
+        },
+        "dept_ids": {
+          "type": "array",
+          "items": {
+            "type": "integer"
+          },
+          "x-backend": "external_member_auth(dept)",
+          "deptIdsDescription": "外部部门 id 列表。别名 deptIds。"
+        }
+      }
+    },
+    "FilterRule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "que_id"
+      ],
+      "properties": {
+        "operator": {
+          "type": "string",
+          "enum": [
+            "eq",
+            "neq",
+            "in",
+            "contains",
+            "gte",
+            "lte",
+            "is_empty",
+            "not_empty"
+          ],
+          "default": "eq",
+          "operatorDescription": "比较符(组内 AND)。别名 op。"
+        },
+        "values": {
+          "type": "array",
+          "items": true,
+          "default": [],
+          "valuesDescription": "比较值;is_empty/not_empty 时忽略。"
+        },
+        "que_id": {
+          "type": "integer",
+          "x-backend": "MatchRule.queId",
+          "queIdDescription": "字段 queId。别名 fieldName/field/name。"
+        }
+      }
+    },
+    "SortRule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "que_id"
+      ],
+      "properties": {
+        "ascending": {
+          "type": "boolean",
+          "default": true,
+          "ascendingDescription": "是否升序;默认 true。",
+          "x-backend": "beingSortAscend"
+        },
+        "que_id": {
+          "type": "integer",
+          "queIdDescription": "排序字段 queId。别名 fieldName/field/name。",
+          "x-backend": "ViewgraphSortQuestion.queId"
+        }
+      }
+    },
+    "QueryConditions": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "enabledDescription": "是否开启查询面板。",
+          "x-backend": "queryConditionStatus"
+        },
+        "exact": {
+          "type": "boolean",
+          "default": false,
+          "exactDescription": "是否精确匹配;true=多条件同时满足,false=任一满足。",
+          "x-backend": "queryConditionExact"
+        },
+        "hide_before_query": {
+          "type": "boolean",
+          "default": false,
+          "x-backend": "hideBeforeQueryCondition",
+          "hideBeforeQueryDescription": "别名 hideBeforeQuery/hideBeforeQueryCondition。"
+        },
+        "rows": {
+          "type": "array",
+          "items": {
+            "type": "array",
+            "items": {
+              "anyOf": [
+                { "type": "integer" },
+                { "type": "string", "minLength": 1 }
+              ]
+            }
+          },
+          "rowsDescription": "查询条件字段行(row×column 布局);元素可用字段名、field_id 或 queId，推荐使用 queId。别名 fields/queryCondition。",
+          "x-backend": "viewgraph_query_condition(rowOrdinal/columnOrdinal/queId)"
+        }
+      }
+    },
+    "ActionButton": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "text",
+        "action"
+      ],
+      "properties": {
+        "button_id": {
+          "type": "integer",
+          "buttonIdDescription": "系统按钮 id(先 app_views_get 回读现有声明以精确定位;新建省略)。别名 buttonId/id。",
+          "x-backend": "button_config.id(SEARCH_BUTTON_ID=6 等系统位)"
+        },
+        "client_key": {
+          "type": "string",
+          "clientKeyDescription": "按钮 client key。别名 clientKey。",
+          "x-backend": "clientKey"
+        },
+        "text": {
+          "type": "string",
+          "minLength": 1,
+          "x-backend": "buttonText",
+          "textDescription": "按钮文案。别名 button_text/buttonText/name。"
+        },
+        "action": {
+          "type": "string",
+          "enum": [
+            "add_data",
+            "link",
+            "qRobot",
+            "wings"
+          ],
+          "x-backend": "triggerAction(addData/link/qRobot/wings)",
+          "actionDescription": "触发动作。别名 trigger_action/triggerAction。"
+        },
+        "url": {
+          "type": "string",
+          "urlDescription": "link 动作的跳转 URL。别名 link_url/linkUrl/trigger_link_url。"
+        },
+        "target_app_key": {
+          "type": "string",
+          "targetAppKeyDescription": "add_data 动作的目标应用。别名 targetAppKey/related_app_key。",
+          "x-backend": "relationAppKey"
+        },
+        "target_app_name": {
+          "type": "string",
+          "targetAppNameDescription": "add_data 动作的目标应用名。别名 targetAppName/related_app_name。"
+        },
+        "field_mappings": {
+          "type": "array",
+          "items": true,
+          "fieldMappingsDescription": "add_data 字段映射。别名 fieldMappings/mappings。",
+          "x-backend": "que_relations"
+        },
+        "default_values": {
+          "type": "object",
+          "additionalProperties": true,
+          "defaultValuesDescription": "add_data 静态默认值。别名 defaultValues/defaults。"
+        },
+        "placement": {
+          "type": "string",
+          "enum": [
+            "header",
+            "detail",
+            "list"
+          ],
+          "default": "detail",
+          "x-backend": "viewgraph_button_config.configType(TOP|DETAIL|INSIDE)",
+          "placementDescription": "按钮位置。别名 position/config_type。"
+        },
+        "primary": {
+          "type": "boolean",
+          "default": false,
+          "primaryDescription": "是否主按钮。别名 being_main/beingMain。",
+          "x-backend": "beingMain"
+        },
+        "visible_when": {
+          "type": "array",
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/$defs/FilterRule"
+            }
+          },
+          "visibleWhenDescription": "按钮可见的记录级权限条件(组内 AND、组间 OR)。别名 visibleWhen/button_limit/buttonLimit。",
+          "x-backend": "buttonLimit(List<List<MatchRule>>)"
+        },
+        "button_formula": {
+          "type": "string",
+          "x-backend": "buttonFormula",
+          "buttonFormulaDescription": "按钮公式。别名 buttonFormula。"
+        },
+        "button_formula_type": {
+          "type": "integer",
+          "default": 1,
+          "x-backend": "buttonFormulaType",
+          "buttonFormulaTypeDescription": "按钮公式类型。别名 buttonFormulaType。"
+        },
+        "print_tpls": {
+          "type": "array",
+          "items": true,
+          "x-backend": "printTpls",
+          "printTplsDescription": "打印模板引用。别名 printTpls。"
+        },
+        "style_preset": {
+          "type": "string",
+          "x-backend": "样式预设",
+          "stylePresetDescription": "样式预设名。别名 stylePreset。"
+        },
+        "background_color": {
+          "type": "string",
+          "x-backend": "backgroundColor(transparent 等)",
+          "backgroundColorDescription": "背景色。别名 backgroundColor。"
+        },
+        "text_color": {
+          "type": "string",
+          "x-backend": "textColor(#494F57 等)",
+          "textColorDescription": "文字色。别名 textColor。"
+        },
+        "button_icon": {
+          "type": "string",
+          "x-backend": "buttonIcon(ex-search 等)",
+          "buttonIconDescription": "图标名。别名 buttonIcon。"
+        },
+        "external_qrobot_config": {
+          "type": "object",
+          "additionalProperties": true,
+          "externalQrobotConfigDescription": "qRobot 触发配置(qRobot 动作必填)。别名 externalQrobotConfig。",
+          "x-backend": "custom_button_external_qrobot_relation_vo"
+        },
+        "trigger_wings_config": {
+          "type": "object",
+          "additionalProperties": true,
+          "triggerWingsConfigDescription": "wings 触发配置(wings 动作必填)。别名 triggerWingsConfig。",
+          "x-backend": "trigger_wings_config"
+        }
+      }
+    },
+    "ButtonBinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "button_type",
+        "config_type",
+        "button_id"
+      ],
+      "properties": {
+        "button_type": {
+          "type": "string",
+          "enum": [
+            "SYSTEM",
+            "CUSTOM"
+          ],
+          "buttonTypeDescription": "按钮类型。别名 buttonType(system/custom 归一)。",
+          "x-backend": "button_config.buttonType"
+        },
+        "config_type": {
+          "type": "string",
+          "enum": [
+            "TOP",
+            "DETAIL",
+            "INSIDE"
+          ],
+          "configTypeDescription": "按钮位置。别名 configType(top/header→TOP、detail→DETAIL、inside/list/row→INSIDE)。",
+          "x-backend": "configType"
+        },
+        "button_id": {
+          "type": "integer",
+          "buttonIdDescription": "按钮 id(创建前先 app_get_buttons 传 button_text 查重,唯一命中直接复用本 id;未命中才用 app_custom_buttons_apply 创建)。别名 buttonId/id。",
+          "x-backend": "button_config.id / custom_button_id"
+        },
+        "button_text": {
+          "type": "string",
+          "x-backend": "buttonText",
+          "buttonTextDescription": "按钮文案。别名 buttonText。"
+        },
+        "button_icon": {
+          "type": "string",
+          "x-backend": "buttonIcon",
+          "buttonIconDescription": "图标名。别名 buttonIcon。"
+        },
+        "style_preset": {
+          "type": "string",
+          "stylePresetDescription": "样式预设名。别名 stylePreset。"
+        },
+        "background_color": {
+          "type": "string",
+          "x-backend": "backgroundColor",
+          "backgroundColorDescription": "背景色。别名 backgroundColor。"
+        },
+        "text_color": {
+          "type": "string",
+          "x-backend": "textColor",
+          "textColorDescription": "文字色。别名 textColor。"
+        },
+        "trigger_action": {
+          "type": "string",
+          "triggerActionDescription": "触发动作(维护既有绑定)。别名 triggerAction。",
+          "x-backend": "triggerAction"
+        },
+        "print_tpls": {
+          "type": "array",
+          "items": true,
+          "printTplsDescription": "打印模板引用。别名 printTpls。"
+        },
+        "being_main": {
+          "type": "boolean",
+          "default": false,
+          "beingMainDescription": "是否主按钮。别名 beingMain。",
+          "x-backend": "beingMain"
+        },
+        "button_limit": {
+          "type": "array",
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/$defs/FilterRule"
+            }
+          },
+          "buttonLimitDescription": "按钮可见权限条件。别名 buttonLimit。",
+          "x-backend": "buttonLimit"
+        },
+        "button_formula": {
+          "type": "string",
+          "buttonFormulaDescription": "按钮公式。别名 buttonFormula。",
+          "x-backend": "buttonFormula"
+        },
+        "button_formula_type": {
+          "type": "integer",
+          "default": 1,
+          "buttonFormulaTypeDescription": "按钮公式类型。别名 buttonFormulaType。",
+          "x-backend": "buttonFormulaType"
+        }
+      }
+    },
+    "AssociatedResources": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "visible": {
+          "type": "boolean",
+          "default": true,
+          "x-backend": "asosChartVisible",
+          "visibleDescription": "关联资源是否可见。别名 enabled/asosChartVisible。"
+        },
+        "limit_type": {
+          "type": "string",
+          "enum": [
+            "all",
+            "select"
+          ],
+          "x-backend": "asosChartConfig.limitType",
+          "limitTypeDescription": "all=全部关联,select=指定。别名 limitType。"
+        },
+        "associated_item_ids": {
+          "type": "array",
+          "items": true,
+          "x-backend": "asosChartIdList → viewgraph_asos_chart",
+          "associatedItemIdsDescription": "指定关联资源 id。别名 associatedItemIds/asosChartIdList/items。"
+        }
+      }
+    },
+    "CardConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "clipping_mode": {
+          "type": "string",
+          "enum": [
+            "default",
+            "fill"
+          ],
+          "clippingModeDescription": "封面裁剪模式:default=默认,fill=填充。",
+          "x-backend": "clippingMode(default 实测)"
+        },
+        "image_adaption": {
+          "type": "boolean",
+          "default": false,
+          "imageAdaptionDescription": "封面图是否自适应尺寸。",
+          "x-backend": "beingImageAdaption"
+        },
+        "show_field_title": {
+          "type": "boolean",
+          "default": true,
+          "showFieldTitleDescription": "是否显示字段标题。",
+          "x-backend": "beingShowQueTitle"
+        },
+        "show_title": {
+          "type": "boolean",
+          "default": true,
+          "showTitleDescription": "是否显示卡片标题。",
+          "x-backend": "beingShowTitleQue"
+        },
+        "show_cover": {
+          "type": "boolean",
+          "default": false,
+          "showCoverDescription": "是否显示封面图。",
+          "x-backend": "beingShowCover"
+        },
+        "group_color": {
+          "type": "boolean",
+          "default": false,
+          "groupColorDescription": "分组是否显示颜色标识。",
+          "x-backend": "beingGroupColor"
+        },
+        "group_que_id": {
+          "type": "integer",
+          "groupQueIdDescription": "看板式分组字段(card 类型适用)。",
+          "x-backend": "groupQueId"
+        },
+        "title_que_id": {
+          "type": "integer",
+          "titleQueIdDescription": "卡片标题字段 queId。",
+          "x-backend": "titleQueId"
+        },
+        "cover_que_id": {
+          "type": "integer",
+          "coverQueIdDescription": "封面图字段(attachment 字段)。",
+          "x-backend": "frontCoverQueId"
+        }
+      }
+    },
+    "GanttConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "default_time_dimension": {
+          "type": "string",
+          "enum": [
+            "day",
+            "week",
+            "month",
+            "year"
+          ],
+          "default": "month",
+          "defaultTimeDimensionDescription": "默认时间维度:day/week/month/year。",
+          "x-backend": "defaultTimeDimension(month×8/week×4 实测)"
+        },
+        "auto_calibration": {
+          "type": "boolean",
+          "default": false,
+          "autoCalibrationDescription": "自动校准开关。",
+          "x-backend": "ganttAutoCalibrationVO.beingAutoCalibration"
+        },
+        "groups": {
+          "type": "array",
+          "groupsDescription": "甘特分组字段列表,按 ordinal 排序。",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "ordinal": {
+                "type": "integer",
+                "ordinalDescription": "分组展示顺序。"
+              },
+              "que_id": {
+                "type": "integer",
+                "queIdDescription": "分组字段 queId。"
+              }
+            }
+          },
+          "x-backend": "ganttGroupVOList(groupQueId, ordinal)"
+        },
+        "dependencies": {
+          "type": "array",
+          "maxItems": 1,
+          "dependenciesDescription": "任务依赖关系;后端为单对象,v1alpha1 限 1 条。",
+          "items": {
+            "$ref": "#/$defs/GanttDependency"
+          },
+          "x-backend": "ganttDependencyVO(后端单对象,v1alpha1 限 1 条)"
+        },
+        "start_que_id": {
+          "type": "integer",
+          "startQueIdDescription": "甘特开始时间字段 queId;与顶层 start_que_id 等价,取其一。",
+          "x-backend": "startTimeQueId"
+        },
+        "end_que_id": {
+          "type": "integer",
+          "endQueIdDescription": "甘特结束时间字段 queId;与顶层 end_que_id 等价,取其一。",
+          "x-backend": "endTimeQueId"
+        },
+        "title_que_id": {
+          "type": "integer",
+          "titleQueIdDescription": "甘特标题字段 queId;与顶层 title_que_id 等价。",
+          "x-backend": "titleQueId"
+        }
+      }
+    },
+    "GanttDependency": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "predecessor_que_id",
+        "dependency_que_id"
+      ],
+      "properties": {
+        "start_start_option_id": {
+          "type": "integer",
+          "startStartOptionIdDescription": "开始→开始依赖的偏移选项 id(可选)。",
+          "x-backend": "startStartOptionId"
+        },
+        "start_end_option_id": {
+          "type": "integer",
+          "startEndOptionIdDescription": "开始→结束依赖的偏移选项 id(可选)。",
+          "x-backend": "startEndOptionId"
+        },
+        "end_start_option_id": {
+          "type": "integer",
+          "endStartOptionIdDescription": "结束→开始依赖的偏移选项 id(可选)。",
+          "x-backend": "endStartOptionId"
+        },
+        "end_end_option_id": {
+          "type": "integer",
+          "endEndOptionIdDescription": "结束→结束依赖的偏移选项 id(可选)。",
+          "x-backend": "endEndOptionId"
+        },
+        "dependency_que_id": {
+          "type": "integer",
+          "dependencyQueIdDescription": "被依赖(后续)任务的关联字段 queId。",
+          "x-backend": "dependencyQueId"
+        },
+        "predecessor_que_id": {
+          "type": "integer",
+          "predecessorQueIdDescription": "前置任务的关联字段 queId。",
+          "x-backend": "predecessorTaskQueId"
+        }
+      }
+    },
+    "HierarchyConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "title_que_id",
+        "children_que_id"
+      ],
+      "properties": {
+        "root_filter": {
+          "type": "array",
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/$defs/FilterRule"
+            }
+          },
+          "rootFilterDescription": "根节点筛选规则(组内 AND、组间 OR;编译为 MatchRule 组)。",
+          "x-backend": "rootNodeFilter(List<List<MatchRule>>)"
+        },
+        "title_que_id": {
+          "type": "integer",
+          "titleQueIdDescription": "层级标题字段 queId。",
+          "x-backend": "viewgraph_hierarchy_config.titleQueId"
+        },
+        "children_que_id": {
+          "type": "integer",
+          "childrenQueIdDescription": "子节点关联字段 queId(引用/关联字段)。",
+          "x-backend": "childrenQueId"
+        }
+      }
+    },
+    "CalendarConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["title_que_id", "date_que_id"],
+      "properties": {
+        "title_que_id": { "type": "integer", "calendarTitleQueIdDescription": "日历事项标题字段 queId。", "x-backend": "titleQueId" },
+        "date_que_id": { "type": "integer", "calendarDateQueIdDescription": "日历日期字段 queId；可使用表单日期字段或系统字段申请时间(2)/更新时间(3)。", "x-backend": "dateQueId" },
+        "color_que_id": { "type": "integer", "calendarColorQueIdDescription": "可选的日历颜色字段 queId。", "x-backend": "colorQueId" }
+      }
+    },
+    "DisplayConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "row_height": {
+          "type": "string",
+          "enum": [
+            "compact",
+            "moderate",
+            "highest",
+            "high"
+          ],
+          "rowHeightDescription": "表格行高:compact=紧凑,moderate=适中,high=高,highest=最高。",
+          "x-backend": "defaultRowHigh(compact×705 实测)"
+        },
+        "pin_navigate": {
+          "type": "boolean",
+          "default": false,
+          "pinNavigateDescription": "是否固定视图内导航;与顶层 pinned(视图列表固定)无关。",
+          "x-backend": "beingPinNavigate"
+        },
+        "remark": {
+          "type": "string",
+          "remarkDescription": "视图备注。",
+          "x-backend": "remark"
+        }
+      }
+    },
+    "RecordConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "audit_visible": {
+          "type": "boolean",
+          "default": true,
+          "auditVisibleDescription": "是否显示操作记录。",
+          "x-backend": "beingAuditRecordVisible"
+        },
+        "data_log_visible": {
+          "type": "boolean",
+          "default": true,
+          "dataLogVisibleDescription": "是否显示数据日志(字段变更历史)。",
+          "x-backend": "beingDataLogVisible"
+        },
+        "qrobot_record_visible": {
+          "type": "boolean",
+          "default": false,
+          "qrobotRecordVisibleDescription": "是否显示机器人记录。",
+          "x-backend": "beingQrobotRecordVisible"
+        },
+        "workflow_future_visible": {
+          "type": "boolean",
+          "default": true,
+          "workflowFutureVisibleDescription": "是否显示流程未来节点。",
+          "x-backend": "beingWorkflowNodeFutureListVisible"
+        },
+        "comment": {
+          "type": "boolean",
+          "default": false,
+          "commentDescription": "是否开启留言。",
+          "x-backend": "beingCommentStatus"
+        }
+      }
+    },
+    "ShareConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "need_pass": {
+          "type": "boolean",
+          "default": false,
+          "needPassDescription": "分享是否需要访问密码;true 时用 password 提供密码。",
+          "x-backend": "beingNeedPass"
+        },
+        "password": {
+          "type": "string",
+          "passwordDescription": "访问密码(need_pass=true 时生效)。别名 pass/viewgraphPass。",
+          "x-backend": "viewgraphPass"
+        },
+        "force_login": {
+          "type": "boolean",
+          "default": false,
+          "forceLoginDescription": "分享是否强制登录后查看。",
+          "x-backend": "beingForceLogin"
+        },
+        "print_enabled": {
+          "type": "boolean",
+          "default": false,
+          "printEnabledDescription": "打印开关(模板明细 v1alpha2)。",
+          "x-backend": "beingPrintStatus"
+        }
+      }
+    }
+  },
+  "$ref": "#/$defs/ViewDeclaration",
+  "x-qingflow-config-sections": [
+    {
+      "kind": "display",
+      "displayDescription": "展示字段、排序、关联资源和各公开视图类型的专属配置。",
+      "fields": ["columns", "sort", "card", "gantt", "hierarchy", "calendar", "associated_resources", "display", "group_que_id", "title_que_id", "start_que_id", "end_que_id"]
+    },
+    {
+      "kind": "data-permission",
+      "dataPermissionDescription": "后台或自定义数据权限模式以及固定筛选。",
+      "fields": ["data_permission", "filters"]
+    },
+    {
+      "kind": "operation-permission",
+      "operationPermissionDescription": "成员可见范围、记录日志、留言、打印和分享开关。",
+      "fields": ["visibility", "record", "share"]
+    },
+    {
+      "kind": "query-condition",
+      "queryConditionDescription": "用户查询面板开关、匹配模式、查询前隐藏和行列布局。",
+      "fields": ["query_conditions"]
+    },
+    {
+      "kind": "button-config",
+      "buttonConfigDescription": "系统动作按钮、自定义按钮绑定以及关联的查询面板。",
+      "fields": ["action_buttons", "action_buttons_mode", "buttons", "query_conditions"]
+    }
+  ],
+  "x-qingflow-related-schemas": {
+    "currentKind": "complete",
+    "fetchTool": "app_views_schema",
+    "fetchArgument": "schema_kind",
+    "fetchCli": "builder views schema --schema-kind KIND",
+    "kinds": {
+      "summary": "最小创建声明:类型/名称/展示字段 + 数据权限形状。",
+      "complete": "完整声明:全部公开可写字段,含各配置域与类型专属配置。",
+      "display": "展示字段、排序、卡片/甘特/层级/日历配置、分组字段和关联资源。",
+      "data-permission": "数据权限模式、数据范围和固定筛选条件。",
+      "operation-permission": "成员可见范围、记录日志、留言、打印和分享策略。",
+      "query-condition": "用户查询面板的开关、匹配模式和字段布局。",
+      "button-config": "系统动作按钮、自定义按钮绑定及按钮清空/合并方式。"
+    },
+    "navigationDescription": "本声明是完整版;最小创建声明用 schema_kind=summary 获取。某个配置域需要专项语义(清空/替换规则、字段约束)时,用 app_views_schema 换对应 schema_kind 读取,专项返回自包含可直接校验。",
+    "readSources": {
+      "queIds": "字段 queId 用 app_get 读 fields(CLI: builder app get --app-key APP fields);现有视图声明用 app_views_get 回读(CLI: builder views get --app-key APP --schema-kind summary|complete)。",
+      "fieldSchema": "字段类型、默认值等表单侧细节用 app_form_schema 传 schema_kind=field 和 field_type 获取(CLI: builder app-form schema --schema-kind field --field-type TYPE)。"
+    }
+  },
+  "x-qingflow-write-semantics": {
+    "create": "省略的配置片段由 builder 组装创建默认值；JSON Schema 的 default 只是注解。",
+    "full_upsert": "提交完整目标配置；数组和嵌套对象的清空或替换规则按配置域调用 app_views_schema 获取专项 Schema(schema_kind=display/data-permission/operation-permission/query-condition/button-config；CLI: builder views schema --schema-kind KIND)。",
+    "partial_patch": "优先使用 patch_views 的 set/unset。builder 会读取现有配置、合并后再向后端完整保存。",
+    "backend_warning": "底层 ViewgraphInfo 更新接口对部分省略字段会执行 false、true、空数组或空字符串初始化，因此不得把直接后端请求中的省略统一理解为保留。"
+  },
+  "x-qingflow-backend-known-unsupported": {
+    "column_permissions": {
+      "backend": "viewgraphQuestions/ViewgraphQuestion",
+      "status": "not-writable",
+      "reason": "当前 columns 只表达展示字段及顺序。"
+    },
+    "advanced_filter_formula": {
+      "backend": "viewgraphLimitType=2 + viewgraphLimitFormula",
+      "status": "not-writable",
+      "reason": "当前 filters 只编译简易 MatchRule。"
+    },
+    "print_templates": {
+      "backend": "beingDefaultPrintTplStatus + printTpls",
+      "status": "not-writable",
+      "reason": "当前 share 只公开 print_enabled。"
+    },
+    "attachment_policy": {
+      "backend": "attachVisibleOnlyConfig",
+      "status": "read-only",
+      "reason": "该配置从工作区继承，视图保存接口不修改。"
+    }
+  },
+  "examples": [
+    {
+      "name": "业务记录",
+      "type": "table",
+      "columns": [101, 102],
+      "visibility": {
+        "mode": "workspace",
+        "external_mode": "not"
+      },
+      "data_permission": {
+        "type": "custom",
+        "scope": "all"
+      },
+      "sort": [
+        {
+          "que_id": 101,
+          "ascending": true
+        }
+      ]
+    },
+    {
+      "name": "待处理记录",
+      "type": "table",
+      "columns": [101, 102],
+      "data_permission": {
+        "type": "custom",
+        "scope": "custom"
+      },
+      "filters": [
+        {
+          "que_id": 103,
+          "operator": "eq",
+          "values": ["待处理"]
+        }
+      ],
+      "query_conditions": {
+        "enabled": true,
+        "exact": false,
+        "hide_before_query": true,
+        "rows": [[101, 103]]
+      }
+    }
+  ]
+}