| 1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465 |
- ---
- description: 将审批流接入任意业务模块时的工作流与前置决策（给 AI 看；人类开工也可参考）
- globs: server/Plugins/**/*BizHandler*.cs, server/Plugins/Admin.NET.Plugin.ApprovalFlow/**/*.cs, Web/src/views/approvalFlow/**, doc/**审批流**
- alwaysApply: false
- ---
- # 审批流集成工作流
- 当用户指派的任务属于「把审批流接入业务模块」或「实现 `IFlowBizHandler` / 嵌入 `ApprovalPanel`」时，严格按以下顺序执行，不要跳步。
- ## 第 1 步：阅读规范（必读，顺序不变）
- 1. **平台能力边界** — [`doc/审批流功能说明.md`](../../doc/审批流功能说明.md)
- 搞清审批流支持什么、不支持什么；节点 / 网关 / 超时 / 升级等配置项的含义。
- 2. **通用集成指南** — [`doc/审批流集成开发指南.md`](../../doc/审批流集成开发指南.md)
- 重点章节：
- - **十、集成实施套路** — 本工作流的五步清单以此为准
- - **十一、常见坑与反模式** — 四个典型坑（外部推送 TODO / 回调缺审批人 / 并发互斥 / 审批人必须是系统账号）
- - **十二、多 BizType 业务示例骨架** — 复杂业务的标准结构
- 3. **目标业务的需求文档** — 根据本次任务定位到对应 `doc/**.md`（如 `doc/S8异常协同-审批流集成功能说明.md`）
- **重点查看该文档末尾是否有「面向 Cursor 的实施参数清单」小节**（含 BizType 编码、GetBizData 字段、状态联动表、互斥规则、前端挂载点、决策上下文）。
- 4. **后期待办登记簿** — [`doc/plan/审批流-综合优化方案.md`](../../doc/plan/审批流-综合优化方案.md)
- 重点查看 **P4-16 外部推送渠道补齐** 和 **P4-17 Handler 回调增补 `instanceId` / `lastApproverId`** 的当前状态。
- ## 第 2 步：前置决策确认（**必须人工拍板**，AI 不得自行选）
- 对以下三项，若业务需求文档未写明或参数清单标注「决策上下文」且未确认，**停下来显式询问用户**：
- 1. **外部推送（钉钉 / 企微 / 邮件 / 短信）**：P4-16 未落地前仅站内消息会真实发送。业务首版接受仅站内 / 等 P4-16 / 走其它途径？
- 2. **Handler 回调拿审批人 ID**：P4-17 未落地前需要走「存 `instanceId` → 查 `timeline`」绕路。接受绕路 / 先推 P4-17 / 本业务不需要？
- 3. **审批人映射**：业务涉及的所有「审批人 / 审批角色」在 `SysUser`/`SysOrg` 里是否已有账号？若依赖「部门负责人」动态解析，`SysOrg.DirectorId` 或 `SysUser.ManagerUserId` 是否已维护？
- 决策结果应记录到该业务的实施方案 / 功能说明文档里，避免下次再问。
- ## 第 3 步：按实施套路五步清单推进
- 完全按 [`doc/审批流集成开发指南.md`](../../doc/审批流集成开发指南.md) 第十章「集成实施套路」的五步走：
- 1. 范围与决策确认
- 2. 后端 Handler（每个 `BizType` 一个，注意 `GetBizData` 字段名与业务参数清单对齐）
- 3. 前端 Panel（含多 `BizType` 互斥判定）
- 4. 配置（业务类型注册 + 流程设计与发布，属于管理员操作，不是代码）
- 5. 验收（8 个必跑场景）
- **每完成一步再进入下一步**；不要同时改后端与前端导致局部不可用。
- ## 第 4 步：验收与收尾
- - 必测 8 个场景：发起 / 同意走完 / 拒绝 / 撤回 / 同 `bizId` 重复发起被拦 / 未发布流程的友好提示 / 条件网关每条分支各走一次 / 超时或升级（若配置）
- - 复杂业务（多 `BizType`、含超时升级）需仿照 `_verify_escalation.py` 写 E2E 脚本自动回归
- - 提交前按 `.cursor/rules/version-bump-on-commit.mdc` 递增前后端 patch 版本
- - **交付完成的标志**：业务需求文档里的「面向 Cursor 的实施参数清单」每一项都能对上实际代码与配置
- ## 硬性禁止
- - ❌ **不得跳过第 1 步**直接开始写 Handler；每次对话开始时如果没确认读过规范，要先读
- - ❌ **不得自行对第 2 步的三个前置决策做选择**；必须显式询问
- - ❌ **不得在未登记为后期待办的前提下**修改 `Admin.NET.Plugin.ApprovalFlow` 插件自身代码；若业务强需求要动插件，先在 `doc/plan/审批流-综合优化方案.md` 登记新编号（P4-XX），再按"动手前须列清单、等确认"规则操作
- - ❌ **不得把审批人绑定为 ERP 员工工号**（审批人必须是 `SysUser` / 角色 / 部门 / 部门负责人 / 发起人本人）
- ## 配套文档
- - 通用（一次做好，所有业务复用）：`doc/审批流功能说明.md`、`doc/审批流集成开发指南.md`
- - 业务参数（每个业务一份，与业务文档同一位置）：`doc/<业务>-审批流集成功能说明.md` 末尾「面向 Cursor 的实施参数清单」
- - 待办与决策登记：`doc/plan/审批流-综合优化方案.md`
|
