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:
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:建待办后复用同意收口;高级设置默认关;或签整过 / 会签只过本人;连续自动通过;进度意见「系统自动通过」。
|
||||
Reference in new issue
Block a user