weaver-e10-builder 1.7.0 → 1.7.2

package/skill-docs/references/form/guide-form-permission.md

@@ -150,29 +150,41 @@ e10-cli form permission data update <objId> <appId> --right-id <id> \
 
 ## 导入导出权限
 
-导入导出是**独立分类**（`data_imp_exp`），不在共享权限里。命令：
+导入导出是**独立分类**，不在共享权限里；授权对象分两类：通用对象 `data_imp_exp`、矩阵相关 `data_imp_exp_matrix`。
 
 ```bash
 e10-cli form permission imp-exp list <objId> <appId>
 
+# 通用对象
 e10-cli form permission imp-exp add <objId> <appId> \
-  --org-type <类型> [--org-id <id>] \
+  --target general --org-type <类型> [--org-id <id>] \
   --rights export import delete-import \
   [--update-import] [--export-details] [--export-attachment] \
   [--export-field-range listShowField|allField]
 
+# 矩阵相关（真矩阵 / e-Builder 表单）
+e10-cli form permission imp-exp add <objId> <appId> \
+  --target matrix --matrix <矩阵id或名称> \
+  [--matrix-value <取值字段>...] [--matrix-condition-raw <JSON>] \
+  --rights export import
+
+# 改/看
 e10-cli form permission imp-exp update <objId> <appId> --right-id <id> [要改的项]
 e10-cli form permission imp-exp show <objId> <appId> --right-id <id>
 ```
 
 - `rights`：`export=8` 导出、`import=9` 导入、`delete-import=93` 删除导入数据；93 必须与 9 同选。
 - `--update-import`：允许更新导入（`importType` 加 1）；勾 93 时自动带更新导入。
-- 授权对象与共享权限同一套 11 种通用对象（含兼职岗位、职级、外部联系人、所有外部联系人）。
+- `--target`：`general` 通用对象（默认）/ `matrix` 矩阵相关。未给 `--target` 时，带 `--matrix`/`--eb-form`/`--matrix-value*` 等矩阵选项会自动按矩阵处理。
+- 通用对象与共享权限同一套 11 种对象（含兼职岗位、职级、外部联系人、所有外部联系人）。
+- 矩阵相关：`--matrix` 真矩阵、`--eb-form` e-Builder 表单；`--matrix-value` 指定取值字段（名称或 `id:名称:valueType`），缺省取矩阵第一个可用取值字段（e-Builder 表单优先「创建者」）；`--matrix-value-raw` / `--matrix-condition-raw` 为原始 JSON 兜底。矩阵类不能用 `--org-type/--org-id/--org-name`。
 - `--export-field-range`：`listShowField` 列表显示字段（默认）/ `allField` 全部字段。
 - `--export-details` / `--export-attachment`：导出明细、导出附件。
-- 修改只改点名项，整行回写并回读。
+- 修改只改点名项，整行回写并回读。`update` 可切换通用/矩阵：切到通用必须给 `--org-type`；只改权限项不给矩阵选项时沿用当前矩阵来源与条件。矩阵取值字段与条件按语义回读（临时 id / 条件节点 key 不同不算失败）。
+
+导入导出权限**不提供**权限描述、更新导入校验数据编辑权限、导入关联布局、优先级、同步至其他表单这些配置参数。
 
-导入导出权限**不提供**权限描述、更新导入校验数据编辑权限、导入关联布局、优先级、同步至其他表单这些配置项。
+`imp-exp update` 会把当前行已有的权限描述（`rightDesc/rightDescLabelId`）和导入关联布局（`layoutId/mobileLayoutId/editLayoutId/mobileEditLayoutId`）**原样保留**，避免更新其它项时把它们清空；但 CLI 仍无法设置或修改这些字段。`layoutOrder` 同样保留当前值，但不可调。
 
 ## 保存后重构
 

package/skill-docs/references/menu/guide-menu-config.md

@@ -0,0 +1,130 @@
+# 菜单地址与目录配置
+
+菜单将页面、表单布局、流程或链接挂入应用导航。已有菜单可以修改跳转目标，目录可以绑定目标成为链接，链接也可以清空目标成为目录；菜单名称、父级、排序、图标、功能描述、显示条件及独立权限保持原配置。PC 与移动端菜单是独立记录，应分别查询、配置。
+
+## 查询与选择目标
+
+```bash
+e10-cli menu list <appId> --terminal pc --raw
+e10-cli menu get <appId> <menuId> --terminal pc
+e10-cli menu targets --kind apps
+e10-cli menu targets --kind menu --app-id <targetAppId> --terminal pc
+e10-cli menu targets --kind layouts --obj-id <formObjId> --terminal pc
+e10-cli menu targets --kind types --terminal pc
+e10-cli menu targets --kind workflow --config '{"current":1,"pageSize":20}'
+e10-cli menu targets --kind report --config '{"current":1,"pageSize":20}'
+```
+
+目标树提供该入口可选的地址；布局查询提供具体终端的可选布局；类型、流程与报表浏览支持通过 `--config` 传入原生搜索及分页参数。返回保留分页信息，应继续查询后续页。目标不限定为普通页面或表单布局，按目标查询结果配置其原生类型和属性。菜单目标树使用菜单入口 `entranceType=1`，不要照搬事件入口参数。
+
+## 修改目标及目录转链接
+
+```bash
+e10-cli menu link set <appId> <menuId> --terminal pc --config @target.json
+e10-cli menu link set <appId> <menuId> --terminal pc --config @target.json --apply
+```
+
+默认预览写入结构，`--apply` 执行保存与回读。简单链接：
+
+```json
+{"url":"https://example.com/help?from=menu","openMode":"new-window"}
+```
+
+内部路径以 `/` 开头，HTTP/HTTPS 地址保留协议和查询参数。`menu add <name> <path> <appId>` 同样支持完整 HTTP/HTTPS 地址。
+
+选择平台目标时使用以下结构，ID、类型、目标地址来自候选查询及对应入口：
+
+```json
+{
+  "page":{"pageId":"<targetId>","pageName":"目标名称","pageType":"PAGE","terminalScopes":"PC,MOBILE","appid":"<targetAppId>"},
+  "menuUrl":"/sp/ebdpage/view/<targetId>",
+  "params":[],
+  "openMode":"default"
+}
+```
+
+`page.pageName` 为目标名称，不修改菜单自己的显示名称；改菜单名使用 `menu rename`。`params` 是完整参数数组，切换目标时缺省清空旧参数。可携带 `selectLayout`、`urlLinkType`、`linkType`、`remoteAppId`、`pageExtend` 等对应目标属性，未提供的其他配置保留。
+
+| 目标 | 配置要点 |
+| --- | --- |
+| 普通页面 | `pageType=PAGE`，pageId 为页面 ID |
+| 表单布局 | `pageType=LAYOUT`，pageId 使用 `<viewType>_<formObjId>`；查询得到的 `<viewType>/<formObjId>` 自动转换为菜单形状。`selectLayout` 指定 `{id,name,clientType}`，布局 ID 与表单对象 ID 含义不同 |
+| 流程系统页面 | 使用候选的类型和 pageId，例如 `WORKFLOW` 下的 `todo`，不要按普通页面拼接地址 |
+| 自定义流程入口 | 保留候选类型（如 `cus_workflow`）及相应目标属性；地址包含菜单 ID 时须使用当前菜单 ID，不能复制其他菜单的完整地址 |
+| 其他原生目标 | 按查询结果设置 page/menuUrl 及该目标所需属性，不套用其他入口的码表 |
+
+打开方式只使用本菜单入口的码表：`default` / `1` 为默认窗口，`new-window` / `2` 为新窗口。参数示例：`{"name":"id","nameType":"dataId","value":"<dataId>","type":"fixed"}`；参数名称和类型按目标需要配置。
+
+## 链接转目录
+
+```bash
+e10-cli menu link clear <appId> <menuId> --terminal pc
+e10-cli menu link clear <appId> <menuId> --terminal pc --apply
+```
+
+清空会显式提交空 pageId、空 pageName、null pageType 及空参数，省略 menuUrl。回读以 `pageType=EMPTY`、空 pageId 为有效目标判断；后台可能保留旧 menuUrl 或不再使用的 selectLayout，它们不代表仍有有效跳转目标。重新绑定时必须提交新的目标地址。
+
+## 保存与检查
+
+写入前核对应用与终端归属，并读取完整详情；写后核对有效目标、参数、菜单原有配置及独立的可见/禁用权限。权限存储在菜单权限表，不可把详情中的空 shareMap 当作没有权限。平台可能归一化 menuType、linkType，或不回显 pageExtend，不能用原始响应字段完全相等替代目标语义检查。
+
+在应用前台分别打开 PC/移动端测试入口，检查跳转目标、参数效果和打开窗口；清空后的菜单应表现为目录。接口回读不能代替浏览器中的跳转与目标页面运行检查。
+
+## 菜单属性、图标、功能描述和显示条件
+
+菜单属性决定导航是否显示、前台初始是否启用、进入应用时的默认选择，以及图标和帮助描述。它们与权限分开：隐藏菜单改变导航展示，默认启用改变初始状态，权限决定哪些对象可使用或被禁用。
+
+```bash
+e10-cli menu configure <appId> <menuId> --terminal pc --config @settings.json
+e10-cli menu configure <appId> <menuId> --terminal pc --config @settings.json --apply
+```
+
+局部更新，省略的属性保持不变：
+
+```json
+{
+  "visible":true,
+  "enabled":true,
+  "defaultSelected":false,
+  "description":"<p>此菜单展示业务数据与相关操作。</p>",
+  "icon":{"path":"#<iconName>","iconDisplayType":"line"}
+}
+```
+
+| 配置 | 作用及保存值 |
+| --- | --- |
+| visible | 显示 true → showType="1"，隐藏 false → "2" |
+| enabled | 前台默认启用 true → defaultFrontEnable="1"，关闭 false → "0" |
+| defaultSelected | 默认选中，布尔值；设为 false 可取消。设置默认项后需检查其他菜单的默认状态 |
+| description | 功能描述，保存富文本 HTML；空字符串清空 |
+| icon | 完整图标对象；null 清空。顶级菜单提供图标设置，子级是否展示图标取决于导航样式 |
+| condition | 完整显示条件树；{} 清空 |
+
+图标候选查询：
+
+```bash
+e10-cli menu icons --kind types
+e10-cli menu icons --kind icons --search <关键词>
+e10-cli menu icons --kind folders
+```
+
+`types` 返回分类，`icons` 返回图标目录与可直接使用的 `icon` 对象，包含 `path` 和 `iconDisplayType`；`folders` 返回图片库目录。按返回候选选择图标，不把示例图标当作唯一可选值。图标写入 `icon`；`activeIcon` 是另一个字段，不用于替代它。菜单详情中的 icon 是 JSON 字符串，保存时转换为对象。
+
+显示条件控制当前应用标识等条件满足时是否展示菜单，与人员可见范围是两套配置。应用标识候选：
+
+```bash
+e10-cli menu condition-candidates --search <关键词>
+```
+
+返回开关与完整候选数据；可用 `--config @query.json` 补充原生查询参数。条件树组使用 `relationship="1"` 表示 AND、`"0"` 表示 OR，`datas` 存放子组或条件叶子。应用标识叶子使用 `$alreadyInstalledSpecialty$`，`fieldType/compType=EbuilderAppTag`；`conditions.func=contains` 表示包含、`uncontains` 表示不包含，`matchType="or"`，`value` 为所选应用标识候选对象数组。原生示例：
+
+```json
+{"condition":{
+  "key":"group","isParent":true,"isNewFilter":true,"relationship":"1","parentNode":"","version":1,
+  "datas":[{"key":"item","isParent":false,"parentNode":"group","id":"$alreadyInstalledSpecialty$","fieldName":"$alreadyInstalledSpecialty$","fieldType":"EbuilderAppTag","compType":"EbuilderAppTag","text":"应用标识","type":"condition","objId":"","mainField":true,"multiSelect":true,"subTableId":"","conditions":{"func":"contains","matchType":"or","value":[{"id":"<candidateId>","ebAppTag":"<tag>","ebTagName":"<名称>","content":"<名称>"}],"text":["<名称>"],"isEsb":false}}]
+}}
+```
+
+同组、子组和叶子应使用不同 key，parentNode 对应所属组。按当前候选构造条件，不固定为某个应用标识。
+
+菜单可见范围、范围内禁用及各对象附加属性见 [菜单权限配置](guide-menu-permission.md)。

package/skill-docs/references/menu/guide-menu-permission.md

@@ -0,0 +1,94 @@
+# 菜单权限配置
+
+菜单权限决定哪些人可以看到或使用菜单，以及在可见对象中排除哪些对象。菜单的“可见范围”和“可见范围内禁用”分别保存，新增一条禁用规则不会替代可见规则。部门、分部、岗位、角色可附加组织范围、兼职、角色级别等设置，以当前环境权限表单提供的选项为准。
+
+## 先查询完整配置与候选
+
+```bash
+e10-cli menu permission schema <appId> <menuId> --terminal pc --scope visible
+e10-cli menu permission schema <appId> <menuId> --terminal pc --scope disabled
+e10-cli menu permission get <appId> <menuId> --terminal pc
+e10-cli menu permission browse <appId> <menuId> --type department --operation complete --config '{"searchValue":"<关键词>"}'
+e10-cli menu permission browse <appId> <menuId> --type department --operation data --config '{"current":1,"pageSize":20}'
+e10-cli menu permission browse <appId> <menuId> --type department --operation destData --config '{"selectIds":"<departmentId>","selectedData":[]}'
+```
+
+schema 返回对象类型、角色级别、岗位范围、部门/分部与岗位属性、安全级别开关，以及对象浏览器的模块、类型、附加参数。browse 按这些元数据查询，支持 associate、complete、prop、condition、data、count、leftData、destData；分页和搜索字段按返回的浏览条件配置，不假设所有对象都使用同一个姓名字段。保留完整候选对象，写入时根据真实 ID 回填。
+
+部门、分部回填先使用本菜单入口的 destData；失败时使用 HRM 回填和组织列表兜底，按真实 ID 精确匹配。不要仅用名称推断唯一对象。get 返回两组完整授权行，顺序为可见、禁用；维护行使用 `permissionShareBean.id`，不是部门/人员等主体 ID。接口失败应作为错误处理，不能解释为空权限。
+
+## 新增、完整替换、删除
+
+```bash
+e10-cli menu permission entry add <appId> <menuId> --scope visible --config @permission.json
+e10-cli menu permission entry add <appId> <menuId> --scope visible --config @permission.json --apply
+e10-cli menu permission entry replace <appId> <menuId> --scope visible --entry-id <grantId> --config @permission.json --apply
+e10-cli menu permission entry remove <appId> <menuId> --scope disabled --entry-id <grantId> --apply
+```
+
+三项默认预览，`--apply` 保存。entry add 不隐式删除其他授权；需要收窄范围时，在确认新规则已存在后，显式删除“所有人”授权。旧的 `menu permission add/remove` 简便入口保留，add 原有自动撤销所有人的语义不变；完整属性配置使用 entry 系列。
+
+replace 接收完整新配置，以删除旧行、建立新行完成替换，授权行 ID 会变化；它不是原子事务。新增失败时尝试恢复原授权，并报告恢复结果。写入中断或报错后先 get 查询现状，再重试。按当前终端与范围操作，不把 PC 菜单 ID 用于移动端。
+
+通用输入：
+
+```json
+{"type":"department","id":"<departmentId>","attributes":["subordinate","partTimeStaff"]}
+```
+
+| 类型 | type | 配置 |
+| --- | --- | --- |
+| 人员 | resource | id：真实人员 ID |
+| 群组 | group | id：真实群组 ID；浏览器类型为 channel |
+| 外部联系人 | external | id：真实外部联系人 ID，与所有外部人不同 |
+| 职级 | grade | id：职级 ID；安全级别按环境能力配置 |
+| 部门 | department | id；attributes 可选包含下级、兼职 |
+| 分部 | subcompany | id；attributes 可选包含下级、兼职 |
+| 角色 | role | id；roleLevel |
+| 岗位 | position | id；positionLevel、subcompanies/departments、positionAttributes |
+| 所有人 | all | 无需 id |
+| 所有外部人 | allExternal | 无需 id |
+
+### 附加属性
+
+- `attributes`：`subordinate` 包含下级，`partTimeStaff` 包含兼职；以 schema 的 department_attribute 为准。
+- `roleLevel`：`4` 所有级别、`3` 分部及总部、`0` 总部、`1` 分部、`2` 部门。
+- `positionLevel`：`1` 总部、`2` 指定分部、`3` 指定部门。选择 `2` 时提供 `subcompanies:["<id>"]`；选择 `3` 时提供 `departments:["<id>"]`。
+- `positionAttributes`：`partTimeStaff` 包含兼职；以 schema 的 position_attribute 为准。
+- `security:{"min":0,"max":100}`：安全级别区间，环境启用安全级别时使用，不替换成其他模块的默认范围。
+
+```json
+{"type":"role","id":"<roleId>","roleLevel":"2"}
+```
+
+```json
+{"type":"position","id":"<positionId>","positionLevel":"2","subcompanies":["<subcompanyId>"],"positionAttributes":["partTimeStaff"]}
+```
+
+## 群组与外部联系人
+
+两类均支持候选查询、可见/禁用范围新增、完整替换及按授权行删除：
+
+```bash
+e10-cli menu permission browse <appId> <menuId> --type group --operation complete --config '{"searchValue":"<关键词>"}'
+e10-cli menu permission browse <appId> <menuId> --type external --operation complete --config '{"searchValue":"<关键词>"}'
+e10-cli menu permission entry add <appId> <menuId> --scope disabled --config @permission.json --apply
+```
+
+群组输入 `{"type":"group","id":"<groupId>"}`；外部联系人输入 `{"type":"external","id":"<externalId>"}`。使用真实 ID 区分同名候选；群组底层浏览器是 `channel`，保存对象仍为 `group`。外部联系人保存为 `external`，不能用人员 resource 或所有外部人 allExternal 替代。
+
+保存时保留浏览对象的名称、头像和附加属性，分别放入 obj_id_group / obj_id_external 数组；顶层 id 为 null，targetId 为主体 ID。新增码为群组 1411、外部联系人 110。不要把授权行 ID 与主体 ID 混用。候选为空时先检查环境、范围、搜索条件和分页，不构造示例对象写入。
+
+## 扩展对象与原生配置
+
+schema 返回当前权限服务提供的类型和属性，可能比实际入口显示的选项更广；不能仅凭共享表单元数据推断页面上一定存在某项设置。以具体菜单入口和其保存协议配置，不把其他权限入口的能力自动纳入本菜单范围。
+
+structuredTypes 列出提供通用输入构建的类型，nativeTypes 列出需要原生配置的类型。其他实际可用的扩展类型可通过 `{"type":"<type>","native":{...}}` 提交当前菜单入口的完整原生授权行；native 至少包含 objType、targetType、targetId 和该类型要求的对象/条件字段。保留完整附加设置，不用其他页面或组件权限的类型码替代。只有候选而没有保存结构时，先取得该入口的保存报文。
+
+## 协议与回读
+
+菜单权限使用独立权限表，`permissionId=sys_view`，`sourceId=menuId`，`sourceType=1`，`moduleId=cus_app_system`；permissionType 为 `1` 可见、`-1` 范围内禁用。不要把 page 的 viewRight 或组件的 ebdcomm_view 整体复制到这里。
+
+通用新增码：职级 `0`、人员 `1`、部门 `2`、分部 `5`、角色 `10`、群组 `1411`、外部联系人 `110`、所有人 `11`、总部岗位 `1311`、指定分部岗位 `13`、指定部门岗位 `12`、所有外部人 `1101`。存储后类型码可能按下级、兼职等属性变化，职级存储码可能为 `32`；删除使用完整回读行及 permissionShareBean，不用新增码反推删除报文。
+
+权限列表有分页，需读完；详情 getMenu 中空 shareMap 不代表没有权限。保存后检查对象、范围、角色/岗位级别、组织属性和机构是否一致，安全级别可能位于 permissionShareBean 的 targetMinSecLevel/targetMaxSecLevel。后台返回成功不等于配置语义正确。