yida-form-permission · diff

git:20260819.85fc132 to git:20260825.ad1c86c

104 added, 135 removed. Audit A to A.

---

name: yida-form-permission

description: 宜搭表单权限组管理。查询、新增权限组，配置成员权限、数据权限、操作权限和字段权限。适用于控制表单数据的访问范围和操作权限。

---

- # 表单权限配置

- ## 严格禁止 (NEVER DO)

- - 不要在未查询现有权限组的情况下直接创建新权限组（先用 get-permission 查询）

- - 字段权限使用 `--field-permission` 透传宜搭 `fieldPermit` JSON；修改前必须先 `get-permission` 查看当前结构

- - 不要使用自定义部门或自定义过滤条件（不支持）

- ## 严格要求 (MUST DO)

+ # 表单权限配置

- - 修改权限前先用 `openyida get-permission` 查询现有配置

- - action-permission 为完全替换模式，只保留 true 的项，操作前确认影响范围

- - **本技能不读写 memory**：权限配置通过 CLI 命令写入宜搭平台，不依赖跨会话的 memory 状态

+ ## 适用范围

- ## 适用场景

+ 用户要求查询或修改表单权限组、成员范围、数据范围、操作权限或字段权限时使用本技能。

- 用户需要"配置权限"、"设置数据权限"、"添加权限组"、"控制谁能看/改/删数据"时使用。

+ 当前 CLI 只查询和保存 `FORM_PACKAGE_VIEW` 权限组。平台模型还包含 `FORM_PACKAGE_START`，本技能不管理该类型。`get-permission` 当前只读取第 1 页、每页 20 条；输出不能代表第 21 条以后的权限组。

- ## 触发条件

+ ## 铁律

- **正向触发**：

- - "配置权限"、"设置数据权限"

- - "添加权限组"、"控制谁能看/改/删数据"

- - "设置成员权限"、"配置操作权限"、"配置字段权限"

+ 1. **目标必须唯一**：更新前按 `DEFAULT`、`MANAGER` 或 `MATRIX` 匹配权限组。匹配 0 个或多个时停止；查询返回满 20 条时也停止，因为无法证明下一页没有同 role 权限组。停止时列出名称和 packageUuid。

+ 2. **未知操作键必须保留**：目标组的 `operatePermit` 包含 CLI 白名单外键时，停止 action-permission 修改；修改其他维度时原样保留整个 `operatePermit`。

+ 3. **成员替换必须展示损失**：执行 `--all-members` 或 `--matrix` 前展示完整 roleData before/after 和会移除的 `DEPARTMENT`、`ROLE`、`PARAM`、`MANAGER` 等条目。CLI 要求确认时，用户确认后追加 `--confirm-member-replace`。

+ 4. **整块保存必须先确认**：action-permission 会整块替换为 operations 中值为 true 的白名单键；执行前展示完整 before/after。

+ 5. **平台状态是真相源**：本技能不使用 memory 保存权限状态；每次修改都查询平台并在写后重查。

- ## 危险操作确认

+ ## 标准流程

- 修改 action-permission 会完全替换现有操作权限配置，执行前必须：

- 1. 展示当前权限配置

- 2. 展示修改后的权限配置

- 3. 等待用户确认

+ 1. **查询**：运行 `openyida get-permission <appType> <formUuid>`，记录目标组名称、packageUuid 和四个权限维度。

+ 2. **差异预览**：输出明确的 `before` 与 `after`；未修改的 roleData、dataPermit、operatePermit、fieldPermit 标记为“保持原值”。

+ 3. **确认**：向用户确认唯一目标、成员损失、操作权限整块替换和数据范围变化。

+ 4. **写入**：只传需要修改的维度，执行一次 `save-permission`。

+ 5. **重查验证**：再次运行 `get-permission`，按写入前记录的 packageUuid 找到目标组并逐项比对。找不到目标或实际值不一致时报告验证失败。

- ---

+ 新增权限组也先查询现有配置并展示新组的完整 after，再确认、写入和重查。

+ ## 命令

- ## 查询权限组

+ 查询前 20 个查看权限组：

```bash

openyida get-permission <appType> <formUuid>

```

- ## 更新权限组

+ 更新唯一权限组：

```bash

openyida save-permission <appType> <formUuid> [选项]

```

- | 选项 | 说明 |

+ | 选项 | 作用 |

|------|------|

- | `--data-permission <json>` | 修改数据权限范围 |

- | `--action-permission <json>` | 修改操作权限（完全替换，只保留 true 的项） |

- | `--field-permission <json>` | 修改字段权限，传入宜搭 `fieldPermit` 对象或 `{ "role": "DEFAULT", "fieldPermit": {...} }` |

- | `--members <userIds>` | 修改成员，多个 userId 逗号分隔 |

- | `--all-members` | 设置权限组为「全员可见」（`roleData.include` 为 `DEFAULT/ALL`） |

- | `--matrix <json>` | 使用权限矩阵作为权限成员，JSON 格式 `{"matrixId":"MATRIX-XXX","columnId":"column_YYY"}`，与 `--members` / `--all-members` 互斥 |

+ | `--data-permission <json>` | 修改 dataPermit；顶层可带 `role` 选择目标组 |

+ | `--action-permission <json>` | 整块替换 operatePermit；顶层可带 `role` |

+ | `--field-permission <json>` | 修改真实 fieldPermit；顶层可带 `role` |

+ | `--members <userIds>` | 替换 `PERSONS` 条目并保留其他 roleData 条目 |

+ | `--all-members` | 把成员维度替换为 `DEFAULT/ALL` |

+ | `--matrix <json>` | 把成员维度替换为指定矩阵；与 `--members`、`--all-members` 互斥 |

+ | `--confirm-member-replace` | 确认会删除复合 roleData 的成员替换 |

- ### 数据权限 `dataRange` 可选值

+ 新增权限组：

- | 值 | 说明 |

- |----|------|

- | `ALL` | 全部数据 |

- | `SELF` / `ORIGINATOR` | 本人提交 |

- | `DEPARTMENT` / `ORIGINATOR_DEPARTMENT` | 本部门提交 |

- | `SAME_LEVEL_DEPARTMENT` | 同级部门 |

- | `SUBORDINATE_DEPARTMENT` | 下级部门 |

- | `MATRIX` | 权限矩阵条件 |

+ ```bash

+ openyida save-permission <appType> <formUuid> --create --name <名称> [选项]

+ ```

- > 如需同时设置多个数据范围、自定义部门或自定义过滤条件，可直接传入宜搭完整的 `dataPermit` JSON（必须包含 `rule` 数组）。例如截图中的「本人提交 + 本部门 + 同级部门 + 下级部门 + 免登 + 自定义部门 + 自定义过滤条件」可表示为：

- >

- > ```json

- > {

- > "rule": [

- > { "type": "ORIGINATOR", "value": "y" },

- > { "type": "ORIGINATOR_DEPARTMENT", "value": "y" },

- > { "type": "SAME_LEVEL_DEPARTMENT", "value": "y" },

- > { "type": "SUBORDINATE_DEPARTMENT", "value": "y" },

- > { "type": "FREE_LOGIN", "value": "y" },

- > { "type": "CUSTOM_DEPARTMENT", "value": "y" },

- > { "type": "FORMULA", "value": "y" }

- > ],

- > "customDepartmentData": {

- > "departmentIds": ["637215248"],

- > "drillDown": "n"

- > },

- > "formulaData": {

- > "condition": "OR",

- > "ruleId": "group-xxx",

- > "rules": []

- > }

- > ```

- >

- > 命令示例：

- >

- > ```bash

- > openyida save-permission APP_XXX FORM_XXX \

- > --create --name "全部成员可查看本人提交数据" \

- > --all-members \

- > --data-permission '{"rule":[{"type":"ORIGINATOR","value":"y"},{"type":"ORIGINATOR_DEPARTMENT","value":"y"},{"type":"SAME_LEVEL_DEPARTMENT","value":"y"},{"type":"SUBORDINATE_DEPARTMENT","value":"y"},{"type":"FREE_LOGIN","value":"y"},{"type":"CUSTOM_DEPARTMENT","value":"y"},{"type":"FORMULA","value":"y"}],"customDepartmentData":{"departmentIds":["637215248"],"drillDown":"n"},"formulaData":{"condition":"OR","ruleId":"group-xxx","rules":[]}}' \

- > --action-permission '{"operations":{"OPERATE_VIEW":true,"OPERATE_EDIT":true,"OPERATE_DELETE":true,"OPERATE_HISTORY":true,"OPERATE_COMMENT":true,"OPERATE_PRINT":true}}'

- > ```

+ 更新目标 role 只支持 `DEFAULT`、`MANAGER`、`MATRIX`。平台 roleData 可出现 `DEFAULT`、`MANAGER`、`PERSONS`、`DEPARTMENT`、`ROLE`、`PARAM`、`MATRIX`；CLI 不新增 `DEPARTMENT`、`ROLE` 或 `PARAM` 成员条目。

- ### 操作权限 key

+ ## 数据权限

- `OPERATE_VIEW`、`OPERATE_EDIT`、`OPERATE_DELETE`、`OPERATE_HISTORY`、`OPERATE_COMMENT`、`OPERATE_PRINT`、`OPERATE_CREATE`、`OPERATE_BATCH_EDIT`、`OPERATE_BATCH_EXPORT`、`OPERATE_BATCH_IMPORT`、`OPERATE_BATCH_DELETE`、`OPERATE_BATCH_PRINT`、`OPERATE_BATCH_DOWNLOAD`、`OPERATE_BATCH_DOWNLOAD_QRCODE`

+ 简写 `dataRange`：

- ## 新增权限组

+ | 输入 | 写入类型 |

+ |------|----------|

+ | `ALL` | `ALL` |

+ | `SELF` / `ORIGINATOR` | `ORIGINATOR` |

+ | `DEPARTMENT` / `ORIGINATOR_DEPARTMENT` | `ORIGINATOR_DEPARTMENT` |

+ | `SUBORDINATE` | `SUBORDINATE` |

+ | `SAME_LEVEL_DEPARTMENT` | `SAME_LEVEL_DEPARTMENT` |

+ | `SUBORDINATE_DEPARTMENT` | `SUBORDINATE_DEPARTMENT` |

+ | `FREE_LOGIN` | `FREE_LOGIN` |

+ | `CUSTOM_DEPARTMENT` | `CUSTOM_DEPARTMENT` |

+ | `CUSTOM` / `FORMULA` | `FORMULA` |

+ | `MATRIX` | `MATRIX` |

- ```bash

- openyida save-permission <appType> <formUuid> --create --name <名称> [选项]

+ 组合范围传完整 dataPermit 对象。`rule` 必须非空；启用 `CUSTOM_DEPARTMENT` 时 `customDepartmentData.departmentIds` 必须非空；启用 `FORMULA` 时必须提供非空 `formulaData`；启用 `MATRIX` 时 roleData 必须选择有效的 matrixId 和 columnId，反向也成立。

+ ```json

+ {

+ "role": "DEFAULT",

+ "rule": [

+ { "type": "ORIGINATOR", "value": "y" },

+ { "type": "CUSTOM_DEPARTMENT", "value": "y" },

+ { "type": "FORMULA", "value": "y" }

+ ],

+ "customDepartmentData": {

+ "departmentIds": ["637215248"],

+ "drillDown": "n"

+ },

+ "formulaData": {

+ "condition": "OR",

+ "ruleId": "group-xxx",

+ "rules": []

+ }

```

- 示例：

+ ## 操作权限

- ```bash

- openyida save-permission APP_XXX FORM_XXX \

- --create --name "部门数据查看组" \

- --members "54255850977641" \

- --data-permission '{"dataRange":"ORIGINATOR_DEPARTMENT"}' \

- --action-permission '{"operations":{"OPERATE_VIEW":true}}' \

- --field-permission '{"fieldRange":"FORM"}'

- ```

+ `operations` 至少有一个值为 true 的操作。当前 CLI 白名单为：

- > 设置「全部人员看全部数据」时，必须加上 `--all-members`，确保 `roleData.include` 为 `DEFAULT/ALL`：

- >

- > ```bash

- > openyida save-permission APP_XXX FORM_XXX \

- > --create --name "全部人员看全部数据" \

- > --all-members \

- > --data-permission '{"dataRange":"ALL"}' \

- > --action-permission '{"operations":{"OPERATE_VIEW":true}}'

- > ```

- >

- > 若目标表单已存在 DEFAULT 权限组，也可直接用 `--all-members --data-permission '{"dataRange":"ALL"}'` 更新该组。

- >

- > ### 使用权限矩阵

- > 1. 先在宜搭后台「权限矩阵」中获取目标矩阵 ID 与结果列 columnId；或调用底层服务 `/query/matrix/getMatrixList.json` / `/query/matrix/getMatrixById.json` 查询。

- > 2. 创建/更新权限组时指定 `--matrix '{"matrixId":"MATRIX-XXX","columnId":"column_YYY"}'`，并配合 `--data-permission` 设置包含 `MATRIX` 的数据范围。

- >

- > ```bash

- > openyida save-permission APP_XXX FORM_XXX \

- > --create --name "使用权限矩阵的权限组" \

- > --matrix '{"matrixId":"MATRIX-XNCVJYB60YW7L0HPY9HE","columnId":"column_1767839664612"}' \

- > --data-permission '{"rule":[{"type":"ORIGINATOR","value":"y"},{"type":"MATRIX","value":"y"}]}' \

- > --action-permission '{"operations":{"OPERATE_VIEW":true,"OPERATE_EDIT":true,"OPERATE_DELETE":true,"OPERATE_HISTORY":true,"OPERATE_COMMENT":true,"OPERATE_PRINT":true}}'

- > ```

+ `OPERATE_VIEW`、`OPERATE_EDIT`、`OPERATE_DELETE`、`OPERATE_HISTORY`、`OPERATE_COMMENT`、`OPERATE_PRINT`、`OPERATE_CREATE`、`OPERATE_BATCH_EDIT`、`OPERATE_BATCH_EXPORT`、`OPERATE_BATCH_IMPORT`、`OPERATE_BATCH_DELETE`、`OPERATE_BATCH_PRINT`、`OPERATE_BATCH_DOWNLOAD`、`OPERATE_BATCH_DOWNLOAD_QRCODE`。

+ 平台出现白名单外键时，本技能不推断其语义，也不通过 action-permission 删除它。

## 字段权限

- - 默认结构通常是 `{ "fieldRange": "FORM" }`，表示继承表单设计中组件状态。

- - 需要自定义字段权限时，先执行 `openyida get-permission <appType> <formUuid>` 获取现有权限组中的 `fieldPermit`，在此基础上修改后传给 `--field-permission`。

- - 更新已有权限组时可在 JSON 顶层带 `role`，例如 `{"role":"DEFAULT","fieldPermit":{"fieldRange":"FORM"}}`。

+ 全部字段沿用表单状态：

- ## 限制

+ ```json

+ { "fieldRange": "FORM" }

+ ```

- - 不支持自定义部门和自定义过滤条件

+ 自定义字段权限使用真实 `fieldStatus` 结构：

- ## 异常处理

+ ```json

+ {

+ "role": "DEFAULT",

+ "fieldRange": "CUSTOM",

+ "fieldStatus": [

+ {

+ "label": "客户名称",

+ "fieldName": "textField_xxx",

+ "componentName": "TextField",

+ "value": "FORM_FIELD_VIEW"

+ }

+ ]

+ }

+ ```

- | 异常场景 | 处理方式 |

- |---------|----------|

- | get-permission 返回空 | 确认 appType 和 formUuid 正确，该表单可能尚未配置权限组 |

- | save-permission 失败 | 检查 userId 格式是否正确，确认登录态有效 |

- | action-permission 误操作 | 该操作为完全替换，执行前必须展示当前配置并获得用户确认 |

- | 不支持的 dataRange 值 | 只能使用文档中列出的 5 种 dataRange 值，不支持自定义 |

+ `value` 支持 `FORM_FIELD_VIEW`、`FORM_FILED_EDIT`（平台原始拼写）、`FORM_FIELD_HIDDEN`、`FORM_FIELD_ENCRYPT`。修改前从查询结果复制真实 label、fieldName 和 componentName，只改变目标项的 value。

- ## Agent 错误处理策略

+ ## 失败处理

- 当 Agent 执行本技能遇到错误时，必须遵循以下默认行为：

+ | 结果 | 动作 |

+ |------|------|

+ | 查询为空、目标不唯一或首批返回满 20 条 | 零写入；展示名称/packageUuid，并让用户缩小目标或改在平台处理 |

+ | 登录态或权限失败 | 停止；运行 `openyida auth status` 后由用户处理账号或组织 |

+ | 参数或结构校验失败 | 零写入；修正 rule、部门 ID、formulaData、矩阵或 fieldStatus |

+ | 保存失败 | 停止，不重复写入；保留 before 和错误响应 |

+ | 写后不一致 | 报告 expected/actual，停止；不宣称完成 |

+ | 网络超时 | 先重查目标状态；只有证明未写入后才允许用户确认重试 |

- | 错误类型 | 默认处理策略 |

- |---------|-------------|

- | 命令执行失败 | 停止执行，向用户展示错误信息，询问是否重试或调整参数 |

- | 参数缺失（appType/formUuid/userId 等） | 主动询问用户补充，不得猜测或编造 |

- | 权限不足 / 登录态失效 | 停止执行，提示用户执行 `openyida auth status` 检查登录态 |

- | 修改前未查询现有配置 | 必须先执行 `get-permission` 查询，再执行修改操作 |

- | 网络超时 | 重试 1 次，仍失败则停止并提示用户检查网络 |

- | 未知错误 | 停止执行，完整展示错误信息，建议用户反馈问题 |

+ ## 明确不支持

+ `FORM_PACKAGE_START`、新操作键、新成员创建参数、packageUuid 直选、权限组删除/复制/重命名、矩阵 CRUD 和 permission-v2。