555 lines
16 KiB
Markdown
555 lines
16 KiB
Markdown
# Credit Parse Client Backend Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 在 `ccdi-lsfx` 模块中新增独立征信解析 `Client` 和联调接口 `POST /lsfx/credit/parse`，通过独立配置调用外部征信解析服务。
|
||
|
||
**Architecture:** 复用 `ccdi-lsfx` 现有 `HttpUtil` 与异常体系，但不复用 `LsfxAnalysisClient` 和 `lsfx.api.*` 配置。控制器负责最小参数校验和临时文件转换，独立 `CreditParseClient` 负责 `multipart/form-data` 调用与响应映射，结果以 `AjaxResult.success(response)` 形式透传。
|
||
|
||
**Tech Stack:** Java 21, Spring Boot 3, Spring MVC, Jackson, RestTemplate, JUnit 5, Mockito, Maven
|
||
|
||
---
|
||
|
||
## 文件结构与职责
|
||
|
||
**新增文件**
|
||
|
||
- `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/client/CreditParseClient.java`
|
||
负责读取 `credit-parse.api.url`、组装 `multipart/form-data`、调用征信解析服务、记录日志。
|
||
- `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/controller/CreditParseController.java`
|
||
负责接收 HTML 文件和可选参数、做最小校验、转换临时文件、调用 `CreditParseClient`、返回 `AjaxResult`。
|
||
- `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/CreditParseResponse.java`
|
||
映射外部返回的 `message`、`status_code`、`payload`。
|
||
- `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/CreditParsePayload.java`
|
||
按三个主题域承载 `payload`，使用 `Map<String, Object>` 保存字段。
|
||
- `ccdi-lsfx/src/test/java/com/ruoyi/lsfx/client/CreditParseClientTest.java`
|
||
校验 `CreditParseClient` 的参数组装、URL 读取和异常传播。
|
||
- `ccdi-lsfx/src/test/java/com/ruoyi/lsfx/controller/CreditParseControllerTest.java`
|
||
校验控制器参数默认值、文件校验、成功透传和异常兜底。
|
||
- `docs/reports/implementation/2026-03-23-credit-parse-client-implementation.md`
|
||
记录本次后端实施实际改动、测试命令和结果。
|
||
|
||
**修改文件**
|
||
|
||
- `ccdi-lsfx/pom.xml`
|
||
补充测试依赖 `spring-boot-starter-test`。
|
||
- `ruoyi-admin/src/main/resources/application-dev.yml`
|
||
新增 `credit-parse.api.url` 配置。
|
||
- `ruoyi-admin/src/main/resources/application-nas.yml`
|
||
新增 `credit-parse.api.url` 配置。
|
||
|
||
**参考文件**
|
||
|
||
- `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/util/HttpUtil.java`
|
||
- `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/controller/LsfxTestController.java`
|
||
- `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/client/LsfxAnalysisClient.java`
|
||
- `docs/design/2026-03-23-credit-parse-client-design.md`
|
||
|
||
## Task 1: 补齐 `ccdi-lsfx` 测试基础
|
||
|
||
**Files:**
|
||
- Modify: `ccdi-lsfx/pom.xml`
|
||
- Create: `ccdi-lsfx/src/test/java/com/ruoyi/lsfx/client/CreditParseClientTest.java`
|
||
- Create: `ccdi-lsfx/src/test/java/com/ruoyi/lsfx/controller/CreditParseControllerTest.java`
|
||
|
||
- [ ] **Step 1: 为 `ccdi-lsfx` 添加测试依赖**
|
||
|
||
在 `ccdi-lsfx/pom.xml` 追加测试依赖：
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-starter-test</artifactId>
|
||
<scope>test</scope>
|
||
</dependency>
|
||
```
|
||
|
||
- [ ] **Step 2: 先写控制器失败用例**
|
||
|
||
在 `ccdi-lsfx/src/test/java/com/ruoyi/lsfx/controller/CreditParseControllerTest.java` 写出最小失败用例，覆盖空文件与非法后缀：
|
||
|
||
```java
|
||
@Test
|
||
void parse_shouldRejectEmptyFile() {
|
||
AjaxResult result = controller.parse(null, null, null);
|
||
assertEquals(500, result.get("code"));
|
||
}
|
||
|
||
@Test
|
||
void parse_shouldRejectNonHtmlFile() {
|
||
MockMultipartFile file = new MockMultipartFile(
|
||
"file", "credit.pdf", "application/pdf", "x".getBytes(StandardCharsets.UTF_8)
|
||
);
|
||
AjaxResult result = controller.parse(file, null, null);
|
||
assertEquals(500, result.get("code"));
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: 运行测试确认失败**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
mvn -pl ccdi-lsfx -Dtest=CreditParseControllerTest test
|
||
```
|
||
|
||
Expected:
|
||
|
||
- 编译失败，提示 `CreditParseController` 或 `parse(...)` 不存在。
|
||
|
||
- [ ] **Step 4: 提交前置依赖与测试骨架**
|
||
|
||
```bash
|
||
git add ccdi-lsfx/pom.xml ccdi-lsfx/src/test/java/com/ruoyi/lsfx/controller/CreditParseControllerTest.java ccdi-lsfx/src/test/java/com/ruoyi/lsfx/client/CreditParseClientTest.java
|
||
git commit -m "新增征信解析测试基础"
|
||
```
|
||
|
||
## Task 2: 实现响应对象
|
||
|
||
**Files:**
|
||
- Create: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/CreditParseResponse.java`
|
||
- Create: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/CreditParsePayload.java`
|
||
- Test: `ccdi-lsfx/src/test/java/com/ruoyi/lsfx/client/CreditParseClientTest.java`
|
||
|
||
- [ ] **Step 1: 先写响应映射测试**
|
||
|
||
在 `CreditParseClientTest` 中先写 Jackson 反序列化测试：
|
||
|
||
```java
|
||
@Test
|
||
void shouldDeserializeCreditParseResponse() throws Exception {
|
||
String json = """
|
||
{
|
||
"message": "成功",
|
||
"status_code": "0",
|
||
"payload": {
|
||
"lx_header": {"query_cert_no": "3301"},
|
||
"lx_debt": {"uncle_bank_house_bal": "12.00"},
|
||
"lx_publictype": {"civil_cnt": 1}
|
||
}
|
||
}
|
||
""";
|
||
|
||
CreditParseResponse response = objectMapper.readValue(json, CreditParseResponse.class);
|
||
|
||
assertEquals("0", response.getStatusCode());
|
||
assertEquals("3301", response.getPayload().getLxHeader().get("query_cert_no"));
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 运行测试确认失败**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
mvn -pl ccdi-lsfx -Dtest=CreditParseClientTest#shouldDeserializeCreditParseResponse test
|
||
```
|
||
|
||
Expected:
|
||
|
||
- FAIL，提示 `CreditParseResponse` 或 `CreditParsePayload` 不存在。
|
||
|
||
- [ ] **Step 3: 编写最小响应对象**
|
||
|
||
在 `CreditParseResponse.java` 中实现：
|
||
|
||
```java
|
||
@Data
|
||
public class CreditParseResponse {
|
||
|
||
private String message;
|
||
|
||
@JsonProperty("status_code")
|
||
private String statusCode;
|
||
|
||
private CreditParsePayload payload;
|
||
}
|
||
```
|
||
|
||
在 `CreditParsePayload.java` 中实现：
|
||
|
||
```java
|
||
@Data
|
||
public class CreditParsePayload {
|
||
|
||
@JsonProperty("lx_header")
|
||
private Map<String, Object> lxHeader;
|
||
|
||
@JsonProperty("lx_debt")
|
||
private Map<String, Object> lxDebt;
|
||
|
||
@JsonProperty("lx_publictype")
|
||
private Map<String, Object> lxPublictype;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 运行测试确认通过**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
mvn -pl ccdi-lsfx -Dtest=CreditParseClientTest#shouldDeserializeCreditParseResponse test
|
||
```
|
||
|
||
Expected:
|
||
|
||
- PASS
|
||
|
||
- [ ] **Step 5: 提交响应对象**
|
||
|
||
```bash
|
||
git add ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/CreditParseResponse.java ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/CreditParsePayload.java ccdi-lsfx/src/test/java/com/ruoyi/lsfx/client/CreditParseClientTest.java
|
||
git commit -m "新增征信解析响应对象"
|
||
```
|
||
|
||
## Task 3: 实现 `CreditParseClient`
|
||
|
||
**Files:**
|
||
- Create: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/client/CreditParseClient.java`
|
||
- Modify: `ruoyi-admin/src/main/resources/application-dev.yml`
|
||
- Modify: `ruoyi-admin/src/main/resources/application-nas.yml`
|
||
- Test: `ccdi-lsfx/src/test/java/com/ruoyi/lsfx/client/CreditParseClientTest.java`
|
||
|
||
- [ ] **Step 1: 先写 `Client` 成功用例**
|
||
|
||
在 `CreditParseClientTest` 中用 Mockito 模拟 `HttpUtil`：
|
||
|
||
```java
|
||
@Test
|
||
void shouldCallConfiguredUrlWithMultipartParams() {
|
||
File file = new File("sample.html");
|
||
CreditParseResponse response = new CreditParseResponse();
|
||
response.setStatusCode("0");
|
||
|
||
when(httpUtil.uploadFile(eq("http://credit-host/xfeature-mngs/conversation/htmlEval"), anyMap(), isNull(), eq(CreditParseResponse.class)))
|
||
.thenReturn(response);
|
||
|
||
CreditParseResponse actual = client.parse("LXCUSTALL", "PERSON", file);
|
||
|
||
assertEquals("0", actual.getStatusCode());
|
||
verify(httpUtil).uploadFile(eq("http://credit-host/xfeature-mngs/conversation/htmlEval"), argThat(params ->
|
||
"LXCUSTALL".equals(params.get("model"))
|
||
&& "PERSON".equals(params.get("hType"))
|
||
&& file.equals(params.get("file"))
|
||
), isNull(), eq(CreditParseResponse.class));
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 再写 `Client` 异常传播用例**
|
||
|
||
```java
|
||
@Test
|
||
void shouldWrapHttpErrorsAsLsfxApiException() {
|
||
when(httpUtil.uploadFile(anyString(), anyMap(), isNull(), eq(CreditParseResponse.class)))
|
||
.thenThrow(new LsfxApiException("网络失败"));
|
||
|
||
assertThrows(LsfxApiException.class,
|
||
() -> client.parse("LXCUSTALL", "PERSON", new File("sample.html")));
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: 运行测试确认失败**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
mvn -pl ccdi-lsfx -Dtest=CreditParseClientTest test
|
||
```
|
||
|
||
Expected:
|
||
|
||
- FAIL，提示 `CreditParseClient` 不存在。
|
||
|
||
- [ ] **Step 4: 实现 `CreditParseClient`**
|
||
|
||
在 `CreditParseClient.java` 中实现最小调用逻辑：
|
||
|
||
```java
|
||
@Slf4j
|
||
@Component
|
||
public class CreditParseClient {
|
||
|
||
@Resource
|
||
private HttpUtil httpUtil;
|
||
|
||
@Value("${credit-parse.api.url}")
|
||
private String creditParseUrl;
|
||
|
||
public CreditParseResponse parse(String model, String hType, File file) {
|
||
Map<String, Object> params = new HashMap<>();
|
||
params.put("model", model);
|
||
params.put("hType", hType);
|
||
params.put("file", file);
|
||
return httpUtil.uploadFile(creditParseUrl, params, null, CreditParseResponse.class);
|
||
}
|
||
}
|
||
```
|
||
|
||
补充日志和异常包装，保持 `LsfxAnalysisClient` 风格：
|
||
|
||
- 请求开始记录文件名、`model`、`hType`
|
||
- 请求结束记录耗时和 `statusCode`
|
||
- 异常时抛 `LsfxApiException("征信解析调用失败: ...", e)`
|
||
|
||
- [ ] **Step 5: 增加独立配置**
|
||
|
||
在 `ruoyi-admin/src/main/resources/application-dev.yml` 与 `ruoyi-admin/src/main/resources/application-nas.yml` 增加：
|
||
|
||
```yml
|
||
credit-parse:
|
||
api:
|
||
url: http://64.202.94.120:8081/xfeature-mngs/conversation/htmlEval
|
||
```
|
||
|
||
- [ ] **Step 6: 运行测试确认通过**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
mvn -pl ccdi-lsfx -Dtest=CreditParseClientTest test
|
||
```
|
||
|
||
Expected:
|
||
|
||
- PASS
|
||
|
||
- [ ] **Step 7: 提交 `Client` 与配置**
|
||
|
||
```bash
|
||
git add ccdi-lsfx/src/main/java/com/ruoyi/lsfx/client/CreditParseClient.java ruoyi-admin/src/main/resources/application-dev.yml ruoyi-admin/src/main/resources/application-nas.yml ccdi-lsfx/src/test/java/com/ruoyi/lsfx/client/CreditParseClientTest.java
|
||
git commit -m "新增征信解析客户端"
|
||
```
|
||
|
||
## Task 4: 实现 `CreditParseController`
|
||
|
||
**Files:**
|
||
- Create: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/controller/CreditParseController.java`
|
||
- Test: `ccdi-lsfx/src/test/java/com/ruoyi/lsfx/controller/CreditParseControllerTest.java`
|
||
|
||
- [ ] **Step 1: 先写控制器成功透传用例**
|
||
|
||
```java
|
||
@Test
|
||
void shouldUseDefaultModelAndTypeWhenMissing() {
|
||
MockMultipartFile file = new MockMultipartFile(
|
||
"file", "credit.html", "text/html", "<html/>".getBytes(StandardCharsets.UTF_8)
|
||
);
|
||
CreditParseResponse response = new CreditParseResponse();
|
||
response.setStatusCode("0");
|
||
|
||
when(client.parse(eq("LXCUSTALL"), eq("PERSON"), any(File.class))).thenReturn(response);
|
||
|
||
AjaxResult result = controller.parse(file, null, null);
|
||
|
||
assertEquals(200, result.get("code"));
|
||
assertSame(response, result.get("data"));
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 再写异常兜底用例**
|
||
|
||
```java
|
||
@Test
|
||
void shouldReturnAjaxErrorWhenClientThrows() {
|
||
MockMultipartFile file = new MockMultipartFile(
|
||
"file", "credit.html", "text/html", "<html/>".getBytes(StandardCharsets.UTF_8)
|
||
);
|
||
when(client.parse(anyString(), anyString(), any(File.class)))
|
||
.thenThrow(new LsfxApiException("超时"));
|
||
|
||
AjaxResult result = controller.parse(file, null, null);
|
||
|
||
assertEquals(500, result.get("code"));
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: 运行测试确认失败**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
mvn -pl ccdi-lsfx -Dtest=CreditParseControllerTest test
|
||
```
|
||
|
||
Expected:
|
||
|
||
- FAIL，提示 `CreditParseController` 不存在。
|
||
|
||
- [ ] **Step 4: 编写控制器最小实现**
|
||
|
||
控制器结构按 `LsfxTestController` 风格实现：
|
||
|
||
```java
|
||
@Tag(name = "征信解析接口测试", description = "用于测试征信解析接口")
|
||
@Anonymous
|
||
@RestController
|
||
@RequestMapping("/lsfx/credit")
|
||
public class CreditParseController {
|
||
|
||
@Resource
|
||
private CreditParseClient creditParseClient;
|
||
|
||
@PostMapping("/parse")
|
||
public AjaxResult parse(@RequestParam("file") MultipartFile file,
|
||
@RequestParam(required = false) String model,
|
||
@RequestParam(required = false) String hType) {
|
||
// 参数校验
|
||
// 默认值补齐
|
||
// 临时文件转换
|
||
// 调用 client
|
||
// finally 删除临时文件
|
||
}
|
||
}
|
||
```
|
||
|
||
校验规则固定为：
|
||
|
||
- `file == null` 或 `file.isEmpty()` -> `AjaxResult.error("征信HTML文件不能为空")`
|
||
- `originalFilename` 为空 -> `AjaxResult.error("文件名不能为空")`
|
||
- 不是 `.html`/`.htm` -> `AjaxResult.error("仅支持 HTML 格式文件")`
|
||
- `model` 为空 -> `LXCUSTALL`
|
||
- `hType` 为空 -> `PERSON`
|
||
|
||
- [ ] **Step 5: 运行测试确认通过**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
mvn -pl ccdi-lsfx -Dtest=CreditParseControllerTest test
|
||
```
|
||
|
||
Expected:
|
||
|
||
- PASS
|
||
|
||
- [ ] **Step 6: 提交控制器**
|
||
|
||
```bash
|
||
git add ccdi-lsfx/src/main/java/com/ruoyi/lsfx/controller/CreditParseController.java ccdi-lsfx/src/test/java/com/ruoyi/lsfx/controller/CreditParseControllerTest.java
|
||
git commit -m "新增征信解析联调接口"
|
||
```
|
||
|
||
## Task 5: 做模块级回归验证
|
||
|
||
**Files:**
|
||
- Modify: `docs/reports/implementation/2026-03-23-credit-parse-client-implementation.md`
|
||
|
||
- [ ] **Step 1: 运行 `ccdi-lsfx` 测试**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
mvn -pl ccdi-lsfx test
|
||
```
|
||
|
||
Expected:
|
||
|
||
- `CreditParseClientTest` PASS
|
||
- `CreditParseControllerTest` PASS
|
||
|
||
- [ ] **Step 2: 运行模块编译验证**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
mvn -pl ccdi-lsfx -am compile
|
||
```
|
||
|
||
Expected:
|
||
|
||
- BUILD SUCCESS
|
||
|
||
- [ ] **Step 3: 手工联调检查 Swagger 与接口**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
mvn -pl ruoyi-admin -am spring-boot:run
|
||
```
|
||
|
||
打开：
|
||
|
||
- `http://localhost:62318/swagger-ui.html`
|
||
|
||
检查：
|
||
|
||
- 存在 `POST /lsfx/credit/parse`
|
||
- 上传 `.html` 文件时能返回 `AjaxResult`
|
||
|
||
测试完成后停止进程。
|
||
|
||
- [ ] **Step 4: 记录实施结果**
|
||
|
||
在 `docs/reports/implementation/2026-03-23-credit-parse-client-implementation.md` 写入：
|
||
|
||
- 实际修改文件列表
|
||
- 执行的测试命令
|
||
- 测试结果
|
||
- 是否完成 Swagger 联调
|
||
|
||
建议结构：
|
||
|
||
```md
|
||
# 征信解析客户端实施记录
|
||
|
||
## 1. 改动概述
|
||
|
||
## 2. 修改文件
|
||
|
||
## 3. 测试记录
|
||
|
||
## 4. 结果说明
|
||
```
|
||
|
||
- [ ] **Step 5: 提交验证与实施记录**
|
||
|
||
```bash
|
||
git add docs/reports/implementation/2026-03-23-credit-parse-client-implementation.md
|
||
git commit -m "补充征信解析客户端实施记录"
|
||
```
|
||
|
||
## Task 6: 最终整理
|
||
|
||
**Files:**
|
||
- Modify: `docs/design/2026-03-23-credit-parse-client-design.md`
|
||
- Modify: `docs/plans/backend/2026-03-23-credit-parse-client-backend-implementation.md`
|
||
|
||
- [ ] **Step 1: 回看设计与实现是否一致**
|
||
|
||
逐项核对：
|
||
|
||
- 独立 `CreditParseClient`
|
||
- 独立配置 `credit-parse.api.url`
|
||
- 接口路径 `POST /lsfx/credit/parse`
|
||
- 不接入 `ccdi-project`
|
||
- 不落库
|
||
|
||
- [ ] **Step 2: 如果实现偏差，更新设计或实施记录**
|
||
|
||
只允许修正文档，不允许在这个阶段临时扩需求。
|
||
|
||
- [ ] **Step 3: 检查暂存区只包含本次任务相关文件**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
git status --short
|
||
git diff --cached --name-only
|
||
```
|
||
|
||
Expected:
|
||
|
||
- 暂存区仅包含本次征信解析相关代码与文档
|
||
|
||
- [ ] **Step 4: 最终提交**
|
||
|
||
```bash
|
||
git add ccdi-lsfx/pom.xml ccdi-lsfx/src/main/java/com/ruoyi/lsfx/client/CreditParseClient.java ccdi-lsfx/src/main/java/com/ruoyi/lsfx/controller/CreditParseController.java ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/CreditParseResponse.java ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/CreditParsePayload.java ccdi-lsfx/src/test/java/com/ruoyi/lsfx/client/CreditParseClientTest.java ccdi-lsfx/src/test/java/com/ruoyi/lsfx/controller/CreditParseControllerTest.java ruoyi-admin/src/main/resources/application-dev.yml ruoyi-admin/src/main/resources/application-nas.yml docs/reports/implementation/2026-03-23-credit-parse-client-implementation.md
|
||
git commit -m "完成征信解析客户端后端实现"
|
||
```
|
||
|
||
## Review Notes
|
||
|
||
- 由于当前仓库协作约定要求“不开启 subagent”，本计划不执行 `writing-plans` 技能中的子代理审阅环节。
|
||
- 实施时如果发现外部接口真实返回结构与说明书不一致，应先修正响应映射，再更新实施记录，不要额外扩展业务逻辑。
|