Mdeical_Sur_Report/docs/testing.md

测试文档

测试命令

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 兼容消息和多模态内容。
后端语音代理帧处理	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
后端语音代理首帧处理	已覆盖	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 说明

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

npx playwright install chromium

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