# 项目银行流水打标状态联动设计

## 背景

当前项目状态仅包含：

- `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/服务端状态切换/拦截/测试
- 前端实施计划：详情页禁用/列表与统计展示/交互提示/联调验证

这样能符合仓库“前后端分别产出实施计划”的协作约定。
