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

2026-03-23 15:25:24 +08:00
parent 97b3783c53
commit 89fb2ff2cc
2 changed files with 153 additions and 0 deletions
--- a/docs/reports/implementation/2026-03-23-credit-parsing-mock-server-backend-record.md
+++ b/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 解析。
+- 未新增设计文档之外的征信接口。
+- 未引入运行时动态配置或管理页面。
--- a/docs/tests/records/2026-03-23-credit-parsing-mock-server-backend-verification.md
+++ b/docs/tests/records/2026-03-23-credit-parsing-mock-server-backend-verification.md
@@ -0,0 +1,108 @@
+# 征信解析 Mock Server 后端验证记录
+
+## 自动化验证
+
+### 1. Payload Service 红绿验证
+
+```bash
+cd lsfx-mock-server
+python3 -m pytest tests/test_credit_payload_service.py -v
+```
+
+- 首次执行结果：失败
+  - 原因：`services.credit_payload_service` 不存在
+- 实现后再次执行结果：通过
+
+### 2. 接口层红绿验证
+
+```bash
+cd lsfx-mock-server
+python3 -m pytest tests/test_credit_api.py -v
+```
+
+- 首次执行结果：失败
+  - 原因：`/xfeature-mngs/conversation/htmlEval` 尚未注册，返回 `404`
+- 实现后再次执行结果：通过
+
+### 3. 启动注册验证
+
+```bash
+cd lsfx-mock-server
+python3 -m pytest tests/test_startup.py -v
+```
+
+- 首次执行结果：失败
+  - 原因：主应用尚未注册征信解析路由
+- 实现后再次执行结果：通过
+
+### 4. 目标回归验证
+
+```bash
+cd lsfx-mock-server
+python3 -m pytest tests/test_credit_payload_service.py tests/test_credit_api.py tests/test_startup.py -v
+```
+
+- 结果：`10 passed`
+
+## 手工冒烟验证
+
+### 启动过程
+
+首次按设计默认端口 `8000` 冒烟时，发现本机已有其他 Python 进程占用 `8000`，`curl` 实际命中了外部已有服务而非当前 worktree 内的 Mock 服务。为避免环境噪音，本次手工验证改用 `18000` 端口前台启动当前应用：
+
+```bash
+cd lsfx-mock-server
+PORT=18000 python3 main.py
+```
+
+启动日志确认：
+
+- `Application startup complete.`
+- `Uvicorn running on http://0.0.0.0:18000`
+
+### 健康检查验证
+
+```bash
+curl -s http://127.0.0.1:18000/credit/health
+```
+
+返回结果：
+
+```json
+{"status":"healthy","service":"credit-mock"}
+```
+
+### 征信解析接口验证
+
+准备示例文件：
+
+```bash
+printf '<html></html>' > /tmp/sample-credit.html
+```
+
+执行请求：
+
+```bash
+curl -s -X POST http://127.0.0.1:18000/xfeature-mngs/conversation/htmlEval \
+  -F model=LXCUSTALL \
+  -F hType=PERSON \
+  -F file=@/tmp/sample-credit.html
+```
+
+返回结果要点：
+
+- `status_code` 为 `"0"`
+- `message` 为 `"成功"`
+- `payload` 包含 `lx_header`、`lx_debt`、`lx_publictype`
+- `lx_header.report_time` 为日期格式字符串
+- `lx_debt` 下 21 个字段、`lx_publictype` 下 6 个字段均已生成
+
+### 服务停止
+
+本次手工验证采用前台启动，验证完成后已通过 `Ctrl+C` 停止服务，确认未残留由本次验证启动的 Mock 进程。
+
+## 结论
+
+- 征信字段 schema 读取、稳定随机 payload 生成、错误码模拟、主应用路由注册均符合计划要求。
+- 自动化测试与手工冒烟验证均通过。
+- 本地环境存在外部进程占用 `8000` 的情况，但不影响当前实现正确性；本次已通过切换到空闲端口完成隔离验证。