weaver-e10-builder 1.7.0 → 1.7.1

package/skill-docs/references/app/guide-app-manager.md

@@ -0,0 +1,93 @@
+# 应用管理权限：管理对象 + 内联权限分组
+
+对应应用设置页「应用权限 → 应用管理权限」。它管两样东西：
+
+1. **管理对象**：谁能维护这个应用（管理权限名单）。
+2. **内联权限分组**：应用管理权限面板里的「添加分组」，把一组人/部门/角色/岗位/所有人
+   打包成一个分组，再给这个分组勾选表单/页面/报表/流程等权限。
+
+> ⚠️ 它**不是**左侧设置菜单里的独立「权限组」页。
+> 独立权限组走 `/api/bs/ebuilder/app/permission/group/*`，是另一套系统组/自定义组、成员、
+> 功能权限与数据权限；CLI 尚未提供那套命令。
+
+## 一、管理对象
+
+```bash
+e10-cli app manager list <appId>
+e10-cli app manager add <appId> <目标...> --type user|dept|role|position|all
+e10-cli app manager remove <appId> <目标...> --type user|dept|role|position|all
+```
+
+- 目标可写名称或 ID；人员/部门/角色/岗位同名多条会报错并要求改用 ID。
+- `--type all` 时可省略目标，等价于「所有人」。
+- 加/删都是**读全量 → 只增删点名对象 → 整组回写 → 回读确认**；已有对象原样保留。
+- 重复添加已存在的对象直接提示「已是目标状态」，不发写请求；移除不存在的对象会报错。
+
+示例：
+
+```bash
+e10-cli app manager list 1234567890123456789
+e10-cli app manager add 1234567890123456789 张三 --type user
+e10-cli app manager add 1234567890123456789 运营部 --type dept
+e10-cli app manager remove 1234567890123456789 张三 --type user
+```
+
+## 二、内联权限分组
+
+```bash
+e10-cli app manager group list <appId>
+e10-cli app manager group add <appId> --name <名称> [--desc <描述>] [--group-type CUSTOM|DEVELOP|READONLY]
+e10-cli app manager group update <appId> <分组id|名称> [--name] [--desc] [--group-type]
+e10-cli app manager group delete <appId> <分组id|名称>
+```
+
+分组类型：
+
+| 值 | 含义 |
+|---|---|
+| `CUSTOM` | 自定义（缺省） |
+| `DEVELOP` | 开发者 |
+| `READONLY` | 查看者 |
+
+- 新建分组的「功能权限」先用全关模板落库；需要具体权限时在平台界面里勾选后保存。
+- 分组名在同应用内必须唯一；同名多条时更新/删除请改用分组 id。
+- 保存走 `app/setting/publish/save`，和「应用设置」同一族；命令会自动带上
+  `teamworkStatus`、`manageDetach`、`fieldPermissionSwitch`、`messageInfo` 等基线字段，
+  避免把应用设置顺手改坏。
+
+## 三、分组成员
+
+```bash
+e10-cli app manager group member list <appId> <分组id|名称>
+e10-cli app manager group member add <appId> <分组id|名称> <目标...> --type user|dept|role|position|all
+e10-cli app manager group member remove <appId> <分组id|名称> <目标...> --type user|dept|role|position|all
+```
+
+成员对象类型与管理对象一致；加/删只动目标成员，分组名称、描述、类型、功能权限配置原样保留。
+
+## 四、平台编码（改动时注意）
+
+- 管理对象写接口 `editRight` 的 `rights` 是**整组替换**，每条 `targetType` 必须用
+  **字符串枚举**：`USER` / `DEPT` / `ROLE` / `POSITION` / `ALL`。
+  传数字会被另一套枚举解析，人员可能被静默写成部门/岗位。
+- 读回是数字（人员=1、部门=2、角色=10、岗位=1311、所有人=11），命令会按 `_entityType`
+  优先还原成字符串再回写。
+- 回写时只带 `sourceId / permissionId(view) / rightType(VIEW) / permissionType(3) /
+  targetType / targetId / targetName / permissionTargetType / isCustom / sourceType /
+  download / shareKey` 及已有的等级字段；**不要把 `browserType`、`objType`、`obj_id`
+  等回显字段塞回去**，否则平台可能解析失败或写成别的对象。
+
+## 五、命令一览
+
+| 命令 | 说明 |
+|---|---|
+| `app manager list <appId>` | 列出管理对象 |
+| `app manager add <appId> <目标...> --type …` | 添加管理对象 |
+| `app manager remove <appId> <目标...> --type …` | 移除管理对象 |
+| `app manager group list <appId>` | 列出内联权限分组 |
+| `app manager group add <appId> --name …` | 新建内联权限分组 |
+| `app manager group update <appId> <分组> [--name/--desc/--group-type]` | 编辑分组 |
+| `app manager group delete <appId> <分组>` | 删除分组 |
+| `app manager group member list <appId> <分组>` | 列出分组成员 |
+| `app manager group member add <appId> <分组> <目标...> --type …` | 添加分组成员 |
+| `app manager group member remove <appId> <分组> <目标...> --type …` | 移除分组成员 |

package/skill-docs/references/app/guide-app-settings.md

@@ -0,0 +1,93 @@
+# 应用设置：菜单展示方式 / 默认首页 / 字段权限
+
+`app setting` 改的是**应用设置页**里的配置（`publishInfo` 层），
+不是 `app publish-info` 改的「前台已发布应用」那份 `sysMenus`，也不是 `app range` 改的
+前台使用范围。三者的存储和接口都不一样，别混用。
+
+## 一、命令
+
+```bash
+# 查看
+e10-cli app setting get <appId>
+e10-cli app setting get <appId> --json
+
+# 修改（只写点名项，保存后回读校验）
+e10-cli app setting set <appId> \
+  --pc-show none \
+  --pc-multi-menu collapse \
+  --pc-home 首页 \
+  --mobile-show display \
+  --mobile-home 首页 \
+  --field-permission on
+```
+
+## 二、菜单设置
+
+| 选项 | 平台键 | 取值 |
+|---|---|---|
+| `--pc-show <v>` / `--mobile-show <v>` | `navigation.pc/mobile.showType` | `display`=默认显示(1) / `hide`=隐藏(0) / `none`=不显示(-1) |
+| `--pc-multi-menu <v>` / `--mobile-multi-menu <v>` | `navigation.pc/mobile.multiMenu` | `expand`=全部展开(1) / `collapse`=全部收起(2，缺省) |
+| `--pc-home <page>` / `--mobile-home <page>` | `homepageId/homepageType/homepageName` | pageId 或页面名；`none` 清除 |
+| `--pc-home-type <t>` / `--mobile-home-type <t>` | `homepageType` | 缺省按页面列表推断为 `PAGE`；内置页 `SHARELIST`/`FOLLOWLIST` 用 `BASE` |
+| `--pc-home-name <n>` / `--mobile-home-name <n>` | `homepageName` | 缺省按页面列表推断 |
+| `--pc-home-params <json>` / `--mobile-home-params <json>` | `homepageParams` | 可选，JSON |
+| `--pc-home-url <url>` / `--mobile-home-url <url>` | `homepageUrl` | 一般不用给 |
+
+说明：
+
+- **默认首页只在 `showType=none`（不显示）时有意义**。把菜单改回 `display`/`hide` 不会自动清掉首页；
+  要清就显式传 `--pc-home none` / `--mobile-home none`。
+- 页面名匹配不到或同名多条会报错并列 pageId；内置页（如 `SHARELIST`）不在页面列表里，
+  需同时给 `--*-home-type BASE --*-home-name "共享给我的"`。
+- 移动端 `multiMenu` 平台 UI 没有暴露，但数据模型支持；CLI 保留该选项，保存后会回读。
+
+## 三、字段权限
+
+```bash
+e10-cli app setting set <appId> --field-permission on
+e10-cli app setting set <appId> --field-permission off
+```
+
+对应 `publishInfo.fieldPermissionSwitch`（1/0）。开启后，应用下各表单的权限页才会出现
+「字段权限」入口；它**不等于** `form permission` 里的字段级授权本身。
+
+## 四、保存行为与坑
+
+- 读：`GET /api/bs/ebuilder/app/setting/publish/info?appId=`。
+- 写：`POST /api/bs/ebuilder/app/setting/publish/save?appId=`，**JSON body**。
+  - **必须走 JSON**。form-urlencoded 会回 `{"code":500,"msg":"系统错误"}`。
+  - `teamworkStatus` 是必填，缺了会 500。
+  - `manageDetach` 缺了会被平台重置成 `false`；因此即使本次不改它，命令也会带上当前值。
+  - `messageInfo` 必须是 **JSON 字符串**；直接发对象会 500。
+  - `navigation` 也是 JSON 字符串；保存前会剔除菜单里的 `createTime/creator/deleteType/tenantKey/updateTime`。
+- 命令只发点名项（外加上述必须保留的基线字段），不会整份回写权限/访问范围；
+  保存后回读校验：目标值必须一致，菜单、管理权限、内联权限分组、访问范围不能被顺手清掉。
+- 值本来就一致时不发保存请求，直接提示「已经是目标值」。
+
+## 五、和相邻命令的区别
+
+| 命令 | 改什么 | 存储 |
+|---|---|---|
+| `app setting` | 应用设置页：菜单展示方式 / 默认首页 / 字段权限开关 | `publishInfo`（`/app/setting/publish/*`） |
+| `app publish-info` | 前台已发布应用的显示名/简称/简介/适用端/分类 | `saveCustomApplication` 的 `sysMenus` |
+| `app range` | 前台已发布应用的使用范围（PC/移动端） | `appmanage/permission/table/*`，定位 `amId` |
+| `menu` / `menu permission` | 菜单项本身、菜单项可见范围 | `savePublishMenu` / `permissionForm` |
+| `form permission` / `page permission` / `report permission` | 单资源的权限 | 各自的权限接口 |
+
+## 六、示例
+
+```bash
+# PC 端不显示菜单，默认落到「首页」页面
+e10-cli app setting set <appId> --pc-show none --pc-home 首页
+
+# 移动端不显示菜单，默认首页用内置页
+e10-cli app setting set <appId> \
+  --mobile-show none \
+  --mobile-home SHARELIST --mobile-home-type BASE --mobile-home-name "共享给我的"
+
+# 恢复 PC 菜单为默认显示，并清掉默认首页
+e10-cli app setting set <appId> --pc-show display --pc-home none
+
+# 开启字段权限
+e10-cli app setting set <appId> --field-permission on
+```

package/skill-docs/references/common/ref-cli-commands.md

@@ -62,6 +62,11 @@
 | `e10-cli app folder [--type 1/2/3]` | 查看应用目录结构（文件夹+应用树，含发布状态）。1=我管理的/2=我创建的/3=全部 |
 | `e10-cli app read <appId>` | 查看应用**详情**（全量配置：名称/描述/简称/范围/目录/组织/发布状态）。`--json` 输出完整对象。走 `/app/info` |
 | `e10-cli app edit <appId> [--name] [--desc] [--short-name]` | 编辑应用信息（至少指定一个写参数；内部先读 `/app/info` 再合并提交） |
+| `e10-cli app setting get <appId>` | 查看**应用设置页**的菜单展示方式、默认首页、字段权限开关（`publishInfo` 层，不是前台发布配置） |
+| `e10-cli app setting set <appId> [--pc-show display\|hide\|none] [--pc-multi-menu expand\|collapse] [--pc-home <pageId\|页面名\|none>] [--mobile-show …] [--mobile-home …] [--field-permission on\|off]` | 修改应用设置。只写点名项，保存后回读；`teamworkStatus` 必填、`manageDetach` 缺了会被重置，命令会自动带上这两个基线值。`--*-home-type/name/params/url` 需与 `--*-home` 同用；内置页用 `type=BASE` |
+| `e10-cli app manager list\|add\|remove <appId> [目标...] --type user\|dept\|role\|position\|all` | 应用**管理对象**（谁能维护这个应用）。读全量 → 只增删点名对象 → 整组回写 → 回读；重复添加幂等、移除不存在报错。`--type all` 可省略目标 |
+| `e10-cli app manager group list\|add\|update\|delete <appId> [分组] [--name/--desc/--group-type CUSTOM\|DEVELOP\|READONLY]` | 应用管理权限面板里的**内联权限分组**（`publishInfo.rightGroupList`）。**不是**独立「权限组」页；同名分组报错，更新/删除可传 id |
+| `e10-cli app manager group member list\|add\|remove <appId> <分组> [目标...] --type …` | 内联权限分组的成员；加/删只动目标成员，分组配置原样保留 |
 | `e10-cli app delete <appId>` | 删除应用（软删除，可恢复；存在关联资源会提示先清理） |
 | `e10-cli app enable <appId>` | 启用应用。`read` 里的 `publishEnabled`：1=已启用 / 2=已停用 / 0=从未启用 |
 | `e10-cli app disable <appId>` | 停用应用。⚠ **会连带收回已发布到前台的入口** —— 不是「临时关一下、发布态还在」 |
@@ -114,7 +119,7 @@
 | `e10-cli form permission create <add\|update\|show> <objId> <appId> [--right-id <id>] --org-type <类型> [--org-id <id>] [--org-name <名>] [设置项]` | **创建权限**（谁能新建记录）。通用对象支持 all/employee/department/company/role/group/post/partTime/grade/external/externalAll；`all`/`externalAll` 的 orgId 自动 0。`update` 只改点名项并整行回写；`show` 查看布局/优先级/描述/条件/同步列表。设置项见下一行 |
 | `e10-cli form permission data <add\|update\|show> <objId> <appId> [--right-id <id>] --target <general\|creator\|field\|matrix\|govern> --rights <view/edit/delete/comment...> [设置项]` | **共享权限**（查看/编辑/删除/评论；`1/2/3/4`）。`general` 通用对象（同上 11 种类型）；`creator --creator-related 0~7` 创建人相关；`field --field <字段id或名>` 字段相关（`--sub-form-id` 支持明细字段）；`matrix --matrix <矩阵>` 或 `--eb-form <e-Builder表单>` + `--matrix-value`/`--matrix-value-raw`/`--matrix-condition-raw`；`govern --govern-json <json>` 政务单位相关。附件 `--file-rights view/download/edit`（401/402/403）与 `--file-right-type temporary\|insert`（临时/插入赋权）。保存后按权限 ID 回读核对。详见 `form/guide-form-permission.md` |
 | 权限通用设置（`create` / `data` 的 `add\|update`） | `--layout` / `--edit-layout` / `--mobile-layout` / `--mobile-edit-layout`（关联 PC、编辑、移动、移动编辑布局）、`--same-layout on\|off`（PC 移动统一布局）、`--layout-order <n>`（优先级，0 最高）、`--desc <文本>` / `--desc-label-id`（权限描述）、`--condition <json\|@file>` / `--clear-condition`（权限条件，写入前按平台算法压缩）、`--org-virtual-type`（组织维度）、`--contain-extra on\|off`（含兼职人员）、`--min-seclevel` / `--max-seclevel`（安全级别 0~100）、`--exclude-obj <json\|@file>`（排除项）、`--sync-forms <objId...>`（同步至其他表单，整体替换）。修改只改点名项；未点名的布局、条件、同步列表原样保留 |
-| `e10-cli form permission imp-exp <list\|add\|update\|show> <objId> <appId> [--right-id <id>] ...` | **导入导出权限**（独立分类 `data_imp_exp`，⚠ 勿用 `data add` 加——共享权限只有 查看/编辑/删除 三种，导出/导入不在其中）。`list` 查看；`add/update --org-type <类型> [--org-id] --rights <export/import/delete-import...> [--update-import] [--export-details] [--export-attachment] [--export-field-range listShowField\|allField]`；`show` 查看单条。`export=8`、`import=9`、`delete-import=93`（93 须与 import 同选，自动带更新导入）；授权对象与共享权限同一套 11 种通用对象（含兼职岗位/职级/外部联系人/所有外部联系人）。保存后按权限 ID 回读 `impRightList` 校验；修改只改点名项。删除同 `permission remove --right-id`。不支持权限描述/更新导入校验数据编辑权限/导入关联布局/优先级/同步至其他表单 |
+| `e10-cli form permission imp-exp <list\|add\|update\|show> <objId> <appId> [--right-id <id>] ...` | **导入导出权限**（独立分类 `data_imp_exp`，⚠ 勿用 `data add` 加——共享权限只有 查看/编辑/删除 三种，导出/导入不在其中）。`list` 查看；`add/update --org-type <类型> [--org-id] --rights <export/import/delete-import...> [--update-import] [--export-details] [--export-attachment] [--export-field-range listShowField\|allField]`；`show` 查看单条。`export=8`、`import=9`、`delete-import=93`（93 须与 import 同选，自动带更新导入）；授权对象与共享权限同一套 11 种通用对象（含兼职岗位/职级/外部联系人/所有外部联系人）。保存后按权限 ID 回读 `impRightList` 校验；修改只改点名项，并原样保留已有的权限描述/导入关联布局（`rightDesc`/`layoutId` 等，防止被更新报文清空）。删除同 `permission remove --right-id`。不支持配置权限描述/更新导入校验数据编辑权限/导入关联布局/优先级/同步至其他表单 |
 | `e10-cli form permission archive <list\|add\|remove\|card> <objId> <appId> --workflow <workflowId>` | **流程归档权限**（归档后数据对谁可见/可改/可删，**按流程各一套**，与共享权限不同）。`add --target <general/creator/field/matrix>`：`general` 通用对象配 `--org-type`+`--org-id`；`creator` 创建人相关配 `--creator-related 0~7`；`field` 字段相关配 `--field <字段id或名>`（`--sub-form-id` 支持明细字段，未收录的字段类型需 `--org-type field_xxx` 显式指定）；`matrix` 矩阵相关配 `--matrix`（真矩阵）或 `--eb-form`（e-Builder 表单）+ `--matrix-value`（e-Builder 表单按名取它自己的人员字段/创建者，人员字段 valueType=resource），另可加**矩阵条件**（e-Builder 表单的条件列自动取该表单主表字段） `--matrix-condition '<json>'`（可重复 / `@文件` 给数组；右值三选一 `value` 固定值 / `field` 引本表单字段 / `fieldRef` 直给字段描述符）+ `--matrix-condition-relation and\|or`。权限码 `5/view` 归档查看、`6/edit` 归档编辑、`7/delete` 归档删除（**归档查看是系统默认必选，界面不可取消；`--rights` 没传 view 会自动并入**）；归档附件另算 `501/view`、`502/download`、`503/edit`（**不是**共享权限的 401/402；**归档附件查看 501 同属系统必选，不给 `--file-rights` 也会带上**）。保存后按 ID 回读逐项核对；`card <workflowId> <appId> [--set 0\|1]` 读写归档卡片开关。详见 `form/guide-form-archive-permission.md` |
 | `e10-cli form permission <list\|add\|remove\|rebuild> <objId> <appId>` | 权限通用管理及兼容入口。新建权限与数据权限分开；旧 `add --right-type` 保留兼容。`list` 查看全部分类；`remove --right-id <id[,id...]>` 删除一条或多条权限；添加后提示 `isShowRebuild=2` 时执行 `rebuild` |
 | `e10-cli form list-view <objId> <appId>` | 查看台账/数据列表（获取 viewId 用于菜单配置） |
@@ -780,3 +785,9 @@ e10-cli workflow action list-node <wf> <nodeId>
 事件顺序动作与递归条件：`designer event set --config @sequence.json` 使用 `{actions:[...]}` 或 `{nativeActions:[...]}`；`designer event action add/update/remove/enable/order`、`branch add/update/remove/enable/order` 支持按 ID 和 `--parent` 编辑；候选用 `event fields/targets` 查询。见 [事件指南](../ebuilder-designer/events/guide-events.md)。
 
 普通页面管理：`page rename <pageId> --name ... [--apply]`、`page copy <pageId> --name ... [--group-id id] [--apply]`、`page transfer <pageId> --app-id ... [--apply]`；`page groups/transfer-targets --app-id ...` 查询候选。`page delete <pageIds...>` 保留默认直接执行方式，`--preview` 只预览。详见 [普通页面管理](../ebuilder-designer/guide-page-management.md)。
+
+### 菜单目标与目录转换
+
+使用 `menu get <appId> <menuId>` 读取完整详情，`menu targets --kind apps|menu|layouts|types|workflow|report` 查询目标；`menu link set <appId> <menuId> --config @file --apply` 修改目标或目录转链接，`menu link clear <appId> <menuId> --apply` 清空转目录。两项写入默认预览，PC/移动端由 `--terminal pc|mobile` 区分。功能、结构和本入口码表见 [菜单地址与目录配置](../menu/guide-menu-config.md)。
+
+菜单属性使用 `menu configure <appId> <menuId> --config @file --apply`，图标使用 `menu icons`，显示条件候选使用 `menu condition-candidates`。菜单权限使用 `menu permission schema/get/browse` 查询，`menu permission entry add/replace/remove` 按授权行维护，默认预览。详见 [菜单配置](../menu/guide-menu-config.md) 与 [菜单权限](../menu/guide-menu-permission.md)。

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

@@ -172,7 +172,9 @@ e10-cli form permission imp-exp show <objId> <appId> --right-id <id>
 - `--export-details` / `--export-attachment`：导出明细、导出附件。
 - 修改只改点名项，整行回写并回读。
 
-导入导出权限**不提供**权限描述、更新导入校验数据编辑权限、导入关联布局、优先级、同步至其他表单这些配置项。
+导入导出权限**不提供**权限描述、更新导入校验数据编辑权限、导入关联布局、优先级、同步至其他表单这些配置参数。
+
+`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。后台返回成功不等于配置语义正确。