9.5 KiB
9.5 KiB
抄送人节点 · 多种选人方式并集(钉钉式)
日期: 2026-07-30
范围:
web-admin审批设计器「3 流程设计」· 抄送人节点配置(FlowDesigner.vue/flow-tree/types.ts)backend发布校验(oa_publish.py)、审批人解析(oa_assignee.py)、引擎建任务 / 预览 / 进度(oa_engine.py)- 发起预览中「发起人自选」判定与人员并集(
OaFlowPreview等相关前端)
关联:
docs/superpowers/specs/2026-07-14-oa-approval-dingtalk-design.md§5.3(选人策略)docs/superpowers/specs/2026-07-23-oa-initiator-select-in-flow-design.md(抄送自选可空)- 产品对照:钉钉审批 · 抄送人可同时启用多种选人方式,结果取并集
1. 背景与目标
现状
- 审批人 / 抄送人节点共用
approverConfig.assigneeType(单值),设计器为分段单选。 - 五种方式:
users|oa_roles|dept_leader|direct_supervisor|initiator_select。 - 引擎
resolve_assignees按单一类型硬分支;失败则抛AssigneeResolveError。 - 抄送特例:仅当
assigneeType === initiator_select且发起人未选人时,跳过建任务且不报错。
目标
- 仅抄送人节点支持同时勾选多种选人方式,运行时对各方式解析结果并集去重后建抄送任务。
- 运行时:软跳过失败/空策略;最终 0 人时不报错、不建任务(对齐现有「发起人自选抄送可空」)。
- 发布时:至少勾选 1 种;勾了
users/oa_roles则必须已配置成员/角色。 - 兼容已发布/草稿中仅含旧字段
assigneeType的抄送配置,行为与现网一致。
非目标
- 不改审批人节点(仍单选一种 + 或签/会签)。
- 不新增数据库表或列(流程定义仍为 JSON)。
- 不改变抄送任务「建即 done / 不阻断流程」语义。
- 不做历史实例数据回填迁移脚本(只读兼容即可)。
2. 产品约定(已确认)
| 项 | 结论 |
|---|---|
| 范围 | 仅抄送人;审批人保持单选 |
| 运行时合并 | 各勾选方式独立解析 → 人 ID 并集去重(保序:按 assigneeTypes 顺序,同策略内保持原序) |
| 单策略失败/空 | 软跳过该策略,继续其它策略 |
| 最终 0 人 | 不报错,不创建抄送任务,流程继续 |
| 发布校验 | 必须勾选 ≥1 种;users / oa_roles 若勾选则配置不可空;dept_leader / direct_supervisor / initiator_select 勾选即可 |
| 取消勾选 | UI 可不清空已填 userIds / oaRoleIds;发布只校验当前勾选的策略 |
| 发起人自选并存 | 仍按节点 ➕ 选人;自选列表可空;与固定策略结果并集 |
3. 配置模型
3.1 类型(前端 ApproverConfig)
export interface ApproverConfig {
/** 审批人:单选(必填)。抄送人:兼容旧数据 / 可选双写首项 */
assigneeType?: AssigneeType
/** 抄送人:多选选人方式(优先)。审批人:不使用 */
assigneeTypes?: AssigneeType[]
userIds?: string[]
oaRoleIds?: string[]
oaRoleCodes?: string[]
signMode?: 'or' | 'and' // 仅审批有意义;抄送引擎侧仍固定 cc
}
3.2 写入约定(设计器保存抄送节点)
- 写入非空
assigneeTypes(去重、仅含合法枚举、保持勾选顺序)。 - 双写
assigneeType = assigneeTypes[0],便于未改完的只读展示兜底。 userIds/oaRoleIds始终可随表单保留;解析时仅当对应类型在assigneeTypes中才使用。
3.3 读取约定(后端 / 前端统一 helper)
对节点 approverConfig:
- 若
assigneeTypes为非空数组 → 过滤非法项后作为类型列表(抄送多选)。 - 否则若存在非空
assigneeType→[assigneeType]。 - 否则 →
[](发布校验会拦;运行时抄送视为 0 人)。
审批节点:忽略 assigneeTypes(即使误写入),只认 assigneeType。
4. 解析与引擎
4.1 oa_assignee.py
保留现有 resolve_assignees(单策略、失败抛错)供审批使用。
新增(名称可微调,语义如下):
resolve_cc_assignees(...) -> (user_ids: List[str], meta: Dict)
行为:
- 用 §3.3 得到
types。 - 对每个
t in types:构造单策略临时 config,调用现有单策略逻辑(或内联相同分支)。 try/except AssigneeResolveError:捕获则跳过该策略,并在meta.skipped记录{ type, reason }。- 单策略返回空列表:视为跳过(不抛错)。
- 合并去重;
meta.resolve_source建议:- 仅一种成功:该策略名(兼容旧展示)
- 多种成功:
"multi",并带sources: [...]
- 永不因「全部失败」抛错;返回
([], meta)合法。
initiator_select:仍使用调用方传入的 initiator_select_user_ids;空则该策略跳过。
4.2 oa_engine.py · _create_tasks_for_node(及预览同类路径)
对 ntype == "cc":
- 调用
resolve_cc_assignees(不再先特判「仅 initiator_select 且空则 return」——该语义被多策略软跳过覆盖)。 - 若
assignees为空 →return created(不抛错)。 - 非空 → 按现逻辑为每人建
task_type=cc、status=done任务。
对 ntype == "approval":行为不变(resolve_assignees + 硬失败;自选空仍抛错)。
预览 / 进度未达节点解析抄送人员:同样走 resolve_cc_assignees,空列表展示为无人抄送(不阻断预览)。
4.3 发起预览前端
判断节点是否可 ➕ 自选:
- 旧:
assigneeType === 'initiator_select' - 新:类型列表(§3.3)包含
initiator_select
固定策略解析出的人只读展示;自选人仍写入按节点 map,提交后与固定人并集由引擎完成。
5. 发布校验(oa_publish.py)
对 type === "cc":
| 条件 | 结果 |
|---|---|
| 类型列表为空 | 错误:未配置抄送人策略 |
| 含非法类型 | 错误 |
含 users 且 userIds 为空 |
错误:指定成员不能为空 |
含 oa_roles 且角色 id/code 皆空 |
错误:工作流角色不能为空 |
| 仅含 dept_leader / direct_supervisor / initiator_select | 通过 |
对 type === "approval":保持现有单 assigneeType 校验,不启用 assigneeTypes。
6. 设计器 UI
6.1 抄送人抽屉
- 「选人方式」分段控件改为多选:再次点击已选可取消(取消后若变为 0 种,确定保存前前端提示至少一种;发布后端再拦一道)。
- 勾选
users时展示指定成员区;勾选oa_roles时展示角色区;可同时展开。 - 副标题可改为:「可同时选择多种方式,抄送时合并去重」。
6.2 审批人抽屉
- 保持单选;逻辑与现网一致。
6.3 画布摘要
- 抄送:多种时拼接标签,如
指定成员 + 部门负责人;过长可截断。 - 审批:不变。
7. 兼容与迁移
| 场景 | 行为 |
|---|---|
旧抄送仅有 assigneeType |
读作单元素列表;运行/发布与现网一致 |
新抄送有 assigneeTypes |
按多选;双写首项 assigneeType |
| 旧运行中实例 | 已落库任务不受影响;未达节点若重解析则走新逻辑(旧 JSON 无 assigneeTypes 时仍单策略) |
审批节点误带 assigneeTypes |
引擎/发布忽略,只认 assigneeType |
无需 SQL patch。
8. 主要改动文件
| 路径 | 变更 |
|---|---|
web-admin/.../flow-tree/types.ts |
assigneeTypes;摘要文案;默认抄送配置 |
web-admin/.../flow-tree/FlowDesigner.vue |
抄送多选 UI;读写;校验提示 |
web-admin/.../OaFlowPreview.vue(及同类) |
includes('initiator_select') |
web-admin/.../OaProgressChain.vue(若展示策略名) |
支持 multi / 多标签 |
backend/app/services/oa_assignee.py |
resolve_cc_assignees |
backend/app/services/oa_publish.py |
抄送多类型校验 |
backend/app/services/oa_engine.py |
抄送建任务/预览走新解析 |
backend/tests/(若有 OA 测例) |
并集、软跳过、0 人、发布校验、旧字段兼容 |
9. 测试要点
- 兼容:旧单
assigneeType=users抄送,指定成员仍抄送成功。 - 并集:勾选指定成员 A + 部门负责人 B(且 B 有效)→ 两人收到抄送。
- 软跳过:勾选部门负责人(未配置)+ 有效指定成员 → 仅抄送指定成员,发起/推进不报错。
- 0 人:仅勾发起人自选且发起不选人 → 不建抄送任务,流程可发起/可推进。
- 全失败:仅勾部门负责人且未配置 → 不建任务、不报错。
- 发布:勾选指定成员但未选人 → 发布失败;至少勾一种通过。
- 审批回归:审批人仍单选;多人会签/或签/自选必填行为不变。
- 发起 ➕:抄送
assigneeTypes含initiator_select时节点仍可点选加人。
10. 开放细节(实现时可定,不阻规格)
meta.resolve_source === "multi"时进度文案具体用「多种选人方式」还是拼接中文标签——实现时与现有OaProgressChain文案表对齐即可。- 设计器取消最后一种选人方式时:禁止取消 vs 允许取消但确定时 ElMessage 拦截——推荐后者与发布校验一致。
修订记录
| 日期 | 说明 |
|---|---|
| 2026-07-30 | 初稿:仅抄送多选;软跳过+允许 0 人;发布至少一种且 users/roles 配置要齐;assigneeTypes + 旧字段兼容 + 双写首项 |