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

征信解析客户端与接口设计方案

1. 背景

本次需求来自以下两份输入材料：

• assets/征信解析/HTML引擎服务_ 接口设计说明书_1.docx
• assets/征信解析/征信解析接口payload.xlsx

根据说明书，本次目标外部接口为 POST /xfeature-mngs/conversation/htmlEval，请求格式为 multipart/form-data，核心入参为：

• model
• file
• hType

返回体结构为：

• message
• status_code
• payload

根据 Excel，payload 当前至少包含以下三个主题域对象：

• lx_header
• lx_debt
• lx_publictype

当前仓库中已有银行流水分析平台的集成代码，集中在 ccdi-lsfx 模块；但征信解析服务与流水分析平台不是同一套接口语义和配置边界。本次目标是在不破坏现有 lsfx 链路的前提下，新增一套独立的征信解析调用能力，并在 ccdi-lsfx 中暴露一个可供联调使用的后端接口。

2. 目标

• 在 ccdi-lsfx 模块中新增独立的征信解析 Client。
• 在 ccdi-lsfx 模块中新增对外联调接口，用于接收 HTML 文件并调用征信解析服务。
• 征信解析配置与现有 lsfx 配置完全隔离，不共用同一配置前缀。
• 配置项使用单一完整 URL，不拆分 base-url 和 endpoints。
• 外部服务成功响应时，保留 message、status_code、payload 的原始语义。
• 控制器仅做最小参数校验，不额外引入项目上传记录、异步任务、状态轮询或结果落库。

3. 非目标

• 不接入 ccdi-project 现有项目文件上传主链路。
• 不新增征信解析结果落库逻辑。
• 不补充前端页面接入。
• 不把征信解析 Client 并入现有 LsfxAnalysisClient。
• 不将征信解析配置挂到 lsfx.api.* 下。
• 不额外设计说明书之外的兜底流程、降级流程或兼容协议。

4. 方案对比

4.1 方案 A：直接扩展现有 LsfxAnalysisClient

把征信解析方法直接加到现有 LsfxAnalysisClient，并继续使用 lsfx.api.* 配置。

优点：

• 改动文件数最少。

缺点：

• 语义上把两套不同外部服务混在同一个 Client 中。
• 配置边界不清晰，后续切换环境容易误改现有流水分析配置。
• 不符合本次“新增 Client，并在配置文件里与 lsfx 分开”的要求。

4.2 方案 B：在 ccdi-lsfx 中新增独立 CreditParseClient

在 ccdi-lsfx 中新增独立控制器和独立 Client，并使用新的配置前缀承载完整 URL。

优点：

• 满足“接口加在 ccdi-lsfx 中”的要求。
• 满足“新增 Client，在配置文件里与 lsfx 分开”的要求。
• 与现有银行流水分析集成边界清晰，不会污染主链路。
• 仍然复用现有 HttpUtil，实现路径最短。

缺点：

• 需要新增少量类和配置项。

4.3 方案 C：在 ccdi-project 中直接暴露业务接口并自行发起调用

由 ccdi-project 新增控制器和 service，直接使用 RestTemplate 调征信解析平台。

优点：

• 对业务模块看起来更直接。

缺点：

• 与用户已确认的“接口加在 ccdi-lsfx 中”不一致。
• 会把外部平台调用能力分散到多个模块。
• 后续复用和维护成本更高。

5. 推荐方案

采用方案 B：在 ccdi-lsfx 中新增独立 CreditParseClient、独立配置和独立联调接口。

推荐原因：

• 与已确认需求完全一致。
• 保持最短路径实现，不引入无关业务改造。
• 外部服务边界清晰，后续如果还要补企业征信或更多解析接口，可以继续沿用这一结构。

6. 模块边界与目录设计

本次改动集中在 ccdi-lsfx 模块。

建议落点如下：

• ccdi-lsfx/src/main/java/com/ruoyi/lsfx/controller/CreditParseController.java
• ccdi-lsfx/src/main/java/com/ruoyi/lsfx/client/CreditParseClient.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
• ruoyi-admin/src/main/resources/application-dev.yml
• ruoyi-admin/src/main/resources/application-nas.yml

职责划分如下：

• CreditParseController

  • 接收联调方上传的 HTML 文件和可选参数。
  • 做最小参数校验。
  • 将 MultipartFile 转换为临时文件。
  • 调用 CreditParseClient。
  • 返回 AjaxResult。

• CreditParseClient

  • 读取独立配置中的完整 URL。
  • 组装 multipart/form-data 参数。
  • 调用现有 HttpUtil.uploadFile(...)。
  • 统一记录调用日志和抛出平台调用异常。

• CreditParseResponse

  • 映射外部接口返回的 message、status_code、payload。

• CreditParsePayload

  • 承载 lx_header、lx_debt、lx_publictype 三个主题域对象。

7. 配置设计

征信解析配置独立于 lsfx，使用新的配置前缀。

建议配置结构如下：

credit-parse:
  api:
    url: http://64.202.94.120:8081/xfeature-mngs/conversation/htmlEval

说明：

• url 保存单一完整地址，不拆分为 base-url 和 endpoints。
• 不复用 lsfx.api.connection-timeout、lsfx.api.read-timeout 等配置项。
• 本次实现优先沿用现有 RestTemplate Bean；若后续确需独立超时配置，再单独扩展专用 HTTP 配置，不在本次设计中预埋。

8. 对外接口设计

8.1 接口定义

• 方法：POST
• 路径：/lsfx/credit/parse
• Content-Type：multipart/form-data

接口放在 ccdi-lsfx 模块中，作为征信解析联调入口。

8.2 请求参数

参数名	类型	必填	默认值	说明
file	MultipartFile	是	无	征信 HTML 文件
model	String	否	LXCUSTALL	主题域编码
hType	String	否	PERSON	报文类型

8.3 本地校验规则

控制器层只做最小必要校验：

• file 不能为空。
• 文件名不能为空。
• 文件后缀必须为 .html 或 .htm。
• model 为空时补默认值 LXCUSTALL。
• hType 为空时补默认值 PERSON。

不在控制器层重复实现外部平台业务码校验，不提前限制：

• model 是否只能取 LXCUSTALL
• hType 是否只能取 PERSON 或 ENTERPRISE

上述业务校验结果以外部服务返回的 status_code 为准。

8.4 返回规则

返回采用若依标准 AjaxResult 包装，规则如下：

• 本地参数校验失败：返回 AjaxResult.error(...)
• 外部调用成功拿到响应：返回 AjaxResult.success(responseBody)
• 网络异常、超时、反序列化异常或其他调用异常：返回 AjaxResult.error("征信解析调用失败：" + e.getMessage())

其中 AjaxResult.data 中保留外部原始业务语义，例如：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "message": "成功",
    "status_code": "0",
    "payload": {
      "lx_header": {},
      "lx_debt": {},
      "lx_publictype": {}
    }
  }
}

这意味着：

• 外部业务失败码如 ERR_99999、ERR_10002 仍然作为正常 HTTP 调用结果返回。
• 调用方根据 data.status_code 判断业务成功与否。
• 本地接口不对外部业务码做二次翻译，避免语义偏移。

9. Client 设计

9.1 调用链

调用链固定为：

CreditParseController -> CreditParseClient -> HttpUtil.uploadFile(...) -> 征信解析服务

9.2 请求组装

CreditParseClient 发送 multipart/form-data，参数仅包含：

• model
• file
• hType

不新增说明书之外的扩展字段。

9.3 URL 读取

CreditParseClient 直接读取：

• credit-parse.api.url

不做 URL 拼接。

9.4 日志

日志风格保持与 ccdi-lsfx 现有习惯一致，至少包含：

• 请求开始：文件名、model、hType
• 请求结束：耗时、返回 status_code
• 请求失败：错误信息和异常堆栈

9.5 异常

CreditParseClient 统一抛出 LsfxApiException 风格异常，保持 ccdi-lsfx 模块内部异常语义一致。

10. 响应对象设计

10.1 请求 DTO

本次不新增请求 DTO。

原因：

• 控制器直接接收 MultipartFile file, String model, String hType 即可。
• Client 内部直接构造 Map<String, Object> 最短路径实现。
• 纯透传场景下，引入请求 DTO 只会增加样板代码。

10.2 响应 DTO

建议新增以下响应对象：

CreditParseResponse

• String message
• String statusCode
• CreditParsePayload payload

其中 statusCode 使用注解映射 JSON 字段 status_code。

CreditParsePayload

• Map<String, Object> lxHeader
• Map<String, Object> lxDebt
• Map<String, Object> lxPublictype

其中字段名使用注解映射：

• lx_header
• lx_debt
• lx_publictype

10.3 为何不展开成 30+ 强类型字段

本次目标是“添加调用征信解析接口的方法”，不是“建立完整征信指标领域模型”。因此本次不把 Excel 中的 30 余个字段全部定义为强类型 Java 属性，原因如下：

• 当前需求核心是打通调用，不是做复杂业务计算。
• 外部字段后续仍可能调整，强类型化会增加维护成本。
• 三段 Map<String, Object> 已足够支撑联调与响应透传。

后续如果业务明确需要对单个字段做服务内计算或落库，再单独收敛更细的领域对象。

11. 文件处理设计

由于现有 HttpUtil.uploadFile(...) 接收的是 File 对象，控制器层需要把上传的 MultipartFile 转为临时文件。

处理规则如下：

• 使用系统临时目录创建临时文件。
• 临时文件名保留原始后缀，方便外部服务识别文件类型。
• Client 调用结束后，在 finally 中删除临时文件。
• 临时文件删除失败只记录日志，不覆盖主流程结果。

该处理仅用于本次同步调用，不沉淀到项目上传目录，不复用 ccdi-project 的文件上传记录表。

12. 测试设计

本次测试只覆盖后端最小闭环，不扩展到前端。

建议至少覆盖以下场景：

1. 合法 HTML 文件上传，外部服务返回 status_code = 0
2. 文件为空，本地接口直接返回参数错误
3. 文件后缀非法，本地接口直接返回参数错误
4. 外部服务不可达或超时，接口返回调用失败信息
5. 外部服务返回业务失败码，例如 ERR_99999，本地接口仍然按成功调用返回 AjaxResult.success(...)

如果测试过程中需要临时启动后端进程，测试完成后必须主动关闭，避免残留进程占用端口。

13. 实施边界确认

本次实施只包含以下内容：

• 新增 CreditParseClient
• 新增 CreditParseController
• 新增征信解析响应对象
• 新增独立配置项 credit-parse.api.url
• 补充后端测试

本次明确不包含：

• ccdi-project 主上传链路改造
• 项目上传记录表扩展
• 征信结果落库
• 前端接入
• 额外的兼容性补丁或兜底方案

14. 风险与约束

• 外部服务返回结构以说明书和联调实际为准；若实际返回字段名与说明书不一致，需要在实现阶段按真实返回修正映射。
• 本次沿用现有 RestTemplate Bean；若后续征信解析服务需要独立连接池或独立超时，再单独设计，不在本次范围内扩展。
• 由于本次不做落库，调用结果仅用于联调和即时查看。

15. 预期交付物

• 一份后端设计实现代码，落在 ccdi-lsfx 模块
• 一份后端实施计划文档，落在 docs/plans/backend/
• 一份前端实施计划文档，落在 docs/plans/frontend/，明确本次无前端实施项
• 一份本次改动实施记录文档，落在 docs/reports/implementation/

本方案采用“ccdi-lsfx 内新增独立征信解析 Client 与联调接口、配置与 lsfx 完全隔离”的方式，以最短路径补齐征信解析调用能力，同时保证与现有银行流水分析链路边界清晰，符合当前需求边界。