# 测试文档

## 测试命令

```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 地址。 |
| 前端语音 PCM 处理 | 麦克风浮点音频会按实际采样率重采样为 16k、编码为 16bit PCM，并按小帧拼接发送给讯飞代理。 |
| 前端字段库和文件 API | 字段库读取/更新、通用文件列表/上传封装。 |
| Auth 兼容映射 | 后端 `doctor` 角色会映射为当前前端使用的 `user`，并保留本地签名和模板授权。 |
| 权限展示 | 侧边栏和路由守卫会按角色显示或阻止模板管理、用户管理、审计日志等入口。 |
| 报告权限 | 医生只看到本人报告，管理员看到本部门报告，超级管理员看到全部后端报告。 |
| 后端报告映射 | Report API 使用 `metadata` 兼容前端扩展字段，使用 `ReportMedia` 组装视频/关键帧兼容字段。 |
| 后端报告 schema | 创建/更新报告时允许草稿暂缺患者姓名和住院号，但完成报告必须包含患者姓名和住院号。 |
| 模板权限 | 医生可使用本部门授权模板和个人模板，不能使用他人个人模板。 |
| 后端模板映射 | Template API 返回前端可消费的 `Template` 结构，并生成权限策略资源。 |
| 后端用户映射 | Users API 返回前端可消费的 `User` 结构，并把部门模板授权映射成 `visibleTemplates/manageableTemplates`。 |
| 后端设置校验 | Settings API 使用 schema 校验抽帧、AI Provider 和语音配置。 |
| 后端 AI 代理入参和错误处理 | AI Proxy 使用 schema 校验 OpenAI 兼容消息和多模态内容；上游 429/5xx 会短暂重试，并保留上游状态与 AI 专用错误码。 |
| 后端语音代理帧处理 | 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 报告 AI 区域同步 | Playwright 验证报告编辑器中新插入的 AI 可编辑区域会立即出现在 AI 撰写目标下拉栏。 |
| E2E 个人模板 | Playwright 验证医生可保存个人模板且模板仅归属本人。 |
| 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` |
| 语音 PCM 重采样和编码 | 已覆盖 | `utils/audioPcm.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` |
| 抽帧百分比工具 | 已覆盖 | `framePositions.test.ts`，覆盖两位小数、保序和按时间生成截图计划。 |
| 默认报告模板结构 | 已覆盖 | `defaultContent.test.ts` |
| 默认字段和 AI Provider | 已覆盖 | `defaultContent.test.ts` |
| AI 区域扫描工具 | 已覆盖 | `aiRegions.test.ts`，覆盖从编辑器 HTML 识别 `.ai-region` 和标题。 |
| 打印导出入口 | 已覆盖 | `print.test.ts` |
| 模板列表合并工具 | 已覆盖 | `templateList.test.ts`，防止新增模板被旧本地缓存覆盖。 |
| 模板导入导出工具 | 已覆盖 | `templateExport.test.ts`，覆盖 HTML 模板包、字段库元数据回导、旧 JSON 导入兼容和文件名清理。 |
| 默认快捷登录 | 已覆盖 | `e2e/login.spec.ts` |
| 报告权限 E2E | 已覆盖 | `e2e/report-permissions.spec.ts` |
| 报告修订版本 E2E | 已覆盖 | `e2e/report-revision.spec.ts` |
| 报告 AI 区域同步 E2E | 已覆盖 | `e2e/report-ai-region.spec.ts`，覆盖已有模板 AI 区域初始显示和新增区域即时显示。 |
| 医生个人模板 E2E | 已覆盖 | `e2e/personal-template.spec.ts` |
| 模板管理新增保存 E2E | 已覆盖 | `e2e/template-management.spec.ts` |
| 路由守卫和审计日志 E2E | 已覆盖 | `e2e/audit-and-route-guards.spec.ts` |
| 后端报告/模板/用户权限策略 | 已覆盖 | `server/src/permissions/permissions.policy.test.ts` |
| 后端报告 schema | 已覆盖 | `server/src/reports/reports.schemas.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` |
| 演示模式默认值 | 已覆盖 | `server/src/demo/demo-defaults.test.ts` 覆盖后端默认模板与前端报告编辑器默认内容一致，并校验语音演示配置完整。 |
| 后端 AI 代理 schema | 已覆盖 | `server/src/ai/ai.schemas.test.ts` |
| 后端 AI 代理重试和错误码 | 已覆盖 | `server/src/ai/ai.service.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。 |
| 报告编辑器完整流程 | 部分覆盖 | 已覆盖保存修订版本、个人模板和后端草稿/完成报告 schema；模板切换、字段同步仍待补。 |
| 视频抽帧 | 待 E2E/人工 | 依赖真实视频解码和 canvas。 |
| AI 撰写 | 待集成测试 | 需要隔离外部模型服务。 |
| 讯飞语音听写 | 部分覆盖/待集成测试 | 已覆盖前端 16k PCM 处理、后端首帧处理、上游文本消息转发和 WebSocket 地址生成；完整链路仍需要 WebSocket 集成测试、麦克风权限和测试凭证。 |

## Playwright 说明

首次运行如果提示浏览器缺失，执行：

```bash
npx playwright install chromium
```

当前 E2E 测试依赖真实后端数据库。Playwright 会在 `3100` 端口启动后端 API，执行 Prisma migrate/seed，然后在 `3001` 启动 Vite，并把 `/api` 代理到 `3100`。`e2e/helpers.ts` 通过真实 API 登录、创建用户/部门/报告和查询模板，不再写入 localStorage 种子数据。