# 流水文件解析成功状态延后到流水入库完成设计

## 概述

调整流水文件上传异步处理链路中“解析成功”的业务含义。

当前实现里，只要流水分析平台返回“解析成功且可确认账户”，系统就会立即把上传记录状态更新为 `parsed_success`，随后才执行步骤 7 获取流水数据并写入本地数据库。

本次设计将 `parsed_success` 的含义收紧为：

- 流水分析平台解析成功
- 步骤 7 获取流水数据成功
- 流水数据成功写入本地数据库

在步骤 7 完成前，页面继续显示“解析中”。

## 背景

### 当前现状

当前核心逻辑位于 `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiFileUploadServiceImpl.java`：

1. 上传文件到流水分析平台
2. 轮询解析状态
3. 调用上传状态接口判断是否解析成功
4. 立即更新 `ccdi_file_upload_record.file_status = parsed_success`
5. 再调用 `fetchAndSaveBankStatements(...)` 获取流水并入库

这会产生两个问题：

1. 前端会看到“解析成功”，但数据库里的流水可能还没有写完
2. 步骤 7 失败时，记录可能先显示成功，随后又因为异常被改成失败，状态语义不稳定

### 前端约束

当前前端只识别以下四种状态：

- `uploading`
- `parsing`
- `parsed_success`
- `parsed_failed`

本次需求明确要求：

- 不新增前端状态
- 当步骤 6 已经确认平台解析成功，但步骤 7 尚未完成时，页面继续显示“解析中”

## 方案对比

### 方案一：仅后移 `parsed_success` 更新时机

做法：

- 步骤 6 解析成功后，不更新状态
- 执行步骤 7
- 步骤 7 执行结束后，再更新为 `parsed_success`

优点：

- 改动最小
- 前端和数据库状态枚举都不需要调整

缺点：

- 当前 `fetchAndSaveBankStatements(...)` 没有显式返回成功或失败结果
- 方法内部存在“记录异常后继续处理”的行为，容易把部分失败误判为成功

### 方案二：后移成功状态，并让步骤 7 返回明确执行结果

做法：

- 步骤 6 只确认“平台解析成功且可以获取流水”
- 记录状态继续保持 `parsing`
- 步骤 7 返回结构化结果，例如 `success`、`savedCount`、`errorMessage`
- 只有步骤 7 明确成功后，才更新 `parsed_success`
- 步骤 7 任一关键失败，则更新为 `parsed_failed`

优点：

- 状态语义完整且稳定
- 能避免“伪成功”
- 与当前前端状态模型兼容

缺点：

- 需要对步骤 7 做一定重构

### 方案三：拆分为解析状态和入库状态两个维度

做法：

- 新增“解析状态”和“入库状态”两个字段
- 前端组合展示

优点：

- 状态表达最完整

缺点：

- 涉及数据库、后端查询统计、前端状态映射等多处改动
- 超出本次需求范围

## 最终方案

采用方案二。

### 核心决策

1. `parsed_success` 只表示“流水数据已经成功入库”
2. 步骤 6 解析成功后，记录状态继续保持 `parsing`
3. 步骤 7 必须显式返回成功或失败结果
4. 步骤 7 失败时，将上传记录更新为 `parsed_failed`
5. 步骤 7 失败时，清理本次 `logId` 对应的已落库流水，避免半成品数据残留

## 详细设计

### 1. 主流程状态流转

调整 `processFileAsync(...)` 的状态流转如下：

1. 初始创建记录时为 `uploading`
2. 文件上传到流水分析平台成功后，更新为 `parsing`
3. 轮询解析完成
4. 调用文件上传状态接口判断平台是否解析成功
5. 若平台解析失败，更新为 `parsed_failed`
6. 若平台解析成功，不更新为 `parsed_success`，继续保持 `parsing`
7. 执行步骤 7 获取流水并入库
8. 步骤 7 成功后，一次性更新：
   - `file_status = parsed_success`
   - `enterprise_names`
   - `account_nos`
   - 清空可能残留的 `error_message`
9. 步骤 7 失败后，更新：
   - `file_status = parsed_failed`
   - `error_message = 失败原因`

### 2. 步骤 7 返回结构化结果

将 `fetchAndSaveBankStatements(Long projectId, Integer groupId, Integer logId)` 从 `void` 改为返回结构化结果对象。

建议新增内部结果对象，例如：

```java
@Data
private static class FetchBankStatementResult {
    private boolean success;
    private int totalCount;
    private int savedCount;
    private String errorMessage;
}
```

返回语义建议如下：

- `success = true`
  - 已成功完成全部分页拉取和数据库落库
  - `savedCount` 为实际保存条数
- `success = false`
  - 任一关键步骤失败
  - `errorMessage` 写明失败原因

### 3. 步骤 7 的成功判定

步骤 7 需同时满足以下条件才算成功：

1. 首次 `getBankStatement` 请求成功返回
2. 分页总数计算正常
3. 所有分页请求成功完成
4. 所有批量插入操作成功完成
5. 最终保存条数与已拉取条数一致

其中 `totalCount = 0` 的场景按成功处理，原因如下：

- 平台已经解析成功
- 业务上允许“解析成功但无流水”
- 否则记录会长期停留在 `parsing` 或被错误标记为失败

### 4. 步骤 7 的失败处理

当前实现中，分页循环内部发生异常后会记录日志并继续下一页。该行为不适用于本次状态语义。

调整后规则：

1. 首次查询总数失败，直接返回失败
2. 任一分页请求失败，直接返回失败
3. 任一批量插入失败，直接返回失败
4. 返回失败前，清理当前 `logId` 已写入的流水数据

### 5. 半成品流水清理

`ccdi_bank_statement` 已存在 `batch_id` 字段，且当前实体 `CcdiBankStatement.batchId` 已映射该字段。

因此步骤 7 中应确保每条流水都带上本次上传的 `logId`：

```java
statement.setProjectId(projectId);
statement.setBatchId(logId);
```

同时在 `CcdiBankStatementMapper` 中新增清理接口，例如：

```java
int deleteByProjectIdAndBatchId(@Param("projectId") Long projectId,
                                @Param("batchId") Integer batchId);
```

用于在步骤 7 失败时删除本次已插入的流水，避免出现“部分落库但上传记录失败”的脏数据。

### 6. 为什么不使用长事务

不建议把步骤 7 做成覆盖远程接口调用和全部分页落库的单个数据库事务，原因如下：

1. 远程接口调用时间不可控
2. 全量分页获取可能持续较久
3. 长事务会占用数据库连接并增加锁持有时间

因此本次采用“显式成功判定 + 失败补偿清理”的方式，而不是“长事务回滚”。

## 影响范围

### 后端

- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiFileUploadServiceImpl.java`
- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/mapper/CcdiBankStatementMapper.java`
- `ccdi-project/src/main/resources/mapper/ccdi/project/CcdiBankStatementMapper.xml`

### 测试

- 新增 `ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiFileUploadServiceImplTest.java`

### 前端

无须改动。

当前前端的 `parsing` 状态即可承载“平台解析成功但流水尚未入库完成”的阶段。

## 测试设计

至少覆盖以下场景：

1. 平台解析成功，步骤 7 全量拉取并入库成功，最终状态应为 `parsed_success`
2. 平台解析成功，但首次获取流水总数失败，最终状态应为 `parsed_failed`
3. 分页处理中途失败，最终状态应为 `parsed_failed`，且已写入流水被清理
4. 批量插入失败，最终状态应为 `parsed_failed`，且已写入流水被清理
5. `totalCount = 0`，最终状态应为 `parsed_success`
6. 平台解析失败，保持现有失败路径

## 风险与缓解

| 风险 | 影响 | 缓解方案 |
|------|------|----------|
| 步骤 7 重构后改变现有异常处理行为 | 中 | 使用单元测试锁定成功、失败、零数据三类分支 |
| 清理逻辑误删其他流水 | 高 | 删除条件必须同时绑定 `projectId` 和 `batchId(logId)` |
| 失败原因不清晰 | 中 | 统一由步骤 7 返回明确 `errorMessage`，最终写入 `ccdi_file_upload_record.error_message` |

## 验收标准

1. 当流水平台解析成功但本地仍在入库时，上传记录保持 `parsing`
2. 只有本地流水入库完成后，上传记录才变为 `parsed_success`
3. 任一步骤 7 失败，上传记录为 `parsed_failed`
4. 步骤 7 失败后，不残留本次 `logId` 的半成品流水
5. 前端无需新增状态，现有页面展示符合预期