# 项目银行流水打标状态联动设计 ## 背景 当前项目状态仅包含： - `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/服务端状态切换/拦截/测试 - 前端实施计划：详情页禁用/列表与统计展示/交互提示/联调验证 这样能符合仓库“前后端分别产出实施计划”的协作约定。