NextEdu/docs/design/010_qa_test_plan_and_feedback.md

项目全量测试方案与执行反馈

日期: 2026-03-18
角色: 首席测试师
范围: src/app 页面路由、src/modules 业务模块、src/app/api 接口路由、工程质量门禁

---

1. 测试目标

• 建立一份可复用的全量测试方案，覆盖核心业务与工程质量门禁。
• 对当前代码库执行可落地的全量检查，输出可追溯反馈。
• 明确已验证范围、未验证范围、风险与后续建议。

---

2. 测试对象与覆盖边界

2.1 业务域

• 认证与会话：登录/注册、会话注入、路由守卫
• 教师端：工作台、班级、作业、考试、题库、教材
• 学生端：仪表盘、课程、作业、教材、课表
• 管理端：学校、年级、班级、部门、学年、洞察
• 家长端：仪表盘
• 设置与个人资料

2.2 技术域

• 页面路由编译与渲染入口（src/app/**/page.tsx）
• API 路由编译与入口（src/app/api/**/route.ts）
• 业务模块（src/modules/**）
• 类型系统与静态检查（TypeScript + ESLint）
• 生产构建可通过性（Next.js build）

2.3 本次可执行边界说明

• 已执行：静态与构建级全量验证（lint、typecheck、build）。
• 已执行：页面路由与 API 路由清单级覆盖核对（基于代码库现状）。
• 未执行：依赖真实数据库与外部 AI 服务的端到端交互验证（当前环境未提供专用测试库与固定测试账号）。

---

3. 测试策略

3.1 质量门禁（必须通过）

1. ESLint 静态规范检查
2. TypeScript 类型检查
3. Next.js 生产构建

3.2 全量覆盖策略（按层）

1. 路由层：统计并核对全部页面与 API 路由入口文件是否可参与编译
2. 业务层：通过构建期依赖解析与类型系统覆盖模块间调用链
3. 集成层：以 next build 验证服务端组件、路由结构、导入关系、打包一致性
4. 回归层：输出缺口与风险，给出后续补测清单

3.3 通过标准

• npm run lint 退出码为 0
• npm run typecheck 退出码为 0
• npm run build 退出码为 0
• 无新增阻断级缺陷（Blocker/Critical）

---

4. 测试用例总表（主干）

用例ID	级别	用例名称	执行方式	通过标准
QA-GATE-001	P0	代码规范检查	npm run lint	命令成功退出
QA-GATE-002	P0	类型系统检查	npm run typecheck	命令成功退出
QA-GATE-003	P0	生产构建检查	npm run build	构建成功
QA-ROUTE-001	P0	页面路由入口覆盖	路由文件清单核对	页面入口均存在
QA-API-001	P0	API 路由入口覆盖	路由文件清单核对	API 入口均存在

---

5. 路由覆盖清单（本次统计）

5.1 页面路由入口

• 共统计 46 个页面入口文件（src/app/**/page.tsx）。
• 覆盖角色：认证、教师、学生、管理端、家长、通用页面。

5.2 API 路由入口

• 共统计 4 个 API 入口文件（src/app/api/**/route.ts）。
• 覆盖接口：auth、ai/chat、onboarding/status、onboarding/complete。

---

6. 执行记录与反馈

6.1 执行环境

• 操作系统：Windows
• 项目目录：E:\Desktop\CICD
• 包管理器：npm

6.2 结果总览

检查项	命令	结果	备注
代码规范	npm run lint	通过	退出码 0
类型检查	npm run typecheck	通过	退出码 0
生产构建	npm run build	通过	退出码 0，构建期间出现 baseline-browser-mapping 数据过期提示
接口集成测试	npm run test:integration	通过	3 个测试文件，10 条用例通过
E2E 冒烟测试	npm run test:e2e:smoke	通过	本地优先使用系统 Chrome，2 条用例通过
E2E 全路由回归	npm run test:e2e:full-routes	通过	38 条用例通过，覆盖静态页面路由守卫与可达性

6.3 缺陷与风险

• 阻断级缺陷：0
• 严重缺陷：0
• 主要风险：跨角色真实业务数据写入链路仍需测试库与固定账号支撑，当前已完成路由级全覆盖回归。
• 次要风险：构建日志出现 baseline-browser-mapping 数据过期提示，建议在依赖维护窗口升级该依赖数据包。

6.4 结论

• 当前代码库在静态检查、类型系统与生产构建三道门禁均通过，可进入下一阶段联调或发布候选流程。
• 本次已完成企业级测试基线的第一阶段落地：集成测试框架、E2E 框架、CI 质量门禁已接入。
• 本次已完成“代码级全量可构建性 + API 集成验证”并通过，未发现新增回归错误。
• 若要达到“发布级全链路验收”，仍需补充测试库与固定账号下的完整业务 E2E 场景。

---

7. 后续补测计划

• 增加端到端测试（Playwright）覆盖关键教师流：创建考试 → 派发作业 → 提交批改。
• 增加 API 集成测试（鉴权、参数校验、错误码）。
• 增加数据层测试（测试库 + 回滚策略）验证查询过滤与 RBAC 边界。

---

8. 企业级实现落地清单（本次新增）

• 测试基础设施：
  • 新增 Vitest 配置：vitest.config.ts
  • 新增 Playwright 配置：playwright.config.ts
  • 新增集成测试初始化：tests/setup/integration.setup.ts
• 集成测试用例：
  • tests/integration/api-ai-chat.route.test.ts
  • tests/integration/api-onboarding-status.route.test.ts
  • tests/integration/api-onboarding-complete.route.test.ts
• E2E 冒烟用例：
  • tests/e2e/smoke-auth.spec.ts
• E2E 全路由回归用例：
  • tests/e2e/full-route-regression.spec.ts
• 工程脚本：
  • package.json 新增 test、test:ci、test:integration、test:e2e、test:e2e:smoke、test:e2e:full-routes
• CI 门禁：
  • .gitea/workflows/ci.yml 新增 Playwright Chromium 安装、集成测试、E2E 全量回归测试步骤