ccdi/docs/design/2026-03-23-credit-parsing-mock-server-design.md

征信解析 Mock Server 设计方案

1. 背景

当前仓库已经有一个基于 FastAPI 的 lsfx-mock-server，用于模拟流水分析平台接口。本次新增需求来自以下两份输入材料：

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

根据说明书，本次目标接口为 POST /xfeature-mngs/conversation/htmlEval，请求格式为 form-data，核心入参为 model、file、hType，返回结构为 message、status_code、payload。根据 Excel，本次 payload 至少覆盖 30 个征信指标字段，分布在 lx_header、lx_debt、lx_publictype 三个主题域对象下。

本次工作目标不是实现真实 HTML 解析能力，而是在现有 Mock 服务中补齐一个“结构正确、返回稳定、便于联调”的征信解析接口。

2. 目标

• 在现有 lsfx-mock-server 中新增征信解析 Mock 能力。
• 实现说明书中的单一核心接口 POST /xfeature-mngs/conversation/htmlEval。
• 支持 model、file、hType 的 form-data 请求。
• 成功返回时输出与 Excel 字段定义一致的 payload 结构。
• 按 model + hType + 文件名 生成稳定随机结果，保证同一请求重复调用结果一致。
• 提供最小调试能力，包括健康检查接口和按参数触发失败码。

3. 非目标

• 不解析真实 HTML 内容，不从文件正文抽取字段。
• 不新增说明书之外的业务接口。
• 不为每个字段单独编写硬编码生成逻辑。
• 不引入独立新项目或第二套运行框架。
• 不设计复杂的动态配置平台或可视化管理后台。

4. 方案对比

4.1 方案 A：最短硬编码

直接在现有路由文件中追加征信接口，并把随机生成逻辑写在单个函数或单个 service 内。

优点：

• 实现最快。

缺点：

• 路由层会掺杂业务规则。
• 后续补错误码、字段规则、样例模板时可维护性差。

4.2 方案 B：模块化扩展

在现有 lsfx-mock-server 中新增独立的征信解析路由、service 和配置文件，复用当前 FastAPI 应用和启动方式。

优点：

• 保持实现路径最短。
• 复用现有工程基础设施和依赖。
• 征信解析逻辑与现有 LSFX Mock 逻辑隔离，后续扩展清晰。

缺点：

• 需要增加少量模块文件和配置文件。

4.3 方案 C：全配置驱动

把 Excel 字段直接转换为运行时元数据，服务根据配置动态生成字段、校验和示例响应。

优点：

• 后续字段调整灵活。

缺点：

• 引入额外抽象，超出本次“最短路径实现”的边界。

5. 推荐方案

采用方案 B。

原因如下：

• 与用户确认的边界一致：直接扩展现有工程，不新建独立服务。
• 可以在不影响已有 LSFX Mock 链路的前提下补齐征信解析能力。
• 代码结构清晰，后续如果字段扩充或错误码增加，仍可局部修改。

6. 模块边界与目录设计

征信解析能力直接并入现有 lsfx-mock-server，但采用独立模块组织，避免与现有银行流水 Mock 逻辑混杂。

建议落点如下：

• lsfx-mock-server/routers/credit_api.py
• lsfx-mock-server/services/credit_payload_service.py
• lsfx-mock-server/services/credit_debug_service.py
• lsfx-mock-server/config/credit_feature_schema.json
• lsfx-mock-server/config/credit_response_examples.json

职责划分如下：

• credit_api.py：负责 HTTP 路由、form-data 入参接收、响应结构封装。
• credit_payload_service.py：负责稳定随机种子生成、字段分组、payload 生成。
• credit_debug_service.py：负责调试标记识别、错误码映射、健康检查响应。
• credit_feature_schema.json：记录字段归属、类型、枚举范围等元数据。
• credit_response_examples.json：保存成功和失败响应模板，保证结构统一。

7. 接口设计

7.1 接口定义

• 方法：POST
• 路径：/xfeature-mngs/conversation/htmlEval
• Content-Type：multipart/form-data

7.2 请求参数

参数名	类型	必填	说明
model	String	是	查询主题域，当前只接受 LXCUSTALL
file	File	是	HTML 文件，仅校验上传存在
hType	String	是	报文类型，只接受 PERSON 或 ENTERPRISE

说明：接口说明书的参数表明确 hType 当前支持 PERSON/ENTERPRISE，但错误码表中 ERR_10003 的文案写为“报文类型无效，仅支持JSON/XML”。本设计将该差异视为原始文档歧义，校验逻辑以参数表为准，失败时的返回码与返回信息沿用错误码表定义。

7.3 成功响应

成功时统一返回：

{
  "message": "成功",
  "payload": {
    "lx_header": {},
    "lx_debt": {},
    "lx_publictype": {}
  },
  "status_code": "0"
}

7.4 失败响应

失败时统一返回：

{
  "message": "关键参数缺失，参数名: model",
  "payload": null,
  "status_code": "ERR_99999"
}

8. Payload 生成设计

8.1 生成原则

• 不解析真实 HTML 文件内容。
• 仅基于 model + hType + 文件名 计算稳定随机种子。
• 同一组输入每次调用返回相同结果。
• 不同 model、hType 或文件名组合返回不同结果。

8.2 字段分组

根据 Excel，本次最小字段集合如下：

• lx_header
  • query_cert_no
  • query_cust_name
  • report_time
• lx_debt
  • 房贷、车贷、经营贷、消费贷、其他贷款、非银行、信用卡等余额/金额/状态字段
• lx_publictype
  • 民事判决、强制执行、行政处罚的记录数和金额字段

8.3 类型规则

为避免 30 个字段写成 30 段硬编码分支，schema 只保留最小类型抽象：

• string
• amount
• count
• status

生成规则如下：

• string：生成符合业务格式的字符串。
• amount：生成非负金额字符串，保留两位小数。
• count：生成非负整数。
• status：严格从 schema 枚举中选值，当前为 正常、逾期、不良。

8.4 头信息字段规则

虽然不解析真实 HTML，头信息字段仍需保证格式可用：

• query_cert_no：生成合法格式的证件号码样式字符串。
• query_cust_name：生成脱敏风格或常见中文姓名样式字符串。
• report_time：生成合法日期字符串，例如 YYYY-MM-DD。

9. 错误处理设计

错误处理只覆盖说明书已明确的最小集合，不新增自定义协议。

场景	返回码	返回信息
缺少 model、file、hType	ERR_99999	关键参数缺失，参数名: XX
model 不为 LXCUSTALL	ERR_10002	无效的主题域
hType 不为 PERSON 或 ENTERPRISE	ERR_10003	报文类型无效，仅支持JSON/XML
调试标记触发无效证件号类错误	ERR_10001	无效的证件号码
调试标记触发机构号错误	ERR_10004	无效机构号或行社号
调试标记触发权限错误	ERR_10005	无权限访问
调试标记触发服务异常	ERR_10006	尽调报告生成异常：异步事件发送失败

调试标记建议复用现有 Mock 服务习惯，通过 model 中包含类似 error_ERR_10001 的值触发对应错误响应。

10. 调试能力设计

本次只提供最小调试能力：

• 提供健康检查接口，例如 GET /credit/health。
• 支持通过特定 model 值触发失败码。
• 不额外增加复杂调试参数。
• 不支持运行时在线修改字段配置。

这样既能满足联调和测试，又不会偏离主业务接口行为。

11. 配置组织设计

Excel 文件只作为需求输入，不作为运行时依赖。服务运行时改为读取项目内的 JSON schema。

credit_feature_schema.json 建议字段结构如下：

[
  {
    "domain": "lx_header",
    "field": "query_cert_no",
    "type": "string"
  },
  {
    "domain": "lx_debt",
    "field": "uncle_bank_house_state",
    "type": "status",
    "options": ["正常", "逾期", "不良"]
  }
]

这样可以保证：

• 扩充字段时只需要补 schema。
• 生成逻辑聚焦类型，不直接绑定具体字段数量。
• 响应结构仍保持说明书和 Excel 要求。

12. 测试与验收设计

测试边界保持最短闭环：

• 单元测试
  • 成功响应结构正确。
  • 同一输入返回稳定随机一致结果。
  • 不同输入返回不同随机结果。
  • 调试标记能返回预期错误码。
• 接口测试
  • multipart/form-data 上传可被正确接收。
  • 缺参时返回说明书约定格式。
  • 健康检查接口返回可用状态。

验收重点如下：

• 调用方按说明书格式发起请求时，能拿到合法 JSON 响应。
• payload 字段结构与 Excel 保持一致。
• 同一组请求参数重复调用时结果一致。
• 参数异常时返回约定错误码与错误信息。

13. 文档与实施计划要求

按仓库约定，设计确认后需要继续产出两份实施计划：

• 后端实施计划：docs/plans/backend/
• 前端实施计划：docs/plans/frontend/

由于本次主体是 Mock 服务开发，前端计划可聚焦联调接入、调试入口或调用说明，不扩展无关页面开发。

后续进入实现阶段后，还需补充本次改动的实施记录到 docs/reports/implementation/。

14. 实现落点

预计涉及如下文件范围：

• 新增 lsfx-mock-server/routers/credit_api.py
• 新增 lsfx-mock-server/services/credit_payload_service.py
• 新增 lsfx-mock-server/services/credit_debug_service.py
• 新增 lsfx-mock-server/config/credit_feature_schema.json
• 新增 lsfx-mock-server/config/credit_response_examples.json
• 按需修改 lsfx-mock-server/main.py 或路由注册入口
• 新增对应测试文件

15. 结论

本方案采用“在现有 Mock 服务中模块化扩展征信解析能力”的方式，以单接口、稳定随机、最小调试能力为边界完成征信解析 Mock Server 建设。该方案满足当前联调目标，同时避免引入真实 HTML 解析和过度设计，符合最短路径实现要求。