补充征信解析Mock后端实施与验证记录

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

@@ -0,0 +1,45 @@
+# 征信解析 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 解析。
+- 未新增设计文档之外的征信接口。
+- 未引入运行时动态配置或管理页面。