修复流水上传原始文件名保持

docs/reports/implementation/2026-05-06-bank-upload-original-filename-implementation.md

@@ -0,0 +1,88 @@
+# 流水上传原始文件名保持实施记录
+
+## 基本信息
+
+- 实施时间：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/`。
+
+### 未完成
+
+- `browser-use:browser` 真实页面验证未完成。
+- 原因：当前会话已加载 `browser-use` 技能，但工具列表未暴露该技能要求的 Node REPL `js` / `mcp__node_repl__js` 调用入口，无法按技能要求控制 Codex in-app browser。
+- 处理：未用 Playwright 结果替代 browser-use 结果，避免与项目要求混淆。
+
+## 影响范围
+
+- 影响用户手工上传流水文件链路。
+- 不改历史记录。
+- 不改数据库结构。
+- 不改前端展示字段。
+- 不改变拉取本行信息链路的文件名展示逻辑。