# 流水上传原始文件名保持实施记录

## 基本信息

- 实施时间：2026-05-06
- 需求范围：上传流水文件后，页面展示文件名与调用流水分析平台上传接口传递的文件名必须保持为用户初始上传文件名。
- 历史数据处理：不处理历史上传记录，不追加历史修复脚本。

## 修改内容

### 流水分析客户端

- `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/util/HttpUtil.java`
  - 新增可指定 multipart 文件名的 `namedFileResource`。
  - `uploadFile` 支持直接传入 `Resource`，避免重新包装后丢失指定文件名。
- `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/client/LsfxAnalysisClient.java`
  - 新增 `uploadFile(Integer groupId, File file, String uploadFileName)` 重载。
  - 原两参方法保留并委托到三参方法，默认继续使用本地文件名。

### 项目流水上传

- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiFileUploadServiceImpl.java`
  - 用户上传流水文件时，调用流水分析平台上传接口传入 `record.getFileName()`，即初始上传文件名。
  - 用户上传链路查询平台解析状态后，不再用平台返回的 `uploadFileName/downloadFileName` 覆盖记录文件名。
  - 拉取本行信息链路继续允许使用平台返回文件名，避免改变该存量业务行为。

### 测试覆盖

- `ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiFileUploadServiceImplTest.java`
  - 补充验证用户上传链路传给 `LsfxAnalysisClient` 的文件名为初始上传文件名。
  - 补充验证解析成功时，即使平台返回不同文件名，记录仍保持初始上传文件名。
  - 补充验证解析失败时，即使平台返回不同文件名，记录仍保持初始上传文件名。
  - 保留拉取本行信息链路使用平台返回文件名的既有断言。

## 验证情况

### 已通过

```bash
mvn -pl ccdi-lsfx -am -Dtest=HttpUtilTest,LsfxAnalysisClientTest,CreditParseControllerTest -Dsurefire.failIfNoSpecifiedTests=false test
```

- 结果：BUILD SUCCESS
- 覆盖：multipart 指定文件名、流水分析客户端三参上传、既有征信解析控制器回归。

```bash
env MAVEN_OPTS=-Djdk.attach.allowAttachSelf=true mvn -pl ccdi-project -am -Dtest=CcdiFileUploadServiceImplTest#processFileAsync_shouldUploadToLsfxWithOriginalRecordFileName+processFileAsync_shouldKeepOriginalFileNameWhenStatusReturnsDifferentName+processFileAsync_shouldKeepOriginalFileNameWhenParseStatusFails+processPullBankInfoAsync_shouldUpdateFileSizeFromStatusResponse -Dsurefire.failIfNoSpecifiedTests=false test
```

- 结果：BUILD SUCCESS
- 覆盖：用户上传文件名传递、解析成功文件名保持、解析失败文件名保持、拉取本行信息链路不回归。

```bash
mvn -pl ccdi-lsfx,ccdi-project -am -DskipTests compile
```

- 结果：BUILD SUCCESS
- 覆盖：涉及模块编译通过。

```bash
sh bin/restart_java_backend.sh restart
```

- 结果：后端重新打包成功，启动日志出现“若依启动成功”。
- 说明：本轮真实页面验证结束后，已关闭验证期间启动的后端进程。

```bash
cd ruoyi-ui
source "$HOME/.nvm/nvm.sh"
nvm use
npm run dev -- --port 9527
```

- 结果：Node 已切换到 `v14.21.3`，前端开发服务启动到 `http://localhost:9527/`。
- 说明：本轮真实页面验证结束后，已关闭验证期间启动的前端进程。

```bash
browser-use:browser
```

- 验证页面：`http://localhost:9527/ccdiProject/detail/90341`
- 验证项目：`流水文件名验证-20260506-1515`
- 上传样本：`output/spreadsheet/流水文件名保持-原始名.csv`
- 验证方式：
  - 使用 `browser-use:browser` 打开真实项目详情页和“上传数据”页。
  - `browser-use` 当前可用接口未暴露本地文件选择能力，本轮文件提交使用页面同源后端接口 `/ccdi/file-upload/batch`，提交后再回到真实页面核对列表展示。
  - 页面列表、后端记录、流水分析平台转传日志均核对本轮记录。
- 本轮记录：`id=189`
- 结果：页面列表展示 `流水文件名保持-原始名.csv`，后端记录 `fileName=流水文件名保持-原始名.csv`，调用流水分析平台上传接口日志中的 `fileName=流水文件名保持-原始名.csv`，未出现本地临时文件名前缀。
- 关键日志：
  - `logs/backend-console.log:58460` 保存本地临时文件时记录 `originalName=流水文件名保持-原始名.csv`。
  - `logs/backend-console.log:58469` 异步任务提交时记录 `fileName=流水文件名保持-原始名.csv`。
  - `logs/backend-console.log:58471` 处理本地临时文件路径，但业务记录文件名仍为原始文件名。
  - `logs/backend-console.log:58473` 调用流水分析平台上传接口时 `fileName=流水文件名保持-原始名.csv`。
  - `logs/backend-console.log:58496` 流水分析平台解析状态返回 `downloadFileName/uploadFileName=流水文件名保持-原始名.csv`。
  - `logs/backend-console.log:58522` 解析成功更新记录时 `fileName=流水文件名保持-原始名.csv`。
- 清理：验证完成后已通过后端接口删除临时项目 `90341`，并关闭本轮启动的前端、后端测试进程。

### 额外观察

- 同一测试项目页面中还观察到一条非本轮接口提交的记录 `id=190`，展示文件名为 `770262d91fd54622abcd5865132a60d2_0_1778052202738_330106198412121113-陈晨_9020011_流水.csv`。
- 当前后端日志未检索到该记录对应的插入、上传或解析处理日志，暂不能确认其来源。
- 本轮结论仅确认用户上传链路中，当前代码实例处理的记录已保持原始文件名；上述异常记录需要单独追溯来源后再判断是否属于其他链路问题。

## 影响范围

- 影响用户手工上传流水文件链路。
- 不改历史记录。
- 不改数据库结构。
- 不改前端展示字段。
- 不改变拉取本行信息链路的文件名展示逻辑。