若依工作流模型管理模块 - 需求分析+设计文档+接口文档

一、需求分析

1. 核心业务背景

该模块是若依（RuoYi-Vue-Plus）框架集成Activiti工作流引擎的核心模块，聚焦流程模型全生命周期管理，解决从模型创建、编辑、部署到导出、转换的全流程管理需求，适配企业级流程设计与执行的业务场景。

2. 核心业务需求

3. 非功能需求

• 参数校验：所有入参（如模型ID、流程定义ID）需做非空/格式校验，避免无效请求；
• 防重复提交：新增、修改、删除操作需防重复提交，避免数据异常；
• 事务控制：批量删除模型需保证事务一致性，失败则回滚；
• 日志记录：核心操作（新增、修改、部署、删除）需记录业务日志，便于审计；
• 异常处理：所有操作需返回统一格式结果（成功/失败），前端可友好展示；
• 兼容性：适配Activiti引擎的模型/流程定义数据结构，保证数据互通。

4. 边界约束

• 仅管理Activiti的Model（模型）对象，不直接操作流程实例/任务；
• 模型部署后生成ProcessDefinition（流程定义），需关联模型ID便于追溯；
• 仅支持单模型导出ZIP，暂不支持批量导出；
• 反向转换仅支持“流程定义→模型”，不支持模型→流程实例的直接转换。

二、设计文档

1. 架构设计

1.1 分层设计

遵循若依框架的分层架构，模块内部分层如下：

• Controller层：接收前端请求，做参数校验、请求分发，返回统一响应；
• Service层：封装核心业务逻辑（如模型部署、转换、导出）；
• Activiti API层：调用Activiti的RepositoryService操作模型/流程定义；
• 数据层：基于Activiti原生表（act_re_model/act_re_procdef）存储核心数据。

1.2 核心类设计

1.3 数据模型设计（核心关联表）

2. 核心流程设计

2.1 新建模型流程

2.2 模型部署流程

3. 关键设计要点

• 参数校验：通过@Validated+分组（AddGroup/EditGroup）实现新增/编辑场景的差异化校验；
• 防重复提交：通过@RepeatSubmit注解拦截重复请求，避免重复创建/修改模型；
• 事务控制：批量删除模型添加@Transactional，保证删除操作的原子性；
• 统一响应：通过R（若依统一响应类）返回结果，前端可统一解析；
• 日志审计：通过@Log注解记录操作日志，包含操作类型、标题，支撑审计需求。

三、接口文档

1. 接口基础信息

### 2. 接口详情 #### 2.1 新建模型 - **接口地址**：`POST /workflow/model` - **接口名称**：新建流程模型 - **接口描述**：创建空的流程模型，初始化基础元信息并存储 - **请求参数**（RequestBody）： | 参数名 | 类型 | 是否必填 | 说明 | |--------|------|----------|------| | name | String | 是 | 模型名称 | | key | String | 是 | 模型标识（唯一） | | category | String | 否 | 模型分类 | | version | Integer | 否 | 模型版本 | | description | String | 否 | 模型描述 | - **请求示例**： ```json { "name": "采购审批流程", "key": "purchase_approval", "category": "采购管理", "version": 1, "description": "企业采购审批全流程" }

• 响应示例：

{"code":200,"msg":"操作成功","data":{"id":"150001","name":"采购审批流程","key":"purchase_approval","category":"采购管理","version":1,"deploymentId":null}}

2.2 查询模型列表

• 接口地址：GET /workflow/model/list
• 接口名称：分页查询模型列表
• 接口描述：根据条件分页查询流程模型列表
• 请求参数（RequestParam）：
  | 参数名 | 类型 | 是否必填 | 说明 |
  |--------|------|----------|------|
  | name | String | 否 | 模型名称（模糊查询） |
  | key | String | 否 | 模型标识（精确查询） |
  | category | String | 否 | 模型分类（精确查询） |
  | pageNum | Integer | 是 | 页码（默认1） |
  | pageSize | Integer | 是 | 页大小（默认10） |
• 响应示例：

{"code":200,"msg":"操作成功","data":{"total":50,"rows":[{"id":"150001","name":"采购审批流程","key":"purchase_approval","category":"采购管理","version":1,"deploymentId":"160001"}]}}

2.3 保存模型XML

• 接口地址：PUT /workflow/model
• 接口名称：保存模型XML配置
• 接口描述：保存流程设计器编辑后的模型XML内容
• 请求参数（RequestBody）：
  | 参数名 | 类型 | 是否必填 | 说明 |
  |--------|------|----------|------|
  | modelId | String | 是 | 模型ID |
  | xmlContent | String | 是 | 模型XML配置内容（BPMN 2.0格式） |
• 请求示例：

{"modelId":"150001","xmlContent":"<definitions xmlns=\"http://www.omg.org/spec/BPMN/20100524/MODEL\">...</definitions>"}

• 响应示例：

{"code":200,"msg":"操作成功","data":null}

2.4 查询模型XML内容

• 接口地址：GET /workflow/model/getInfo/{modelId}/xml
• 接口名称：查询模型XML编辑内容
• 接口描述：获取指定模型的XML配置，供流程设计器加载
• 路径参数：
  | 参数名 | 类型 | 是否必填 | 说明 |
  |--------|------|----------|------|
  | modelId | String | 是 | 模型ID |
• 响应示例：

{"code":200,"msg":"操作成功","data":{"xmlContent":"<definitions xmlns=\"http://www.omg.org/spec/BPMN/20100524/MODEL\">...</definitions>","modelInfo":{"name":"采购审批流程","key":"purchase_approval"}}}

2.5 模型部署

• 接口地址：POST /workflow/model/deploy/{id}
• 接口名称：部署流程模型
• 接口描述：将模型转换为可执行的流程定义
• 路径参数：
  | 参数名 | 类型 | 是否必填 | 说明 |
  |--------|------|----------|------|
  | id | String | 是 | 模型ID |
• 响应示例：

{"code":200,"msg":"部署成功","data":null}

2.6 批量删除模型

• 接口地址：DELETE /workflow/model/{ids}
• 接口名称：批量删除模型
• 接口描述：删除指定ID的流程模型（支持批量）
• 路径参数：
  | 参数名 | 类型 | 是否必填 | 说明 |
  |--------|------|----------|------|
  | ids | String[] | 是 | 模型ID数组（多个用逗号分隔，如150001,150002） |
• 响应示例：

{"code":200,"msg":"删除成功","data":null}

2.7 导出模型ZIP

• 接口地址：GET /workflow/model/export/zip/{modelId}
• 接口名称：导出模型为ZIP包
• 接口描述：将模型XML和基础信息导出为ZIP压缩包，支持下载
• 路径参数：
  | 参数名 | 类型 | 是否必填 | 说明 |
  |--------|------|----------|------|
  | modelId | String | 是 | 模型ID |
• 响应说明：直接返回ZIP文件流，前端触发下载

2.8 流程定义转模型

• 接口地址：PUT /workflow/model/convertToModel/{processDefinitionId}
• 接口名称：流程定义转模型
• 接口描述：将已部署的流程定义反向转换为可编辑的模型
• 路径参数：
  | 参数名 | 类型 | 是否必填 | 说明 |
  |--------|------|----------|------|
  | processDefinitionId | String | 是 | 流程定义ID |
• 响应示例：

{"code":200,"msg":"转换成功","data":null}

3. 异常响应示例

{"code":500,"msg":"模型标识已存在","data":null}

四、总结

1. 核心亮点

• 覆盖流程模型全生命周期管理，适配企业级流程设计场景；
• 遵循若依框架规范，统一参数校验、响应格式、日志审计；
• 深度集成Activiti引擎，保证模型与流程定义的互通；
• 接口设计RESTful风格，语义清晰，便于前后端对接。

2. 扩展建议

• 新增模型版本管理接口，支持模型版本回溯；
• 新增模型复制接口，减少重复设计成本；
• 新增模型权限控制，限制不同角色对模型的操作权限；
• 补充接口入参的格式校验（如模型key的正则校验）。