375 lines
11 KiB
Markdown
375 lines
11 KiB
Markdown
# OA 审批流程节点与审批人规则参考
|
||
|
||
本文档描述钉钉 OA 审批的流程节点类型、审批模式、条件分支和审批人选择规则，用于理解审批模板结构和正确填写 `create-instance` 的节点参数。
|
||
|
||
---
|
||
|
||
## 流程结构概览
|
||
|
||
审批流程是一个嵌套树结构：
|
||
|
||
- **根节点**：发起人节点（`type: "start"`，`nodeId: "sid-startevent"`），固定不可删除
|
||
- **后续节点**：通过 `childNode` 链接形成链式结构
|
||
- **分支节点**：条件分支（`route` + `condition`）或并行分支（`parallel`）
|
||
- 当没有后续节点时，`childNode` 字段**必须省略**（不可设为 `null`）
|
||
|
||
---
|
||
|
||
## 7 种节点类型
|
||
|
||
### 1. 发起人节点（start）
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| `type` | `start` |
|
||
| `nodeId` | `sid-startevent`（固定） |
|
||
| `properties` | `{}`（空对象） |
|
||
|
||
唯一、不可删除。是流程的起点。
|
||
|
||
### 2. 审批人节点（approver）
|
||
|
||
核心决策节点，有审批/拒绝权限。
|
||
|
||
| 属性 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `actionerRules` | Array | 是 | 审批人选择规则，至少一条 |
|
||
| `activateType` | String | 是 | 多人审批模式（见下方） |
|
||
| `approvalType` | String | 是 | 固定 `"MANUAL"` |
|
||
| `agreeAll` | Boolean | 是 | `true` 全部通过 / `false` 任一通过 |
|
||
| `noneActionerAction` | String | 否 | 如 `"admin"`（找不到审批人时转管理员） |
|
||
|
||
支持全部 10 种 actionerRules 类型。
|
||
|
||
### 3. 办理人节点（handler）
|
||
|
||
执行工作，无审批决策权。
|
||
|
||
| 属性 | 类型 | 必填 |
|
||
|------|------|------|
|
||
| `actionerRules` | Array | 是 |
|
||
| `activateType` | String | 是 |
|
||
|
||
支持 9 种 actionerRules（不支持 `target_matrix_approval`）。
|
||
|
||
### 4. 抄送人节点（notifier）
|
||
|
||
仅接收通知，无决策权。
|
||
|
||
| 属性 | 类型 | 必填 |
|
||
|------|------|------|
|
||
| `actionerRules` | Array | 是 |
|
||
|
||
支持多条 actionerRules 组合在一个节点中，实现同时抄送多类人员。
|
||
|
||
### 5. 条件分支（route + condition）
|
||
|
||
条件路由节点，包含多个条件分支。
|
||
|
||
**route 节点：**
|
||
- `type: "route"`
|
||
- `conditionNodes[]`：分支数组，按优先级排序，**默认分支必须在最后**
|
||
- `properties: {}`
|
||
|
||
**condition 节点（conditionNodes 的每个元素）：**
|
||
- `type: "condition"`
|
||
- `isdefault: true`：标记默认分支
|
||
- `properties.conditions`：二维条件数组
|
||
- 外层数组：多个条件组，**OR 关系**
|
||
- 内层数组：多个条件对象，**AND 关系**
|
||
- 默认分支：`[[]]`（一个空组）
|
||
|
||
### 6. 并行分支（parallel）
|
||
|
||
多个分支同时执行，全部完成后才继续。
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| `branches[]` | 分支数组 |
|
||
| `branches[].name` | 分支名称 |
|
||
| `branches[].childNode` | 该分支的第一个节点 |
|
||
|
||
### 7. 付款人节点（payer）
|
||
|
||
财务付款节点。
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| `actionerRules` | 审批人规则 |
|
||
| `paymentConfig.amountField` | 金额控件 ID |
|
||
| `paymentConfig.accountField` | 收款账户控件 ID |
|
||
|
||
---
|
||
|
||
## 多人审批模式
|
||
|
||
| 模式 | `activateType` | `agreeAll` | 说明 |
|
||
|------|---------------|-----------|------|
|
||
| 会签 | `"ALL"` | `true` | 所有审批人都必须审批通过 |
|
||
| 或签 | `"ALL"` | `false` | 任一审批人审批即可 |
|
||
| 依次审批 | `"ONE_BY_ONE"` | `true` | 按顺序逐级审批 |
|
||
|
||
---
|
||
|
||
## 10 种审批人选择规则（actionerRules）
|
||
|
||
### 1. 指定成员（target_approval）
|
||
|
||
明确指定具体人员。
|
||
|
||
```json
|
||
{
|
||
"type": "target_approval",
|
||
"approvals": [
|
||
{ "userName": "张三", "workNo": "manager123" }
|
||
],
|
||
"isEmpty": false
|
||
}
|
||
```
|
||
|
||
- `workNo` 必须通过 `dws aisearch person --query "<工号>" --dimension jobNumber --format json` 获取，**严禁编造**
|
||
- 在 `create-instance` 中对应 `directAppointedApprovers` 的 `staffIds`
|
||
|
||
### 2. 直属主管（target_formula / reportLineManager）
|
||
|
||
按汇报线找到直属主管。
|
||
|
||
```json
|
||
{
|
||
"type": "target_formula",
|
||
"subType": "reportLineManager",
|
||
"formula": "ReportLineManager(corpId,originator,1)",
|
||
"isEmpty": false
|
||
}
|
||
```
|
||
|
||
- `formula` 中最后的数字 N 表示第 N 级主管
|
||
- **重要区分：** 用户说"直属主管/直属领导/汇报线主管"才用此规则；用户说"主管审批/leader审批"（模糊）时默认用 `target_management`（部门主管）
|
||
|
||
### 3. 发起人自己（target_originator）
|
||
|
||
发起人自行审批。
|
||
|
||
```json
|
||
{
|
||
"type": "target_originator",
|
||
"isEmpty": false
|
||
}
|
||
```
|
||
|
||
最简单的规则，只有 `type` 和 `isEmpty`。
|
||
|
||
### 4. 部门主管（target_management）
|
||
|
||
从发起人所在部门层级找主管。
|
||
|
||
```json
|
||
{
|
||
"type": "target_management",
|
||
"level": 1,
|
||
"autoUp": true,
|
||
"isEmpty": false
|
||
}
|
||
```
|
||
|
||
- `level: 1`：直接部门主管
|
||
- `autoUp: true`：找不到时向上级部门搜索
|
||
- **这是"主管审批/leader审批"模糊场景的默认选择**
|
||
|
||
### 5. 表单部门主管（target_formula / managerOfDept）
|
||
|
||
根据表单中部门控件选择的主管。
|
||
|
||
```json
|
||
{
|
||
"type": "target_formula",
|
||
"subType": "managerOfDept",
|
||
"formula": "ManagerOfDept(corpId,$('DepartmentField_XXX'),1)",
|
||
"isEmpty": false
|
||
}
|
||
```
|
||
|
||
- `formula` 中引用表单中的 `DepartmentField` 控件 ID
|
||
|
||
### 6. 发起人自选（target_select）
|
||
|
||
发起人在提单时自行选择审批人。
|
||
|
||
```json
|
||
{
|
||
"type": "target_select",
|
||
"select": ["allStaff"],
|
||
"range": {},
|
||
"key": "manual_nodeId_xxxx_yyyy",
|
||
"multi": 1,
|
||
"isEmpty": false
|
||
}
|
||
```
|
||
|
||
- `select: ["allStaff"]`：可选全组织人员
|
||
- `multi: 1`：单选
|
||
- `key`：格式 `manual_{nodeId}_{hex}_{hex}`
|
||
- 在 `create-instance` 中对应 `targetSelectActioners` 的 `actionerKey`
|
||
|
||
### 7. 角色标签主管（target_managers_labels）
|
||
|
||
按角色标签找多级主管。
|
||
|
||
```json
|
||
{
|
||
"type": "target_managers_labels",
|
||
"labelNames": ["项目经理"],
|
||
"labels": ["labelId123"],
|
||
"levels": [1],
|
||
"isEmpty": false
|
||
}
|
||
```
|
||
|
||
- `labels` 中的 ID 必须通过 `dws contact label get --names "<角色名>" --format json` 获取；已知角色名时直接查询，否则先 `dws contact label list --format json` 获取全部角色列表后匹配
|
||
|
||
### 8. 表单联系人（target_formcomponent_approval）
|
||
|
||
从表单中的联系人控件读取审批人。
|
||
|
||
```json
|
||
{
|
||
"type": "target_formcomponent_approval",
|
||
"paramKey": "InnerContactField_XXX",
|
||
"label": "项目负责人",
|
||
"isEmpty": false
|
||
}
|
||
```
|
||
|
||
- `paramKey` 指向表单中的 `InnerContactField` 控件 ID
|
||
- 该控件中填写的人即为审批人
|
||
|
||
### 9. 角色标签（target_label）
|
||
|
||
按角色标签找人（如"财务"、"HR"）。
|
||
|
||
```json
|
||
{
|
||
"type": "target_label",
|
||
"labelNames": "财务",
|
||
"labels": "459272424",
|
||
"isEmpty": false
|
||
}
|
||
```
|
||
|
||
- `labels`：角色标签 ID（字符串），必须通过 `dws contact label get --names "<角色名>" --format json` 获取；未知角色名时先 `dws contact label list --format json`
|
||
- `labelNames`：角色显示名称
|
||
- **严禁编造 label ID**
|
||
|
||
### 10. 审批矩阵（target_matrix_approval）
|
||
|
||
按审批矩阵规则确定审批人。
|
||
|
||
```json
|
||
{
|
||
"type": "target_matrix_approval",
|
||
"matrixId": "xxx",
|
||
"roleColumnId": "yyy",
|
||
"expression": {
|
||
"subFilters": [...],
|
||
"operator": "AND"
|
||
}
|
||
}
|
||
```
|
||
|
||
- 仅适用于审批人节点
|
||
- 目前尚在完善中
|
||
|
||
---
|
||
|
||
## 条件分支详解
|
||
|
||
### 条件类型
|
||
|
||
| `type` | 依据 | 关键字段 |
|
||
|--------|------|---------|
|
||
| `dingtalk_actioner_dept_condition` | 发起人部门/人员/角色 | `paramKey: "dingtalk_origin_dept"`, `conds[]` |
|
||
| `dingtalk_actioner_dept_component_condition` | 表单部门控件 | `paramKey: 控件ID`, `conds[]` |
|
||
| `dingtalk_actioner_range_condition` | 数值/金额/时长范围 | `lowerBound`(>=) / `lowerBoundNotEqual`(>) / `upperBoundEqual`(<=) / `upperBound`(<) / `boundEqual`(=) |
|
||
| `dingtalk_actioner_value_condition` | 单选匹配 | `paramKey: 控件ID`, `paramValues[]`（选项 key） |
|
||
| `dingtalk_multi_value_condition` | 多选匹配 | `paramKey: 控件ID`, `paramValues[]`, `matchType`(1=精确/2=全选/3=任一) |
|
||
| `dingtalk_actioner_cascade_component_condition` | 级联控件 | `paramValues[]`, `displayValues[]` |
|
||
| `dingtalk_actioner_boolean_condition` | 布尔值 | `boundEqual: true/false` |
|
||
| `dingtalk_rule_template` | 节假日判断 | `template`, `outVars` |
|
||
| `dingtalk_formula` | 公式 | `formula`, `formulaDisplay` |
|
||
| `dingtalk_biz_var_condition` | 业务变量 | `dsKey`, `conds[]` |
|
||
| `dingtalk_table_condition` | 明细内字段 | `parentFieldId`, `componentName`, `paramValue` |
|
||
|
||
### 范围条件操作符
|
||
|
||
| 字段 | 含义 |
|
||
|------|------|
|
||
| `lowerBound` | >= (大于等于) |
|
||
| `lowerBoundNotEqual` | > (大于) |
|
||
| `upperBoundEqual` | <= (小于等于) |
|
||
| `upperBound` | < (小于) |
|
||
| `boundEqual` | = (等于) |
|
||
|
||
### 默认分支
|
||
|
||
- `isdefault: true`
|
||
- `conditions: [[]]`（一个空的条件组）
|
||
- **必须放在 `conditionNodes[]` 的最后**
|
||
|
||
---
|
||
|
||
## create-instance 中的节点参数映射
|
||
|
||
### directAppointedApprovers（指定审批人覆盖模板流程）
|
||
|
||
当需要**不使用模板默认流程、直接指定审批人**时使用。
|
||
|
||
```json
|
||
{
|
||
"directAppointedApprovers": [
|
||
{
|
||
"staffIds": ["userId1", "userId2"],
|
||
"taskActionType": "NONE",
|
||
"staffId": ""
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `staffIds` | 审批人 userId 列表（通过 `dws aisearch person --query "<姓名>" --dimension name --format json` 获取；多结果须消歧） |
|
||
| `taskActionType` | `NONE`（单人）/ `AND`（会签）/ `OR`（或签） |
|
||
| `staffId` | 留空字符串 |
|
||
|
||
### targetSelectActioners（自选审批人）
|
||
|
||
当模板流程中存在**自选审批节点**（`target_select` 类型）时必填。
|
||
|
||
```json
|
||
{
|
||
"targetSelectActioners": [
|
||
{
|
||
"actionerKey": "manual_nodeId_xxxx_yyyy",
|
||
"actionerStaffIds": ["userId1"]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `actionerKey` | 自选节点的规则 key，从审批流程节点信息接口获取 `actorKey` |
|
||
| `actionerStaffIds` | 操作人 userId 列表 |
|
||
|
||
---
|
||
|
||
## 组装优先级
|
||
|
||
1. 先用 `forecast-process` 获取模板的流程节点结构（`workflowActivityRuleVOs`）
|
||
2. 根据节点中的 `activityType` 和 `targetSelect` 判断是否需要传入 `directAppointedApprovers` 或 `targetSelectActioners`
|
||
3. 如果预测返回 `targetSelect: true` 的自选节点，`targetSelectActioners` 必填
|
||
4. 如果用户要求覆盖默认流程，使用 `directAppointedApprovers`
|
||
5. **所有 userId 必须通过 `dws aisearch person --query "<姓名>" --dimension name --format json` 获取，严禁填姓名；多结果须消歧**
|
||
|
||
> **交互优化：** 若用户在 `forecast-process` 前已指定审批人/抄送人姓名，`forecast-process` 返回自选节点后应自动映射，仅对未覆盖的自选节点追问，不要重复询问。详见 [oa.md](../oa.md) 交互优化原则。
|