新增征信解析Mock设计文档
This commit is contained in:
295
docs/design/2026-03-23-credit-parsing-mock-server-design.md
Normal file
295
docs/design/2026-03-23-credit-parsing-mock-server-design.md
Normal file
@@ -0,0 +1,295 @@
|
||||
# 征信解析 Mock Server 设计方案
|
||||
|
||||
## 1. 背景
|
||||
|
||||
当前仓库已经有一个基于 FastAPI 的 [lsfx-mock-server](/Users/wkc/Desktop/ccdi/ccdi/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](/Users/wkc/Desktop/ccdi/ccdi/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](/Users/wkc/Desktop/ccdi/ccdi/lsfx-mock-server) 中新增独立的征信解析路由、service 和配置文件，复用当前 FastAPI 应用和启动方式。
|
||||
|
||||
优点：
|
||||
|
||||
- 保持实现路径最短。
|
||||
- 复用现有工程基础设施和依赖。
|
||||
- 征信解析逻辑与现有 LSFX Mock 逻辑隔离，后续扩展清晰。
|
||||
|
||||
缺点：
|
||||
|
||||
- 需要增加少量模块文件和配置文件。
|
||||
|
||||
### 4.3 方案 C：全配置驱动
|
||||
|
||||
把 Excel 字段直接转换为运行时元数据，服务根据配置动态生成字段、校验和示例响应。
|
||||
|
||||
优点：
|
||||
|
||||
- 后续字段调整灵活。
|
||||
|
||||
缺点：
|
||||
|
||||
- 引入额外抽象，超出本次“最短路径实现”的边界。
|
||||
|
||||
## 5. 推荐方案
|
||||
|
||||
采用方案 B。
|
||||
|
||||
原因如下：
|
||||
|
||||
- 与用户确认的边界一致：直接扩展现有工程，不新建独立服务。
|
||||
- 可以在不影响已有 LSFX Mock 链路的前提下补齐征信解析能力。
|
||||
- 代码结构清晰，后续如果字段扩充或错误码增加，仍可局部修改。
|
||||
|
||||
## 6. 模块边界与目录设计
|
||||
|
||||
征信解析能力直接并入现有 [lsfx-mock-server](/Users/wkc/Desktop/ccdi/ccdi/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 成功响应
|
||||
|
||||
成功时统一返回：
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "成功",
|
||||
"payload": {
|
||||
"lx_header": {},
|
||||
"lx_debt": {},
|
||||
"lx_publictype": {}
|
||||
},
|
||||
"status_code": "0"
|
||||
}
|
||||
```
|
||||
|
||||
### 7.4 失败响应
|
||||
|
||||
失败时统一返回：
|
||||
|
||||
```json
|
||||
{
|
||||
"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` 建议字段结构如下：
|
||||
|
||||
```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 解析和过度设计，符合最短路径实现要求。
|
||||
Reference in New Issue
Block a user