weaver-e10-builder 1.5.9 → 1.5.10

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

@@ -0,0 +1,122 @@
+# 流程归档权限
+
+「流程归档权限」管的是**某个流程归档之后**，它的数据对谁可见、可改、可删。它和表单的共享权限是两套：
+共享权限按表单配一次，归档权限**按流程各配一套**（同一张表单的不同流程可以不一样），并且多一档「归档附件」权限。
+
+## 命令
+
+```bash
+# 查看某个流程的归档权限
+e10-cli form permission archive list <objId> <appId> --workflow <workflowId>
+
+# 通用对象：给某个部门开「归档查看」
+e10-cli form permission archive add <objId> <appId> --workflow <workflowId> \
+  --target general --org-type department --org-id <deptId> --rights view --file-rights view download
+
+# 创建人相关：创建人本人及本部门可查看/编辑
+e10-cli form permission archive add <objId> <appId> --workflow <workflowId> \
+  --target creator --creator-related 0 --rights view edit
+
+# 字段相关：以表单里的「负责人」字段取值决定权限
+e10-cli form permission archive add <objId> <appId> --workflow <workflowId> \
+  --target field --field 负责人 --rights view edit delete
+
+# 矩阵相关（真矩阵）
+e10-cli form permission archive add <objId> <appId> --workflow <workflowId> \
+  --target matrix --matrix 门店经理矩阵 --rights view
+
+# 矩阵相关（e-Builder 表单当矩阵用）
+e10-cli form permission archive add <objId> <appId> --workflow <workflowId> \
+  --target matrix --eb-form <表单名或id> --matrix-value 创建者 --rights view
+
+# 删除（按 list 里的权限 ID）
+e10-cli form permission archive remove <objId> <appId> --right-id <id[,id...]>
+
+# 归档卡片开关
+e10-cli form permission archive card <workflowId> <appId>
+e10-cli form permission archive card <workflowId> <appId> --set 1
+```
+
+## 四类授权对象
+
+同一个端点上靠 `codeType` + `orgType` 区分四类，命令层用 `--target` 选择：
+
+| `--target` | 类别 | `codeType` | `orgType` | 主体怎么给 |
+|---|---|---|---|---|
+| `general` | 通用对象 | `obj_data_admin` | `employee` / `department` / `company` / `role` / `group` / `all` … | `--org-type` + `--org-id`（`all` 自动 0） |
+| `creator` | 创建人相关 | `obj_data_creator` | `creatorRelated` | `--creator-related` 0~7 |
+| `field` | 字段相关 | `obj_data` | `field_<字段类型>` | `--field <字段 id 或名称>` |
+| `matrix` | 矩阵相关 | `matrix` / `ebuilder_form` | 同 `codeType` | `--matrix`（真矩阵）或 `--eb-form` |
+
+`--target` 也接受中文名（`通用对象` / `创建人相关` / `字段相关` / `矩阵相关`）。
+
+### 创建人相关的 0~7
+
+`0` 本人、本部门、本分部；`1` 直接上级、本部门及所有下级部门、本分部及所有下级分部；`2` 本分部、本部门及所有上级部门、本分部及所有上级分部；
+`3` 本部门、所有下级部门、所有下级分部；`4` 所有上级、所有上级部门、所有上级分部；`5` 本岗位；`6` 直接下属；`7` 上级部门。
+
+### 字段相关的字段类型
+
+`--field` 既可给字段 id，也可给字段名（重名会报错，改用 id）。字段属于明细表时补 `--sub-form-id`。
+
+`orgType` 由字段的组件类型推出，目前覆盖：
+
+| 组件类型 | `orgType` | 回显名 |
+|---|---|---|
+| `Employee` | `field_employee` | 人员字段 |
+| `Department` | `field_department` | 部门字段 |
+| `SubCompany` | `field_company` | 分部字段 |
+| `Post` | `field_post` | 岗位字段 |
+| `EBuilder` | `field_ebuilder` | 关联ebuilder字段 |
+
+其余字段类型（人员范围选择、人力资源条件、人员组织多选等）不在自动推断表里 —— 组件类型名与 `field_*` 后缀不是一一对应，
+猜错会**静默授错对象**，所以命令会报错而不是替你选。这类请用 `--org-type field_xxx` 显式指定：
+
+`field_employee_condition`（人员范围选择字段）、`field_employee_share_condition`（人力资源条件字段）、`field_employee_organization`（人员组织多选）。
+
+### 矩阵相关的「取值字段」
+
+取值字段决定**用矩阵里的哪一列**去匹配当前用户，必需，且取值来源分两种：
+
+- **真矩阵**（`--matrix`）：值字段自动取该矩阵的值字段配置；也可用 `--matrix-value 名称` 指定其中几个。
+- **e-Builder 表单**（`--eb-form`）：取值字段是**系统值**体系，不是矩阵的值字段配置。
+  目前只有「创建者」可直接用名称指定；其余取值请用 `--matrix-value <id>:<名称>:<valueType>` 明写，
+  或用 `--matrix-value-raw '<JSON 数组>'` 整体透传（数组元素形状以设计器实际请求为准）。
+
+矩阵下面的「条件」这一层暂未开放，固定为空。
+
+## 权限码
+
+归档权限 `--rights`（可组合，逗号或空格分隔，也可用编号）：
+
+| 编号 | 别名 | 含义 |
+|---|---|---|
+| 5 | `view` / `read` | 归档查看 |
+| 6 | `edit` / `update` | 归档编辑 |
+| 7 | `delete` | 归档删除 |
+
+归档附件权限 `--file-rights`（与上面的查看/编辑/删除**互相独立**，是另一处勾选）：
+
+| 编号 | 别名 | 含义 |
+|---|---|---|
+| 501 | `view` / `read` | 归档附件查看 |
+| 502 | `download` | 归档附件下载 |
+| 503 | `edit` | 归档附件编辑 |
+
+> 归档附件用的是 `501/502/503`，**不是**共享权限的 `401/402/403`，两套别混。
+
+`--file-rights` 不给就不发生成附件权限键，该行只有数据权限。
+
+## 幂等与回读
+
+- 添加前先查一遍：同一个授权对象 + 同一权限组合已存在时直接跳过并报「已存在」，不会重复创建。
+- 保存后按新增 ID 回读，逐项核对 `codeType` / `orgType` / `rightType` / `fileRight` / 创建人关系 / 取值字段映射；
+  `rightType` 与 `fileRight` 按**集合**比对（平台保留提交时的顺序，但顺序不承载语义）。
+- 回读的 `orgTypeName` 会和该类别的预期名称对照（如 `field_employee` 对应「人员字段」）。对不上直接报错 ——
+  那意味着授权对象写错了，不能静默放过。
+- 字段相关这类计算型授权，平台会回 `isShowRebuild=2`，此时按提示执行
+  `e10-cli form permission rebuild <objId> <appId> <权限ID>`。
+
+## 归档卡片
+
+每个流程还有一个「归档卡片」开关（`0` 关 / `1` 开）。不带 `--set` 时只读；带 `--set` 时先写再回读，以回读值为准。