diff --git a/docs/superpowers/specs/2026-07-27-oa-auto-pass-initiator-approver-design.md b/docs/superpowers/specs/2026-07-27-oa-auto-pass-initiator-approver-design.md new file mode 100644 index 00000000..da11b3a6 --- /dev/null +++ b/docs/superpowers/specs/2026-07-27-oa-auto-pass-initiator-approver-design.md @@ -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:建待办后复用同意收口;高级设置默认关;或签整过 / 会签只过本人;连续自动通过;进度意见「系统自动通过」。