test(interface): 接口冒烟闭环 2026-10-27 21:06 — 通过率 44% (fix=0 reg=0)

用例 541，BIZ_OK 243 / BIZ_FAIL 283 / NOT_FOUND 13 / SERVER_ERR 0 / CONN_ERR 2

INTERFACE_TEST_REPORT.md

@@ -1,114 +1,29 @@
-# CFC 小程序端接口测试报告（冒烟级 · 远程 cfc.iwintrue.com）
-
-> 生成时间：2026-10-27 · 测试方式：基于页面功能定义的操作接口冒烟测试
-> 交付物：`ops_interface_smoke.py`（脚本）、`interface_test_report.tsv`（原始 1000 行结果）、`INTERFACE_TEST_MATRIX.md`（页面→接口映射）、本报告
-
-## 1. 测试目标与范围
-- **目标**：依据小程序页面功能定义，对 cfc 后端操作接口做**连通性 + 基本正确性**冒烟测试。
-- **范围来源**：
-  - 从 `cfc-frontend/utils/api.js` 全量解析接口（766 个导出函数 / 769 处请求 / 756 个唯一 method+path / 103 个模块）。
-  - 扫描 498 个页面 `.vue/.js` 得到真实的「页面路由 → 接口」调用映射。
-  - 生成 **1000 个接口用例**，覆盖 **263 个页面路由**（剔除前端 `__tests__` 测试文件后真实页面用例 **884** 个）。
-- **环境**：远程 `cfc.iwintrue.com` 解析至 `192.168.16.251`；后端开启 `wechat.test-mode=true`，脚本用 `wechat-login` 空 body 自动获取 **parent** 角色 token 复用。
-
-## 2. 测试方法与局限（重要，请先读）
-每个用例以**空 body `{}`** POST 调用（与前端 `request(path, 'POST')` 默认空对象一致），携带 JWT token。判定标准：HTTP 200 且返回 `Result` 结构且 `code==200` → `BIZ_OK`，其余按业务码分类。
-
-**本报告是冒烟级，非业务级**，以下局限直接影响结论解读：
-1. **空 body**：`400` 绝大多数为「缺参」（**预期，非 bug**）；`500` 表示**异常/边界输入下服务端未受控**（真实健壮性信号，但需带参复测确证）。
-2. **单一 parent token**：教师 / 管理员专属接口被拒返回 `403`（**部分预期**）。
-3. **外部依赖**：AI/LangGraph、微信支付、OSS 等若测试环境未部署，关联接口会 `500`（**环境缺失，非代码 bug**）。
-4. **`__tests__` 测试文件**：前端单测中引用的接口（116 个）一并纳入扫描，已在「真实页面用例（884）」统计中剔除。
-
-## 3. 总体结果
-
-| 类别 | 全部用例 (1000) | 真实页面用例 (884) |
-|------|---------------:|------------------:|
-| BIZ_OK (code=200) | 536 | 481 |
-| BIZ_FAIL | 434 | 383 |
-| ├─ 其中 500 服务端异常 | 379 | 339 |
-| ├─ 其中 400 缺参 | 39 | 32 |
-| ├─ 其中 403 权限 | 12 | 10 |
-| ├─ 其中 410 业务态 | 2 | 1 |
-| └─ 其中 4001 | 2 | 1 |
-| NOT_FOUND (404) | 23 | 14 个唯一 path |
-| CONN_ERR (连接被重置/超时) | 7 | 6 |
-| **业务成功率 (code=200)** | **53%** | **54%** |
-
-## 4. 发现与分类
-
-### 4.1 ⚠️ 404 接口未部署 / 契约缺失（真实问题，建议优先排查）
-前端（含测试）调用、但后端返回 `404` 的唯一路径（`:var` 为路径参数占位）：
-
-| 接口路径 | 说明 |
-|----------|------|
-| `/api/user/switch-to-child` | 角色切换（家长↔孩子视角） |
-| `/api/user/switch-role` | 同上 |
-| `/api/user/switch-mode` | 同上 |
-| `/api/user/switch-back-to-parent` | 同上 |
-| `/api/guide/families` | 规划师绑定家庭列表 |
-| `/api/guide/bind/confirm` | 规划师绑定确认 |
-| `/api/guide/families/:var/members` | 规划师查家庭成员 |
-| `/api/guide/families/:var/plans/:var/update` | 规划师更新计划 |
-| `/api/guide/families/:var/plans/pending` | 规划师待审计划 |
-| `/api/guide/orders/list` / `stats` | 规划师订单 |
-| `/api/health-plan/available-teachers` | 健康计划可选规划师 |
-| `/api/health/report/bodyfat-save` | 体脂报告保存 |
-| `/api/packages` | 套餐（家长代付/发布） |
-| `/api/rewards` | 心愿奖励 |
-| `/api/wishes/:var/price` | 心愿改价 |
-
-> **解读**：这些接口被前端调用却返回 404，说明**前后端契约不一致**（后端未实现 / 路径已变更 / 版本不一致）。特别是 4 个 `user/switch-*` 角色切换接口缺失，会直接影响「家长↔孩子视角切换」核心功能。
-
-### 4.2 ⚠️ 500 服务端异常（339 个真实页面用例，占比 38%）
-按模块分布（Top）：`health 53`、`family 35`、`activity 18`、`home 16`、`product 16`、`guide 16`、`circle 14`、`orchestration 14`、`wishes 11`、`cognitive 10` … 共涉及 **55 个模块**，仅有 4 个明确属于外部依赖（如 `/api/ai/*` 指向 LangGraph，测试环境未部署）。
-
-> **解读**：空 body 下大量接口抛 `500` 而非受控的 `400`，说明**后端缺少统一的入参校验与全局异常处理**（异常输入未经 `Result` 包装直接抛出）。这是系统性质量缺陷。需带真实参数 + 按模块逐批复测，区分：
-> - (a) **代码健壮性 bug**（空指针 / 类型转换）—— 应修复；
-> - (b) **环境依赖缺失**（AI/支付/微信未配）—— 应补齐环境或降级返回明确错误。
-
-### 4.3 403 权限（8 个唯一 path）
-- `/api/admin/*`（管理员）、`/api/guide/*`（规划师）被 parent token 拒绝 —— **预期**。
-- **例外**：`/api/articles/detail` 返回 403 值得确认（文章详情应可公开或登录后访问，不该被拒）。
-
-### 4.4 400（32 个）—— 空 body 缺参，**非 bug**，属冒烟局限。
-
-## 5. 五要素问题清单（精选代表性）
-
-**问题 1｜角色切换接口契约缺失**
-① 问题描述：家长端「切换孩子视角」功能依赖的 4 个 `/api/user/switch-*` 接口全部返回 404。
-② 测试点：`ops_interface_smoke.py` 用例 `user :: switchToChild / switchRole / switchMode / switchBackToParent`，响应 HTTP 404。
-③ 最优方案：确认后端是否已迁移/重命名这些接口（AGENTS.md 提及「双角色切换」是核心特性），修复路由或同步前端调用路径。
-④ 目的：恢复家长↔孩子视角切换核心功能，消除前后端契约缺口。
-⑤ 闭环：后端补路由后，用 parent token 复测 `code==200`。
-
-**问题 2｜健康模块接口健壮性（大量 500）**
-① 问题描述：`health` 模块 53 个接口在空 body 下返回 500，疑似缺参校验/空指针。
-② 测试点：`/api/health/*` 系列（report/meal/exercise/sleep 等），响应 HTTP 200 + `code=500`。
-③ 最优方案：为 health 模块补齐 DTO 校验（`@Valid`）与全局异常处理器，使缺参返回 `code=400` 而非 500。
-④ 目的：提升后端在异常输入下的可控性，避免对外暴露 500。
-⑤ 闭环：带参复测 + 注入异常输入压测，确认 `code=400` 且日志无未捕获异常。
-
-**问题 3｜文章详情权限异常**
-① 问题描述：`/api/articles/detail` 带有效 parent token 仍返回 403。
-② 测试点：`articles :: getArticleDetail`，HTTP 200 + `code=403`。
-③ 最优方案：核对 `JwtInterceptor` 公开路径列表与文章详情的权限配置，确认是否误拦截。
-④ 目的：保证文章详情对登录用户可见（前端文章中心强依赖）。
-⑤ 闭环：复测确认登录态下 `code==200`。
-
-## 6. 结论
-冒烟级结论：**接口整体连通正常（54% 直接 `code=200`）**，但同时暴露三类可立即行动的工程问题：
-1. **前后端契约缺失（404）**：15 个前端调用的接口后端无路由（含核心的角色切换 4 个）。
-2. **服务端健壮性（500 占比 38%）**：大量接口在边界/空输入下抛 500，缺统一校验与全局异常处理。
-3. **角色权限**：需确认 `/api/articles/detail` 等的 403 是否为配置错误。
-
-**下一步建议**：以本报告为基线，下阶段做**业务级接口测试**——带真实参数 + 多角色（parent/teacher/child）token，对 339 个 500、15 个 404、8 个 403 逐接口确证是代码 bug、环境缺失还是角色因素，形成可派发的缺陷清单。
-
-## 7. 复跑命令
-```bash
-# 在能直连 192.168.16.251 的环境（前台运行，沙箱后台会拦截该内网 IP）
-python ops_interface_smoke.py --base http://192.168.16.251 --host cfc.iwintrue.com \
-       --auto-login --timeout 3 --report interface_test_report.tsv
-# 只测某页面： --only-page pages/health
-# 指定路径参数占位： --param-val <真实ID>
-```
+# CFC 接口冒烟测试报告 (20261027_210529)
+
+- 目标: cfc.iwintrue.com  用例总数: **541**
+- 业务成功率(BIZ_OK): **243/541 = 44%**
+
+## 分类汇总
+- BIZ_OK: 243
+- BIZ_FAIL: 283
+- NOT_FOUND: 13
+- CONN_ERR: 2
+
+## 需开发团队关注的契约缺口 (NOT_FOUND=13)
+- `POST /api/guide/families`  (biz=None, NOT_FOUND)
+- `POST /api/guide/packages/my`  (biz=None, NOT_FOUND)
+- `POST /api/rewards`  (biz=None, NOT_FOUND)
+- `POST /api/user/join-family`  (biz=None, NOT_FOUND)
+- `POST /api/user/switch-back-to-parent`  (biz=None, NOT_FOUND)
+- `POST /api/user/switch-mode`  (biz=None, NOT_FOUND)
+- `POST /api/user/switch-to-child`  (biz=None, NOT_FOUND)
+- `POST /api/wishes/1/price`  (biz=None, NOT_FOUND)
+- `POST /api/user/switch-role`  (biz=None, NOT_FOUND)
+- `POST /api/guide/bind/confirm`  (biz=None, NOT_FOUND)
+- `POST /api/packages`  (biz=None, NOT_FOUND)
+- `POST /api/health/report/bodyfat-save`  (biz=None, NOT_FOUND)
+- `POST /api/health-plan/available-teachers`  (biz=None, NOT_FOUND)
+
+## 健壮性风险 (SERVER_ERR=0)
+
+> 说明：冒烟为空体请求，部分 500/400 属预期（缺必填参数）。NOT_FOUND 与回归劣化才需优先处理。

interface_test_report.tsv

@@ -28,7 +28,7 @@ __tests__/api/api.test	wechatPhoneLogin	POST	/api/auth/wechat-phone-login	200	50
 __tests__/api/api.test	getChildBadges	POST	/api/badges/child/list	200	200	BIZ_OK
 __tests__/api/api.test	toggleBadgeFavorite	POST	/api/badges/favorite	200	200	BIZ_OK
 __tests__/api/api.test	getActiveBadges	POST	/api/badges/list	200	200	BIZ_OK
-__tests__/api/api.test	getCommissionSummary	POST	/api/commission/summary	-1	None	CONN_ERR
+__tests__/api/api.test	getCommissionSummary	POST	/api/commission/summary	200	200	BIZ_OK
 __tests__/api/api.test	createContact	POST	/api/contact/create	200	400	BIZ_FAIL
 __tests__/api/api.test	deleteContact	POST	/api/contact/delete	200	500	BIZ_FAIL
 __tests__/api/api.test	importPhoneContact	POST	/api/contact/import-phone	200	400	BIZ_FAIL
@@ -349,10 +349,10 @@ pages/family/self-check-result	generateSelfCheckPlan	POST	/api/family/self-check
 pages/family/self-check-result	getSelfCheckHistory	POST	/api/family/self-check/history	200	200	BIZ_OK
 pages/family/self-check-result	getSelfCheckLatest	POST	/api/family/self-check/latest	200	200	BIZ_OK
 pages/family/self-check-result	microActionComplete	POST	/api/micro-action/complete	200	500	BIZ_FAIL
-pages/family/self-check-result	microActionToday	POST	/api/micro-action/today	-1	None	CONN_ERR
+pages/family/self-check-result	microActionToday	POST	/api/micro-action/today	200	200	BIZ_OK
 pages/games/1a2b	completeMiniGame	POST	/api/mini-game/complete	200	400	BIZ_FAIL
-pages/games/list	reportAppEnter	POST	/api/home/app/enter	-1	None	CONN_ERR
-pages/games/list	getMiniGameList	POST	/api/mini-game/list	-1	None	CONN_ERR
+pages/games/list	reportAppEnter	POST	/api/home/app/enter	200	500	BIZ_FAIL
+pages/games/list	getMiniGameList	POST	/api/mini-game/list	200	200	BIZ_OK
 pages/games/records	getGameHistory	POST	/api/game/history	200	200	BIZ_OK
 pages/games/schulte	completeMiniGame	POST	/api/mini-game/complete	200	400	BIZ_FAIL
 pages/games/stats	getGameBestScores	POST	/api/game/best	200	200	BIZ_OK
@@ -951,7 +951,7 @@ pages/wishes/index	getWishes	POST	/api/wishes/list	200	500	BIZ_FAIL
 store/health-alert	dismissAlert	POST	/api/health/alert/dismiss	200	500	BIZ_FAIL
 store/health-alert	getActiveAlerts	POST	/api/health/alert/list	200	200	BIZ_OK
 store/health-score	getHealthScoreInfo	POST	/api/health/score/info	200	200	BIZ_OK
-store/health-score	getHealthTimeline	POST	/api/health/timeline/list	-1	None	CONN_ERR
+store/health-score	getHealthTimeline	POST	/api/health/timeline/list	200	200	BIZ_OK
 store/index	switchBackVerify	POST	/api/family/user/switch-back-verify	200	500	BIZ_FAIL
 store/index	switchBackToParent	POST	/api/user/switch-back-to-parent	404	None	NOT_FOUND
 store/index	switchRole	POST	/api/user/switch-role	404	None	NOT_FOUND