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

## 本次改动

- 新增 [`credit_feature_schema.json`](/Users/wkc/Desktop/ccdi/ccdi/.worktrees/codex-credit-parsing-mock-server-backend/lsfx-mock-server/config/credit_feature_schema.json)，将 Excel 中 30 个征信字段按 `lx_header`、`lx_debt`、`lx_publictype` 三个主题域固化为 schema，并统一映射到 `string`、`amount`、`count`、`status` 四类生成规则。
- 新增 [`credit_response_examples.json`](/Users/wkc/Desktop/ccdi/ccdi/.worktrees/codex-credit-parsing-mock-server-backend/lsfx-mock-server/config/credit_response_examples.json)，沉淀成功模板和 `ERR_99999`、`ERR_10001` 至 `ERR_10006` 的失败模板。
- 新增 [`credit_payload_service.py`](/Users/wkc/Desktop/ccdi/ccdi/.worktrees/codex-credit-parsing-mock-server-backend/lsfx-mock-server/services/credit_payload_service.py)，负责加载 schema，并基于 `model + hType + filename` 生成稳定随机 payload。
- 新增 [`credit_debug_service.py`](/Users/wkc/Desktop/ccdi/ccdi/.worktrees/codex-credit-parsing-mock-server-backend/lsfx-mock-server/services/credit_debug_service.py)，负责参数缺失校验、调试错误码识别、成功/失败响应封装。
- 新增 [`credit_api.py`](/Users/wkc/Desktop/ccdi/ccdi/.worktrees/codex-credit-parsing-mock-server-backend/lsfx-mock-server/routers/credit_api.py)，提供：
  - `POST /xfeature-mngs/conversation/htmlEval`
  - `GET /credit/health`
- 更新 [`main.py`](/Users/wkc/Desktop/ccdi/ccdi/.worktrees/codex-credit-parsing-mock-server-backend/lsfx-mock-server/main.py)，将征信解析 router 注册到主应用，并补充应用描述。
- 更新 [`README.md`](/Users/wkc/Desktop/ccdi/ccdi/.worktrees/codex-credit-parsing-mock-server-backend/lsfx-mock-server/README.md)，补充征信解析 Mock 的调用示例、错误码调试方式和健康检查说明。
- 新增测试文件 [`test_credit_payload_service.py`](/Users/wkc/Desktop/ccdi/ccdi/.worktrees/codex-credit-parsing-mock-server-backend/lsfx-mock-server/tests/test_credit_payload_service.py)、[`test_credit_api.py`](/Users/wkc/Desktop/ccdi/ccdi/.worktrees/codex-credit-parsing-mock-server-backend/lsfx-mock-server/tests/test_credit_api.py)，并补充 [`test_startup.py`](/Users/wkc/Desktop/ccdi/ccdi/.worktrees/codex-credit-parsing-mock-server-backend/lsfx-mock-server/tests/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 解析。
- 未新增设计文档之外的征信接口。
- 未引入运行时动态配置或管理页面。