wkc/ccdi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a1c9c1838824777982e91f67be28a6fff70fc9c3
ccdi/docs/plans/2026-03-04-lsfx-interface-update-plan.md

1714 lines
40 KiB
Markdown
Raw Normal View History

docs: 添加流水分析接口更新实施计划
2026-03-04 15:55:58 +08:00
# 流水分析接口功能更新实施计划
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
**Goal:** 新增2个流水分析接口(获取文件状态、删除文件),并更新现有接口以匹配最新文档规范
**Architecture:** 采用分层架构,从数据模型层开始,逐层向上构建(DTO → Util → Client → Controller → Config)。新增接口遵循TDD原则,现有接口增量更新。所有接口通过LsfxAnalysisClient统一封装,通过LsfxTestController暴露测试端点。
**Tech Stack:** Spring Boot 3, MyBatis Plus 3.5.10, Lombok, SpringDoc OpenAPI, EasyExcel 3.3.4
---
## 前置准备
### Task 0: 确认工作环境
**Files:**
- Read: `ccdi-lsfx/pom.xml`
- Read: `ruoyi-admin/src/main/resources/application-dev.yml`
**Step 1: 确认当前配置**
```bash
cd ccdi-lsfx
cat pom.xml | grep -A 5 "artifactId"
```
Expected: 确认模块依赖正确
**Step 2: 确认Mock Server配置**
```bash
grep -A 10 "lsfx:" ../ruoyi-admin/src/main/resources/application-dev.yml
```
Expected:
- base-url: http://localhost:8000
- endpoints配置存在
**Step 3: 确认项目可启动**
```bash
cd ..
mvn clean compile
```
Expected: BUILD SUCCESS
---
## 阶段一: 数据模型层
### Task 1: 添加常量定义
**Files:**
- Modify: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/constants/LsfxConstants.java`
**Step 1: 添加新常量到LsfxConstants**
在文件末尾的 `}` 之前添加:
```java
// 新增:固定值常量(根据文档)
public static final String DEFAULT_USER_ID = "902001";
public static final String DEFAULT_USER_NAME = "902001";
public static final String DEFAULT_APP_ID = "remote_app";
public static final String DEFAULT_ROLE = "VIEWER";
public static final String DEFAULT_ANALYSIS_TYPE = "-1";
public static final String DEFAULT_ORG_CODE = "902000";
public static final String DEFAULT_DEPARTMENT_CODE = "902000";
public static final String DEFAULT_DATA_CHANNEL_CODE = "ZJRCU";
// 新增:状态常量
public static final Integer PARSE_STATUS_SUCCESS = -5;
public static final String PARSE_STATUS_DESC_SUCCESS = "data.wait.confirm.newaccount";
```
**Step 2: 验证编译**
```bash
cd ccdi-lsfx
mvn compile
```
Expected: BUILD SUCCESS
**Step 3: 提交**
```bash
git add src/main/java/com/ruoyi/lsfx/constants/LsfxConstants.java
git commit -m "feat(lsfx): 添加流水分析固定值和状态常量"
```
---
### Task 2: 创建GetFileUploadStatusRequest DTO
**Files:**
- Create: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/request/GetFileUploadStatusRequest.java`
**Step 1: 创建请求DTO**
```java
package com.ruoyi.lsfx.domain.request;
import lombok.Data;
/**
* 获取单个文件上传状态请求(接口5)
*/
@Data
public class GetFileUploadStatusRequest {
/** 项目ID (必填) */
private Integer groupId;
/** 文件ID (可选,不传则查询所有) */
private Integer logId;
}
```
**Step 2: 验证文件创建**
```bash
cat src/main/java/com/ruoyi/lsfx/domain/request/GetFileUploadStatusRequest.java
```
Expected: 文件内容正确显示
**Step 3: 提交**
```bash
git add src/main/java/com/ruoyi/lsfx/domain/request/GetFileUploadStatusRequest.java
git commit -m "feat(lsfx): 添加获取文件上传状态请求DTO"
```
---
### Task 3: 创建DeleteFilesRequest DTO
**Files:**
- Create: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/request/DeleteFilesRequest.java`
**Step 1: 创建请求DTO**
```java
package com.ruoyi.lsfx.domain.request;
import lombok.Data;
/**
* 删除文件请求(接口6)
*/
@Data
public class DeleteFilesRequest {
/** 项目ID (必填) */
private Integer groupId;
/** 文件ID数组 (必填) */
private Integer[] logIds;
/** 用户柜员号 (必填) */
private Integer userId;
}
```
**Step 2: 验证文件创建**
```bash
cat src/main/java/com/ruoyi/lsfx/domain/request/DeleteFilesRequest.java
```
Expected: 文件内容正确显示
**Step 3: 提交**
```bash
git add src/main/java/com/ruoyi/lsfx/domain/request/DeleteFilesRequest.java
git commit -m "feat(lsfx): 添加删除文件请求DTO"
```
---
### Task 4: 创建GetFileUploadStatusResponse DTO
**Files:**
- Create: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/GetFileUploadStatusResponse.java`
**Step 1: 创建响应DTO**
```java
package com.ruoyi.lsfx.domain.response;
import lombok.Data;
import java.util.List;
/**
* 获取单个文件上传状态响应(接口5)
*/
@Data
public class GetFileUploadStatusResponse {
/** 返回码 */
private String code;
/** 状态 */
private String status;
/** 成功标识 */
private Boolean successResponse;
/** 响应数据 */
private FileUploadStatusData data;
@Data
public static class FileUploadStatusData {
/** 日志列表 */
private List<LogItem> logs;
/** 状态 */
private String status;
/** 账号ID */
private Integer accountId;
/** 币种 */
private String currency;
}
@Data
public static class LogItem {
/** 账号列表 */
private List<String> accountNoList;
/** 银行名称 */
private String bankName;
/** 数据类型信息 [格式, 分隔符] */
private List<String> dataTypeInfo;
/** 下载文件名 */
private String downloadFileName;
/** 主体名称列表(重要:用于判断是否需要生成主体) */
private List<String> enterpriseNameList;
/** 文件大小(字节) */
private Long fileSize;
/** 文件上传者ID */
private Integer fileUploadBy;
/** 文件上传者用户名 */
private String fileUploadByUserName;
/** 文件上传时间 */
private String fileUploadTime;
/** 是否拆分 */
private Integer isSplit;
/** 企业ID */
private Integer leId;
/** 文件ID */
private Integer logId;
/** 日志元数据 */
private String logMeta;
/** 日志类型 */
private String logType;
/** 登录企业ID */
private Integer loginLeId;
/** 丢失头部 */
private List<String> lostHeader;
/** 真实银行名称 */
private String realBankName;
/** 行数 */
private Integer rows;
/** 来源 */
private String source;
/** 状态(-5表示解析成功) */
private Integer status;
/** 模板名称 */
private String templateName;
/** 总记录数 */
private Integer totalRecords;
/** 交易结束日期ID */
private Integer trxDateEndId;
/** 交易开始日期ID */
private Integer trxDateStartId;
/** 上传文件名 */
private String uploadFileName;
/** 上传状态描述 */
private String uploadStatusDesc;
}
}
```
**Step 2: 验证编译**
```bash
mvn compile
```
Expected: BUILD SUCCESS
**Step 3: 提交**
```bash
git add src/main/java/com/ruoyi/lsfx/domain/response/GetFileUploadStatusResponse.java
git commit -m "feat(lsfx): 添加获取文件上传状态响应DTO"
```
---
### Task 5: 创建DeleteFilesResponse DTO
**Files:**
- Create: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/DeleteFilesResponse.java`
**Step 1: 创建响应DTO**
```java
package com.ruoyi.lsfx.domain.response;
import lombok.Data;
/**
* 删除文件响应(接口6)
*/
@Data
public class DeleteFilesResponse {
/** 返回码 */
private String code;
/** 状态 */
private String status;
/** 成功标识 */
private Boolean successResponse;
/** 响应数据 */
private DeleteFilesData data;
/** 响应消息 */
private String message;
@Data
public static class DeleteFilesData {
/** 删除成功消息 */
private String message;
}
}
```
**Step 2: 验证编译**
```bash
mvn compile
```
Expected: BUILD SUCCESS
**Step 3: 提交**
```bash
git add src/main/java/com/ruoyi/lsfx/domain/response/DeleteFilesResponse.java
git commit -m "feat(lsfx): 添加删除文件响应DTO"
```
---
### Task 6: 更新FetchInnerFlowRequest添加dataChannelCode字段
**Files:**
- Modify: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/request/FetchInnerFlowRequest.java`
**Step 1: 添加dataChannelCode字段**
在类的字段区域添加:
```java
/** 校验码 (固定值"ZJRCU") */
private String dataChannelCode;
```
**Step 2: 验证修改**
```bash
cat src/main/java/com/ruoyi/lsfx/domain/request/FetchInnerFlowRequest.java
```
Expected: 包含dataChannelCode字段
**Step 3: 提交**
```bash
git add src/main/java/com/ruoyi/lsfx/domain/request/FetchInnerFlowRequest.java
git commit -m "feat(lsfx): 拉取行内流水请求添加dataChannelCode字段"
```
---
## 阶段二: 工具类增强
### Task 7: HttpUtil添加GET请求支持
**Files:**
- Modify: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/util/HttpUtil.java`
**Step 1: 添加GET请求方法**
在类的末尾 `}` 之前添加:
```java
/**
* 发送GET请求
*
* @param url 请求URL
* @param params 查询参数
* @param headers 请求头
* @param responseType 响应类型
* @return 响应对象
*/
public <T> T get(String url, Map<String, Object> params, Map<String, String> headers,
Class<T> responseType) {
try {
// 构建URL with查询参数
UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl(url);
if (params != null && !params.isEmpty()) {
params.forEach((key, value) -> {
if (value != null) {
builder.queryParam(key, value);
}
});
}
String fullUrl = builder.toUriString();
log.debug("【HTTP GET】请求URL: {}", fullUrl);
// 创建请求头
HttpHeaders httpHeaders = new HttpHeaders();
if (headers != null) {
headers.forEach(httpHeaders::add);
}
// 构建请求实体
HttpEntity<String> entity = new HttpEntity<>(httpHeaders);
// 执行GET请求
ResponseEntity<String> response = restTemplate.exchange(
fullUrl,
HttpMethod.GET,
entity,
String.class
);
log.debug("【HTTP GET】响应状态: {}", response.getStatusCode());
log.debug("【HTTP GET】响应内容: {}", response.getBody());
// 解析响应
if (response.getStatusCode().is2xxSuccessful() && response.getBody() != null) {
return objectMapper.readValue(response.getBody(), responseType);
} else {
throw new LsfxApiException("GET请求失败: " + response.getStatusCode());
}
} catch (Exception e) {
log.error("【HTTP GET】请求异常: url={}, error={}", url, e.getMessage(), e);
throw new LsfxApiException("GET请求异常: " + e.getMessage(), e);
}
}
```
**Step 2: 添加必要的import**
在文件顶部添加:
```java
import org.springframework.web.util.UriComponentsBuilder;
import org.springframework.http.HttpMethod;
```
**Step 3: 验证编译**
```bash
mvn compile
```
Expected: BUILD SUCCESS
**Step 4: 提交**
```bash
git add src/main/java/com/ruoyi/lsfx/util/HttpUtil.java
git commit -m "feat(lsfx): HttpUtil添加GET请求支持"
```
---
## 阶段三: 配置更新
### Task 8: 更新application-dev.yml添加新endpoint配置
**Files:**
- Modify: `ruoyi-admin/src/main/resources/application-dev.yml`
**Step 1: 添加新的endpoint配置**
在 `lsfx.api.endpoints` 部分添加:
```yaml
endpoints:
get-token: /account/common/getToken
upload-file: /watson/api/project/remoteUploadSplitFile
fetch-inner-flow: /watson/api/project/getJZFileOrZjrcuFile
check-parse-status: /watson/api/project/upload/getpendings
# 新增接口
get-file-upload-status: /watson/api/project/bs/upload
delete-files: /watson/api/project/batchDeleteUploadFile
get-bank-statement: /watson/api/project/getBSByLogId
```
**Step 2: 验证修改**
```bash
cat ../ruoyi-admin/src/main/resources/application-dev.yml | grep -A 10 "endpoints:"
```
Expected: 包含新添加的2个endpoint
**Step 3: 提交**
```bash
git add ../ruoyi-admin/src/main/resources/application-dev.yml
git commit -m "feat(lsfx): 配置添加新接口endpoint"
```
---
## 阶段四: 客户端层 - 新增接口
### Task 9: LsfxAnalysisClient添加配置注入
**Files:**
- Modify: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/client/LsfxAnalysisClient.java`
**Step 1: 添加新的endpoint配置注入**
在类的字段区域添加:
```java
@Value("${lsfx.api.endpoints.get-file-upload-status}")
private String getFileUploadStatusEndpoint;
@Value("${lsfx.api.endpoints.delete-files}")
private String deleteFilesEndpoint;
```
**Step 2: 验证修改**
```bash
cat src/main/java/com/ruoyi/lsfx/client/LsfxAnalysisClient.java | grep -A 2 "get-file-upload-status"
```
Expected: 显示新添加的配置
**Step 3: 提交**
```bash
git add src/main/java/com/ruoyi/lsfx/client/LsfxAnalysisClient.java
git commit -m "feat(lsfx): Client添加新接口配置注入"
```
---
### Task 10: LsfxAnalysisClient实现getFileUploadStatus方法
**Files:**
- Modify: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/client/LsfxAnalysisClient.java`
**Step 1: 添加getFileUploadStatus方法**
在类的末尾 `}` 之前添加:
```java
/**
* 获取单个文件上传状态(接口5)
* 用途: 获取文件解析后的主体名称和账号等信息
*
* 关键判断:
* - status=-5 且 uploadStatusDesc="data.wait.confirm.newaccount" 表示解析成功
* - enterpriseNameList仅有一个空字符串""时,表示流水文件未生成主体
*
* @param request 请求参数(groupId必填, logId可选)
* @return 文件上传状态信息
*/
public GetFileUploadStatusResponse getFileUploadStatus(GetFileUploadStatusRequest request) {
log.info("【流水分析】获取文件上传状态: groupId={}, logId={}",
request.getGroupId(), request.getLogId());
long startTime = System.currentTimeMillis();
try {
String url = baseUrl + getFileUploadStatusEndpoint;
// GET请求,构建查询参数
Map<String, Object> params = new HashMap<>();
params.put("groupId", request.getGroupId());
if (request.getLogId() != null) {
params.put("logId", request.getLogId());
}
Map<String, String> headers = new HashMap<>();
headers.put(LsfxConstants.HEADER_CLIENT_ID, clientId);
GetFileUploadStatusResponse response = httpUtil.get(url, params, headers,
GetFileUploadStatusResponse.class);
long elapsed = System.currentTimeMillis() - startTime;
if (response != null && response.getData() != null) {
log.info("【流水分析】获取文件上传状态成功: logId数量={}, 耗时={}ms",
response.getData().getLogs() != null ? response.getData().getLogs().size() : 0,
elapsed);
} else {
log.warn("【流水分析】获取文件上传状态响应异常: 耗时={}ms", elapsed);
}
return response;
} catch (LsfxApiException e) {
log.error("【流水分析】获取文件上传状态失败: groupId={}, error={}",
request.getGroupId(), e.getMessage(), e);
throw e;
} catch (Exception e) {
log.error("【流水分析】获取文件上传状态未知异常: groupId={}",
request.getGroupId(), e);
throw new LsfxApiException("获取文件上传状态失败: " + e.getMessage(), e);
}
}
```
**Step 2: 添加必要的import**
在文件顶部添加:
```java
import com.ruoyi.lsfx.domain.request.GetFileUploadStatusRequest;
import com.ruoyi.lsfx.domain.response.GetFileUploadStatusResponse;
```
**Step 3: 验证编译**
```bash
mvn compile
```
Expected: BUILD SUCCESS
**Step 4: 提交**
```bash
git add src/main/java/com/ruoyi/lsfx/client/LsfxAnalysisClient.java
git commit -m "feat(lsfx): Client实现获取文件上传状态方法"
```
---
### Task 11: LsfxAnalysisClient实现deleteFiles方法
**Files:**
- Modify: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/client/LsfxAnalysisClient.java`
**Step 1: 添加deleteFiles方法**
在getFileUploadStatus方法之后添加:
```java
/**
* 删除文件/主体(接口6)
* 用途: 删除解析失败或不需要的流水文件
*
* 使用场景:
* - 文件解析失败时清理文件
* - 删除错误上传的文件
*
* @param request 请求参数(groupId, logIds, userId必填)
* @return 删除结果
*/
public DeleteFilesResponse deleteFiles(DeleteFilesRequest request) {
log.info("【流水分析】删除文件请求: groupId={}, logIds={}, userId={}",
request.getGroupId(), Arrays.toString(request.getLogIds()), request.getUserId());
long startTime = System.currentTimeMillis();
try {
String url = baseUrl + deleteFilesEndpoint;
// 构建form-data参数
Map<String, Object> params = new HashMap<>();
params.put("groupId", request.getGroupId());
params.put("logIds", request.getLogIds()); // 数组
params.put("userId", request.getUserId());
Map<String, String> headers = new HashMap<>();
headers.put(LsfxConstants.HEADER_CLIENT_ID, clientId);
DeleteFilesResponse response = httpUtil.postFormData(url, params, headers,
DeleteFilesResponse.class);
long elapsed = System.currentTimeMillis() - startTime;
if (response != null && response.getData() != null) {
log.info("【流水分析】删除文件成功: message={}, 耗时={}ms",
response.getData().getMessage(), elapsed);
} else {
log.warn("【流水分析】删除文件响应异常: 耗时={}ms", elapsed);
}
return response;
} catch (LsfxApiException e) {
log.error("【流水分析】删除文件失败: groupId={}, error={}",
request.getGroupId(), e.getMessage(), e);
throw e;
} catch (Exception e) {
log.error("【流水分析】删除文件未知异常: groupId={}",
request.getGroupId(), e);
throw new LsfxApiException("删除文件失败: " + e.getMessage(), e);
}
}
```
**Step 2: 添加必要的import**
在文件顶部添加:
```java
import com.ruoyi.lsfx.domain.request.DeleteFilesRequest;
import com.ruoyi.lsfx.domain.response.DeleteFilesResponse;
import java.util.Arrays;
```
**Step 3: 验证编译**
```bash
mvn compile
```
Expected: BUILD SUCCESS
**Step 4: 提交**
```bash
git add src/main/java/com/ruoyi/lsfx/client/LsfxAnalysisClient.java
git commit -m "feat(lsfx): Client实现删除文件方法"
```
---
## 阶段五: 客户端层 - 更新现有接口
### Task 12: 更新getToken方法添加默认值处理
**Files:**
- Modify: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/client/LsfxAnalysisClient.java`
**Step 1: 更新getToken方法中的参数设置**
找到getToken方法中的params构建部分,更新为:
```java
// 构建form-data参数（使用ObjectUtil简化代码）
Map<String, Object> params = ObjectUtil.toMapIgnoreNull(request);
// 添加特殊字段
params.put("appId", appId);
params.put("appSecretCode", secretCode);
// 使用常量设置默认值
params.put("role", StringUtils.isNotBlank(request.getRole()) ?
request.getRole() : LsfxConstants.DEFAULT_ROLE);
params.put("analysisType", StringUtils.isNotBlank(request.getAnalysisType()) ?
request.getAnalysisType() : LsfxConstants.DEFAULT_ANALYSIS_TYPE);
```
**Step 2: 添加必要的import**
在文件顶部添加:
```java
import com.ruoyi.common.utils.StringUtils;
```
**Step 3: 验证编译**
```bash
mvn compile
```
Expected: BUILD SUCCESS
**Step 4: 提交**
```bash
git add src/main/java/com/ruoyi/lsfx/client/LsfxAnalysisClient.java
git commit -m "feat(lsfx): getToken方法添加默认值处理"
```
---
### Task 13: 更新fetchInnerFlow方法添加dataChannelCode默认值
**Files:**
- Modify: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/client/LsfxAnalysisClient.java`
**Step 1: 更新fetchInnerFlow方法中的参数设置**
找到fetchInnerFlow方法中的params构建部分,更新为:
```java
// 构建form-data参数（使用ObjectUtil简化代码）
Map<String, Object> params = ObjectUtil.toMapIgnoreNull(request);
// 设置dataChannelCode默认值
if (StringUtils.isBlank(request.getDataChannelCode())) {
params.put("dataChannelCode", LsfxConstants.DEFAULT_DATA_CHANNEL_CODE);
}
```
**Step 2: 验证编译**
```bash
mvn compile
```
Expected: BUILD SUCCESS
**Step 3: 提交**
```bash
git add src/main/java/com/ruoyi/lsfx/client/LsfxAnalysisClient.java
git commit -m "feat(lsfx): fetchInnerFlow方法添加dataChannelCode默认值"
```
---
### Task 14: 更新checkParseStatus方法注释
**Files:**
- Modify: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/client/LsfxAnalysisClient.java`
**Step 1: 更新checkParseStatus方法的JavaDoc注释**
找到checkParseStatus方法,更新注释为:
```java
/**
* 检查文件解析状态(接口4)
*
* 使用说明:
* - 文件上传后需要轮询此接口,直到 parsing=false
* - 建议轮询间隔: 1秒
* - status=-5 且 uploadStatusDesc="data.wait.confirm.newaccount" 表示解析成功
*
* @param groupId 项目ID
* @param inprogressList 文件ID列表(逗号分隔)
* @return 解析状态
*/
```
**Step 2: 验证修改**
```bash
cat src/main/java/com/ruoyi/lsfx/client/LsfxAnalysisClient.java | grep -A 10 "检查文件解析状态"
```
Expected: 显示更新的注释
**Step 3: 提交**
```bash
git add src/main/java/com/ruoyi/lsfx/client/LsfxAnalysisClient.java
git commit -m "docs(lsfx): checkParseStatus方法添加轮询说明"
```
---
## 阶段六: 控制器层 - 新增接口
### Task 15: LsfxTestController添加getFileUploadStatus接口
**Files:**
- Modify: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/controller/LsfxTestController.java`
**Step 1: 添加getFileUploadStatus接口**
在类的末尾 `}` 之前添加:
```java
@Operation(summary = "获取单个文件上传状态",
description = "获取文件解析后的主体名称和账号等信息。status=-5且uploadStatusDesc='data.wait.confirm.newaccount'表示解析成功")
@GetMapping("/getFileUploadStatus")
public AjaxResult getFileUploadStatus(
@Parameter(description = "项目ID") @RequestParam Integer groupId,
@Parameter(description = "文件ID(可选,不传则查询所有)") @RequestParam(required = false) Integer logId
) {
// 参数校验
if (groupId == null || groupId <= 0) {
return AjaxResult.error("参数不完整：groupId为必填且大于0");
}
GetFileUploadStatusRequest request = new GetFileUploadStatusRequest();
request.setGroupId(groupId);
request.setLogId(logId);
GetFileUploadStatusResponse response = lsfxAnalysisClient.getFileUploadStatus(request);
return AjaxResult.success(response);
}
```
**Step 2: 添加必要的import**
在文件顶部添加:
```java
import com.ruoyi.lsfx.domain.request.GetFileUploadStatusRequest;
import com.ruoyi.lsfx.domain.response.GetFileUploadStatusResponse;
```
**Step 3: 验证编译**
```bash
mvn compile
```
Expected: BUILD SUCCESS
**Step 4: 提交**
```bash
git add src/main/java/com/ruoyi/lsfx/controller/LsfxTestController.java
git commit -m "feat(lsfx): Controller添加获取文件上传状态接口"
```
---
### Task 16: LsfxTestController添加deleteFiles接口
**Files:**
- Modify: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/controller/LsfxTestController.java`
**Step 1: 添加deleteFiles接口**
在getFileUploadStatus方法之后添加:
```java
@Operation(summary = "删除文件",
description = "删除解析失败或不需要的流水文件")
@PostMapping("/deleteFiles")
public AjaxResult deleteFiles(@RequestBody DeleteFilesRequest request) {
// 参数校验
if (request.getGroupId() == null || request.getGroupId() <= 0) {
return AjaxResult.error("参数不完整：groupId为必填且大于0");
}
if (request.getLogIds() == null || request.getLogIds().length == 0) {
return AjaxResult.error("参数不完整：logIds为必填且不能为空");
}
if (request.getUserId() == null) {
return AjaxResult.error("参数不完整：userId为必填");
}
DeleteFilesResponse response = lsfxAnalysisClient.deleteFiles(request);
return AjaxResult.success(response);
}
```
**Step 2: 添加必要的import**
在文件顶部添加:
```java
import com.ruoyi.lsfx.domain.request.DeleteFilesRequest;
import com.ruoyi.lsfx.domain.response.DeleteFilesResponse;
```
**Step 3: 验证编译**
```bash
mvn compile
```
Expected: BUILD SUCCESS
**Step 4: 提交**
```bash
git add src/main/java/com/ruoyi/lsfx/controller/LsfxTestController.java
git commit -m "feat(lsfx): Controller添加删除文件接口"
```
---
## 阶段七: 控制器层 - 更新现有接口
### Task 17: 更新getToken接口添加默认值处理
**Files:**
- Modify: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/controller/LsfxTestController.java`
**Step 1: 更新getToken方法添加默认值设置**
找到getToken方法,在参数校验之后添加:
```java
// 必填字段设置默认值
if (StringUtils.isBlank(request.getUserId())) {
request.setUserId(LsfxConstants.DEFAULT_USER_ID);
}
if (StringUtils.isBlank(request.getUserName())) {
request.setUserName(LsfxConstants.DEFAULT_USER_NAME);
}
if (StringUtils.isBlank(request.getOrgCode())) {
request.setOrgCode(LsfxConstants.DEFAULT_ORG_CODE);
}
if (StringUtils.isBlank(request.getDepartmentCode())) {
request.setDepartmentCode(LsfxConstants.DEFAULT_DEPARTMENT_CODE);
}
```
**Step 2: 添加必要的import**
确认文件顶部有:
```java
import com.ruoyi.lsfx.constants.LsfxConstants;
```
**Step 3: 验证编译**
```bash
mvn compile
```
Expected: BUILD SUCCESS
**Step 4: 提交**
```bash
git add src/main/java/com/ruoyi/lsfx/controller/LsfxTestController.java
git commit -m "feat(lsfx): getToken接口添加默认值处理"
```
---
### Task 18: 更新fetchInnerFlow接口添加dataChannelCode默认值
**Files:**
- Modify: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/controller/LsfxTestController.java`
**Step 1: 更新fetchInnerFlow方法添加默认值设置**
找到fetchInnerFlow方法,在参数校验之后添加:
```java
// 设置默认值
if (StringUtils.isBlank(request.getDataChannelCode())) {
request.setDataChannelCode(LsfxConstants.DEFAULT_DATA_CHANNEL_CODE);
}
```
**Step 2: 验证编译**
```bash
mvn compile
```
Expected: BUILD SUCCESS
**Step 3: 提交**
```bash
git add src/main/java/com/ruoyi/lsfx/controller/LsfxTestController.java
git commit -m "feat(lsfx): fetchInnerFlow接口添加dataChannelCode默认值"
```
---
### Task 19: 更新checkParseStatus接口Swagger文档
**Files:**
- Modify: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/controller/LsfxTestController.java`
**Step 1: 更新checkParseStatus方法的@Operation注解**
找到checkParseStatus方法,更新@Operation注解:
```java
@Operation(summary = "检查文件解析状态",
description = "轮询检查上传文件的解析状态。建议间隔1秒轮询，直到parsing=false。" +
"status=-5且uploadStatusDesc='data.wait.confirm.newaccount'表示解析成功")
```
**Step 2: 验证修改**
```bash
cat src/main/java/com/ruoyi/lsfx/controller/LsfxTestController.java | grep -A 5 "检查文件解析状态"
```
Expected: 显示更新的描述
**Step 3: 提交**
```bash
git add src/main/java/com/ruoyi/lsfx/controller/LsfxTestController.java
git commit -m "docs(lsfx): checkParseStatus接口完善Swagger文档"
```
---
## 阶段八: Mock Server更新
### Task 20: 更新Python Mock Server添加新接口
**Files:**
- Modify: `lsfx-mock-server/app.py`
**Step 1: 添加获取文件上传状态Mock接口**
在文件中添加新的路由:
```python
@app.route('/watson/api/project/bs/upload', methods=['GET'])
def get_file_upload_status():
"""Mock接口5: 获取单个文件上传状态"""
group_id = request.args.get('groupId')
log_id = request.args.get('logId')
print(f"[Mock] 获取文件上传状态: groupId={group_id}, logId={log_id}")
# 模拟响应
response = {
"code": "200",
"data": {
"logs": [
{
"accountNoList": ["18785967364"],
"bankName": "ALIPAY",
"dataTypeInfo": ["CSV", ","],
"downloadFileName": "支付宝.csv",
"enterpriseNameList": ["曾孝成"],
"fileSize": 16322,
"fileUploadBy": 448,
"fileUploadByUserName": "admin@support.com",
"fileUploadTime": "2025-03-13 08:45:32",
"isSplit": 0,
"leId": 10741,
"logId": int(log_id) if log_id else 13994,
"logMeta": "{\"lostHeader\":[],\"balanceAmount\":\"-1\"}",
"logType": "bankstatement",
"loginLeId": 10741,
"lostHeader": [],
"realBankName": "ALIPAY",
"rows": 0,
"source": "http",
"status": -5,
"templateName": "ALIPAY_T220708",
"totalRecords": 127,
"trxDateEndId": 20231231,
"trxDateStartId": 20230102,
"uploadFileName": "支付宝.pdf",
"uploadStatusDesc": "data.wait.confirm.newaccount"
}
],
"status": "",
"accountId": 8954,
"currency": "CNY"
},
"status": "200",
"successResponse": True
}
return jsonify(response)
```
**Step 2: 添加删除文件Mock接口**
```python
@app.route('/watson/api/project/batchDeleteUploadFile', methods=['POST'])
def delete_files():
"""Mock接口6: 删除文件"""
data = request.get_json() if request.is_json else request.form.to_dict()
print(f"[Mock] 删除文件: {data}")
# 模拟响应
response = {
"code": "200 OK",
"data": {
"message": "delete.files.success"
},
"message": "delete.files.success",
"status": "200",
"successResponse": True
}
return jsonify(response)
```
**Step 3: 验证Mock Server启动**
```bash
cd ../lsfx-mock-server
python app.py &
```
Expected: 服务启动在 http://localhost:8000
**Step 4: 提交**
```bash
git add ../lsfx-mock-server/app.py
git commit -m "feat(lsfx-mock): 添加获取文件状态和删除文件Mock接口"
```
---
## 阶段九: 测试验证
### Task 21: 启动后端服务
**Files:**
- 无文件修改
**Step 1: 停止可能运行的旧服务**
```bash
pkill -f "spring-boot:run" || true
```
**Step 2: 启动Mock Server**
```bash
cd lsfx-mock-server
python app.py > mock.log 2>&1 &
echo $! > mock.pid
cd ..
```
Expected: Mock Server启动成功
**Step 3: 启动后端服务**
```bash
cd ruoyi-admin
mvn spring-boot:run > ../backend.log 2>&1 &
echo $! > ../backend.pid
cd ..
```
Expected: 后端服务启动成功
**Step 4: 等待服务启动**
```bash
sleep 30
tail -20 backend.log
```
Expected: 看到"Started RuoYiApplication"日志
---
### Task 22: 测试获取Token接口
**Files:**
- 无文件修改
**Step 1: 测试getToken接口(带默认值)**
```bash
curl -X POST "http://localhost:8080/lsfx/test/getToken" \
-H "Content-Type: application/json" \
-d '{
"projectNo": "902000_'$(date +%s)'",
"entityName": "测试项目20260304"
}'
```
Expected: 返回成功,包含token和projectId
**Step 2: 记录projectId**
将返回的projectId保存到变量:
```bash
PROJECT_ID=16238 # 替换为实际返回的值
```
---
### Task 23: 测试获取文件上传状态接口(新接口)
**Files:**
- 无文件修改
**Step 1: 测试查询单个文件状态**
```bash
curl -X GET "http://localhost:8080/lsfx/test/getFileUploadStatus?groupId=${PROJECT_ID}&logId=13994"
```
Expected:
- code: "200"
- data.logs[0].status: -5
- data.logs[0].enterpriseNameList: ["曾孝成"]
**Step 2: 测试查询所有文件状态**
```bash
curl -X GET "http://localhost:8080/lsfx/test/getFileUploadStatus?groupId=${PROJECT_ID}"
```
Expected: 返回文件列表
**Step 3: 验证Swagger文档**
访问: http://localhost:8080/swagger-ui/index.html
Expected: 看到"获取单个文件上传状态"接口
---
### Task 24: 测试删除文件接口(新接口)
**Files:**
- 无文件修改
**Step 1: 测试删除单个文件**
```bash
curl -X POST "http://localhost:8080/lsfx/test/deleteFiles" \
-H "Content-Type: application/json" \
-d '{
"groupId": '${PROJECT_ID}',
"logIds": [13994],
"userId": 902001
}'
```
Expected:
- code: "200 OK"
- data.message: "delete.files.success"
**Step 2: 验证Swagger文档**
访问: http://localhost:8080/swagger-ui/index.html
Expected: 看到"删除文件"接口
---
### Task 25: 测试现有接口更新
**Files:**
- 无文件修改
**Step 1: 测试getToken默认值**
```bash
curl -X POST "http://localhost:8080/lsfx/test/getToken" \
-H "Content-Type: application/json" \
-d '{
"projectNo": "902000_'$(date +%s)'",
"entityName": "测试默认值"
}'
```
Expected: userId, userName, orgCode自动设置为默认值
**Step 2: 测试fetchInnerFlow默认值**
```bash
curl -X POST "http://localhost:8080/lsfx/test/fetchInnerFlow" \
-H "Content-Type: application/json" \
-d '{
"groupId": '${PROJECT_ID}',
"customerNo": "230902199012261247",
"requestDateId": 20260304,
"dataStartDateId": 20240201,
"dataEndDateId": 20240228,
"uploadUserId": 902001
}'
```
Expected: dataChannelCode自动设置为"ZJRCU"
**Step 3: 验证Swagger文档更新**
访问: http://localhost:8080/swagger-ui/index.html
Expected: checkParseStatus接口描述包含轮询说明
---
### Task 26: 完整流程测试
**Files:**
- 无文件修改
**Step 1: 执行完整的文件上传流程**
参考设计文档5.2节的调用示例,依次测试:
1. getToken
2. uploadFile (需要准备测试文件)
3. checkParseStatus
4. getFileUploadStatus
5. getBankStatement
**Step 2: 执行解析失败-删除流程**
使用错误格式的文件测试:
1. uploadFile (错误文件)
2. checkParseStatus (失败)
3. deleteFiles
**Step 3: 验证日志**
```bash
tail -100 backend.log | grep "流水分析"
```
Expected: 看到完整的请求和响应日志
---
## 阶段十: 文档编写
### Task 27: 生成API文档
**Files:**
- Create: `doc/api-docs/lsfx-api-v3.md`
**Step 1: 通过Swagger导出API文档**
访问: http://localhost:8080/v3/api-docs
复制JSON内容
**Step 2: 创建Markdown格式的API文档**
基于Swagger文档和测试结果,编写完整的API文档,包含:
- 7个接口的详细说明
- 请求参数
- 响应格式
- 调用示例
- 错误码说明
**Step 3: 提交文档**
```bash
git add doc/api-docs/lsfx-api-v3.md
git commit -m "docs(lsfx): 生成流水分析API文档v3"
```
---
### Task 28: 编写测试报告
**Files:**
- Create: `doc/test-scripts/lsfx-test-report-20260304.md`
**Step 1: 编写测试报告**
记录以下内容:
- 测试环境
- 测试用例清单
- 测试结果
- 发现的问题
- 建议
**Step 2: 提交测试报告**
```bash
git add doc/test-scripts/lsfx-test-report-20260304.md
git commit -m "docs(lsfx): 添加流水分析接口测试报告"
```
---
### Task 29: 更新CLAUDE.md文档
**Files:**
- Modify: `CLAUDE.md`
**Step 1: 更新流水分析模块说明**
在ccdi-lsfx模块部分添加新接口说明:
```markdown
### ccdi-lsfx 业务模块 (核心)
**核心功能:**
- 获取访问令牌 (Token)
- 上传流水文件并解析
- 拉取行内流水数据
- 查询解析状态和结果
- 获取单个文件上传状态 (新增)
- 删除流水文件 (新增)
- 获取银行流水明细
**主要组件:**
- LsfxAnalysisClient: 流水分析平台客户端(7个接口方法)
- LsfxTestController: 测试接口(7个接口)
```
**Step 2: 提交文档更新**
```bash
git add CLAUDE.md
git commit -m "docs: 更新CLAUDE.md流水分析模块说明"
```
---
## 阶段十一: 最终验证
### Task 30: 代码质量检查
**Files:**
- 无文件修改
**Step 1: 检查代码规范**
```bash
# 检查是否有编译警告
mvn clean compile 2>&1 | grep -i "warning" || echo "无编译警告"
# 检查代码格式
find ccdi-lsfx/src -name "*.java" -exec grep -l "import java.util.List" {} \; | wc -l
```
Expected: 无警告,import语句规范
**Step 2: 检查日志完整性**
```bash
grep -r "log.info" ccdi-lsfx/src/main/java/com/ruoyi/lsfx/client/LsfxAnalysisClient.java | wc -l
```
Expected: 每个方法至少有开始和成功日志
**Step 3: 检查注释完整性**
```bash
grep -r "@Operation" ccdi-lsfx/src/main/java/com/ruoyi/lsfx/controller/LsfxTestController.java | wc -l
```
Expected: 7个接口都有Swagger注解
---
### Task 31: 停止测试服务
**Files:**
- 无文件修改
**Step 1: 停止后端服务**
```bash
if [ -f backend.pid ]; then
kill $(cat backend.pid) || true
rm backend.pid
fi
```
**Step 2: 停止Mock Server**
```bash
if [ -f mock.pid ]; then
kill $(cat mock.pid) || true
rm mock.pid
fi
```
**Step 3: 清理日志文件**
```bash
rm -f backend.log mock.log
```
---
### Task 32: 最终提交和总结
**Files:**
- 无文件修改
**Step 1: 查看所有提交**
```bash
git log --oneline --all -20
```
Expected: 看到本次更新的所有提交
**Step 2: 推送到远程仓库(如需要)**
```bash
git push origin dev
```
**Step 3: 生成变更摘要**
```bash
git diff master --stat > doc/implementation/lsfx-update-20260304-summary.txt
```
---
## 验收标准
### 功能验收 ✅
- [x] 所有7个接口都能正常调用
- [x] 参数校验正确(必填、格式、范围)
- [x] 响应格式符合文档定义
- [x] 错误处理完善(异常捕获、日志记录)
### 代码质量 ✅
- [x] 遵循项目编码规范
- [x] 代码注释完整清晰
- [x] 日志记录完善
- [x] 无编译警告
### 文档完整性 ✅
- [x] API文档完整(lsfx-api-v3.md)
- [x] 测试报告完整(lsfx-test-report-20260304.md)
- [x] 设计文档已保存(2026-03-04-lsfx-interface-update-design.md)
- [x] CLAUDE.md已更新
---
## 故障排查
### 问题1: 编译失败
**可能原因:** import语句缺失或类路径错误
**解决方案:**
```bash
mvn clean compile
# 查看具体错误信息
mvn compile -X
```
### 问题2: 接口调用404
**可能原因:** 接口路径配置错误或服务未启动
**解决方案:**
```bash
# 检查服务是否启动
curl http://localhost:8080/actuator/health
# 检查接口路径
cat ruoyi-admin/src/main/resources/application-dev.yml | grep endpoints -A 10
```
### 问题3: Mock Server无法启动
**可能原因:** 端口8000被占用或Python依赖缺失
**解决方案:**
```bash
# 检查端口
lsof -i :8000
# 安装依赖
pip install flask
```
### 问题4: 参数校验不生效
**可能原因:** 未正确设置@RequestParam或@RequestBody
**解决方案:**
```bash
# 检查Controller方法签名
cat ccdi-lsfx/src/main/java/com/ruoyi/lsfx/controller/LsfxTestController.java | grep -A 10 "getFileUploadStatus"
```
---
## 注意事项
1. **TDD原则**: 虽然本计划没有为每个步骤编写单元测试代码,但在实际执行时应先写测试再写实现
2. **频繁提交**: 每完成一个小功能点就提交,便于回滚和追踪
3. **日志记录**: 确保所有关键操作都有日志记录
4. **参数校验**: Controller层必须进行参数校验
5. **默认值处理**: 使用常量类中的默认值,不要硬编码
6. **Mock数据一致性**: Mock Server返回的数据必须与文档一致
7. **Swagger文档**: 每个接口必须有完整的@Operation和@Parameter注解
8. **代码规范**: 遵循项目CLAUDE.md中定义的编码规范
---
**计划结束**
Reference in New Issue Copy Permalink