303 lines
9.6 KiB
Markdown
303 lines
9.6 KiB
Markdown
|
# 项目银行流水打标状态联动设计
|
|||
|
|
|
|||
|
|
## 背景
|
|||
|
|
|
|||
|
|
当前项目状态仅包含：
|
|||
|
|
|
|||
|
|
- `0-进行中`
|
|||
|
|
- `1-已完成`
|
|||
|
|
- `2-已归档`
|
|||
|
|
|
|||
|
|
银行流水打标已经具备手工触发和自动触发两条链路：
|
|||
|
|
|
|||
|
|
- 手工触发：用户在项目中发起标签重算
|
|||
|
|
- 自动触发：上传流水文件或拉取本行信息成功后触发自动重算
|
|||
|
|
|
|||
|
|
但现状里“项目状态”和“银行流水打标任务状态”是分离的：
|
|||
|
|
|
|||
|
|
- 打标开始时，项目状态不会切到明确的“执行中”
|
|||
|
|
- 打标期间，上传数据页仍可继续拉取本行信息、上传流水
|
|||
|
|
- 打标期间，参数模型页仍可修改阈值
|
|||
|
|
- 项目列表、详情页、状态统计也无法反映项目是否处于打标执行中
|
|||
|
|
|
|||
|
|
这会带来两个问题：
|
|||
|
|
|
|||
|
|
1. 用户无法判断项目当前是否正在执行银行流水打标
|
|||
|
|
2. 打标运行过程中仍允许修改输入数据和参数，容易导致执行口径与结果不一致
|
|||
|
|
|
|||
|
|
## 目标
|
|||
|
|
|
|||
|
|
- 为项目增加“打标中”这一正式业务状态。
|
|||
|
|
- 所有银行流水打标入口统一驱动项目状态切换。
|
|||
|
|
- 打标成功后将项目状态变更为“已完成”。
|
|||
|
|
- 打标失败后将项目状态回退为“进行中”。
|
|||
|
|
- 当项目处于“打标中”时：
|
|||
|
|
- 上传数据页禁止拉取本行信息、上传流水等会改变输入数据的操作
|
|||
|
|
- 参数模型页禁止修改参数
|
|||
|
|
- 项目列表、项目详情、项目状态统计统一展示“打标中”。
|
|||
|
|
- 前端禁用与后端校验保持一致，避免仅靠页面控制被绕过。
|
|||
|
|
|
|||
|
|
## 范围
|
|||
|
|
|
|||
|
|
### In Scope
|
|||
|
|
|
|||
|
|
- `ccdi_project.status` 业务状态扩展
|
|||
|
|
- 银行流水打标任务开始/结束时的项目状态切换
|
|||
|
|
- 手工触发与自动触发两类打标链路
|
|||
|
|
- 项目列表、详情页、状态统计的“打标中”展示
|
|||
|
|
- 上传数据页与参数模型页的前端禁用
|
|||
|
|
- 文件上传、拉取本行信息、参数保存的后端状态拦截
|
|||
|
|
- 对应 SQL、测试与实施记录
|
|||
|
|
|
|||
|
|
### Out of Scope
|
|||
|
|
|
|||
|
|
- 打标执行线程模型调整
|
|||
|
|
- 新增消息推送、WebSocket、实时进度条
|
|||
|
|
- 已归档项目的业务流程重构
|
|||
|
|
- 打标结果口径、规则 SQL、本次标签计算逻辑本身的调整
|
|||
|
|
|
|||
|
|
## 设计原则
|
|||
|
|
|
|||
|
|
- 项目状态是页面展示、统计、交互控制的唯一业务事实来源。
|
|||
|
|
- “打标中”不是临时页面标记，而是项目正式状态。
|
|||
|
|
- 所有打标触发入口必须复用同一套状态切换逻辑，不能分散在多个控制器中各自处理。
|
|||
|
|
- 前端负责体验层禁用，后端负责最终业务兜底。
|
|||
|
|
- 失败回退遵循用户确认规则：打标失败回退为 `0-进行中`。
|
|||
|
|
|
|||
|
|
## 方案选择
|
|||
|
|
|
|||
|
|
本次采用“把打标中做成项目正式状态”的方案，不采用“从任务表动态推导打标中”。
|
|||
|
|
|
|||
|
|
原因：
|
|||
|
|
|
|||
|
|
- 当前项目列表、详情、统计、按钮显隐都已直接依赖 `ccdi_project.status`
|
|||
|
|
- 将“打标中”纳入正式状态，能最小化前后端口径分叉
|
|||
|
|
- 相比运行时拼装任务态，字典、统计、筛选、禁用逻辑更容易统一维护
|
|||
|
|
|
|||
|
|
## 状态模型设计
|
|||
|
|
|
|||
|
|
项目状态扩展为：
|
|||
|
|
|
|||
|
|
- `0-进行中`
|
|||
|
|
- `1-已完成`
|
|||
|
|
- `2-已归档`
|
|||
|
|
- `3-打标中`
|
|||
|
|
|
|||
|
|
### 状态流转
|
|||
|
|
|
|||
|
|
#### 1. 项目创建
|
|||
|
|
|
|||
|
|
- 新建项目默认状态仍为 `0-进行中`
|
|||
|
|
|
|||
|
|
#### 2. 打标开始
|
|||
|
|
|
|||
|
|
当任一银行流水打标任务开始执行时，项目状态切换为 `3-打标中`。
|
|||
|
|
|
|||
|
|
覆盖入口包括：
|
|||
|
|
|
|||
|
|
- 手工重算
|
|||
|
|
- 批量上传流水完成后触发的自动打标
|
|||
|
|
- 拉取本行信息完成后触发的自动打标
|
|||
|
|
|
|||
|
|
#### 3. 打标成功
|
|||
|
|
|
|||
|
|
- 当前轮及补跑轮次全部执行完成后，项目状态切换为 `1-已完成`
|
|||
|
|
|
|||
|
|
#### 4. 打标失败
|
|||
|
|
|
|||
|
|
- 当前轮打标执行失败时，项目状态切换回 `0-进行中`
|
|||
|
|
|
|||
|
|
#### 5. 补跑场景
|
|||
|
|
|
|||
|
|
`ProjectBankTagRebuildCoordinator` 当前已经支持 `needRerun` 机制。
|
|||
|
|
|
|||
|
|
设计要求：
|
|||
|
|
|
|||
|
|
- 当项目已经处于打标流程中且出现补跑标记时，项目状态持续保持 `3-打标中`
|
|||
|
|
- 仅当最后一轮实际执行结束后，才根据最终结果落为 `1-已完成` 或 `0-进行中`
|
|||
|
|
|
|||
|
|
## 后端设计
|
|||
|
|
|
|||
|
|
## 1. 项目状态统一更新能力
|
|||
|
|
|
|||
|
|
建议在项目模块中补充一个明确的项目状态更新能力，供打标服务、文件上传服务、参数服务复用。
|
|||
|
|
|
|||
|
|
职责：
|
|||
|
|
|
|||
|
|
- 根据 `projectId` 获取项目并校验存在性
|
|||
|
|
- 更新 `status`、`updateBy`、`updateTime`
|
|||
|
|
- 对已归档项目做保护，避免被意外改写状态
|
|||
|
|
|
|||
|
|
不建议把状态切换逻辑散落在多个业务类里直接 `projectMapper.updateById(...)`。
|
|||
|
|
|
|||
|
|
## 2. 打标状态切换落点
|
|||
|
|
|
|||
|
|
状态切换收口在 `CcdiBankTagServiceImpl.rebuildProject(...)`。
|
|||
|
|
|
|||
|
|
建议流程：
|
|||
|
|
|
|||
|
|
1. 创建打标任务前或任务创建后、规则执行前，将项目状态更新为 `3-打标中`
|
|||
|
|
2. 规则执行全部完成后，将项目状态更新为 `1-已完成`
|
|||
|
|
3. 捕获异常时，将项目状态更新为 `0-进行中`
|
|||
|
|
4. 若存在补跑循环，则状态保持 `3`，由最后一轮执行负责写最终态
|
|||
|
|
|
|||
|
|
这样可以保证手工和自动触发都复用同一套状态流转。
|
|||
|
|
|
|||
|
|
## 3. 前置拦截能力
|
|||
|
|
|
|||
|
|
后端需要对“打标中不可改输入”的规则做服务端校验，避免前端禁用被绕过。
|
|||
|
|
|
|||
|
|
### 文件上传相关
|
|||
|
|
|
|||
|
|
在 `CcdiFileUploadServiceImpl` 中，对以下入口增加项目状态校验：
|
|||
|
|
|
|||
|
|
- 批量上传流水
|
|||
|
|
- 拉取本行信息
|
|||
|
|
|
|||
|
|
当项目状态为 `3-打标中` 时，直接抛出业务异常，例如：
|
|||
|
|
|
|||
|
|
- `当前项目正在进行银行流水打标，暂不允许上传或拉取数据`
|
|||
|
|
|
|||
|
|
### 参数保存相关
|
|||
|
|
|
|||
|
|
在 `CcdiModelParamServiceImpl` 中，对以下入口增加项目状态校验：
|
|||
|
|
|
|||
|
|
- `saveParams`
|
|||
|
|
- `saveAllParams`
|
|||
|
|
|
|||
|
|
当项目状态为 `3-打标中` 时，直接抛出业务异常，例如：
|
|||
|
|
|
|||
|
|
- `当前项目正在进行银行流水打标，暂不允许修改参数`
|
|||
|
|
|
|||
|
|
## 4. 已归档项目保护
|
|||
|
|
|
|||
|
|
若已归档项目被误触发打标，不应继续推进状态切换。
|
|||
|
|
|
|||
|
|
建议策略：
|
|||
|
|
|
|||
|
|
- 已归档项目不允许进入新的打标流程
|
|||
|
|
- 若入口层未提前拦住，状态更新能力也应拒绝把 `2-已归档` 改写为 `3`
|
|||
|
|
|
|||
|
|
这样能避免“已归档”与“打标中”之间出现非法流转。
|
|||
|
|
|
|||
|
|
## 前端设计
|
|||
|
|
|
|||
|
|
## 1. 项目详情页状态展示
|
|||
|
|
|
|||
|
|
`ruoyi-ui/src/views/ccdiProject/detail.vue` 需要新增 `3-打标中` 的状态展示：
|
|||
|
|
|
|||
|
|
- 状态文字：`打标中`
|
|||
|
|
- 状态样式：与现有“进行中/已完成/已归档”区分
|
|||
|
|
|
|||
|
|
详情页向子组件透传的 `projectInfo.projectStatus` 保持为统一禁用依据。
|
|||
|
|
|
|||
|
|
## 2. 上传数据页禁用
|
|||
|
|
|
|||
|
|
`UploadData.vue` 在项目状态为 `3` 时进入受限态。
|
|||
|
|
|
|||
|
|
### 禁用范围
|
|||
|
|
|
|||
|
|
- `拉取本行信息`
|
|||
|
|
- `上传流水`
|
|||
|
|
- 所有会触发上传、拉取、重新提交输入数据的入口按钮
|
|||
|
|
|
|||
|
|
### 交互要求
|
|||
|
|
|
|||
|
|
- 按钮使用 `disabled`
|
|||
|
|
- 禁用状态有明确提示文案，而不是仅变灰
|
|||
|
|
- 已存在的文件列表、统计、查看类操作仍允许使用
|
|||
|
|
|
|||
|
|
目标是“禁止改变输入”，而不是“整个页面不可看”。
|
|||
|
|
|
|||
|
|
## 3. 参数模型页只读
|
|||
|
|
|
|||
|
|
`ParamConfig.vue` 在项目状态为 `3` 时进入只读态。
|
|||
|
|
|
|||
|
|
### 控制项
|
|||
|
|
|
|||
|
|
- 参数输入框禁用
|
|||
|
|
- “保存所有修改”按钮禁用
|
|||
|
|
- 页面顶部或按钮区展示提示文案：
|
|||
|
|
- `项目正在进行银行流水打标，参数暂不可修改`
|
|||
|
|
|
|||
|
|
## 4. 项目列表与状态统计
|
|||
|
|
|
|||
|
|
### 项目列表
|
|||
|
|
|
|||
|
|
项目列表页需要新增 `3-打标中` 的显示与操作策略：
|
|||
|
|
|
|||
|
|
- 状态列可正常显示“打标中”
|
|||
|
|
- “打标中”项目允许进入详情页查看
|
|||
|
|
- 不显示仅适用于完成态的“查看结果/归档”
|
|||
|
|
- 不把“打标中”误判为“进行中”或“已完成”
|
|||
|
|
|
|||
|
|
### 状态统计
|
|||
|
|
|
|||
|
|
项目首页状态统计扩展为：
|
|||
|
|
|
|||
|
|
- 全部
|
|||
|
|
- 进行中
|
|||
|
|
- 已完成
|
|||
|
|
- 已归档
|
|||
|
|
- 打标中
|
|||
|
|
|
|||
|
|
对应后端统计 VO 与前端 tabCounts 都要同步扩展。
|
|||
|
|
|
|||
|
|
## SQL 与字典设计
|
|||
|
|
|
|||
|
|
需要新增一条增量 SQL，补齐状态字典与注释口径：
|
|||
|
|
|
|||
|
|
- `ccdi_project.status` 注释补充 `3-打标中`
|
|||
|
|
- `sys_dict_data` 为 `ccdi_project_status` 新增：
|
|||
|
|
- `dict_label = 打标中`
|
|||
|
|
- `dict_value = 3`
|
|||
|
|
|
|||
|
|
不直接依赖历史初始化脚本作为唯一变更承载，避免新环境与增量环境口径不一致。
|
|||
|
|
|
|||
|
|
## 错误处理
|
|||
|
|
|
|||
|
|
- 打标失败时，项目状态必须回退为 `0-进行中`
|
|||
|
|
- 若状态更新失败，不应静默吞掉，需要保留日志，便于排查“任务完成但状态未切回”的问题
|
|||
|
|
- 服务端拦截返回的错误文案要能让用户理解是“项目正在打标，所以暂时不可操作”
|
|||
|
|
- 前端收到业务错误后直接展示后端文案，不再自行拼装另一套口径
|
|||
|
|
|
|||
|
|
## 测试设计
|
|||
|
|
|
|||
|
|
至少覆盖以下测试：
|
|||
|
|
|
|||
|
|
### 1. 打标状态流转测试
|
|||
|
|
|
|||
|
|
- 手工打标开始时置为 `3`
|
|||
|
|
- 手工打标成功后置为 `1`
|
|||
|
|
- 手工打标失败后回退为 `0`
|
|||
|
|
- 自动打标开始时也会置为 `3`
|
|||
|
|
- 存在补跑时，期间持续保持 `3`
|
|||
|
|
|
|||
|
|
### 2. 服务端拦截测试
|
|||
|
|
|
|||
|
|
- 项目状态为 `3` 时，批量上传流水被拒绝
|
|||
|
|
- 项目状态为 `3` 时，拉取本行信息被拒绝
|
|||
|
|
- 项目状态为 `3` 时，参数保存被拒绝
|
|||
|
|
|
|||
|
|
### 3. 前端页面测试/联调验证
|
|||
|
|
|
|||
|
|
- 项目详情页正确显示“打标中”
|
|||
|
|
- 上传数据页相关按钮禁用
|
|||
|
|
- 参数模型页输入框和保存按钮禁用
|
|||
|
|
- 项目列表与状态统计正确显示“打标中”
|
|||
|
|
|
|||
|
|
## 风险与兼容性
|
|||
|
|
|
|||
|
|
- 新增状态 `3` 后，所有基于项目状态写死 `0/1/2` 的前后端逻辑都要排查，避免出现未知状态回退到默认分支
|
|||
|
|
- 字典数据、状态统计 VO、前端颜色映射、按钮显隐条件需同步改造，否则会出现展示不一致
|
|||
|
|
- 若存在历史完成项目再次触发自动打标，按本设计会先进入 `3-打标中`，完成后重新回到 `1-已完成`，这是符合本次需求的
|
|||
|
|
|
|||
|
|
## 实施拆分建议
|
|||
|
|
|
|||
|
|
后续实施计划建议拆成两份：
|
|||
|
|
|
|||
|
|
- 后端实施计划：状态枚举/SQL/服务端状态切换/拦截/测试
|
|||
|
|
- 前端实施计划：详情页禁用/列表与统计展示/交互提示/联调验证
|
|||
|
|
|
|||
|
|
这样能符合仓库“前后端分别产出实施计划”的协作约定。
|