流程用户组与评论

概述

流程用户组与流程评论是工作流（BPM）中两个相对独立但都很常用的能力：

• 流程用户组：把一批用户组织成一个可复用的"组"，在流程设计器中作为审批人候选策略（指定用户组）被节点引用，避免在每个审批节点重复选择人员。
• 流程评论：围绕流程实例/任务产生的讨论与操作记录，既支持用户主动留言，也会由审批动作（通过、驳回、退回、转派等）自动写入系统评论。

两者都归属 module_bpm，分别位于 user_group 与 comment 子模块，表名分别为 bpm_user_group 与 bpm_comment。

---

流程用户组

概念与定位

用户组本质上是一份"用户编号数组 + 元信息"的配置，本身不参与流程流转，而是作为候选人策略的输入被引擎消费。在审批节点的候选策略中，选择"指定用户组"（USER_GROUP = 40）并勾选若干用户组后，引擎在节点推进时会把组内所有成员展开为候选审批人。

与"指定用户""指定角色""部门成员"等策略相比，用户组的优势在于人员可集中维护：人事变动时只需在用户组里增删成员，无需逐个修改流程模型。

数据模型

用户组表 bpm_user_group 关键字段：

字段	说明
name	组名
description	描述
user_ids	成员用户编号数组（JSON 存储）
status	状态，0 开启 / 1 关闭
remark	备注

用户组继承 ModelMixin 与 UserMixin，具备标准创建/更新时间与操作人字段；权限策略为 NONE，由接口层 RBAC 控制。

后端接口

用户组接口路径前缀为 /bpm/user-group，统一需要对应权限。

接口	方法	权限	说明
/bpm/user-group/page	GET	bpm:user-group:query	分页查询
/bpm/user-group/simple-list	GET	bpm:user-group:query	下拉用简单列表（设计器加载用）
/bpm/user-group/get	GET	bpm:user-group:query	详情
/bpm/user-group/create	POST	bpm:user-group:create	新增
/bpm/user-group/update	PUT	bpm:user-group:update	修改
/bpm/user-group/delete	DELETE	bpm:user-group:delete	删除

服务层 BpmUserGroupService 基于通用 CRUDBase 实现，逻辑较薄（分页、详情、增删改），成员以 user_ids 数组整体写入。

在流程引擎中的集成

用户组真正的价值在候选计算。引擎 framework/candidate.py 的 calculate_users 在校验策略属于 SUPPORTED_CANDIDATE_STRATEGIES 后，针对 USER_GROUP 分支读取所选用户组的 user_ids 并合并去重：

elif strategy == BpmCandidateStrategyEnum.USER_GROUP:
    group_ids = parse_param_ids(param)
    if group_ids:
        rows = await db.execute(
            select(BpmUserGroupModel.user_ids).where(BpmUserGroupModel.id.in_(group_ids))
        )
        for group_user_ids in rows.scalars().all():
            user_ids.extend(group_user_ids or [])

也就是说，节点配置里保存的是"用户组编号列表"，运行时引擎再去解析成具体用户。这意味着用户组增删成员会实时反映到后续发起的流程，已生成任务不受影响（任务已落库候选人）。

前端

前端位于 apps/web-ele/src/views/bpm/group，页面 index.vue 使用 Vben 的 useVbenVxeGrid 表格 + FormModal 弹窗完成增删改查，工具栏与行内操作按钮均绑定 bpm:user-group:* 权限。

接口封装在 src/api/bpm/userGroup/index.ts，除常规的 page / get / create / update / delete 外，特别提供 getUserGroupSimpleList() 用于流程设计器的用户组下拉。

在设计器内，用户组以"候选策略 → 用户组"的方式被引用：

• 设计器初始化时调用 getUserGroupSimpleList() 加载 userGroupList 并 provide 给各节点配置组件；
• user-task-node-config.vue 与 copy-task-node-config.vue 在 candidateStrategy === USER_GROUP(40) 时展示"指定用户组"多选框，绑定 configForm.userGroups；
• 保存时将 userGroups 以逗号拼接成 candidateParam；回显时再拆分回数组。

---

流程评论

概念与定位

流程评论以流程实例为单位组织，并可关联到具体任务。它同时承担两类角色：

1. 协作讨论：参与者在流程详情页主动留言，沟通审批意见。
2. 操作留痕：审批动作（通过、不通过、退回、转派、加签、委派等）由系统自动写入一条对应类型的评论，形成完整的流程时间线。

数据模型

评论表 bpm_comment 关键字段：

字段	说明
instance_id	流程实例编号（索引）
task_id	关联任务编号（可选）
user_id	评论人编号（索引）
type	评论类型，见下方枚举
message	评论内容（最长 1024）

评论同样继承 ModelMixin/UserMixin，权限策略 NONE，由接口层 bpm:task:* 控制读写。

评论类型枚举

framework/constants.py 中 BpmCommentTypeEnum（字符串枚举）定义了评论类型，前端通过字典 bpm_comment_type 渲染标签与颜色：

type	含义
0 COMMENT	评论
1 APPROVE	审批通过
2 REJECT	不通过
3 CANCEL	已取消
4 RETURN	退回
5 DELEGATE_START	委派发起
6 DELEGATE_END	委派完成
7 TRANSFER	转派
8 ADD_SIGN	加签
9 SUB_SIGN	减签

其中 COMMENT 由用户主动创建，其余多由引擎在审批动作中自动产生（本文档聚焦评论模块本身，审批动作如何写评论可参见"流程实例与任务"）。

后端接口

评论接口路径前缀为 /bpm/comment：

接口	方法	权限	说明
/bpm/comment/create	POST	bpm:task:update	新增评论
/bpm/comment/list-by-process-instance-id	GET	bpm:task:query	按流程实例查询评论列表

BpmCommentService.create 的入参只需 message，并允许通过 task_id 或 process_instance_id 指定归属：若只传了 task_id，服务会自动反查出所属 instance_id；两者皆缺则抛出异常。创建时 type 固定为 COMMENT，user_id 取自当前登录用户。

查询接口 list_by_process_instance_id 按 id 升序返回该实例的全部评论，并通过 candidate.get_user_map 批量拼接评论人的昵称、头像、部门信息，最终返回结构含 id / taskId / userId / type / message / createTime / user。

前端

前端接口封装在 src/api/bpm/comment/index.ts：

• getCommentListByProcessInstanceId(processInstanceId)：拉取某实例评论。
• createComment(taskId, message)：提交评论（注意该封装默认只传 taskId，由后端反查实例；如需直接关联实例可扩展传 processInstanceId）。

流程详情页 views/bpm/processInstance/detail 中的 modules/comment-list.vue 负责渲染评论时间线：

• 顶部显示"流程评论 共 N 条"；
• 每条评论左侧用首字圆形头像代表类型（取自 bpm_comment_type 字典的简称/颜色），区分评论与各类系统操作；
• 展示评论人头像/昵称、DictTag 类型标签、关联任务名（如有）以及格式化时间；
• 内容区以气泡样式呈现 message，空状态显示 ElEmpty。