crawler-plugin/docs/specs/12-testing-acceptance.md

12 测试、回归与验收

模块职责

定义后台 Vue 化的测试层次、跨后端契约回归、版本接口保护和最终删除验收。该 spec 不实现测试代码，只规定后续任务必须覆盖的行为。

依赖关系

上游：所有模块 spec；现有 backend-java Maven 测试体系；新 admin-frontend-vue 构建和测试命令。

相关现有测试/工具：

• backend-java/src/test/java 下的权限、控制器和契约测试。
• frontend-vue/tests 仅作为客户端工程参考，不得把后台测试混入客户端测试目录。
• 新后台测试放在 admin-frontend-vue/tests，Java 契约测试放在 backend-java/src/test/java。

核心接口\n\n测试对象包括菜单树、用户/权限 API、业务 API、公开版本接口、Nginx History 路由和 Flask 删除后的流量边界。\n\n## 内部结构\n\n验收分为前端静态检查、前端契约测试、Java API 契约测试、数据库迁移测试、真实 HTTP 验收和最终删除验收六层。\n\n## 类型映射\n\n测试夹具需要覆盖 AdminMenuNode、AdminUser、分页结果、任务状态、版本公开响应和空值响应。\n\n## 迁移/实现注意事项\n\n先冻结旧快照，再执行迁移和新实现回归；任何客户端版本接口差异都阻断 Flask 删除和 /admin 正式切换。\n\n## 测试层次

前端静态和类型检查

• Vue/TypeScript 类型检查零错误。
• Vite 构建成功，产出 dist/index.html 和所有 assets。
• 构建产物中的 base 路径全部为 /admin-vue/。
• 页面模块按路由拆 chunk。
• 工程不引用客户端 frontend-vue/new_web_source。

前端单元/契约测试

至少覆盖：

• 菜单树扁平节点组装为树。
• 分组节点无 route 时不可作为页面进入。
• 当前用户无菜单时展示空状态。
• 非超级管理员访问无权限 route 时跳到第一个有权限页面。
• 超级管理员可访问有效 admin 菜单。
• 401 跳转登录。
• API {data}、{item}、{items} 归一化。
• 分页字段边界、空列表、请求失败。
• 退出登录清理 Pinia 状态。
• 上传/导入/下载终态和重复点击保护。

Java API 契约测试

至少覆盖：

• /api/admin/current-user 返回当前用户的 item。
• /api/admin/current-user/menus 只返回有效 admin 菜单树。
• 树节点 key、route、name 和 parent-child 关系正确。
• 普通用户、管理员、超级管理员菜单不同且不越权。
• /api/version 字段为 version/desc/url。
• /api/version/latest 字段为 version/file_url。
• web_config 无记录返回两个 null。
• 多条版本记录按创建时间和 id 稳定取最新。
• 不带登录态访问需鉴权的 admin API 被拒绝。

Flyway/数据库测试

• 迁移后所有 admin 菜单 route_path 唯一。
• column_key 不被改写。
• 用户直接授权记录数量不减少。
• 父菜单授权的有效子菜单展开语义保持一致。
• 重复执行迁移不会产生重复菜单或重复授权。

Nginx/真实 HTTP 验收

• /admin 返回 302 到 /admin-vue/。
• /admin-vue/ 返回 HTML。
• /admin-vue/account/users 刷新仍返回 HTML。
• assets 正常返回正确 MIME。
• 不存在 assets 返回 404。
• /api/admin/current-user Cookie 能透传到 Java。
• /api/version/latest 在 Flask 停止后仍可访问。

迁移前后对比

必须保存以下快照：

• 旧后台每个角色可见菜单 key。
• 新菜单树每个角色可见菜单 key。
• 版本公开接口响应。
• 每个业务面板主要列表字段和分页语义。
• 关键导入/导出/下载错误场景。

允许变化：

• 菜单显示分组。
• Vue route path。
• 页面布局和交互流程。
• 前端组件实现。

不允许变化：

• 客户端版本接口路径和字段。
• 后端业务 API 路径，除非另有独立迁移决策。
• 用户菜单权限的实际范围。
• 数据删除、导入、导出和任务终态语义。

最终验收清单

1. admin-frontend-vue 构建和测试通过。
2. Java 编译、单测、契约测试通过。
3. Flyway 在测试库执行成功。
4. 17 个后台业务页面均有 Vue 对应页面或明确的验收记录。
5. /admin 已稳定重定向 /admin-vue/。
6. Nginx History 刷新和 assets 404 语义正确。
7. /api/version/latest 已完成真实客户端兼容验证。
8. Flask 管理页面和管理 API 已无生产流量。
9. 旧 admin.html、admin.js、admin-interactions.js 已删除。
10. 客户端 frontend-vue 和 new_web_source 未被后台工程污染。