Mdeical_Sur_Report/docs/backendization-plan.md

# 后端化与用户化改造方案

本文基于当前迁移期版本整理需要改动的范围。当前系统已完成主业务后端化，目标是继续把开发回退、审计、安全、部署和运维能力收紧为“多用户、可审计、可部署、可维护”的前后端系统。

## 改造目标

当前系统已经有较完整的页面、业务流程和后端 API。仍需关注的迁移期边界包括：

- 用户、密码、权限、工作台统计、报告、报告媒体关系、模板、字段库、模板图片、用户和部门权限已优先接入后端 API；`localStorage.users` 仅作为开发回退兼容缓存存在。
- 设置和部分兼容缓存仍存在 `localStorage`；生产构建默认关闭本地回退。
- 签名、模板图片资源、视频和关键帧文件已优先进入后端文件资源；报告媒体引用已通过 `ReportMedia` 关系表保存。
- AI Key 和讯飞语音密钥已进入后端代理链路。
- 权限判断主要在前端页面里完成。

后端化后应达到：

- 登录认证由后端完成。
- 所有数据以用户、部门、医院/租户为边界存储。
- 权限在后端强校验，前端只做展示控制。
- 文件和图片从 Base64 本地存储迁移到后端文件服务或对象存储。
- AI 与语音等密钥由后端托管，前端不接触真实密钥。
- 报告查看、编辑、删除等关键行为有审计记录；报告导出按权限控制，不要求专门导出审计。

## 技术栈决策

后端化第一阶段建议采用 TypeScript 全栈方案，优先保证权限边界、模块结构、数据迁移和测试可维护。

| 层级 | 选择 | 说明 |
| --- | --- | --- |
| 前端 | React 19 + TypeScript + Vite + Tailwind CSS | 保留现有页面主体，逐步把 `localStorage` 读写替换为 API 调用。 |
| 后端框架 | NestJS + TypeScript | 适合按认证、报告、模板、用户、设置、文件、AI 等模块拆分；Guard/Interceptor/Service 结构适合集中权限控制和审计。 |
| 数据库 | PostgreSQL | 适合报告、历史版本、权限关系、审计日志等关系型数据；支持事务、索引和后续统计。 |
| ORM/迁移 | Prisma | 类型生成清晰，迁移和 seed 成本低，便于前后端共享 DTO 思路。 |
| 认证 | HttpOnly Cookie Session，Access Token 仅作为可选扩展 | 前端不直接持久化敏感 token；后端维护会话、退出和失效。第一阶段可用数据库会话表，后续再引入 Redis。 |
| 密码 | Argon2 哈希 | 禁止明文密码进入前端或日志。 |
| 文件存储 | 本地文件目录 + `files` 表，预留 MinIO/S3 兼容接口 | 开发和院内部署先降低成本；生产可切换对象存储。 |
| 输入校验 | Zod 或 NestJS DTO 校验 | 所有 API 入参都必须校验，尤其是 HTML、文件、权限相关参数。 |
| 测试 | Vitest/Testing Library + Playwright + 后端单元/集成测试 | 保留现有前端测试；新增后端 policy/service/API 测试；E2E 后续从 localStorage seed 改为 API/test DB seed。 |
| 部署 | Docker Compose | 前端静态资源、NestJS API、PostgreSQL、可选 Redis/MinIO 分服务部署。 |

暂不建议第一阶段使用微服务、复杂租户系统或后端抽帧服务。抽帧可以先继续留在前端 canvas，生成关键帧后上传后端文件接口。

## 当前后端骨架

已新增 `server/` 目录作为后端化第一阶段基础：

- `server/src/main.ts`：NestJS 启动入口，设置 `/api` 前缀、CORS、Cookie Session、数据库 Session Store 和统一错误响应。
- `server/src/dashboard`：`GET /api/dashboard/stats`，按角色范围统计报告、模板、用户和趋势。
- `server/src/audit`：第一版审计服务，记录登录、报告、模板、用户、设置和文件修改。
- `server/src/health`：`GET /api/health` 健康检查。
- `server/src/auth`：`POST /api/auth/login`、`GET /api/auth/me`、`POST /api/auth/logout` 认证接口。
- `server/src/reports`：`GET/POST/PATCH/DELETE /api/reports` 报告接口，含角色范围过滤、历史版本、软删除和报告媒体关系同步。
- `server/src/templates`：`GET/POST/PATCH/DELETE /api/templates` 模板接口，含 `access=use/manage`、部门模板、部门授权和个人模板。
- `server/src/users`：`GET/POST/PATCH/DELETE /api/users` 与 `/api/departments` 接口，含用户范围过滤、管理员唯一性、医生创建约束和部门模板授权。
- `server/src/settings`：`GET/PATCH /api/settings/system` 和重置接口，保存全局设置与个人默认模板。
- `server/src/files`：通用文件上传、列表、删除、受控读取接口；签名文件会额外关联 `User.signatureFileId`。
- `server/src/library`：`GET/PATCH /api/library/fields` 字段库接口，保存字段、时间格式和选项库。
- `server/src/ai`：`GET /api/ai/models` 和 `POST /api/ai/chat`，使用全局共用 Provider Key 代理 OpenAI 兼容接口。
- `server/src/speech`：`GET /api/speech/iat` WebSocket 代理，使用 Session 校验用户，后端生成讯飞鉴权 URL 并转发音频帧和识别结果。
- `server/src/prisma`：PrismaService，使用 Prisma 7 的 PostgreSQL driver adapter。
- `server/src/permissions`：报告、模板、用户和管理员创建权限策略，已配套单元测试。
- `server/prisma/schema.prisma`：PostgreSQL 数据模型，覆盖租户、部门、用户、业务 Session、`AppSession`、报告、报告媒体、历史、模板、文件、设置和审计日志。
- `server/prisma/seed.ts`：写入默认医院、部门和 `admin`、`manager`、`0001` 三个账号。

当前前端登录、Dashboard、报告读写、报告媒体关系、模板读写、字段库、模板图片资源、视频/关键帧文件、用户管理、部门模板授权、系统设置、签名文件、AI 对话代理和语音听写代理已接入后端认证/API。真实 PostgreSQL 服务集成测试已覆盖 Auth、Dashboard、Reports、ReportMedia、Templates 和 Files 核心服务，下一步应逐步替换剩余开发回退数据访问。

## 总体架构建议

### 前端

保留当前 React + Vite 页面主体，逐步把 `storage.get/set` 替换成 API 调用。

建议新增：

- `src/api/`：统一 API client。
- `src/auth/`：登录态、Token、权限上下文。
- `src/hooks/`：数据获取和变更 hook。
- `src/services/`：报告、模板、用户、系统设置、文件、AI 服务封装。

### 后端

建议先采用 NestJS 单体后端，避免一开始拆太复杂：

- Node.js + NestJS + TypeScript。
- PostgreSQL + Prisma。
- Redis 可选，用于会话、限流、任务状态。
- 对象存储可选，院内部署可先用本地文件目录，生产建议 MinIO/S3 兼容存储。

### 数据边界

后端需要引入明确的组织边界：

- `tenant`：医院或部署实例。
- `department`：科室。
- `user`：用户账号。
- `role`：超级管理员、管理员、医生。
- `permission`：模板权限、报告权限、系统配置权限。

如果项目只给单医院内网使用，可以先不做复杂租户模型，但数据库字段建议预留 `tenant_id`。

## 数据模型改造

### 用户与认证

新增表：

- `users`
- `departments`
- `roles` 或直接使用枚举字段
- `user_sessions` 或使用 JWT + refresh token
- `user_template_permissions`

当前 `User` 需要变化：

- `password` 改为 `password_hash`，禁止前端返回。
- `signature` 从 Base64 改为 `signature_file_id` 或 `signature_url`。
- `visibleTemplates/manageableTemplates` 拆成权限关联表。
- `status` 保留。
- 增加 `last_login_at`、`created_by`、`updated_by`。

### 报告

新增表：

- `reports`
- `report_histories`
- `report_media`
- `report_exports` 可选

当前 `Report` 需要变化：

- `content` 仍可保存 HTML，但必须后端清洗。
- `videos.url` 不再长期依赖浏览器对象 URL，后端保存 `ReportMedia.fileId/url` 并返回受控文件 URL。
- `capturedFrames.dataUrl` 改成 `ReportMedia.fileId/url` 派生出的图片 URL。
- `author/authorName` 改成 `author_id`，展示时 join 用户表。
- `createdAt/updatedAt` 统一为 ISO 时间戳。
- `status` 保留 `draft/completed`。
- `history` 拆到 `report_histories`。

### 模板与字段

新增表：

- `templates`
- `template_versions` 可选
- `form_fields`
- `template_fields` 可选
- `image_assets`

当前 `Template` 需要变化：

- `content` 保存 HTML，但导入和保存时后端清洗。
- `fields` 不建议长期嵌在模板对象里，可拆出字段配置版本。
- `author` 改成 `author_id`。
- 增加 `department_id`、`tenant_id`、`is_global`、`status`。

### 系统设置

新增表：

- `system_settings`
- `ai_provider_configs`
- `speech_provider_configs`

当前 `SystemSettings` 需要变化：

- AI Key、讯飞密钥只存后端，前端只看到是否已配置和脱敏信息；普通用户请求设置时不返回真实密钥。
- 抽帧设置可以按全局、科室或用户默认值分层。
- 默认模板可以改成用户级配置 `user_preferences.default_template_id`。

### 文件资源

新增表：

- `files`

字段建议：

- `id`
- `tenant_id`
- `owner_id`
- `kind`：`signature`、`template_asset`、`video`、`frame`、`report_export`
- `filename`
- `mime_type`
- `size`
- `storage_key`
- `checksum`
- `created_at`

## API 改造清单

### 认证

- `POST /api/auth/login`
- `POST /api/auth/logout`
- `POST /api/auth/refresh`
- `GET /api/auth/me`
- `PATCH /api/auth/password`

### 用户

- `GET /api/users`
- `POST /api/users`
- `GET /api/users/:id`
- `PATCH /api/users/:id`
- `DELETE /api/users/:id`
- `POST /api/users/:id/signature`
- `GET /api/departments`
- `POST /api/departments`
- `PATCH /api/departments/:id`
- `DELETE /api/departments/:id`
- `PATCH /api/departments/:id/template-permissions`

### 模板

- `GET /api/templates`
- `POST /api/templates`
- `GET /api/templates/:id`
- `PATCH /api/templates/:id`
- `DELETE /api/templates/:id`
- `POST /api/templates/import`
- `GET /api/templates/:id/export`
- `POST /api/templates/batch-export`
- `GET /api/form-fields`
- `PUT /api/form-fields`

### 报告

- `GET /api/reports`
- `POST /api/reports`
- `GET /api/reports/:id`
- `PATCH /api/reports/:id`
- `DELETE /api/reports/:id`
- `POST /api/reports/:id/complete`
- `GET /api/reports/:id/history`
- `POST /api/reports/:id/restore`
- `GET /api/reports/:id/export.json`
- `POST /api/reports/export`

### 文件与视频

- `POST /api/files`
- `GET /api/files`
- `GET /api/files/:id`
- `DELETE /api/files/:id`

当前第一版已经保留前端 canvas 抽帧，并把视频和生成的关键帧通过通用文件 API 上传为 `VIDEO` / `FRAME` 文件资源。后续如果要做后端视频服务，再新增专用 `videos` 模块，用于转码、异步抽帧、断点续传和媒体引用关系维护。

### AI 与语音

- `POST /api/ai/chat`
- `GET /api/ai/providers`
- `PATCH /api/ai/providers/:id`
- `POST /api/ai/providers/:id/test`
- `GET /api/speech/config`
- `PATCH /api/speech/config`
- `POST /api/speech/token` 或 `GET /api/speech/ws-auth`

前端不再直接调用第三方 AI 接口，不再保存真实 API Key。

### 系统设置

- `GET /api/settings`
- `PATCH /api/settings`
- `POST /api/settings/reset`

清空浏览器本地数据只作为开发/显式回退模式能力；如果未来需要“重置全部后端数据”，应作为独立维护接口谨慎保留，只允许超级管理员在维护模式下执行，并写审计日志。

## 前端改造清单

### 第一批必须改

1. 新增 API Client
   - 统一 base URL、认证头、错误处理、401 刷新或跳登录。
   - 当前已新增 `src/api/client.ts`，支持 `{ data }` envelope 解包、Cookie credentials 和错误 envelope。

2. 替换登录逻辑
   - 登录调用 `/api/auth/login`。
   - 当前用户来自 `/api/auth/me`。
   - 当前已完成登录 API 接入；默认模板、字段、图片和本地用户初始化仍暂时保留，供未迁移页面使用。

3. 替换 `currentUser`
   - 从 `localStorage.currentUser` 改成 Auth Context 或全局 store。
   - 本地只保存 token 或 session 标识。
   - 当前已新增 Auth Context，但仍会同步 `currentUser` 兼容旧页面；后续页面完成 API 迁移后再移除该缓存依赖。

4. 替换报告数据
   - `ReportManage` 用 `GET /api/reports`。
   - `ReportView` 用 `GET /api/reports/:id`。
   - `ReportEditor` 保存用 `POST/PATCH /api/reports`。
   - 历史恢复用后端历史 API。
   - 当前前三项已接入；历史恢复仍通过返回的兼容 `history` 和 `sessionStorage.restore_${reportId}` 进入编辑器。

5. 替换模板数据
   - `TemplateManage` 全部从 API 获取和保存。
   - 模板权限由后端返回可见/可管理范围。
   - 当前已接入模板列表、创建、编辑、保存内容、删除、医生个人模板、字段库和模板图片资源。

6. 替换用户管理
   - `UserManage` 调用用户 API。
   - 密码不再回显，也不进入前端用户对象。
   - 当前已接入用户列表、新增、编辑、删除、部门模板授权和签名文件上传。

7. 替换系统设置
   - 当前已接入 Settings API，保存全局设置和个人默认模板。
   - 后续应只展示脱敏密钥；保存时发送新密钥，后端加密存储并由代理使用。

### 第二批建议改

1. 文件上传
   - 签名、模板图片、视频和关键帧已完成第一版文件 API；报告媒体引用已通过 `ReportMedia` 正规化，报告正文内手动插入图片仍需改为上传文件。
   - 报告 HTML 中引用文件 URL 或受控下载 URL。

2. 报告内容清洗
   - 前端仍可编辑 HTML。
   - 保存前后端做白名单清洗。
   - 渲染时避免直接信任历史 HTML。

3. 草稿同步
   - 当前草稿在本地，可改成服务端 draft autosave。
   - 防止换浏览器或清缓存丢草稿。

4. AI 代理
   - `ReportEditor` 的 `fetch(chat/completions)` 改成 `/api/ai/chat`。
   - 后端记录请求摘要和错误，避免前端暴露密钥。
   - 当前已接入 `/api/ai/models` 和 `/api/ai/chat`，所有用户共用全局 Provider Key；仍待第三方调用摘要和错误追踪落库。

5. 审计日志
   - 登录、编辑、完成、删除、重置、权限变更等关键操作写日志。
   - 报告导出不要求水印、导出原因、审批或专门导出审计。

## 权限模型建议

### 角色能力

| 能力 | 超级管理员 | 管理员 | 医生 |
| --- | --- | --- | --- |
| 管理全局设置 | 是 | 否 | 否 |
| 管理 AI/语音密钥 | 是 | 否 | 否 |
| 管理全部用户 | 是 | 否 | 否 |
| 管理同部门医生 | 是 | 是 | 否 |
| 管理模板 | 全部 | 授权模板 | 否 |
| 使用模板 | 全部 | 可见模板 | 可见模板 |
| 查看报告 | 全部 | 本部门 | 本人 |
| 编辑报告 | 全部 | 本部门 | 本人，包括已完成报告 |
| 删除报告 | 全部 | 本部门，包括已完成报告 | 本人，包括已完成报告 |
| 导出报告 | 全部 | 本部门 | 本人 |

已确定权限规则以 [权限设计](./permissions.md) 为准：

- 超级管理员全权限，可修改任何数据。
- 超级管理员默认属于 `admin` 部门。
- 管理员只能看、改、删本部门报告。
- 医生完成报告后可以继续修改，也可以删除本人已完成报告。
- 完成报告后的每次修改必须增加修订版本号。
- 模板按部门授权；管理员可修改本部门模板；医生可复制/新建个人模板。
- 一个部门只能有一个管理员，且只有超级管理员能创建或授权管理员。
- AI 只能接收当前报告内容作为上下文。

### 后端强校验

每个 API 都必须根据当前用户进行后端权限判断。前端菜单隐藏只是体验优化，不能作为安全依据。

## 安全改造清单

- 密码使用 bcrypt/argon2 哈希。
- Token 使用 HttpOnly Cookie 或短期 access token + refresh token。
- API 增加 CSRF 或 SameSite 策略。
- HTML 内容用 DOMPurify 或服务端白名单清洗。
- 文件上传限制 MIME、大小、扩展名，并做病毒扫描或隔离策略。
- AI/语音密钥后端加密存储。
- 敏感日志脱敏，禁止记录完整病历到普通日志。
- 报告导出当前不要求水印、原因、审批或专门审计；后续重点是权限控制、错误追踪和后端导出能力。
- 对报告、模板、用户操作增加审计日志。
- 增加数据库备份和恢复策略。

## 测试改造清单

### 后端测试

- Auth：登录、登出、刷新、密码错误、禁用用户。
- RBAC：不同角色访问用户、模板、报告、设置 API。
- Reports：新增、编辑、完成、历史、删除、导出。
- Templates：新增、导入、导出、权限过滤、字段配置。
- Files：上传、读取、权限、大小限制。
- Settings：密钥脱敏、配置保存、抽帧设置。
- AI Proxy：请求构造、错误处理、密钥不下发。

### 前端测试

保留现有 Vitest 测试，并新增：

- API client 401/错误处理。
- Auth Context 登录态恢复。
- 报告列表 API 数据渲染。
- 模板权限数据渲染。
- 用户管理表单 API 提交。

### E2E 测试

建议新增 Playwright：

- 管理员登录、创建医生、分配模板。
- 医生登录、新建报告、保存草稿、完成报告。
- 报告管理搜索、查看、导出。
- 模板新增、字段插入、报告套用模板。
- 视频上传和抽帧可用性。

## 迁移步骤建议

### 阶段 0：冻结当前功能

- 保留现有 `localStorage` 版本作为 baseline。
- 当前 Vitest 测试继续作为前端契约测试。
- 增加功能验收清单，避免后端化时漏功能。

### 阶段 1：后端骨架

- 建后端项目、数据库迁移、基础表结构。
- 实现登录、当前用户、用户列表、模板列表、报告列表。
- 前端新增 API client，但先不大规模替换页面。

### 阶段 2：认证和用户后端化

- 替换 `Login`、`Sidebar`、`UserManage`。
- 移除前端默认账号初始化。
- 前端不再保存密码和完整用户列表。

### 阶段 3：模板和报告后端化

- 替换 `TemplateManage`、`ReportManage`、`ReportView`、`ReportEditor` 保存逻辑。
- 报告历史改为后端历史表。
- 字段配置由后端提供。

### 阶段 4：文件和关键帧后端化

- 签名、图片资源、关键帧、视频统一上传。
- 报告 HTML 中从 Data URL 改为文件 URL 或受控资源地址。

### 阶段 5：AI/语音代理与审计

- 前端调用后端 AI API。
- 后端托管 AI 密钥；语音密钥仍待代理化。
- 增加查看日志、第三方代理调用摘要和错误追踪；报告导出不要求专门审计，后端导出能力另行实现。

### 阶段 6：生产化

- 部署数据库、对象存储、后端服务。
- 配置备份、监控、日志、权限审计。
- 做安全扫描、数据迁移演练和院内验收。

## 需要优先决策的问题

1. 后端技术栈：Express、NestJS、Fastify，还是已有院内后端技术？
2. 数据库：PostgreSQL、MySQL，还是院内指定数据库？
3. 部署方式：单机 Docker Compose，还是院内 Kubernetes/服务器？
4. 文件存储：本地磁盘、MinIO、S3 兼容，还是院内文件系统？
5. 租户模型：只支持单医院，还是要支持多医院/多院区？
6. 报告权限：管理员是否只能看同部门，还是可以按模板/患者/手术组授权？
7. 完成报告后是否允许医生修改？是否需要审批或留痕版本？
8. AI 和语音是否必须在院内网代理，是否允许公网访问第三方模型？