weaver-e10-builder 1.6.16 → 1.7.1

package/skill-docs/references/ebuilder-designer/component-permission.md

@@ -0,0 +1,131 @@
+# 页面组件权限
+
+## 功能介绍
+
+组件权限控制页面内单个组件的使用范围，以及使用范围内的禁用范围。普通范围按人员、部门、分部、角色、岗位等组织对象授权；矩阵相关范围从矩阵或 EB 表单的数据中取得人员，可进一步筛选来源数据。
+
+页面整体使用权限使用 `page permission`；组件权限使用 `designer permission`。列表的数据权限决定可读取哪些数据，不能用组件隐藏或禁用代替数据权限。事件中的显示/隐藏动作也独立于组件权限。
+
+配置入口是普通页面设计器中选中组件后的权限设置。PC 与移动端分别维护，两个终端组件 ID 不相同。命令每次指定一个终端，另一终端需用其组件 ID 单独配置。
+
+## 命令与配置流程
+
+```sh
+e10-cli designer permission schema
+e10-cli designer permission lookup --type department --id <departmentId>
+e10-cli designer permission get <pageId> --comp <compId> --terminal pc
+e10-cli designer permission fields <pageId> --source-type matrix --source-id <matrixId>
+e10-cli designer permission fields <pageId> --source-type ebuilder_form --source-id <objId>
+e10-cli designer permission common add <pageId> --comp <compId> --scope use --config @permission.json
+e10-cli designer permission common add <pageId> --comp <compId> --scope use --config @permission.json --apply
+```
+
+先读取组件和配置表，再查询真实对象/来源字段，生成配置，预览后添加 `--apply` 保存。配置参数支持内联 JSON 或 `@文件`，文件更适合复杂条件。
+
+普通规则提供 `common add/update/remove/clear`，`--scope use|disabled`，默认 `use`。矩阵及表单规则提供 `matrix add/update/remove/clear`，仅用于使用范围。所有写命令均支持 `--terminal pc|mobile`，默认 `pc`。
+
+修改或删除普通规则用 `--rule <shareKey>`；矩阵规则用 `--rule <id>`，未保存草稿可使用 `uuid`。ID 必须取自最新 `get` 或保存返回值。平台可能重建规则 ID，不能长期缓存旧 ID。
+
+`update` 未提供的属性保留原值；主体类型更换需删除原行再新增。`clear` 只清空指定范围，不清空其他范围。空范围是撤销该项限制，不能当作拒绝所有人的表达式；实际展示还受页面权限及组件行为影响。
+
+## 普通范围
+
+| `type` | 含义 | 对象 ID |
+|---|---|---|
+| `resource` | 人员 | 人员 ID |
+| `department` | 部门 | 部门 ID |
+| `subcompany` | 分部 | 分部 ID |
+| `role` | 角色 | 角色 ID |
+| `position` | 岗位 | 岗位 ID |
+| `all` | 所有人 | 省略 |
+| `allExternal` | 所有外部人 | 省略 |
+
+群组使用 `type: "group"` 和群组 ID；指定外部联系人使用 `type: "external"` 和外部联系人 ID。两者均可配置普通使用范围或禁用范围。群组基础权限类型为 `1411`，外部联系人为 `110`。每个入口仍读取自身 schema，仅在该入口提供此主体类型时允许新增。
+
+普通配置的可用属性如下；仅向对应主体传入属性。
+
+| 属性 | 说明 |
+|---|---|
+| `id` | 单个真实对象 ID；对象名称由浏览接口取得 |
+| `attributes` | 部门、分部：`subordinate` 包含下级、`include_superior` 含上级、`partTimeStaff` 包含兼职；传 `[]` 清空 |
+| `roleLevel` | 角色：`4` 所有级别、`3` 分部及总部、`0` 总部、`1` 分部、`2` 部门 |
+| `positionLevel` | 岗位：`1` 总部、`2` 指定分部、`3` 指定部门 |
+| `subcompanies` | 岗位级别为 `2` 时必填，分部 ID 数组 |
+| `departments` | 岗位级别为 `3` 时必填，部门 ID 数组 |
+| `positionAttributes` | 岗位：`partTimeStaff` 包含兼职；传 `[]` 清空 |
+| `security` | 安全级别 `{ "min": 0, "max": 100 }`；需环境启用并符合范围 |
+
+`subordinate` 与 `include_superior` 不能同时设置；可各自与 `partTimeStaff` 组合。
+
+`schema` 返回本组件权限入口的可用主体、附加选项、安全级别能力和 `disableAll`。不能拿组合页签或页面整体权限的选项替代。禁用所有人仅在 `disableAll=true` 时允许；所有外部人可用于禁用范围。
+
+```json
+{
+  "type": "position",
+  "id": "<positionId>",
+  "positionLevel": "3",
+  "departments": ["<departmentId>"],
+  "positionAttributes": ["partTimeStaff"]
+}
+```
+
+## 矩阵及 EB 表单相关范围
+
+一条规则包含来源 `source`、取值 `values` 和可选筛选条件 `condition`。来源为矩阵时使用矩阵 ID；来源为 EB 表单时使用 objId，不是 formId、布局 ID 或组件 ID。
+
+```json
+{
+  "source": { "type": "matrix", "id": "<matrixId>" },
+  "values": [
+    { "field": "<ownerColumnId>", "relation": "SELF" },
+    { "field": "<assistantColumnId>", "relation": "IMMEDIATE_SUPERIOR" }
+  ],
+  "condition": {
+    "logic": "and",
+    "children": [
+      { "field": "<departmentColumnId>", "operator": "eq", "value": [{ "id": "<departmentId>", "name": "部门名称" }] }
+    ]
+  }
+}
+```
+
+表单来源写为 `{"type":"ebuilder_form","id":"<objId>"}`，其他结构相同。`fields` 返回可用取值列和条件字段，不能任意使用目标页面字段。
+
+取值当前开放人员类型字段：`SELF` 本人、`IMMEDIATE_SUPERIOR` 直接上级、`IMMEDIATE_SUBORDINATE` 直接下属。同一字段可选择多个关系，也可选择多个取值字段。`values` 至少一行。更换来源时同时重新提供 `values` 和 `condition`；`condition:null` 撤销筛选，省略则保留原筛选。
+
+## 筛选条件
+
+条件组使用 `{"logic":"and|or","children":[...]}`，可混合嵌套；最多 12 层、500 个节点。叶子为 `{"field":"字段ID","operator":"操作符","value":值}`。单个叶子自动包装为 AND 组。
+
+| 操作 | 写入码 | 可用别名 |
+|---|---|---|
+| 等于 | `eq` | `eq` |
+| 不等于 | `neq` | `notEq` |
+| 属于 | `aggregate` | `in` |
+| 不属于 | `unaggregate` | `notIn` |
+| 为空 | `empty` | `isNull` |
+| 不为空 | `nempty` | `isNotNull` |
+
+人员、部门、分部的固定值为真实浏览对象数组，包括 `eq`、`neq`，例如 `[{"id":"<id>","name":"显示名称"}]`。文本及当前支持的 Ebuilder 条件值为字符串。为空/不为空省略 `value`，不接受右侧值。数值、日期及其他尚未开放的取值协议会报错，不能以任意 JSON 绕过。`fieldRef` 字段引用简写暂不开放。
+
+角色级别修改同时更新原生级别镜像，岗位级别变更同时更新机构取值并清除旧级别机构；命令自动处理这些字段，无需手工拼装。部门、分部及岗位的原生权限类型会随附加属性变化，不能固定复用读取到的 `permissionTargetType`。
+
+原生保存树使用 `relationship:"0"` 表示 AND、`"1"` 表示 OR；与页面事件条件码表不同。命令使用 `and/or` 自动转换。权限条件的值形状应按本入口字段处理，不能从其他浏览范围配置推断。
+
+## 保存与回读
+
+普通范围位于组件 `config.rights`，禁用范围位于 `config.disableRights`，矩阵及表单范围位于 `config.matrixRights`。矩阵的人员关系和筛选树在原生协议中分别序列化为 `matrixValueRelation`、`matrixConditionData`。
+
+命令读取完整布局，在局部修改权限后保存，保留另一终端、其他组件、事件、源码及原布局元数据。页面已有软锁或预检期间发生变化时停止覆盖。保存后重新读取，比较对象、级别、组织属性、安全范围及矩阵条件等授权含义，同时检查无关内容。平台生成的规则 ID、时间和对象展示元数据不作为失败依据。不要自行重算 `rightCompIds`。
+
+平台回读成功表示配置保存完整。组件是否可见、是否可操作还需要使用对应身份在前台检查；管理员设计器预览不能替代不同身份下的使用效果检查。
+
+群组与指定外部联系人：普通权限配置使用 `{"type":"group","id":"<groupId>"}` 或 `{"type":"external","id":"<externalId>"}`，适用于使用范围和禁用范围。以当前入口 schema 的可用类型为准；对象由当前入口浏览接口解析，不能跨环境复用 ID。
+
+群组的权限主体码为 `group`，浏览对象接口类型为 `channel`；外部联系人两处均为 `external`。CLI 自动转换浏览类型，不要将主体码直接拼成群组浏览接口。
+
+## 部门与分部对象解析
+
+组件使用范围、禁用范围、`designer permission lookup`、岗位指定部门/分部以及列表按钮 `--subjects` 复用同一个对象解析入口。优先读取 `/api/ebuilder/designer/common/browser/destData/{department|subcompany}`；请求失败、业务失败或未唯一匹配目标时，依次使用 HRM 通用 `destData` 和 HRM `data` 分页列表，按真实 ID 精确匹配。列表结果转换为权限需要的浏览对象，不能用名称代替 ID。
+
+仅部门、分部使用该兜底；人员、角色、岗位主体、群组及外部联系人的解析失败仍报原错误。岗位主体本身与岗位级别中的部门/分部分别查询。列表扫描受账号可见范围影响，默认每页 200 条、最多 100 页；所有路径都查不到时明确报错，不伪造对象写入。PC 与移动端复用同一解析方法，终端的权限保存分别维护。

package/skill-docs/references/ebuilder-designer/events/actions-interaction.md

@@ -1,108 +1,132 @@
-# 页面事件交互动作
-
-以下 config 放在 `{ "type":"动作类型", "enabled":true, "config":... }` 中。查询当前定义用 `designer event schema`；先读 [事件指南](guide-events.md) 理解单事件单动作和终端规则。
-
-## 打开页面 NewPage
-
-设置目标页面、打开形式、参数以及窗口外观。config 对应平台 linkInfo，目标信息通过 `designer event lookup --kind page --id <页面ID>` 获取。目标页面名称、所属应用等使用真实元数据。
-
-| openMode | 本事件入口的含义 |
-|---|---|
-| `"4"` | 当前页面 |
-| `"0"` | 新窗口 |
-| `"5"` | 弹出窗口 |
-| `"1"` | 右侧滑出 |
-| `"7"` | 右侧推出 |
-
-本码表不等于组合页面 openMode 或 ebSdk.openPage 的 openType。实际打开方式在 linkInfo.openMode；目标 page 中可能也保留 openMode 元数据，不能拿它覆盖本动作设置。
-
-```json
-{
-  "type":"NewPage",
-  "config":{
-    "page":{"pageId":"目标页面ID","pageName":"目标名称","pageType":"PAGE","parentId":"pages","appid":"目标应用ID","terminalScopes":"PC,MOBILE"},
-    "openMode":"5",
-    "name":"打开详情",
-    "params":[{"name":"source","value":"workbench","type":"fixed"}],
-    "modalWidth":"70%","modalHeight":"70%",
-    "pageTitle":{"nameAlias":"详情"},
-    "isBlankClose":false
-  }
-}
-```
-
-附加设置有 `icon` 图标描述、`flatToBottom`、`isRelationCustomPage`、`winSize`/`winSizeNew` 等。它们是否生效与窗口形式有关，读取对应设置后保留，不把所有尺寸字段当成同义字段。参数数组支持多个命名参数，本轮结构化参数为 name/value/type:fixed，值可包含平台表达式；不将其等同普通字符串替换。
-
-`paramsMode` 可保留本入口的 `"1"`/`"2"`。两值与界面传参模式的逐项含义尚需独立核清，命令不按其他入口的码表转换；未指定时不自动补值。存在此字段不意味着可以宣称“隐式传参无限长”。
-
-## 刷新组件 RefreshComp
-
-设置 `selectedCom` 目标组件数组；`filterIsNull`、`isOverrideFilter` 为本动作过滤选项布尔值；有过滤时携带完整 `dataset` 和 `conditionSet`。目标必须属于配置终端，both 会映射组件 ID。
-
-```json
-{"type":"RefreshComp","config":{"selectedCom":["列表组件ID"],"filterIsNull":true,"isOverrideFilter":true}}
-```
-
-SQL WHERE 条件独立存储，不能把条件文本直接放进 condition ID：
-
-```bash
-e10-cli designer event condition-create <pageId> --comp <触发组件ID> --where-file where.txt --apply
-```
-
-where.txt 是条件文本，例如 `1=1`。命令将文本 LZW 压缩，以 multipart 的 compId、conditionValue 创建条件并返回 ID；它不执行查询，也不替代数据库字段、表达式有效性及权限检查。创建是独立写入，之后保存事件失败时可能留下未引用条件，先记录 ID 再检查，不反复创建。
-
-引用形式：
-
-```json
-{"type":"sql_where","isNewFilter":true,"version":1,"data":{"condition":"返回条件ID","formDw":false,"sourceId":"目标数据源ID"}}
-```
-
-该对象放在 config.conditionSet 中，同时提供与目标组件一致的 dataset。条件创建接口没有在本命令中定义删除能力。
-
-## 关闭页面 ClosePage / 复制链接 CopyLink
-
-这两种动作不需要 config：`{"type":"ClosePage"}`、`{"type":"CopyLink"}`。关闭效果取决于页面宿主，复制效果取决于浏览器剪贴板能力，不用数据保存成功替代运行检查。
-
-## 条件控制 IF
-
-有规则判断和确认框两种模式，控制本次事件的条件结果；本入口不能在其后追加多个动作作为流程。
-
-```json
-{"type":"IF","config":{"mode":"dialog","title":"确认","content":"是否继续？","confirmText":"是","cancelText":"否"}}
-```
-
-规则使用明确的逻辑组和条件，不写平台机器 key：
-
-```json
-{"type":"IF","config":{"mode":"rule","condition":{"logic":"and","rules":[{"left":"{userid}","operator":"eq","right":"人员ID"},{"logic":"or","rules":[{"left":"20","operator":"gt","right":"15"}]}]}}}
-```
-
-本事件规则保存 `relationship:"1"` 为 AND、`"0"` 为 OR。CLI 同时生成条件树和条件显示文字；不沿用其他范围条件的逻辑码。当前可结构化编译 eq 等于、gt 大于；right 使用字符串。left 按平台表达式或输入文字原样写入，不把字段标题擅自转换为组件引用。规则模式保存 Rule；确认框保存 Dialog，切换模式移除原规则遗留字段。树最多 12 层、500 节点。
-
-## JavaScript JsCode
-
-```json
-{"type":"JsCode","config":{"code":"ebSdk.msg('操作完成');"}}
-```
-
-命令生成 compiledCode；编译失败不保存。脚本只影响当前事件环境，不在这里写页面 load 外壳或 import/export。可调用页面源码导出的函数：`pageSdk.getExports().方法名()`，前提是源码中存在对应 export。
-
-## 显示/隐藏组件 ShowHideComponent
-
-config 为数组，每项 id 是目标组件 ID，display 为 show 显示、hide 隐藏、switchover 切换：
-
-```json
-{"type":"ShowHideComponent","config":[{"id":"列表组件ID","display":"switchover"},{"id":"导航组件ID","display":"show","children":[{"id":"导航项ID","display":"hide"}]}]}
-```
-
-children 用于组件内部真实子项，并非任意 DOM 节点；不把显示隐藏当成权限控制。
-
-## 显示菜单 ShowMenu
-
-`menuType`：dropDownMenu 下拉菜单、footerMenu 底部菜单；`displayMode`：vertical 纵向、horizontal 横向；本次可用位置字段 menuPosition 包括 bottom、right，其他位置需读取本入口设置后再用。
-
-```json
-{"type":"ShowMenu","config":{"menuType":"dropDownMenu","menuPosition":"bottom","displayMode":"vertical","menuItems":[{"menuName":"显示提示","menuIcon":"","action":{"type":"JsCode","config":{"code":"ebSdk.msg('菜单执行');"}}}]}}
-```
-
-每项可配置独立 id、menuName、menuIcon。新增时省略 id 由 CLI 生成；action 编译为该菜单项的 CLICK 事件，仍只有一个动作。读取原有菜单时可见原生 menuEvent；action 与 menuEvent 二选一，不同时填。嵌套菜单事件最多 8 层，不能利用嵌套数组绕过单事件单动作限制。
+# 页面事件交互动作
+
+以下 config 放在 `{ "type":"动作类型", "enabled":true, "config":... }` 中。查询当前定义用 `designer event schema`；先读 [事件指南](guide-events.md) 理解顺序动作、递归分支和终端规则。
+
+## 打开页面 NewPage
+
+设置目标页面、打开形式、参数以及窗口外观。config 对应平台 linkInfo，目标信息通过 `designer event lookup --kind page --id <页面ID>` 获取。目标页面名称、所属应用等使用真实元数据。
+
+| openMode | 本事件入口的含义 |
+|---|---|
+| `"4"` | 当前页面 |
+| `"0"` | 新窗口 |
+| `"5"` | 弹出窗口 |
+| `"1"` | 右侧滑出 |
+| `"7"` | 右侧推出 |
+
+本码表不等于组合页面 openMode 或 ebSdk.openPage 的 openType。实际打开方式在 linkInfo.openMode；目标 page 中可能也保留 openMode 元数据，不能拿它覆盖本动作设置。
+
+```json
+{
+  "type":"NewPage",
+  "config":{
+    "page":{"pageId":"目标页面ID","pageName":"目标名称","pageType":"PAGE","parentId":"pages","appid":"目标应用ID","terminalScopes":"PC,MOBILE"},
+    "openMode":"5",
+    "name":"打开详情",
+    "params":[{"name":"source","value":"workbench","type":"fixed"}],
+    "modalWidth":"70%","modalHeight":"70%",
+    "pageTitle":{"nameAlias":"详情"},
+    "isBlankClose":false
+  }
+}
+```
+
+附加设置有 `icon` 图标描述、`flatToBottom`、`isRelationCustomPage`、`winSize`/`winSizeNew` 等。它们是否生效与窗口形式有关，读取对应设置后保留，不把所有尺寸字段当成同义字段。参数数组支持多个命名参数，本轮结构化参数为 name/value/type:fixed，值可包含平台表达式；不将其等同普通字符串替换。
+
+`paramsMode` 可保留本入口的 `"1"`/`"2"`。两值与界面传参模式的逐项含义尚需独立核清，命令不按其他入口的码表转换；未指定时不自动补值。存在此字段不意味着可以宣称“隐式传参无限长”。
+
+## 刷新组件 RefreshComp
+
+设置 `selectedCom` 目标组件数组；`filterIsNull`、`isOverrideFilter` 为本动作过滤选项布尔值；有过滤时携带完整 `dataset` 和 `conditionSet`。目标必须属于配置终端，both 会映射组件 ID。
+
+```json
+{"type":"RefreshComp","config":{"selectedCom":["列表组件ID"],"filterIsNull":true,"isOverrideFilter":true}}
+```
+
+SQL WHERE 条件独立存储，不能把条件文本直接放进 condition ID：
+
+```bash
+e10-cli designer event condition-create <pageId> --comp <触发组件ID> --where-file where.txt --apply
+```
+
+where.txt 是条件文本，例如 `1=1`。命令将文本 LZW 压缩，以 multipart 的 compId、conditionValue 创建条件并返回 ID；它不执行查询，也不替代数据库字段、表达式有效性及权限检查。创建是独立写入，之后保存事件失败时可能留下未引用条件，先记录 ID 再检查，不反复创建。
+
+引用形式：
+
+```json
+{"type":"sql_where","isNewFilter":true,"version":1,"data":{"condition":"返回条件ID","formDw":false,"sourceId":"目标数据源ID"}}
+```
+
+该对象放在 config.conditionSet 中，同时提供与目标组件一致的 dataset。条件创建接口没有在本命令中定义删除能力。
+
+## 关闭页面 ClosePage / 复制链接 CopyLink
+
+这两种动作不需要 config：`{"type":"ClosePage"}`、`{"type":"CopyLink"}`。关闭效果取决于页面宿主，复制效果取决于浏览器剪贴板能力，不用数据保存成功替代运行检查。
+
+## 条件控制 IF / ELSEIF / ELSE
+
+条件控制组织分支的执行内容；每个分支有自己的 actions，可包含多个动作以及进一步的条件控制，内部与外层共用同一套动作类型和配置方法。
+
+一般性示例：
+
+```json
+{
+  "actions":[
+    {"type":"JsCode","config":{"code":"console.info('开始');"}},
+    {"type":"IF","config":{"branches":[
+      {"mode":"rule","condition":{"left":"1","operator":"eq","right":"1"},"actions":[
+        {"type":"JsCode","config":{"code":"console.info('首分支');"}},
+        {"type":"IF","config":{"branches":[
+          {"mode":"dialog","title":"确认","content":"是否继续？","confirmText":"是","cancelText":"否","actions":[{"type":"CopyLink"}]},
+          {"mode":"else","actions":[{"type":"JsCode","config":{"code":"console.info('内层否则');"}}]}
+        ]}}
+      ]},
+      {"mode":"rule","condition":{"left":"2","operator":"gt","right":"1"},"actions":[]},
+      {"mode":"else","actions":[{"type":"JsCode","config":{"code":"console.info('否则');"}}]}
+    ]}},
+    {"type":"JsCode","config":{"code":"console.info('后续动作');"}}
+  ]
+}
+```
+
+原生保存中 IF/ELSEIF/ELSE 为同级节点，子列表为各自 events，CLI 负责把 branches 转换为该形状。也可直接使用 type:IF/ELSEIF/ELSE 与 actions 表达原生层次。首分支不能为 else，同组只有一个末尾 ELSE；多个独立 IF 组可在动作列表中先后出现。
+
+mode:rule 保存 Rule 条件；mode:dialog 保存 Dialog 的标题、内容和确认/取消文字；ELSE 无需 conditionData。切换条件模式清理旧条件字段。空 actions 表示空分支，和删除分支不同。
+
+条件表达式支持三种输入：
+
+1. 自定义文字或表达式：`{"left":"{userid}","operator":"eq","right":"人员ID"}`。
+2. 真实字段：`{"field":完整字段元数据,"operator":"本入口保存码","right":右值,"valueType":"需要时的来源类型","text":"需要时的回显文字"}`，保留字段 id/name/compType、formInfo/refObjId 等。
+3. 完整原生条件树：直接提供 isParent/relationship/datas/conditions，保留字段专属值结构，支持数字和字符串节点 key。
+
+条件组使用 `{"logic":"and","rules":[条件或嵌套组]}` 或 logic:or。保存 relationship:"1" 为 AND、"0" 为 OR。CLI 生成条件显示文字，也可在分支 config 中提供完整 conditionsText。自定义条件值支持标量；浏览对象数组等使用字段输入或原生树。字段操作符和值来源按该入口真实配置，不套用其他范围配置的码表；没有右值的操作符不要伪造选择值。
+
+条件表达式的 AND/OR 嵌套决定分支是否命中，动作树的嵌套决定命中后执行什么，两者分别维护。后续节点如何衔接异步操作和确认取消，需要遵循平台动作运行语义，不能只靠保存结构推定。
+
+## JavaScript JsCode
+
+```json
+{"type":"JsCode","config":{"code":"ebSdk.msg('操作完成');"}}
+```
+
+命令生成 compiledCode；编译失败不保存。脚本只影响当前事件环境，不在这里写页面 load 外壳或 import/export。可调用页面源码导出的函数：`pageSdk.getExports().方法名()`，前提是源码中存在对应 export。
+
+## 显示/隐藏组件 ShowHideComponent
+
+config 为数组，每项 id 是目标组件 ID，display 为 show 显示、hide 隐藏、switchover 切换：
+
+```json
+{"type":"ShowHideComponent","config":[{"id":"列表组件ID","display":"switchover"},{"id":"导航组件ID","display":"show","children":[{"id":"导航项ID","display":"hide"}]}]}
+```
+
+children 用于组件内部真实子项，并非任意 DOM 节点；不把显示隐藏当成权限控制。
+
+## 显示菜单 ShowMenu
+
+`menuType`：dropDownMenu 下拉菜单、footerMenu 底部菜单；`displayMode`：vertical 纵向、horizontal 横向；本次可用位置字段 menuPosition 包括 bottom、right，其他位置需读取本入口设置后再用。
+
+```json
+{"type":"ShowMenu","config":{"menuType":"dropDownMenu","menuPosition":"bottom","displayMode":"vertical","menuItems":[{"menuName":"显示提示","menuIcon":"","action":{"type":"JsCode","config":{"code":"ebSdk.msg('菜单执行');"}}}]}}
+```
+
+每项可配置独立 id、menuName、menuIcon。新增时省略 id 由 CLI 生成；action 编译为该菜单项的 CLICK 事件；可传单动作，或 {actions:[...]} 配置多个动作及递归条件。读取原有菜单时可见原生 menuEvent；action 与 menuEvent 二选一，不同时填。菜单项动作与普通触发共用动作列表模型，可在节点编辑时按动作 ID 递归定位。

package/skill-docs/references/ebuilder-designer/events/guide-events.md

@@ -1,57 +1,112 @@
-# 页面与组件事件配置
-
-## 整体功能介绍
-
-事件配置把页面或组件的触发时机与一个动作绑定，可实现打开/关闭页面、刷新、条件判断、JavaScript、组件显隐、菜单、集成及其他交互。它保存于页面布局的事件设置中，与页面源码 JS/CSS 分别维护。
-
-**同一配置对象的单击 CLICK 和加载完成 DIDMOUNT 各最多一条，每条最多一个动作。两种事件可以同时存在。** 修改事件是替换该动作，不追加动作列表；没有动作的事件不承担业务行为。条件控制不是包含多个动作的流程编排，需要复杂步骤时绑定已经配置好的逻辑流或使用相应事件脚本。
-
-配置对象可为页面、组件，或组件中的导航/按钮子项。每个对象独立维护事件；显示菜单的菜单项也可有自己的单击事件。页面事件位于 `layout.config.eventGroup`，组件事件位于 `comp.config.eventGroup`，子项事件位于对应子项。它们采用双层 `eventGroup`，条目内 `events` 只包含一个动作，不把平台数组形式理解为支持多个动作。
-
-## 查询与命令
-
-```bash
-e10-cli designer event schema
-e10-cli designer event get <pageId> --comp <compId> --terminal pc
-e10-cli designer event get <pageId> --terminal pc
-e10-cli designer event set <pageId> --comp <compId> --trigger CLICK --config @action.json
-e10-cli designer event set <pageId> --comp <compId> --trigger CLICK --config @action.json --apply
-e10-cli designer event enable <pageId> --comp <compId> --trigger CLICK --value false --apply
-e10-cli designer event remove <pageId> --comp <compId> --trigger DIDMOUNT --apply
-```
-
-默认预览，`--apply` 保存。`set` 在没有该事件时新增，在已有该事件时替换唯一动作，保留另一种事件。`enable` 只改动作启用标记；`remove` 删除指定触发事件。不存在事件时删除会报错，不将其当成成功。
-
-省略 `--comp` 操作页面事件。操作直接子项时传 `--comp`、`--collection menuConfig|btnGroup|navMenus|newButtons`、`--item <子项ID>`，按真实 ID 定位，不按显示名称或数组下标猜测。
-
-配置统一为：
-
-```json
-{"type":"JsCode","enabled":true,"config":{"code":"ebSdk.msg('操作完成');"}}
-```
-
-`type` 为本入口动作类型，`enabled` 默认为 true，`config` 为该动作的设置。普通动作配置见 [交互动作](actions-interaction.md)，外部资源和宿主相关动作见 [集成动作](actions-integration.md)。
-
-## 终端与保存
-
-`--terminal pc|mobile|both`，默认 pc。单端修改保留另一端；both 以 PC 组件为源，通过双向 `refCompId` 定位 MOBILE 组件。刷新目标、显隐目标会转换为对应终端的组件 ID，缺少配对则拒绝。子项必须在对应终端存在相同真实子项 ID；不按名称猜测子项映射。
-
-JavaScript 和集成参数属于不透明业务内容，不在字符串内部替换组件 ID。两端需要不同代码或打开方式时，分别设置 pc/mobile，不使用 both 强行覆盖。打开方式只控制对应动作，不改变目标页面的布局或权限。
-
-保存前读取整页双端布局和编辑状态；页面已锁定时停止，不解除他人编辑锁。保存前再次检查并发变化，保存后核对组件、事件、页面配置和源码，再释放本次保存软锁。其他事件、其他组件、源码和主题配置均保留。失败或响应丢失时先 get 查询状态，不重复盲写。
-
-修改动作类型时仅生成新类型的配置，移除上一类型遗留的参数。更新同一事件仍需提供完整 config，不对缺少的动作参数作隐式继承。
-
-## 编写边界
-
-事件 JavaScript 的 `code` 与 `compiledCode` 同步维护；这里只编译脚本片段，不使用页面源码的 JSONP/load 外壳，不使用 import/export。`ebSdk`、`pageSdk` 和事件环境由平台提供。异步动作衔接可使用仅适用于事件动作的 `asyncFn`，见 [页面 SDK 基础](../page-source/sdk-foundations.md)。
-
-页面源码 `pageSdk.on('pageLoad')` 与事件配置 `DIDMOUNT` 是不同入口，不混写名称。涉及组件内部数据时按页面 SDK 的 compLoad 等时机处理；不要在加载完成动作中无条件刷新自身，造成重复加载。
-
-配置保存检查和前台行为检查分别判断。设备、企业微信、签署和报表依赖对应资源及运行宿主；不能因动作成功写入普通页面就认定这些外部功能已经执行成功。
-
-## 当前支持范围
-
-18 种动作可识别、查询和保留；其中 17 种支持本指南所列结构的新增/替换。StartSignAction 仅支持已有动作的查询、启停、删除，非空签署目标的新增结构需补充后开放。规则条件结构化编译当前支持 eq、gt 和 and/or 嵌套；不将其他模块的操作符或逻辑码直接拿来填。
-
-原有导航专用命令只覆盖其特定跳页配置，不代表通用事件能力；统一事件设置使用本组命令。新增事件或动作排序不适用于这里。
+# 页面与组件事件配置
+
+## 整体功能介绍
+
+事件配置让页面、组件或组件子项在指定触发时机执行一组有顺序的动作，可实现打开页面、刷新、JavaScript、组件显隐、菜单和集成调用。条件控制把动作组织为 IF/ELSEIF/ELSE 分支；每个分支内部仍然是同样的动作列表，可包含多个动作和进一步的条件控制。
+
+事件配置与页面源码 JS/CSS、表单 JSSDK 事件分别维护。复杂交互可以直接组合事件与条件，不要求一律改写为 JS 或逻辑流；需要代码计算或已有业务流程时再绑定对应动作。
+
+## 模型与存储位置
+
+配置对象拥有触发记录，例如 CLICK 单击、DIDMOUNT 加载完成、列表的 CLICKDATA 单击每一条数据。每种触发记录的 events 是顺序动作列表，支持多个动作；不同触发分别维护。触发类型以对象实际提供的选项为准，不要求所有组件都具有所有触发。
+
+| 对象 | 存储位置/定位方式 |
+|---|---|
+| 页面 | layout.config.eventGroup；省略 --comp |
+| 组件 | comp.config.eventGroup；指定 --comp |
+| 导航/按钮组等子项 | --collection menuConfig/btnGroup/navMenus/newButtons，指定 --item |
+| 标签栏菜单 | --collection items |
+| 列表自定义操作按钮 | --collection listButtons，对应 buttonConfig.btns[].actions |
+| 自定义页面帮助按钮 | --collection customPageButtons，对应按钮 event.value；只配置 CLICK |
+| 显示菜单中的菜单项 | ShowMenu 的 menuItems[].menuEvent |
+
+以上事件容器采用双层数组；其中的触发记录包含有序 events。同一种触发按唯一记录定位，动作数量不限制为一个。条件分支原生保存为同级 IF、零至多个 ELSEIF、可选 ELSE，各分支用自己的 events 保存子动作。条件组与普通动作可以继续组成外层顺序列表。
+
+动作顺序与异步等待不是同一概念：配置按顺序组织；异步完成、失败是否中断、确认框取消后如何继续，取决于动作运行实现。编写异步事件脚本时按 SDK 的 asyncFn 规则处理，不凭数组顺序承诺所有异步请求自动等待完成。
+
+## 查询与整体配置
+
+```bash
+e10-cli designer event schema
+e10-cli designer event get <pageId> --comp <compId> --terminal pc
+e10-cli designer event get <pageId> --terminal pc
+e10-cli designer event set <pageId> --comp <compId> --trigger CLICK --config @sequence.json --apply
+```
+
+sequence.json 使用完整动作列表：
+
+```json
+{"actions":[{"type":"JsCode","config":{"code":"console.info('开始');"}},{"type":"CopyLink"}]}
+```
+
+默认预览，--apply 保存。set 明确替换该触发的完整动作列表，保留其他触发。actions:[] 清空列表并保留触发记录；remove 删除整个触发记录。兼容旧单动作输入 {type,enabled?,config?}，但已有多个动作时拒绝用旧单动作输入隐式覆盖，改用完整 actions 或按 ID 编辑。
+
+可使用 {nativeActions:[平台原生动作节点]} 整体配置原生结构，和 actions 二选一。原生节点须有 id/type，分支必须符合结构；普通未知节点可保留。原生 JS 仍根据 code 重新编译，刷新和显隐检查目标组件。此入口不把未知属性当成已掌握的功能，业务字段和值来源须使用对应入口的真实结构。
+
+```bash
+e10-cli designer event remove <pageId> --comp <compId> --trigger DIDMOUNT --apply
+e10-cli designer event enable <pageId> --comp <compId> --trigger CLICK --value false --apply
+```
+
+enable 兼容入口只用于唯一动作；有多个动作时用 action enable 指定动作 ID。删除不存在的触发会报错。
+
+## 单节点与动作顺序
+
+```bash
+e10-cli designer event action add <pageId> --comp <compId> --trigger CLICK --config @action.json --apply
+e10-cli designer event action update <pageId> --comp <compId> --trigger CLICK --action-id <actionId> --config @action.json --apply
+e10-cli designer event action remove <pageId> --comp <compId> --trigger CLICK --action-id <actionId> --apply
+e10-cli designer event action enable <pageId> --comp <compId> --trigger CLICK --action-id <actionId> --value false --apply
+e10-cli designer event action order <pageId> --comp <compId> --trigger CLICK --config @ids.json --apply
+```
+
+- add 默认追加；--before <兄弟ID> 插入指定节点之前。
+- --parent <分支ID> 定位该分支内部动作列表。省略时 add/order 操作触发的顶层列表；update/remove/enable 按 ID 递归定位。
+- update 提供完整动作 type/config；同类型的内部动作不做隐式参数合并。修改条件分支时不传 actions 会保留其原有子动作，明确 actions:[] 才清空。
+- order 输入该层所有普通动作 ID 和 IF 组首节点 ID，IF/ELSEIF/ELSE 作为完整组一起移动，不把分支拆开排序。
+- 删除 IF 会连同它的 ELSEIF/ELSE 组一起删除；删除其他分支只删除该分支及其后代。未知兄弟动作及其配置保留。
+- 已有节点修改保留 ID；新增生成 ID；用 get 读取真实 ID，不按名称或数组序号猜测。
+
+## 条件分支
+
+完整配置可使用 IF 的 config.branches；首项为 IF，之后为 ELSEIF，mode:else 为末尾 ELSE。每项 actions 支持所有已接入动作及嵌套条件。详见 [交互动作与条件示例](actions-interaction.md)。
+
+```bash
+e10-cli designer event branch add <pageId> --comp <compId> --trigger CLICK --parent <ifId> --config @branch.json --apply
+e10-cli designer event branch update <pageId> --comp <compId> --trigger CLICK --action-id <branchId> --config @branch.json --apply
+e10-cli designer event branch remove <pageId> --comp <compId> --trigger CLICK --action-id <branchId> --apply
+e10-cli designer event branch enable <pageId> --comp <compId> --trigger CLICK --action-id <branchId> --value false --apply
+e10-cli designer event branch order <pageId> --comp <compId> --trigger CLICK --parent <ifId> --config @branch-ids.json --apply
+```
+
+branch add 接受 type:ELSEIF 或 ELSE，指定所属 IF；默认 ELSEIF 插到 ELSE 前，ELSE 放末尾。order 提供同组全部分支 ID，IF 保持首位、ELSE 保持末尾。分支与其内部动作分别启停。结构化配置和原生配置可以表达同样的分支树，不限制分支只有一个子动作。
+
+## 条件字段与目标查询
+
+```bash
+e10-cli designer event fields <pageId> --comp <componentId> --terminal pc
+e10-cli designer event targets --kind apps
+e10-cli designer event targets --kind menu --app-id <appId> --page-id <pageId> --terminal pc
+e10-cli designer event targets --kind layouts --obj-id <objId> --terminal pc
+e10-cli designer event targets --kind types
+e10-cli designer event targets --kind workflow --config @query.json
+e10-cli designer event targets --kind report --config @query.json
+```
+
+fields 按组件当前 dataset 查询字段和 conditionType，并携带数据扩展参数，支持 --config 附加参数。没有数据源时不伪造字段，可使用自定义条件或取得相应来源后提供原生条件树。字段、条件表达式、分支动作是三个不同层次。
+
+目标菜单使用事件入口 entranceType=2。布局查询使用 complete，而非只有浏览控件信息的 associate；支持 --search。workflow/report 保留原生浏览参数，可用 --config 指定搜索、分类和分页；报表默认使用分类 0（全部）；返回分页信息，不将一页当成全量。系统类型查询使用平台提供的选择器，不固定只能选择普通页面或表单布局。需要已知 ID 的资源查询及 ESB 输入结构见 [集成动作](actions-integration.md)。
+
+条件操作符要区分候选显示码与保存码；field.conditionType 提供当前可选内容，不直接据其名称推定保存协议。条件可使用自定义输入、完整字段对象或完整原生树，保留 formInfo/refObjId 等来源属性，不只写字段名称。原生树允许数字或字符串 key/parentNode，节点 key 需唯一，同一字段 ID 可以重复使用。
+
+## 终端与保存
+
+--terminal pc|mobile|both，默认 pc。both 通过双向 refCompId 定位组件；递归处理所有顺序动作、条件后代和显示菜单中的刷新/显隐组件引用。新增结构化动作 ID 两端对应；已有不同 ID 的子项或动作不按名称猜测，请分别配置。显隐内部子项要求同 ID 或明确配对关系，否则停止。代码及业务字符串不做组件 ID 字符串替换。
+
+保存前读取完整双端布局，检查模块、编辑权限、软锁和并发变化；只改选定对象。保存后核对完整事件树、顺序、分支、两端组件、页面配置和源码，在 finally 中释放本次保存软锁。回读失败明确报错，先 get 查询实际状态，不盲目重试。不解除其他编辑会话持有的锁。
+
+## 编写边界
+
+事件 JS 的 code 与 compiledCode 同步编译，使用脚本片段，不写页面源码 JSONP/load 外壳或 import/export。ebSdk/pageSdk 和事件环境由平台提供；页面源码 pageSdk.on('pageLoad') 与 DIDMOUNT 分别维护。加载事件不要无条件刷新自身，避免重复加载。
+
+18 种原有动作与 ELSEIF/ELSE 分支节点可读取和保留；StartSignAction 的非空签署目标新增仍需对应保存结构，其余动作按各自动作参数维护。原生结构可以保留已有签署配置，不等于已经提供签署目标的结构化编译方法。设备、企业微信、ESB、逻辑流和报表还依赖真实资源及宿主，保存回读不替代业务运行检查。