docs(oa): add auto-pass when approver is initiator design

Document advanced setting and engine behavior for skipping self-approval when the assignee equals the initiator.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
zlwuandCursor committed 2026-07-27 17:32:48 +08:00
1 parent 7f4c9720e9
commit 9b76aa654e
1 file changed
+179
@@ -0,0 +1,179 @@
# OA 审批 · 审批人为发起人时自动通过
| 项 | 内容 |
|----|------|
| 状态 | 已定稿(待实现) |
| 日期 | 2026-07-27 |
| 范围 | 高级设置开关;引擎在建待办后对「审批人含发起人」自动同意并推进;进度留痕;设计器 UI |
| 关联 | OA 引擎 `oa_engine.complete_task` / `advance_from`;高级设置 `DEFAULT_ADVANCED_SETTINGS`;钉钉风格总设计 `2026-07-14-oa-approval-dingtalk-design.md` §3(曾提及本能力未落地) |
---
## 1. 背景
流程设计可将第一步(或任意节点)审批人配成指定成员、部门负责人、主管、工作流角色等。当解析结果含**当前发起人本人**时,现网仍会建 `pending` 待办,需本人再点「同意」——常见于部门负责人发起、或配置失误把发起人写进审批人。
产品要求:做成**应用级高级设置开关(默认关)**,开启后系统代为同意并推进,减少无意义自批。
---
## 2. 目标与非目标
**目标**
- 高级设置增加开关 `autoPassWhenApproverIsInitiator`,默认 `false`,按**已发布应用版本**生效。
- 开启后:审批节点建完 pending,若存在 `assignee_user_id == initiator_user_id` 的待办,则系统按「同意」收口。
- **或签**:本人自动同意 → 整节点通过并推进(同节点其余 pending → `done`)。
- **会签**:仅自动完成本人那份;他人仍待批;若本人是唯一审批人则推进。
- **连续**:一直自动到「下一审批节点不含发起人」、会签仍有他人 pending、或流程结束。
- 进度可见:本人行为记为 `approved`,意见固定「系统自动通过」。
**非目标**
- 本期不实现「审批人去重」`approverDedup` 的引擎逻辑(UI 开关可继续存在,与本开关独立)。
- 不改变 `direct_supervisor`「主管不能是发起人本人」的解析报错。
- 不新增独立 `event_type=auto_approve`(以任务意见留痕;后续若报表需要再补)。
- 发起预览 V1 不增加「将自动通过」旁注。
- 小程序端、抄送节点语义变更。
- 加签后对整节点再次触发「整节点自动过」。
---
## 3. 产品决策(已确认)
| 项 | 决定 |
|----|------|
| 配置方式 | 高级设置开关,默认关,按应用版本 |
| 多人节点 | 或签整节点过;会签只过本人 |
| 连续节点 | 连续自动通过,直到不含发起人或结束 / 会签等人 |
| 实现路径 | 建待办后复用与 `complete_task(approve)` 等价的收口内核(方案 1) |
| 意见必填 | 系统代批**跳过** `commentRequired` |
| 进度 | 节点不隐藏;意见「系统自动通过」 |
---
## 4. 开关字段与配置 UI
### 4.1 存储
- 键名:`autoPassWhenApproverIsInitiator`
- 位置:`oa_app_version.advanced_settings_json`(与 `allowAddSign` 等同源)
- 默认:在 `DEFAULT_ADVANCED_SETTINGS` 中设为 `False` / `false`
- 与 `approverDedup` **独立**
### 4.2 设计器
- 路径:OA审批 → 审批管理 → 四步配置 → 高级设置
- 文案:**审批人为发起人时自动通过**
- Tip:开启后,解析到的审批人含发起人本人时,系统代为同意并推进;或签整节点通过,会签仅完成本人;可连续自动通过多个节点。默认关闭。
- 保存草稿 / 发布:随 `advancedSettingsJson` 一并读写(与现有开关相同)
### 4.3 生效范围
- 以实例绑定的**已发布版本**为准。
- 旧实例不回溯;开关变更只影响新发起(及该版本下后续推进时的新建待办节点)。
---
## 5. 引擎行为(SHALL)
### 5.1 实现路径
从 `complete_task` 抽出可复用的同意收口内核(建议名 `_approve_task_core` 或等价),供:
1. 人工 `complete_task(..., action="approve")`(保留 `commentRequired` 校验与 `db.commit`)
2. 自动通过(跳过意见必填;固定意见;由调用方决定是否 `commit`——通常随 `start_instance` / `complete_task` 外层一次提交)
内核须保持与现网一致:
- 任务 → `approved`,写入 `comment_text`、`update_by`、`update_time`
- `db.flush()` 后再查同节点 pending(避免 autoflush=False 下把自己盖成 `done`)
- 或签:同节点其余 pending → `done`,再 `advance_from(from_node=该节点)`
- 会签:若仍有他人 pending → **不** `advance_from`;否则推进
### 5.2 触发时机
在 `advance_from` 对审批节点调用 `_create_tasks_for_node` **成功之后**立刻检查:
1. `_advanced(ver).get("autoPassWhenApproverIsInitiator")` 为真
2. 实例仍 `running`
3. 刚创建(或该节点当前)存在:`task_type=approval`、`status=pending`、`assignee_user_id == inst.initiator_user_id`
满足则对该本人任务调用同意内核,`comment_text = "系统自动通过"`,`user_id` 使用发起人 id(与「本人同意」一致)。
若同意导致节点通过并 `advance_from` 进入下一审批节点,下一节点建待办后再次执行同一检查(连续自动通过)。沿用现有 `advance_from` safety 上限防死循环。
### 5.3 不触发
- 开关关闭
- 抄送节点(保持现有建即 done / 知会)
- 本人不在该节点 assignee 列表
- `direct_supervisor` 解析到本人仍抛错(不依赖本开关兜底)
- **加签**:仅追加他人 pending,不因加签对本节点发起人再跑一遍「自动整节点通过」
### 5.4 与意见必填
`commentRequired=true` 时,人工同意仍须填意见;系统自动通过**不**因此失败。
---
## 6. 进度 / 待办 / 预览
### 6.1 进度与 PDF
- 自动通过节点**不隐藏**。
- 发起人行:`approved` + 意见「系统自动通过」+ 代批时间。
- 或签其他人:现网「无需处理」;会签其他人:仍「待处理」直至其完成。
- 不新增专用进度组件;靠现有 `commentText` 区分。
### 6.2 实例事件
- V1 **不**新增 `auto_approve` 事件类型;任务状态与意见即为留痕。
### 6.3 待办列表
- 自动通过后本人该节点不再 `pending`。
- 会签下其他人待办不变。
### 6.4 发起预览
- V1:预览人员解析与展示不变,不加「将自动通过」旁注;以提交后进度为准。
---
## 7. 涉及文件(预期)
| 路径 | 变更 |
|------|------|
| `backend/app/crud/oa_approval.py` | `DEFAULT_ADVANCED_SETTINGS` 增加键 |
| `backend/app/services/oa_engine.py` | 抽同意内核;建待办后自动通过;连续推进 |
| `backend/tests/test_oa_engine.py`(或新测文件) | 或签/会签/连续/开关关/意见必填 |
| `web-admin/src/views/oa-approval/designer/index.vue` | 高级设置开关 + tip;reactive 默认值 |
---
## 8. 测试要点
1. 开关关:发起人在第一步审批人 → 仍 pending,需自批。
2. 开关开 + 或签单人=发起人 → 提交后该节点 approved,意见「系统自动通过」,流程推进。
3. 开关开 + 或签多人含发起人 → 本人 approved,他人 done,节点推进。
4. 开关开 + 会签多人含发起人 → 本人 approved,他人仍 pending,实例停在该节点。
5. 开关开 + 连续两审批节点皆含发起人 → 两节点均自动通过并继续。
6. `commentRequired=true` + 开关开 → 自动通过成功。
7. 开关开但节点不含发起人 → 行为与现网一致。
---
## 9. 风险与缓解
| 风险 | 缓解 |
|------|------|
| 抽内核时漏 flush 导致或签覆盖本人 approved | 单测覆盖或签;对齐现 `complete_task` 注释 |
| 连续自动通过死循环 | 沿用 `advance_from` safety;仅对 pending 本人触发一次 |
| 与未实现的 `approverDedup` 混淆 | 文档与 UI tip 写清二者独立;本期不改去重 |
---
## 10. 决议摘要
采用方案 1:建待办后复用同意收口;高级设置默认关;或签整过 / 会签只过本人;连续自动通过;进度意见「系统自动通过」。