# 工单流程模块(工单系统)

** 工单流程在下文中等同于工单 **

## 工单流程模块与其他模块的关系
1. rmdc-project-management依赖本模块
2. rmdc-user-auth模块依赖本模块
3. deliver-update模块依赖本模块

## 工单流程说明

### 工单流程发起与处理
1. 工单流程发起
   1. 工单流程从特定的模块中发起
      1. 用户模块 rmdc-user-auth
      2. 项目管理模块 rmdc-project-management
   2. 不涉及手动创建工单，本项目均通过业务模块直接创建工单
2. 工单流程处理
   1. 所有用户具备工单流程的页面
      1. 可以查看到自己的发起的工单流程
      2. 可以查看到自己的被委派（需要处理）的工单流程
      3. 展示完整的工单流程列表，点击可以查看到工单流程的详情
   2. 工单流程的详情页面
      1. 具体的详情页面需要根据各个模块的工单流程逻辑进行定制
      2. 工单详情页面的模板相同
      3. 工单详情页面绑定覆盖业务模块的必要信息,可以直接调转到业务模块的详情页面
3. **工单流程状态追踪机制**
   1. **业务回调机制**: 业务模块处理完成后,必须调用工单系统的回调接口 `POST /api/workflow/callback` 更新工单状态
   2. **状态变更历史表**: 所有状态变更均写入 `workflow_track_history` 表,支持全生命周期审计
   3. **实时通知推送**: 状态变更时通过通知中心模块向发起人和处理人推送实时通知(WebSocket/App推送)
   4. **轮询兜底**: 前端可选配置定时轮询接口 `GET /api/workflow/{id}/status` 获取最新状态
4. 工单流程通知
   1. 通过[通知中心模块](0-设计方案/6-rmdc-notice-center)进行消息通知的

### 工单流程执行策略
1. 从非超级管理员用户到超级管理员的工单流程,有如下的策略
   1. 超级管理员可以自行执行
   2. 超级管理员可以委派工单执行人,即执行人可以变更
   3. 超级管理员可以设置自动审批，工单可以自动审批处理
   4. 超级管理员可以设置定时执行，代表工单审批通过，在未来的特定时间点执行
2. 超级管理员到非超级管理员用户的工单流程
   1. 非超级管理员用户无法委派,即执行人无法变更
   2. 只能由非超级管理员用户自行操作执行

### 工单流程的生命周期
1. 工单流程的生命周期
   1. 工单流程的创建
   2. 工单流程的处理
   3. 工单流程的完成
   4. 工单流程的撤销
   5. 工单流程的拒绝
   6. 工单流程的超时
   7. 工单流程的结束
2. **并发处理场景** - 当用户正在处理工单流程时的竞态条件处理
   1. **工单流程被委派给其他用户**
      - 采用 **乐观锁机制**: 工单表增加 `version` 字段,每次更新必须校验版本号
      - 委派操作成功后,通过通知中心向原处理人推送 `WORKFLOW_REASSIGNED` 事件
      - 前端收到事件后显示提示弹窗: "此工单已被重新委派给XXX,您的处理权限已转移"
      - 原处理人页面切换为只读模式或引导返回列表
      - 若原处理人仍尝试提交,后端校验版本号不匹配,返回 `409 Conflict`
   2. **工单流程被撤销**
      - 撤销操作前校验工单状态: 仅 `pending/assigned` 状态可直接撤销
      - `in_progress` 状态撤销需要二次确认,并通知处理人
      - 撤销成功后推送 `WORKFLOW_REVOKED` 事件
      - 前端收到事件后自动关闭处理页面,引导至工单列表
      - 已执行的步骤数据保留,状态标记为 `revoked`
   3. **工单流程被修改**
      - 修改操作前校验乐观锁版本号
      - 仅特定状态允许修改: `pending/assigned/returned`
      - 修改成功后推送 `WORKFLOW_MODIFIED` 事件,携带变更字段摘要
      - 前端收到事件后提示刷新,或自动刷新表单数据
      - 如用户本地有未保存的修改,提示冲突并允许手动合并
3. 每一个工单流程具备唯一的ID进行全生命周期的追踪处理
   1. 唯一ID的生成方式, 模块简称+时间戳+发起人英文名称
   2. 例子 项目管理模块发起的工单流程ID为 project-20260106110303-zeaslity


## 工单流程持久化说明
1. 每一个工单流程需要进行持久化保存
2. 每一种类型的工单流程的状态机是否应该不同
3. 工单流程必须的字段
   1. 工单流程ID
   2. 工单流程发起人
   3. 工单流程发起时间
   4. 工单流程超时时间 需要在多长时间内完成
   5. 工单流程处理人
   6. 工单流程被委派人 工单流程的实际处理人
   7. 工单流程处理时间
   8. 工单流程处理状态
   9. 工单流程处理结果
   10. 工单流程处理备注
   11. 工单流程每一步骤的处理时间
   12. 工单流程每一步骤的处理人
   13. 工单流程每一步骤的处理状态
   14. 工单流程每一步骤的处理结果
   15. 工单流程每一步骤的处理备注 为下一步提供信息
   16. 工单流程可能需要传递参数给下一步


## 工单流程权限

### 项目信息填写工单流程权限
1. 非超级管理员用户
   1. 只能查看，处理分配给自己的或者自己创建的项目信息填写工单
2. 超级管理员
   1. 可以查看，处理全部项目信息填写工单

### 微服务更新流程权限
1. 非超级管理员用户
   1. 只能查看，处理自己创建的微服务更新工单流程
2. 超级管理员
   1. 可以查看，处理全部微服务更新工单流程

### 用户注册工单流程权限
1. 非超级管理员用户
   1. 只能查看，处理自己创建的用户注册工单流程
2. 超级管理员
   1. 可以查看，处理全部的用户注册工单流程

### 用户信息管理工单流程权限
1. 非超级管理员用户
   1. 只能查看，处理自己创建的户信息管理工单流程
2. 超级管理员
   1. 可以查看，处理全部的户信息管理工单流程


## 工单流程详情
1. 工单流程的每一步均可以附带信息给下一步
2. 工单流程可能需要传递参数给下一步

### 项目信息填写工单流程
1. 超级管理员初步创建项目的Metadata数据
2. 发起工单分派给普通用户进行项目详情的填写
3. 普通用户可以保存草稿,直到可以提交项目审批
4. 普通用户提交项目审批
5. 自动分配给超级管理员审批
6. 超级管理员进行项目的审批
   1. 审批通过
      1. 工单结束
      2. 项目详情表正式上线
   2. 审批拒绝
      1. 重新回到普通用户补充项目信息的阶段（项目详情处于草稿状态）
      2. 用户重新修改项目的详情信息之后
      3. 用户可以基于此工单重新提交审批
   3. 超级管理员可以进行项目管理详情的修改,修改完成之后,工单结束
7. 当用户的项目信息没有被审批通过
   1. 草稿状态的项目信息应该绑定唯一工单
   2. 草稿状态的项目详情应该显示工单号
   3. 草稿状态的项目信息，提交审批之后可以跳转到 项目详情工单详情页面
   4. 除非工单的状态进入到closed状态，项目信息才可以重新关联新的工单
8. 用户无法取消项目详情工单的流程
   1. 只有超级管理员可以取消项目详情工单

### 用户注册工单流程
1. 非超级管理员用户的在用户注册之后
   1. 用户状态默认为 disabled
2. 启动用户注册工单流程
   1. 自动创建用户注册工单
   2. 自动提交给超级管理员
3. 超级管理员审核
   1. 审核通过
      1. 自动修改用户状态为 active, 用户启用
   2. 审核不通过
      1. 回退到用户注册阶段
      2. 用户可以重新修改用户注册信息
      3. 可以在此工单详情中重新发起审批
4. 处于注册草稿状态（disable）的用户详情页面
   1. 草稿状态的用户详情页面，需要关联唯一用户注册工单流程工单
   2. 草稿状态的用户详情页面，可以发起用户注册审批
   3. 草稿状态的用户详情页面，提交用户注册审批之后，可以跳转用户注册工单详情页面
5. 用户可以撤回用户注册工单申请
   1. 撤回之后，工单重新进入用户信息注册阶段 created状态
   2. 撤回之后，用户详情页面仍然处于草稿状态，可以进行草稿状态的操作
6. 用户可以取消注册工单流程
   1. 用户取消用户注册工单之后，工单进入closed状态
   2. 用户取消用户注册工单之后，无法基于此工单提交审批工作
   3. 取消之后，从用户数据库中硬删除创建的用户
7. 用户可以基于取消的注册工单一键重新创建新的注册工单流程
   1. 密码等信息不能再前端保存
   2. 密码需要重新创建

### 用户管理（修改、删除、 状态（启用、禁用））工单流程
1. 用户侧-用户管理页面，用户可以通过编辑按钮、删除按钮进行用户管理
2. 启动用户管理工单流程
   1. 自动创建用户管理工单
   2. 自动提交给超级管理员进行审批
3. 超级管理员审核
   1. 审核通过
      1. 根据管理的内容，修改用户相应的信息，更新数据库
      2. 用户管理工单结束
   2. 审核不通过
      1. 回退到用户管理阶段
      2. 用户可以继续修改相关信息，继续提交审核
4. 处于编辑状态的用户详情
   1. 编辑状态的用户详情页面，需要关联唯一用户管理工单流程工单
   2. 编辑状态的用户详情页面，可以发起用户管理审批
   3. 编辑状态的用户详情页面，提交用户管理审批之后，可以跳转用户管理工单详情页面
5. 用户可以撤回用户管理工单流程
   1. 撤回之后的管理工单，处于created状态
   2. 撤回之后，用户详情页面仍然处于编辑状态
   3. 撤回之后，仍然可以基于此工单重新发起审批
6. 用户可以关闭用户管理工单流程
   1. 关闭之后的用户管理工单，处于状态机中的closed状态
   2. 工单的生命周期结束，无法操作该工单的状态（即无法提交审批 审批 拒绝等）
   3. 关闭之后，相应的用户详情应该退出编辑状态，用户详情页面不显示用户管理工单和相关操作

### 微服务更新工单流程
1. 普通用户在构建详情页面点击微服务更新
2. 携带构建物信息跳转至微服务更新详情页面
   1. 微服务更新页面使用3大竖列的形式,发起微服务升级工单
   2. 如果正确的跳转,构建物信息应该出现在最左侧一栏
   3. 中间一栏是微服务更新的表单, 用户可以选择需要更新的项目及微服务, 预期的更新时间
   4. 最右侧一栏是微服务更新的发起按钮
3. 普通用户提交微服务更新工单,进行工单的下一步
4. 超级管理员可以自己执行,也可以委派更新任务
5. 超级管理员进行微服务更新的审批
   1. 微服务更新如果满足更新条件,则同意更新,进入工单的下一步
   2. 微服务更新如果不满足更新条件,则拒绝更新,返回到普通用户修改更新信息的阶段,进行循环直到审批通过
   3. 针对定期的更新,超级管理员同意更新,进入工单的下一步
6. 超级管理员进行微服务更新的执行操作
   1. 微服务的更新操作,更新状态需要通过 rmdc-exchange-hub rmdc-watchdog模块进行
   2. 微服务的更新状态可以在工单中展示
7. 微服务更新状态
   1. 微服务更新成功,进入工单的下一步
   2. 微服务更新失败,回到超级管理员进行微服务更新的执行操作,进行循环直到更新成功
8. 微服务运行状态
   1. 微服务更新后运行状态正常,工单结束
   2. 微服务更新后运行状态异常, rmdc-watchdog应该自动回滚微服务至更新前的版本, 工单需要记录微服务更新失败的信息, 工单结束

## 工单详情页面

### 工单处理流程图
1. 工单详情页面应该展示工单处理流程图
2. 工单处理流程图应该展示工单的当前状态
3. 工单处理流程图应该展示每一步分处理人
4. 工单处理流程图应该展示每一步的处理时间
5. 工单处理流程图应该展示每一步的处理结果
6. 工单处理流程图由后端生成mermaid格式的内容,由前端负责渲染
7. 后端需要根据工单的当前状态,生成对应的mermaid格式的内容
8. 开源的库实现为Vue-Mermaid @mermaid-js/mermaid-tiny
9. 动态加载与性能：为了减小对前端性能的影响，通过异步 import('mermaid') 来加载库，避免它进入主 bundle

### 工单处理历史
1. 工单详情页面应该展示工单处理历史
2. 工单处理历史应该展示每一步的处理人
3. 工单处理历史应该展示每一步的处理时间
4. 工单处理历史应该展示每一步的处理结果
5. 工单处理历史应该展示每一步的处理备注

### 跳转策略
1. 工单详情页面 应该可以跳转至业务详情页面
2. 工单详情页面 可以返回至工单列表页面

## 用户注册工单流程详情页面
1. 可以跳转至用户注册详情页面
2. 用户注册详情页面可以跳转至工单详情页面
3. 用户侧 和 管理测的界面有些许不同,但是大部分都可以复用

## 项目信息填写工单流程详情页面
1. 可以跳转至项目详情页面
2. 项目详情页面可以跳转至工单详情页面
3. 用户侧 和 管理测的界面有些许不同,但是大部分都可以复用

## 参考的开源工单系统

设计参考了以下开源项目的最佳实践:

1. **Ferry** - Go语言工单系统,支持工单流程引擎、权限管理、灵活配置
2. **Flowable** - Java工单流程引擎,乐观锁并发控制机制
3. **Camunda** - BPMN工单流程引擎,微服务编排
4. **NocoBase** - 低代码平台,灵活的数据建模与工单流程设计