ccdi/docs/reports/implementation/2026-03-23-credit-parse-client-implementation.md

征信解析客户端实施记录

1. 改动概述

本次在 ccdi-lsfx 模块新增了独立征信解析能力，包含以下内容：

• 新增 CreditParseClient，通过独立配置 credit-parse.api.url 调用外部征信解析服务。
• 新增 POST /lsfx/credit/parse 联调接口，支持上传 .html/.htm 文件、默认补齐 model=LXCUSTALL 与 hType=PERSON，并将结果以 AjaxResult 形式返回。
• 新增征信解析响应对象 CreditParseResponse、CreditParsePayload。
• 为 ccdi-lsfx 补充 spring-boot-starter-test 依赖，并新增客户端、控制器单元测试。

2. 修改文件

• 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

3. 测试记录

3.1 TDD 过程命令

执行过的关键测试命令如下：

mvn -pl ccdi-lsfx -Dtest=CreditParseControllerTest test
mvn -pl ccdi-lsfx -Dtest=CreditParseClientTest#shouldDeserializeCreditParseResponse test
mvn -pl ccdi-lsfx -Dtest=CreditParseClientTest test
mvn -pl ccdi-lsfx -Dtest=CreditParseControllerTest test

结果：

• CreditParseControllerTest 首次运行按预期失败，定位为 CreditParseController 不存在。
• CreditParseClientTest#shouldDeserializeCreditParseResponse 首次运行按预期失败，定位为响应对象不存在。
• CreditParseClientTest 与 CreditParseControllerTest 最终均通过。

3.2 模块回归命令

mvn -pl ccdi-lsfx test
mvn -pl ccdi-lsfx -am compile

结果：

• mvn -pl ccdi-lsfx test：通过，CreditParseClientTest 和 CreditParseControllerTest 共 7 个测试全部通过。
• mvn -pl ccdi-lsfx -am compile：通过，ruoyi-common、ccdi-lsfx 编译成功。

3.3 Swagger / 接口联调

执行过程：

mvn -pl ruoyi-admin -am install -DskipTests
cd ruoyi-admin && mvn spring-boot:run
curl -I http://127.0.0.1:62318/swagger-ui.html
curl http://127.0.0.1:62318/v3/api-docs
curl -F 'file=@/tmp/credit-parse-sample.html;type=text/html' http://127.0.0.1:62318/lsfx/credit/parse

结果：

• swagger-ui.html 可正常跳转到 /swagger-ui/index.html。
• OpenAPI 文档中已存在 征信解析接口测试 标签以及 POST /lsfx/credit/parse 路径。
• 上传 .html 文件时，请求已进入 CreditParseController 与 CreditParseClient，但外部地址 http://64.202.94.120:8081/xfeature-mngs/conversation/htmlEval 在联调时返回 The target server failed to respond，因此未拿到成功解析结果。
• 联调结束后已停止 ruoyi-admin 启动进程，未保留端口占用。

4. 结果说明

• 设计范围内的后端代码已完成，未接入 ccdi-project，未新增落库逻辑。
• 独立配置 credit-parse.api.url 已在 application-dev.yml 与 application-nas.yml 中补齐。
• 控制器已实现文件校验、默认值补齐、临时文件转换、调用客户端和临时文件清理。
• 客户端已实现调用日志、耗时记录和统一异常包装。
• 本次联调结论为：系统侧接口注册、Swagger 暴露和请求链路已打通；外部征信解析服务当前未响应，需待对方服务可用后继续做成功结果验证。

5. 追加调整记录

• 为便于本地联调，已将 application-dev.yml 中的 credit-parse.api.url 调整为本地 Mock 地址：http://localhost:8000/xfeature-mngs/conversation/htmlEval。