表单权限配置

适用范围

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

当前 CLI 只查询和保存 FORM_PACKAGE_VIEW 权限组。平台模型还包含 FORM_PACKAGE_START，本技能不管理该类型。查询会按每页 20 条安全翻页；达到安全上限、分页重复或响应结构不完整时 fail-closed，不把不完整列表当作全量结果。

铁律

1. 目标必须唯一：优先使用查询结果中的 packageUuid，通过 --package-uuid 精确更新；未提供 UUID 时才按 DEFAULT、MANAGER 或 MATRIX 匹配。匹配 0 个或多个、分页无法完整结束时停止。
   packageUuid 只属于本次查询的 formUuid；多表单配置必须逐表查询，禁止跨表单复用。
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 保存权限状态；CLI 保存前完整查询、只写一次，保存后按 packageUuid 精确回读。目标维度不一致或非目标维度漂移时报 verify failed；无法恢复 create UUID、精确目标暂不可见或回读失败时报 verify unknown，两者都不得宣称成功或直接重放写入。

标准流程

1. 查询：运行 openyida get-permission <appType> <formUuid>，记录目标组名称、packageUuid 和四个权限维度。
2. 差异预览：输出明确的 before 与 after；未修改的 roleData、dataPermit、operatePermit、fieldPermit 标记为“保持原值”。
3. 确认：向用户确认唯一目标、成员损失、操作权限整块替换和数据范围变化。
4. 写入：只传需要修改的维度，更新时追加 --package-uuid <packageUuid>，执行一次 save-permission。
5. 重查验证：CLI 会自动按 packageUuid 做 canonical readback，并返回 verification.status=verified 才算成功；Agent 可再用精确查询复核。failed 或 unknown 时停止且不重放。

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

命令

查询全部查看权限组，或按 packageUuid 精确过滤：

openyida get-permission <appType> <formUuid>
openyida get-permission <appType> <formUuid> --package-uuid <packageUuid>

更新唯一权限组：

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

新增权限组：

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

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

数据权限

简写 dataRange：

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

{
  "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": []
  }
}

匿名提交的 FREE_LOGIN 门禁

公开访问自定义页面向普通表单匿名提交时，目标表单 DEFAULT 权限组的 dataPermit.rule 必须包含 {"type":"FREE_LOGIN","value":"y"}。它只是三项前置门禁之一；显示页和目标表单还必须分别满足 isOpen === 'y'。完整运行时契约见公开访问（匿名态）提交。

配置时必须先查询并锁定 DEFAULT 组的 packageUuid，复制其完整 dataPermit，只在原有 rule 中补入 FREE_LOGIN，保留 ORIGINATOR 及其他已有规则、customDepartmentData、formulaData 等非目标内容；不得用固定的 ORIGINATOR + FREE_LOGIN 模板覆盖现网规则。保存后按同一 packageUuid 回读，确认 FREE_LOGIN 存在且其他规则未漂移。

操作权限

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

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" }

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

{
  "role": "DEFAULT",
  "fieldRange": "CUSTOM",
  "fieldStatus": [
    {
      "label": "客户名称",
      "fieldName": "textField_xxx",
      "componentName": "TextField",
      "value": "FORM_FIELD_VIEW"
    }
  ]
}

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

失败处理

明确不支持

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