ccdi/docs/reports/implementation/2026-05-14-credit-parse-result-polling-implementation.md

征信解析双接口与结果轮询实施记录

背景

本次按 天座征信解析接口文档.xlsx 调整征信解析调用方式：由单次发起接口直接获取 payload，改为发起接口 /api/service/interface/invokeService/xfeature 加结果接口 /api/service/interface/invokeService/xfeatureResult 的两步调用。

修改内容

1. CreditParseClient

   • 保持原有 parse 方法签名不变。
   • 发起接口提交 serialNum/orgCode/runType/remotePath/model。
   • 结果接口使用同一 serialNum 提交 serialNum/orgCode/runType。
   • 结果接口最多轮询 5 次，每次间隔 2 秒。
   • 严格校验外层 success=true、code=10000 和业务层 status_code=0。

2. 配置

   • application-dev.yml、application-uat.yml、application-nas.yml、application-pro.yml 新增 credit-parse.api.result-url。
   • 上述环境的 credit-parse.api.org-code 统一调整为 999000。

3. CcdiCreditInfoServiceImpl

   • 征信维护落库前补充外层 code=10000 校验。
   • 上传入口、HTML 保存、remotePath 生成和落库字段映射保持不变。

4. lsfx-mock-server

   • /xfeature 改为发起接口，只暂存结果并返回发起成功结构。
   • 新增 /xfeatureResult，按 serialNum 返回暂存 payload。
   • Mock README 和启动路由说明同步更新。

5. 测试

   • Java 测试补充同一 serialNum 双接口调用、5 次轮询、2 秒间隔和外层状态码校验。
   • Mock 测试补充发起接口、结果接口、缺参、未知流水号和 payload 返回。

影响范围

• 影响征信解析客户端、征信维护上传后的解析调用、征信解析 Mock 服务和相关环境配置。
• 不涉及前端页面、前端 API、数据库表结构和业务 payload 字段变更。

验证

• mvn -pl ccdi-lsfx -Dtest=CreditParseControllerTest test：通过，6 个用例成功。
• mvn -pl ccdi-info-collection -am -Dtest=CcdiCreditInfoServiceImplTest -Dsurefire.failIfNoSpecifiedTests=false test：通过，4 个用例成功。
• mvn -pl ccdi-lsfx,ccdi-info-collection -am compile：通过。
• cd lsfx-mock-server && python3 -m pytest tests/test_credit_api.py tests/test_startup.py -q：通过，9 个用例成功。
• git diff --check：通过。
• 后端联调：
  • 启动 lsfx-mock-server，并通过 bin/restart_java_backend.sh restart 重启后端。
  • 调用 /login/test 获取测试令牌后，通过 /ccdi/creditInfo/upload 上传本轮 HTML 测试文件。
  • 上传结果：totalCount=1、successCount=1、failureCount=0。
  • 列表按身份证号 330781199001019914 查询到 1 条征信记录。
  • 后端日志确认同一个 serialNum 先调用 /api/service/interface/invokeService/xfeature，再调用 /api/service/interface/invokeService/xfeatureResult。
  • 调用删除接口清理本轮测试数据，回查列表 total=0。
  • 本轮启动的 mock 和后端进程已关闭。
• 浏览器验证说明：
  • 已使用 browser-use 打开本地前端并完成登录。
  • 后端重启后，浏览器旧登录态触发接口 500，且 browser-use 安全策略阻止通过 javascript: URL 清理本地状态，因此未继续执行页面上传动作。
  • 已改用真实后端接口完成上传、落库、日志和清理闭环验证。