admin
8de3a12dc1
- Remove the super-admin one-time migration from browser local settings into backend AI and speech settings. - Delete the migration-specific SystemSettings unit test that no longer matches the desired behavior. - Restore feature, module, testing, and progress docs so settings secrets are documented as backend-managed only.
115 lines
8.4 KiB
Markdown
115 lines
8.4 KiB
Markdown
# 测试文档
|
||
|
||
## 测试命令
|
||
|
||
```bash
|
||
npm run lint
|
||
npm run test
|
||
npm run test:e2e
|
||
npm run server:build
|
||
npm run build
|
||
```
|
||
|
||
当前单元/组件测试框架为 Vitest，运行环境为 jsdom。React 页面测试使用 Testing Library。端到端测试使用 Playwright，当前会启动/复用 Vite 前端和 NestJS 后端，并通过真实 Auth/Reports/Templates/Users/Audit API 准备数据。后端使用 Vitest 覆盖权限策略、schema、DTO 映射、Nest HTTP 层集成测试和真实 PostgreSQL 服务集成测试，NestJS API 构建用 `npm run server:build` 验证。
|
||
|
||
## 测试范围
|
||
|
||
| 范围 | 当前覆盖 |
|
||
| --- | --- |
|
||
| 数据初始化 | 登录页首次加载会创建默认用户、模板、字段和系统设置。 |
|
||
| 前端 API client | 统一解包 `{ data }` 响应、携带 Cookie credentials、识别后端错误 envelope。 |
|
||
| 前端 Dashboard API | 工作台统计封装会请求 `/api/dashboard/stats` 并校验响应结构。 |
|
||
| 前端审计 API | 审计日志列表封装会请求 `/api/audit-logs` 并校验响应结构。 |
|
||
| 前端语音代理地址 | 根据当前页面来源或 `VITE_API_BASE_URL` 生成 `/api/speech/iat` WebSocket 地址。 |
|
||
| 前端字段库和文件 API | 字段库读取/更新、通用文件列表/上传封装。 |
|
||
| Auth 兼容映射 | 后端 `doctor` 角色会映射为当前前端使用的 `user`，并保留本地签名和模板授权。 |
|
||
| 权限展示 | 侧边栏和路由守卫会按角色显示或阻止模板管理、用户管理、审计日志等入口。 |
|
||
| 报告权限 | 医生只看到本人报告，管理员看到本部门报告，超级管理员看到全部后端报告。 |
|
||
| 后端报告映射 | Report API 使用 `metadata` 兼容前端扩展字段，使用 `ReportMedia` 组装视频/关键帧兼容字段。 |
|
||
| 模板权限 | 医生可使用本部门授权模板和个人模板，不能使用他人个人模板。 |
|
||
| 后端模板映射 | Template API 返回前端可消费的 `Template` 结构，并生成权限策略资源。 |
|
||
| 后端用户映射 | Users API 返回前端可消费的 `User` 结构，并把部门模板授权映射成 `visibleTemplates/manageableTemplates`。 |
|
||
| 后端设置校验 | Settings API 使用 schema 校验抽帧、AI Provider 和语音配置。 |
|
||
| 后端 AI 代理入参 | AI Proxy 使用 schema 校验 OpenAI 兼容消息和多模态内容。 |
|
||
| 后端语音代理帧处理 | Speech Proxy 对首个讯飞 IAT 音频帧补齐 APPID 和默认业务参数，后续帧保持兼容。 |
|
||
| 后端字段库和文件 schema | Library/Files API 校验字段库和通用文件上传 payload。 |
|
||
| 后端 HTTP 集成 | Nest HTTP 层覆盖 API prefix、登录会话、未登录保护、受保护接口 actor 传递。 |
|
||
| 后端真实数据库集成 | 使用 Prisma/PostgreSQL 覆盖 Auth、Dashboard、Reports、ReportMedia、Templates、Files、HTML 清洗和审计核心服务。 |
|
||
| 存储封装 | 常规 JSON 存储、`systemSettings` 混淆、历史明文兼容、session 恢复键。 |
|
||
| 默认模板契约 | 智能字段、图片占位符、AI 区域、默认字段和 AI Provider 配置。 |
|
||
| 打印入口 | `printDocument` 会创建隐藏 iframe、写入报告 HTML 并调用浏览器打印。 |
|
||
| E2E 登录流程 | Playwright 验证默认快捷登录进入工作台。 |
|
||
| E2E 权限过滤 | Playwright 验证超级管理员、管理员、医生在报告管理页的可见范围。 |
|
||
| E2E 报告修订 | Playwright 验证已完成报告再次完成保存后 `revision` 递增并保留历史。 |
|
||
| E2E 个人模板 | Playwright 验证医生可保存个人模板且模板仅归属本人。 |
|
||
| E2E 路由守卫和审计日志 | Playwright 验证医生不能直进管理页，超级管理员可查看审计日志。 |
|
||
| 后端权限策略 | Vitest 验证报告、模板、用户和管理员创建权限策略。 |
|
||
|
||
## Mock 边界
|
||
|
||
测试中 mock 了以下浏览器或外部边界：
|
||
|
||
- `fetch('/logo_square.png')`：用于登录初始化图片资源。
|
||
- `/api/auth/me`、`/api/auth/login`：组件测试中使用 mock，避免单元测试依赖真实数据库；Playwright E2E 使用真实后端 API。
|
||
- `window.alert` / `window.confirm`：避免测试阻塞。
|
||
- `document.execCommand`：当前富文本编辑依赖浏览器命令。
|
||
- `URL.createObjectURL` / `URL.revokeObjectURL`：用于文件、视频和导出。
|
||
- iframe `contentWindow.print`：用于验证打印入口，不生成真实 PDF。
|
||
|
||
AI 第三方接口、讯飞语音上游 WebSocket、麦克风权限和真实视频 canvas 抽帧没有在自动化测试中直连，原因是它们依赖第三方服务、硬件权限或真实媒体解码。AI 代理已有 schema 测试，语音代理已有首帧处理测试，后续应增加隔离测试密钥的 HTTP/WebSocket 集成测试。
|
||
|
||
## 测试清单
|
||
|
||
| 功能 | 测试状态 | 说明 |
|
||
| --- | --- | --- |
|
||
| 登录默认数据初始化 | 已覆盖 | `Login.test.tsx` |
|
||
| 后端登录禁用账号错误 | 已覆盖 | `Login.test.tsx` |
|
||
| API client 响应/错误处理 | 已覆盖 | `api/client.test.ts` |
|
||
| Dashboard API 封装 | 已覆盖 | `api/dashboard.test.ts` |
|
||
| 审计日志 API 封装 | 已覆盖 | `api/audit.test.ts` |
|
||
| 语音 WebSocket 代理地址 | 已覆盖 | `api/speech.test.ts` |
|
||
| 字段库 API 封装 | 已覆盖 | `api/library.test.ts` |
|
||
| 通用文件 API 封装 | 已覆盖 | `api/files.test.ts` |
|
||
| 后端用户到前端用户映射 | 已覆盖 | `auth/backendUser.test.ts` |
|
||
| 角色菜单权限 | 已覆盖 | `Sidebar.test.tsx` |
|
||
| 报告列表角色过滤 | 已覆盖 | `ReportManage.test.tsx` |
|
||
| 报告权限工具 | 已覆盖 | `permissions.test.ts` |
|
||
| 模板权限和个人模板 | 已覆盖 | `permissions.test.ts` |
|
||
| 本地存储读写与容错 | 已覆盖 | `storage.test.ts` |
|
||
| 系统设置混淆兼容 | 已覆盖 | `storage.test.ts` |
|
||
| 默认报告模板结构 | 已覆盖 | `defaultContent.test.ts` |
|
||
| 默认字段和 AI Provider | 已覆盖 | `defaultContent.test.ts` |
|
||
| 打印导出入口 | 已覆盖 | `print.test.ts` |
|
||
| 默认快捷登录 | 已覆盖 | `e2e/login.spec.ts` |
|
||
| 报告权限 E2E | 已覆盖 | `e2e/report-permissions.spec.ts` |
|
||
| 报告修订版本 E2E | 已覆盖 | `e2e/report-revision.spec.ts` |
|
||
| 医生个人模板 E2E | 已覆盖 | `e2e/personal-template.spec.ts` |
|
||
| 路由守卫和审计日志 E2E | 已覆盖 | `e2e/audit-and-route-guards.spec.ts` |
|
||
| 后端报告/模板/用户权限策略 | 已覆盖 | `server/src/permissions/permissions.policy.test.ts` |
|
||
| 后端报告兼容映射 | 已覆盖 | `server/src/reports/report.mapper.test.ts` |
|
||
| 后端模板兼容映射 | 已覆盖 | `server/src/templates/template.mapper.test.ts` |
|
||
| 后端用户兼容映射 | 已覆盖 | `server/src/users/users.mapper.test.ts` |
|
||
| 后端系统设置 schema | 已覆盖 | `server/src/settings/settings.schemas.test.ts` |
|
||
| 后端 AI 代理 schema | 已覆盖 | `server/src/ai/ai.schemas.test.ts` |
|
||
| 后端语音代理首帧处理 | 已覆盖 | `server/src/speech/xf-frame.test.ts` |
|
||
| 后端字段库 schema | 已覆盖 | `server/src/library/library.schemas.test.ts` |
|
||
| 后端文件 schema | 已覆盖 | `server/src/files/files.schemas.test.ts` |
|
||
| 后端 HTTP 集成 | 已覆盖 | `server/src/http.integration.test.ts` |
|
||
| 后端真实数据库集成 | 已覆盖 | `server/src/database.integration.test.ts`，含 Dashboard 角色范围、报告媒体关系表同步、报告 HTML 清洗、审计写入和审计查询权限。 |
|
||
| 后端健康检查和认证 API | 已覆盖 | HTTP 集成测试覆盖健康检查、登录 session 和未登录保护；真实数据库集成覆盖 Argon2 登录、禁用账号和数据库 Session Store。 |
|
||
| 模板编辑器深度交互 | 待 E2E | 依赖 contentEditable 和 execCommand。 |
|
||
| 报告编辑器完整流程 | 部分覆盖 | 已覆盖保存修订版本和个人模板；模板切换、字段同步仍待补。 |
|
||
| 视频抽帧 | 待 E2E/人工 | 依赖真实视频解码和 canvas。 |
|
||
| AI 撰写 | 待集成测试 | 需要隔离外部模型服务。 |
|
||
| 讯飞语音听写 | 部分覆盖/待集成测试 | 已覆盖后端首帧处理；完整链路仍需要 WebSocket 集成测试、麦克风权限和测试凭证。 |
|
||
|
||
## Playwright 说明
|
||
|
||
首次运行如果提示浏览器缺失，执行：
|
||
|
||
```bash
|
||
npx playwright install chromium
|
||
```
|
||
|
||
当前 E2E 测试依赖真实后端数据库。Playwright 会在 `3100` 端口启动后端 API，执行 Prisma migrate/seed，然后在 `3001` 启动 Vite，并把 `/api` 代理到 `3100`。`e2e/helpers.ts` 通过真实 API 登录、创建用户/部门/报告和查询模板，不再写入 localStorage 种子数据。
|