@qingflow-tech/qingflow-cli 1.1.51 → 1.1.53

package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/details/button-config.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qingflow.com/schemas/builder/views/v1alpha1/details/button-config.json",
+  "title": "Qingflow Views button configuration",
+  "buttonConfigDescription": "视图系统按钮和自定义按钮绑定片段(schema_kind=button-config),字段直接并入完整视图声明。action_buttons 是公开 DSL 的动作按钮；buttons 用于维护已有按钮绑定。空数组表示清空对应列表。",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "action_buttons": { "type": "array", "items": { "$ref": "../complete.json#/$defs/ActionButton" }, "maxItems": 60, "actionButtonsDescription": "系统动作按钮(add_data/link/qRobot/wings);省略保留现有,空数组清空。" },
+    "action_buttons_mode": { "type": "string", "enum": ["merge", "replace"], "default": "merge", "actionButtonsModeDescription": "merge=与现有按钮合并(默认),replace=按声明全量替换。" },
+    "buttons": { "type": "array", "items": { "$ref": "../complete.json#/$defs/ButtonBinding" }, "maxItems": 60, "buttonsDescription": "已有自定义按钮的视图绑定(按 button_id 引用,维护位置/主次/显隐)。" },
+    "query_conditions": { "$ref": "../complete.json#/$defs/QueryConditions", "queryConditionsDescription": "搜索按钮配置依赖的查询面板。" }
+  },
+  "x-qingflow-related-schemas": {
+    "currentKind": "button-config",
+    "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=complete)的按钮配置域,字段并入视图声明后交给 app_views_apply/patch_views(CLI: builder views apply --app-key APP --view-file PATH 或 --patch-views-file);其他配置域用 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-apply-semantics": "action_buttons/buttons 省略表示保留现有配置，空数组表示清空。action_buttons_mode=merge 合并动作按钮，replace 按声明替换。自定义按钮主体通过 app_custom_buttons_apply 创建或更新，本 schema 只维护视图绑定。",
+  "x-qingflow-count-limits": {
+    "header": "最多 20 个。",
+    "detail": "总计最多 20 个，主按钮和次按钮各最多 10 个。",
+    "list": "主按钮和次按钮各最多 10 个。"
+  },
+  "x-qingflow-button-types": {
+    "action_buttons": "公开系统动作按钮；app_views_apply 负责创建配置并绑定到目标视图。",
+    "buttons": "引用应用中已存在的自定义按钮，只维护视图绑定、位置、主次和显隐条件。"
+  },
+  "x-qingflow-custom-button-workflow": {
+    "query": "创建前先用 app_get_buttons 传 button_text 按文案精确查重(CLI: builder button get --app-key APP --button-text 文案);唯一命中直接复用其 button_id,同名多条用 button_id 精确指定。",
+    "createOrUpdate": "未命中再用 app_custom_buttons_apply 创建;它自身也按 button_text 去重(无 button_id 时唯一同名匹配转为更新),不要重复创建同名按钮。需要维护按钮主体、样式、跨视图复用或 qRobot/wings 细节时同样使用 app_custom_buttons_apply。",
+    "viewBinding": "普通业务动作优先声明 action_buttons;已有自定义按钮使用 buttons 绑定(button_id 来自查询结果)。"
+  },
+  "examples": [
+    { "action_buttons": [{ "text": "新增", "action": "add_data", "placement": "header", "primary": true }], "action_buttons_mode": "merge" },
+    { "buttons": [{ "button_type": "CUSTOM", "config_type": "DETAIL", "button_id": 123, "button_text": "提交审批", "being_main": true }] }
+  ]
+}

package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/details/data-permission.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qingflow.com/schemas/builder/views/v1alpha1/details/data-permission.json",
+  "title": "Qingflow Views data permission configuration",
+  "dataPermissionDescription": "视图数据范围和固定筛选片段(schema_kind=data-permission),字段直接并入完整视图声明。data_permission 使用公开 DSL；filters 为空表示清空自定义筛选。",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "data_permission": { "$ref": "../complete.json#/$defs/DataPermission", "dataPermissionDescription": "数据权限生效类型(config/custom)与数据范围(scope)。" },
+    "filters": {
+      "type": "array",
+      "items": { "anyOf": [
+        { "$ref": "../complete.json#/$defs/FilterRule" },
+        { "type": "array", "items": { "$ref": "../complete.json#/$defs/FilterRule" } }
+      ] },
+      "filtersDescription": "筛选规则；扁平数组为 AND，嵌套数组为 OR 组。规则中的 que_id 必须是整数。"
+    }
+  },
+  "x-qingflow-related-schemas": {
+    "currentKind": "data-permission",
+    "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=complete)的数据权限配置域,字段并入视图声明后交给 app_views_apply/patch_views(CLI: builder views apply --app-key APP --view-file PATH 或 --patch-views-file);其他配置域用 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-apply-semantics": "data_permission 缺省使用 custom + all。filters 省略表示保留现有筛选，空数组表示清空筛选。",
+  "x-qingflow-mode-requirements": {
+    "config": "跟随应用后台数据权限；scope 和 filters 不作为主要权限来源。",
+    "custom": "使用视图自定义范围；scope=custom 时应同时提供 filters。",
+    "filters": "扁平数组表示一组 AND；嵌套数组表示组间 OR、组内 AND。"
+  },
+  "x-qingflow-backend-semantics": {
+    "data_permission.type": "dataPermissionType(CONFIG/CUSTOM)",
+    "data_permission.scope": "dataScope(ALL/ONESELF/DEPT/SUBORDINATE/CUSTOM)",
+    "filters": "viewgraphLimitType=1 + viewgraphLimit；空数组清除简易条件。"
+  },
+  "x-qingflow-unsupported": {
+    "advanced_formula": "viewgraphLimitFormula 高级筛选公式尚未进入公开 DSL；filters 仅表示简易条件。"
+  },
+  "examples": [
+    { "data_permission": { "type": "custom", "scope": "all" }, "filters": [] },
+    {
+      "data_permission": { "type": "custom", "scope": "custom" },
+      "filters": [[{ "que_id": 101, "operator": "eq", "values": ["待处理"] }]]
+    }
+  ]
+}

package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/details/display.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qingflow.com/schemas/builder/views/v1alpha1/details/display.json",
+  "title": "Qingflow Views display configuration",
+  "displayDescription": "视图展示配置片段(schema_kind=display),字段直接并入完整视图声明。所有字段引用均为实际整数 queId。",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "pinned": { "type": "boolean", "pinnedDescription": "是否固定在应用的视图列表顶部。true=固定，false=取消固定；省略时保持当前状态。它与 display.pin_navigate 无关。", "x-backend": "POST /app/{appKey}/view/ordinal (FIXED_VIEW_LIST|VIEW_LIST)" },
+    "columns": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "columnsDescription": "表格或卡片展示字段，按数组顺序显示。" },
+    "sort": { "type": "array", "items": { "$ref": "../complete.json#/$defs/SortRule" }, "sortDescription": "多级排序。空数组恢复默认排序。" },
+    "card": { "$ref": "../complete.json#/$defs/CardConfig", "cardDescription": "卡片视图配置(封面/标题/字段标题/分组)。" },
+    "gantt": { "$ref": "../complete.json#/$defs/GanttConfig", "ganttDescription": "甘特视图配置(时间维度/分组/依赖)。" },
+    "hierarchy": { "$ref": "../complete.json#/$defs/HierarchyConfig", "hierarchyDescription": "层级视图配置(必填 title_que_id/children_que_id,可选 root_filter)。" },
+    "calendar": { "$ref": "../complete.json#/$defs/CalendarConfig", "calendarDescription": "日历视图配置(必填 title_que_id/date_que_id)。" },
+    "associated_resources": { "$ref": "../complete.json#/$defs/AssociatedResources", "associatedResourcesDescription": "关联报表/图表资源展示配置;应用级资源池用 app_associated_resources_apply 维护。" },
+    "display": { "$ref": "../complete.json#/$defs/DisplayConfig", "displayMiscDescription": "展示杂项(行高/视图内导航固定/备注)。" },
+    "group_que_id": { "type": "integer", "groupQueIdDescription": "看板分组字段 queId。" },
+    "title_que_id": { "type": "integer", "titleQueIdDescription": "卡片、甘特、层级或日历标题字段 queId。" },
+    "start_que_id": { "type": "integer", "startQueIdDescription": "甘特开始时间字段 queId。" },
+    "end_que_id": { "type": "integer", "endQueIdDescription": "甘特结束时间字段 queId。" }
+  },
+  "x-qingflow-related-schemas": {
+    "currentKind": "display",
+    "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=complete)的展示配置域,字段并入视图声明后交给 app_views_apply/patch_views(CLI: builder views apply --app-key APP --view-file PATH 或 --patch-views-file);其他配置域用 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-apply-semantics": {
+    "pinned": "true 将视图移动到固定列表，false 将其移回普通列表；省略时不改变当前列表状态。",
+    "columns": "数组顺序就是展示顺序；table/card 至少需要一个有效业务字段。",
+    "sort": "省略表示保留现有排序，空数组恢复默认排序。",
+    "associated_resources": "省略表示保留；显式提交按目标态更新。"
+  },
+  "x-qingflow-create-defaults": {
+    "display": { "pin_navigate": true, "row_height": "compact" },
+    "sort": "首个展示字段升序；没有展示字段时使用后端兼容默认字段。",
+    "card": { "show_cover": false, "show_field_title": true, "image_adaption": false },
+    "associated_resources": { "visible": true, "limit_type": "all", "associated_item_ids": [] }
+  },
+  "x-qingflow-type-requirements": {
+    "table": "columns 至少包含一个业务字段。",
+    "card": "columns 至少包含一个业务字段；标题和封面等使用 card。",
+    "board": "必须提供 group_que_id。",
+    "gantt": "必须提供 start_que_id 和 end_que_id，或在 gantt 中提供等价字段。",
+    "hierarchy": "必须提供 hierarchy.title_que_id 和 hierarchy.children_que_id。",
+    "calendar": "必须提供 calendar.title_que_id 和 calendar.date_que_id。date_que_id 可为表单日期字段或系统字段 2(申请时间)/3(更新时间)。"
+  },
+  "x-qingflow-unsupported": {
+    "column_permissions": "列级可编辑、隐藏、下载等 ViewgraphQuestion 配置尚未进入公开 DSL。"
+  },
+  "examples": [
+    { "columns": [101, 102], "sort": [{ "que_id": 101, "ascending": true }] },
+    { "group_que_id": 103, "title_que_id": 101, "card": { "show_title": true, "group_color": true } },
+    { "gantt": { "title_que_id": 101, "start_que_id": 104, "end_que_id": 105, "default_time_dimension": "month", "auto_calibration": false } },
+    { "hierarchy": { "title_que_id": 101, "children_que_id": 106, "root_filter": [] } },
+    { "calendar": { "title_que_id": 101, "date_que_id": 104, "color_que_id": 103 } }
+  ]
+}

package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/details/operation-permission.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qingflow.com/schemas/builder/views/v1alpha1/details/operation-permission.json",
+  "title": "Qingflow Views operation permission configuration",
+  "operationPermissionDescription": "视图操作和记录权限片段(schema_kind=operation-permission),字段直接并入完整视图声明。包括成员可见范围、记录日志、数据日志、留言、打印和分享策略。",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "visibility": { "$ref": "../complete.json#/$defs/Visibility", "visibilityDescription": "对内可见范围 + 外部成员授权。" },
+    "record": { "$ref": "../complete.json#/$defs/RecordConfig", "recordDescription": "记录可见性开关:操作记录/数据日志/机器人记录/流程未来节点/留言。" },
+    "share": { "$ref": "../complete.json#/$defs/ShareConfig", "shareDescription": "分享与安全:密码/强制登录/打印。" }
+  },
+  "x-qingflow-related-schemas": {
+    "currentKind": "operation-permission",
+    "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=complete)的操作权限配置域,字段并入视图声明后交给 app_views_apply/patch_views(CLI: builder views apply --app-key APP --view-file PATH 或 --patch-views-file);其他配置域用 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-apply-semantics": "省略片段表示不修改对应现有配置；显式布尔值按目标态写入。",
+  "x-qingflow-create-defaults": {
+    "record": { "audit_visible": true, "data_log_visible": true, "qrobot_record_visible": false, "workflow_future_visible": true, "comment": false },
+    "share": { "need_pass": false, "force_login": false, "print_enabled": false }
+  },
+  "x-qingflow-backend-semantics": "底层完整更新会重建字段权限和打印模板绑定；当前公开 DSL 不接受这两类目标态。使用 patch_views 更新本 schema 已公开的片段，builder 会读取并保留其他后端配置。",
+  "x-qingflow-unsupported": {
+    "field_permissions": "viewgraphQuestions 字段级编辑、隐藏、下载权限尚未进入公开 DSL。",
+    "print_templates": "默认打印模板和 printTpls 绑定尚未进入公开 DSL；share.print_enabled 只控制打印开关。",
+    "attachment_policy": "attachVisibleOnlyConfig 是工作区只读快照，不属于视图写入契约。"
+  },
+  "examples": [
+    { "visibility": { "mode": "workspace", "external_mode": "not" }, "record": { "audit_visible": true, "comment": false } },
+    { "record": { "audit_visible": true, "data_log_visible": true, "workflow_future_visible": false, "comment": true }, "share": { "print_enabled": true } }
+  ]
+}

package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/details/query-condition.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qingflow.com/schemas/builder/views/v1alpha1/details/query-condition.json",
+  "title": "Qingflow Views query condition configuration",
+  "queryConditionDescription": "视图查询面板配置片段(schema_kind=query-condition),字段直接并入完整视图声明。query_conditions 是用户输入条件布局，固定数据筛选属于数据权限配置域，用 app_views_schema 传 schema_kind=data-permission 获取专项 Schema(CLI: builder views schema --schema-kind data-permission)。",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "query_conditions": { "$ref": "../complete.json#/$defs/QueryConditions", "queryConditionsDescription": "查询面板开关/匹配模式/查询前隐藏/行列布局。" }
+  },
+  "x-qingflow-related-schemas": {
+    "currentKind": "query-condition",
+    "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=complete)的查询面板配置域,字段并入视图声明后交给 app_views_apply/patch_views(CLI: builder views apply --app-key APP --view-file PATH 或 --patch-views-file);其他配置域用 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-apply-semantics": "query_conditions 省略表示保留；enabled=false 且 rows=[] 会关闭并清空查询布局。enabled=true 时 apply 要求至少一个字段。",
+  "x-qingflow-create-defaults": {
+    "enabled": false,
+    "exact": false,
+    "hide_before_query": false,
+    "rows": []
+  },
+  "x-qingflow-backend-semantics": "rows 会编译为 queryCondition 的行列布局。底层直接更新若省略 queryConditionExact 或 hideBeforeQueryCondition，默认行为可能与 builder 创建默认不同；app_views_apply 会显式组装公开语义。",
+  "x-qingflow-unsupported": {
+    "search_button": "querySearchStatus 由按钮配置间接管理，尚未作为 query_conditions 字段公开。",
+    "row_titles": "showConditionTitle 和查询行 title 尚未进入公开 DSL。"
+  },
+  "examples": [
+    { "query_conditions": { "enabled": false, "exact": false, "hide_before_query": false, "rows": [] } },
+    { "query_conditions": { "enabled": true, "exact": true, "hide_before_query": true, "rows": [[101, 102]] } }
+  ]
+}

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

@@ -0,0 +1,319 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qingflow.com/schemas/builder/views/v1alpha1/summary.json",
+  "title": "Qingflow Builder Views Declaration · summary (v1alpha1)",
+  "viewSummaryDescription": "视图最小声明(最简版 spec):视图基本属性 + 数据权限信息。创建一个可用视图的最小字段集;其余配置项通过 app_views_schema 传 schema_kind=complete 获取完整声明(CLI: builder views schema --schema-kind complete),或按配置域传 display/data-permission/operation-permission/query-condition/button-config 读取专项 Schema。除必填项外全部可选,缺省走后端默认。字段引用使用实际整数 queId。schema 校验在别名归一之后执行,JSON Schema 只约束规范名(别名见各字段说明)。",
+  "$defs": {
+    "ViewDeclaration": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "type"
+      ],
+      "properties": {
+        "view_key": {
+          "type": "string",
+          "viewKeyDescription": "视图唯一键;upsert 锁定已有视图(存在即更新)。缺省按 name 匹配,重名报 AMBIGUOUS_VIEW。别名 viewKey。",
+          "x-backend": "viewgraph.viewgraphKey"
+        },
+        "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": "视图名称",
+          "x-backend": "viewgraph.viewgraphName"
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "table",
+            "card",
+            "board",
+            "gantt",
+            "hierarchy",
+            "calendar"
+          ],
+          "viewTypeDescription": "视图类型。别名归一:tableView→table、cardView→card、kanban→board、ganttView→gantt、hierarchyView→hierarchy、calendarView→calendar。",
+          "x-backend": "viewgraph.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 字段中承载(app_views_schema schema_kind=complete,或专项 schema_kind=data-permission);summary 级重放比对仅校验形状。"
+        },
+        "group_que_id": {
+          "type": "integer",
+          "groupQueIdDescription": "分组字段 queId"
+        },
+        "title_que_id": {
+          "type": "integer",
+          "titleQueIdDescription": "卡片/看板/甘特/层级标题字段 queId(可选)。"
+        },
+        "start_que_id": {
+          "type": "integer",
+          "startQueIdDescription": "甘特开始时间字段 queId(gantt 必填)。别名 startField。",
+          "x-backend": "viewgraphGanttConfigVO.startTimeQueId"
+        },
+        "end_que_id": {
+          "type": "integer",
+          "endQueIdDescription": "甘特结束时间字段 queId(gantt 必填)。别名 endField。",
+          "x-backend": "viewgraphGanttConfigVO.endTimeQueId"
+        },
+        "hierarchy": {
+          "$ref": "#/$defs/HierarchyConfig",
+          "hierarchyDescription": "层级视图特有配置(hierarchy 类型适用,必填)。"
+        },
+        "calendar": {
+          "$ref": "#/$defs/CalendarConfig",
+          "calendarDescription": "日历视图特有配置(calendar 类型适用,必填)。"
+        }
+      },
+      "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"] }
+        }
+      ]
+    },
+    "HierarchyConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["title_que_id", "children_que_id"],
+      "properties": {
+        "title_que_id": { "type": "integer", "hierarchyTitleQueIdDescription": "层级节点标题字段 queId。" },
+        "children_que_id": { "type": "integer", "hierarchyChildrenQueIdDescription": "层级父子关系字段 queId。" }
+      }
+    },
+    "CalendarConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["title_que_id", "date_que_id"],
+      "properties": {
+        "title_que_id": { "type": "integer", "calendarTitleQueIdDescription": "日历事项标题字段 queId。" },
+        "date_que_id": { "type": "integer", "calendarDateQueIdDescription": "日历日期字段 queId；可使用表单日期字段或系统字段申请时间(2)/更新时间(3)。" },
+        "color_que_id": { "type": "integer", "calendarColorQueIdDescription": "可选的日历颜色字段 queId。" }
+      }
+    },
+    "DataPermission": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "config",
+            "custom"
+          ],
+          "default": "custom",
+          "dataPermissionDescription": "数据权限生效类型:config=跟随应用配置,custom=视图自定义。别名 dataPermissionType(CONFIG/CUSTOM)。",
+          "x-backend": "viewgraph.dataPermissionType(CONFIG|CUSTOM)"
+        },
+        "scope": {
+          "type": "string",
+          "enum": [
+            "all",
+            "oneself",
+            "dept",
+            "subordinate",
+            "custom"
+          ],
+          "default": "all",
+          "dataScopeDescription": "数据范围:all=全部数据,oneself=自己发起的,dept=所在部门的,subordinate=下属的,custom=自定义(规则明细在完整声明的 filters 字段,通过 app_views_schema schema_kind=complete 或 data-permission 获取)。dataset-v0 实测分布:all×560 / custom×74 / oneself×71。",
+          "x-backend": "viewgraph.dataScope(ALL|ONESELF|DEPT|SUBORDINATE|CUSTOM)"
+        }
+      }
+    }
+  },
+  "$ref": "#/$defs/ViewDeclaration",
+  "x-qingflow-detail-query": {
+    "currentKind": "summary",
+    "tool": "app_views_schema",
+    "cli": "builder views schema --schema-kind KIND",
+    "argument": "schema_kind",
+    "kinds": [
+      "display",
+      "data-permission",
+      "operation-permission",
+      "query-condition",
+      "button-config",
+      "complete"
+    ],
+    "kindDescriptions": {
+      "display": "展示字段、排序、卡片/甘特/层级/日历配置、分组字段和关联资源。",
+      "data-permission": "数据权限模式、数据范围和固定筛选条件。",
+      "operation-permission": "成员可见范围、记录日志、留言、打印和分享策略。",
+      "query-condition": "用户查询面板的开关、匹配模式和字段布局。",
+      "button-config": "系统动作按钮、自定义按钮绑定及按钮清空/合并方式。",
+      "complete": "完整视图声明，汇总当前公开可写配置；summary 是它的最小子集。"
+    },
+    "detailQueryDescription": "复杂配置按需调用 app_views_schema 并传对应 schema_kind(CLI: builder views schema --schema-kind KIND);专项返回已内联其引用的定义,可独立交给 JSON Schema 校验器。",
+    "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-create-defaults": {
+    "createDefaultsDescription": "以下是 app_views_apply 当前创建路径在相应片段完全省略时组装的后端值。default 和 x-qingflow-* 是契约注解，通用 JSON Schema 校验器不会自动填值。更新已有视图时应优先使用 patch_views，避免把创建默认值当作现有值。",
+    "visibility": {
+      "mode": "workspace",
+      "external_mode": "not"
+    },
+    "display": {
+      "pin_navigate": true,
+      "row_height": "compact"
+    },
+    "data_permission": {
+      "type": "custom",
+      "scope": "all"
+    },
+    "query_conditions": {
+      "enabled": false,
+      "exact": false,
+      "hide_before_query": false,
+      "rows": []
+    },
+    "record": {
+      "audit_visible": true,
+      "qrobot_record_visible": false,
+      "workflow_future_visible": true,
+      "comment": false
+    },
+    "share": {
+      "need_pass": false,
+      "force_login": false,
+      "print_enabled": false
+    },
+    "action_buttons": [],
+    "buttons": []
+  },
+  "x-qingflow-capability-boundary": {
+    "contract": "仅列出 app_views_apply 当前可写字段。",
+    "backendKnownUnsupported": {
+      "column_permissions": "后端 ViewgraphQuestion 支持列级查看、编辑和下载权限，当前公开 DSL 尚未开放。",
+      "advanced_filter_formula": "后端支持 viewgraphLimitFormula，当前 filters 只公开简易条件。",
+      "print_templates": "后端支持默认打印模板和 printTpls 绑定，当前只公开打印开关。",
+      "attachment_policy": "attachVisibleOnlyConfig 是工作区继承的只读快照，不属于视图写入契约。"
+    }
+  },
+  "examples": [
+    { "name": "任务层级", "type": "hierarchy", "hierarchy": { "title_que_id": 101, "children_que_id": 106 } },
+    { "name": "事项日历", "type": "calendar", "calendar": { "title_que_id": 101, "date_que_id": 104, "color_que_id": 103 } },
+    {
+      "name": "业务记录",
+      "type": "table",
+      "columns": [101, 102],
+      "data_permission": {
+        "type": "custom",
+        "scope": "all"
+      }
+    },
+    {
+      "name": "待办看板",
+      "type": "board",
+      "group_que_id": 103,
+      "title_que_id": 101
+    }
+  ]
+}