Initialize backendized SurClaw report system

- Add React/Vite frontend for login, dashboard, reports, templates, users, settings, AI, speech, and media workflows. - Add NestJS/Prisma/PostgreSQL backend with auth, dashboard stats, reports, templates, users, departments, settings, files, AI, speech, audit logs, and HTML sanitization. - Add Prisma schema, migrations, seed data, persistent app sessions, Docker/Nginx deployment files, and upload volume configuration. - Add Vitest, Playwright, backend integration tests, and project documentation for requirements, design, permissions, API contracts, testing, deployment, security, and progress. - Configure production local fallback switch and remove unused Gemini direct dependency/env wiring.
2026-05-02 01:37:20 +08:00
commit 014aca8619
162 changed files with 27116 additions and 0 deletions
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -0,0 +1,110 @@
+# 测试文档
+
+## 测试命令
+
+```bash
+npm run lint
+npm run test
+npm run test:e2e
+npm run server:build
+npm run build
+```
+
+当前单元/组件测试框架为 Vitest，运行环境为 jsdom。React 页面测试使用 Testing Library。端到端测试使用 Playwright，当前仍以 localStorage 种子数据锁定迁移期前端基线行为；登录相关测试会 mock Auth API。后端使用 Vitest 覆盖权限策略、schema、DTO 映射、Nest HTTP 层集成测试和真实 PostgreSQL 服务集成测试，NestJS API 构建用 `npm run server:build` 验证。
+
+## 测试范围
+
+| 范围 | 当前覆盖 |
+| --- | --- |
+| 数据初始化 | 登录页首次加载会创建默认用户、模板、字段和系统设置。 |
+| 前端 API client | 统一解包 `{ data }` 响应、携带 Cookie credentials、识别后端错误 envelope。 |
+| 前端 Dashboard API | 工作台统计封装会请求 `/api/dashboard/stats` 并校验响应结构。 |
+| 前端语音代理地址 | 根据当前页面来源或 `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 验证医生可保存个人模板且模板仅归属本人。 |
+| 后端权限策略 | Vitest 验证报告、模板、用户和管理员创建权限策略。 |
+
+## Mock 边界
+
+测试中 mock 了以下浏览器或外部边界：
+
+- `fetch('/logo_square.png')`：用于登录初始化图片资源。
+- `/api/auth/me`、`/api/auth/login`：组件测试和登录 E2E 中使用 mock，避免单元/E2E 依赖真实数据库。
+- `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` |
+| 语音 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` |
+| 后端报告/模板/用户权限策略 | 已覆盖 | `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 测试不会依赖真实后端数据库：登录 E2E mock 认证 API，其余业务 E2E 通过 `e2e/helpers.ts` 写入 localStorage 种子数据。后端化后应保留这些用户流程测试，并逐步把数据准备方式从 localStorage seed 改为 API seed 或测试数据库 seed。