ccdi/docs/reports/implementation/2026-05-12-credit-parse-remote-path-backend-implementation.md

征信解析远程路径调用改造实施记录

背景

天座征信解析接口调用方式变更：不再直接 multipart 上传 HTML 文件，改为先将 HTML 保存到业务服务器可访问目录，再将完整远程访问地址作为 remotePath 以 application/x-www-form-urlencoded 表单参数提交到新接口。

本次按新接口文档确认输出外层结构为 success/code/data/mappingOutputFields，其中 mappingOutputFields.payload 内部仍沿用原有 lx_header/lx_debt/lx_publictype 结构。

修改内容

1. 后端上传处理

   • 上传入口 /ccdi/creditInfo/upload 保持不变。
   • 新增 CreditHtmlStorageService，校验通过后的 HTML 保存到 ruoyi.profile/credit-html/...。
   • 根据 credit-parse.api.file-public-base-url 与 /profile/credit-html/... 拼接生成 remotePath。
   • 征信维护落库逻辑改为调用 CreditParseClient.parse(remotePath)，后续日期校验、落库、失败记录逻辑保持原样。

2. 天座接口客户端

   • CreditParseClient 改为提交 serialNum/orgCode/runType/remotePath/model 表单参数。
   • HttpUtil 增加 postUrlEncodedForm 方法，统一提交 application/x-www-form-urlencoded。
   • 新增 CreditParseInvokeResponse、CreditParseInvokeData，承载新外层响应结构。
   • 业务解析只读取 data.mappingOutputFields 下的 message/status_code/payload。

3. 配置

   • application-dev.yml、application-pro.yml、application-nas.yml、application-uat.yml 同步调整 credit-parse.api.url 到 /api/service/interface/invokeService/xfeature。
   • 新增 credit-parse.api.file-public-base-url、org-code=902000、run-type=1、model=LXCUSTALL。

4. 本地 mock

   • lsfx-mock-server 新增支持 /api/service/interface/invokeService/xfeature。
   • mock 接收新表单参数并通过 remotePath 读取 HTML。
   • mock 返回新外层结构，payload 仍按旧结构生成。

5. 测试覆盖

   • CreditParseControllerTest 覆盖新调试入口、默认模型、客户端异常、表单参数完整性。
   • CcdiCreditInfoServiceImplTest 覆盖 HTML 保存路径与 remotePath 拼接、旧日期拦截、成功落库、从新外层结构读取旧 payload。

验证结果

1. 接口文档核对

   • 已读取 天座征信解析接口文档.xlsx，确认调用方式为 POST application/x-www-form-urlencoded。
   • 已确认输入参数为 serialNum/orgCode/runType/remotePath/model。
   • 已确认输出结构为 success/code/data/mappingOutputFields。

2. 单元测试与编译

   • mvn -pl ccdi-lsfx -Dtest=CreditParseControllerTest test：通过，4 个用例成功。
   • mvn -pl ccdi-info-collection -am -Dtest=CcdiCreditInfoServiceImplTest -Dsurefire.failIfNoSpecifiedTests=false test：通过，3 个用例成功。
   • mvn -pl ccdi-lsfx,ccdi-info-collection -am compile：通过。

3. 联调验证

   • 通过 bin/restart_java_backend.sh restart 启动后端。
   • 启动本地 mock 后，通过 /ccdi/creditInfo/upload 上传临时 HTML。
   • 后端日志确认调用参数包含：
     • model=LXCUSTALL
     • remotePath=http://127.0.0.1:62318/profile/credit-html/2026/05/12/credit_remote_path_test_20260512190228A001.html
   • mock 日志确认收到 POST /api/service/interface/invokeService/xfeature 并返回 200。
   • 上传结果：successCount=1、failureCount=0。
   • 列表与详情均可查询到解析后的征信负面信息和债务信息。
   • 联调测试身份证号 330781199001019999 对应数据已通过删除接口清理，复查列表 total=0。

影响范围

• 影响征信维护上传入口、征信解析客户端、本地 mock、相关环境配置。
• 前端上传入口和页面接口路径不变。
• 不保留旧 multipart 外部接口兼容逻辑。