ccdi/docs/reports/implementation/2026-03-23-credit-parsing-mock-server-backend-record.md

征信解析 Mock Server 后端实施记录

本次改动

• 新增 credit_feature_schema.json，将 Excel 中 30 个征信字段按 lx_header、lx_debt、lx_publictype 三个主题域固化为 schema，并统一映射到 string、amount、count、status 四类生成规则。
• 新增 credit_response_examples.json，沉淀成功模板和 ERR_99999、ERR_10001 至 ERR_10006 的失败模板。
• 新增 credit_payload_service.py，负责加载 schema，并基于 model + hType + filename 生成稳定随机 payload。
• 新增 credit_debug_service.py，负责参数缺失校验、调试错误码识别、成功/失败响应封装。
• 新增 credit_api.py，提供：
  • POST /xfeature-mngs/conversation/htmlEval
  • GET /credit/health
• 更新 main.py，将征信解析 router 注册到主应用，并补充应用描述。
• 更新 README.md，补充征信解析 Mock 的调用示例、错误码调试方式和健康检查说明。
• 新增测试文件 test_credit_payload_service.py、test_credit_api.py，并补充 test_startup.py 的路由注册断言。

实现说明

稳定随机策略

• 随机种子固定为 model|hType|filename。
• 同一组输入重复调用时，payload 全量字段保持一致。
• amount 输出为非负两位小数字符串。
• count 输出为非负整数字符串。
• status 严格从 schema 的 options 中选值，当前统一为 正常、逾期、不良。
• string 类型按字段语义生成：
  • query_cert_no：身份证号样式字符串
  • query_cust_name：中文姓名样式字符串
  • report_time：YYYY-MM-DD

说明书歧义处理

• 设计文档中已指出 hType 参数表写明只支持 PERSON/ENTERPRISE，但错误码 ERR_10003 的文案仍保留“仅支持JSON/XML”。
• 本次实现按参数表校验真实取值范围，只要 hType 不在 PERSON/ENTERPRISE 内，就返回 ERR_10003，同时保留说明书原始错误文案不改写。

接口行为

• 接口层所有表单参数均使用 Form(None) / File(None) 接收，避免缺参时被 FastAPI 直接转换成 422。
• 缺参、非法主题域、非法 hType、调试错误码场景统一返回 {message, payload, status_code} 结构。
• 调试错误码通过 model 中包含 error_ERR_10001 这类标记触发。

未包含内容

• 未实现真实 HTML 解析。
• 未新增设计文档之外的征信接口。
• 未引入运行时动态配置或管理页面。