ccdi/docs/plans/backend/2026-05-14-credit-parse-result-polling-backend-plan.md

征信解析双接口与结果轮询后端实施计划

背景

根据 天座征信解析接口文档.xlsx，征信解析需要拆分为发起接口和结果接口：先通过 /api/service/interface/invokeService/xfeature 提交 HTML 远程地址，再通过 /api/service/interface/invokeService/xfeatureResult 按同一业务流水号查询解析结果。

实施内容

1. 后端客户端

   • 保持 CreditParseClient.parse(remotePath) 和 parse(model, remotePath) 对外签名不变。
   • 内部生成同一个 serialNum，发起接口提交 serialNum/orgCode/runType/remotePath/model。
   • 结果接口提交 serialNum/orgCode/runType，最多查询 5 次，每次间隔 2 秒。
   • 外层严格校验 success=true、code=10000，业务层严格校验 status_code=0。
   • 仅当结果未就绪或 payload 为空时继续轮询，明确业务失败立即返回失败原因。

2. 配置

   • 保留 credit-parse.api.url 作为发起接口地址。
   • 新增 credit-parse.api.result-url 作为结果接口地址。
   • dev/uat/nas/pro 环境 credit-parse.api.org-code 统一调整为 999000。

3. Mock 服务

   • /xfeature 读取 remotePath 生成 payload，按 serialNum 暂存结果，只返回发起成功结构。
   • /xfeatureResult 按 serialNum 返回暂存 payload，未知流水号返回业务失败。

4. 征信维护落库

   • 上传入口、HTML 落盘、remotePath 拼接、页面接口均保持不变。
   • 原有落库逻辑继续读取最终结果中的 lx_header/lx_debt/lx_publictype。

验证计划

• mvn -pl ccdi-lsfx -Dtest=CreditParseControllerTest test
• mvn -pl ccdi-info-collection -am -Dtest=CcdiCreditInfoServiceImplTest -Dsurefire.failIfNoSpecifiedTests=false test
• mvn -pl ccdi-lsfx,ccdi-info-collection -am compile
• cd lsfx-mock-server && pytest tests/test_credit_api.py tests/test_startup.py -q