补充征信解析客户端实施记录

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

@@ -0,0 +1,80 @@
+# 征信解析客户端实施记录
+
+## 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 过程命令
+
+执行过的关键测试命令如下：
+
+```bash
+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 模块回归命令
+
+```bash
+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 / 接口联调
+
+执行过程：
+
+```bash
+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 暴露和请求链路已打通；外部征信解析服务当前未响应，需待对方服务可用后继续做成功结果验证。