# 功能盘点

本文按当前源码筛选功能状态，区分“真实可用”“真实集成但依赖外部条件”“前端演示/非生产安全”和“预留或未使用”。

## 状态定义

| 状态 | 含义 |
| --- | --- |
| 真实可用 | 在当前应用内已有完整交互和持久化；可能是本地存储或已接入后端。 |
| 真实集成 | 已调用浏览器能力或第三方接口，但需要浏览器权限、有效密钥、网络或用户手动操作。 |
| 前端演示 | UI 和流程存在，但安全边界或数据层只是浏览器本地模拟，不等于生产实现。 |
| 后端骨架 | 服务入口、数据模型或策略已存在，但尚未接入前端主流程或补齐完整业务 API。 |
| 预留/未使用 | 依赖、环境变量或字段存在，但当前功能链路未实际使用或命名未统一。 |

## 功能矩阵

| 功能 | 状态 | 证据/说明 |
| --- | --- | --- |
| 登录 | 真实集成 | `Login` 通过 `AuthContext` 调用 `POST /api/auth/login`，后端用 Session Cookie 维持登录态；成功后同步 `currentUser` 兼容旧页面。 |
| 默认数据初始化 | 真实可用 | 登录页初始化默认用户、模板、字段、图片资源和系统设置。 |
| 登录态恢复/退出 | 真实集成 | `AuthProvider` 调用 `GET /api/auth/me` 恢复会话，`POST /api/auth/logout` 退出；后端 Session 已持久化到 `AppSession` 表，生产构建默认不再用本地缓存恢复。 |
| 角色导航 | 真实可用 | `Sidebar` 优先读取 Auth Context，回退 `currentUser.role` 显示菜单。 |
| 页面级权限跳转 | 真实可用/前端体验控制 | 路由统一通过 Auth Context 按角色阻止医生进入模板管理、用户管理和审计日志；这只是体验层，生产安全仍以后端 API 权限为准。 |
| 工作台统计 | 真实集成 | `Dashboard` 调用 `GET /api/dashboard/stats`，后端按角色范围统计报告、模板、用户和趋势；只有开发/显式回退模式下 API 不可用才回退本地统计。 |
| 报告基本信息表单 | 真实可用 | `ReportEditor` 管理 `reportData`，支持文本、日期、时间、单选、多选。 |
| 正文智能字段绑定 | 真实可用 | 模板 HTML 的 `data-bind` 字段与表单双向同步。 |
| 富文本编辑 | 真实可用 | 使用 `contentEditable` 和 `document.execCommand`。实现可用，但 API 过时。 |
| 报告草稿 | 真实可用 | 编辑过程自动保存到 `reportEditorDraft_${username}`；点击“保存草稿”会优先写后端，草稿状态允许患者姓名和住院号暂空。 |
| 保存/完成报告 | 真实集成 | `ReportEditor` 优先调用 `POST/PATCH /api/reports`，后端写入 PostgreSQL、清洗 HTML、保留历史版本、写审计，并在已完成报告再次修改时递增 `revision`；完成报告仍强制要求患者姓名和住院号；只有开发/显式回退模式下 API 不可用才回退本地保存。 |
| 报告历史恢复 | 真实可用 | 管理页写 `sessionStorage.restore_${reportId}`，编辑器读取恢复。 |
| 报告管理筛选 | 真实集成 | `ReportManage` 优先调用 `GET /api/reports`，后端按超级管理员/管理员/医生过滤；前端继续支持搜索、状态和时间筛选；只有开发/显式回退模式下 API 不可用才回退本地报告。 |
| 报告查看 | 真实集成 | `ReportView` 优先调用 `GET /api/reports/:id`，后端校验查看权限；页面渲染报告 HTML；只有开发/显式回退模式下 API 不可用才回退本地权限检查。 |
| PDF 导出 | 真实集成 | 通过隐藏 iframe 或 `window.print()` 调用浏览器打印，用户手动保存为 PDF；不是后端 PDF 生成。 |
| JSON 导出 | 真实可用 | Blob 下载结构化报告字段或模板包。 |
| 模板管理 | 真实集成 | `TemplateManage` 优先调用 `/api/templates?access=manage`，新增/编辑/删除会写后端并清洗 HTML；字段库优先调用 `/api/library/fields`，模板图片资源优先调用 `/api/files`。导入导出仍主要在前端处理。 |
| 模板权限 | 真实集成 | 后端按部门模板、部门授权和个人模板过滤 `access=use/manage`；迁移期仍同步 `localStorage.templates`，仅在开发/显式回退模式下作为回退。 |
| 我的个人模板 | 真实集成 | 医生在报告编辑器中保存个人模板时优先调用 `POST /api/templates`，后端把模板归属当前用户；只有开发/显式回退模式下 API 不可用才回退本地模板。 |
| 用户管理 | 真实集成 | `UserManage` 优先调用 `/api/users` 增删改查，后端校验超级管理员/管理员范围、管理员唯一性和医生创建约束；只有开发/显式回退模式下 API 不可用才保留本地回退。 |
| 部门模板授权 | 真实集成 | 后端提供 `/api/departments` 和 `/api/departments/:id/template-permissions`，超级管理员可通过管理员模板权限更新部门授权。 |
| 电子签名 | 真实集成 | 用户管理页上传后压缩为 Data URL，再调用 `/api/users/:id/signature` 写入后端文件资源；报告中有对应绑定字段时通过受控文件 URL 展示。只有开发/显式回退模式下 API 不可用才保留本地签名回退。 |
| 视频上传 | 真实集成 | 使用浏览器 File API 和对象 URL即时预览，并优先通过 `/api/files` 以 `kind = VIDEO` 写入后端文件资源。 |
| 自动抽帧 | 真实集成 | 使用 `<video>` + `<canvas>` 按百分比截取 JPEG，关键帧优先通过 `/api/files` 以 `kind = FRAME` 写入后端文件资源。 |
| 关键帧插入 | 真实集成 | 关键帧可点击插入或拖入图片占位符；上传成功后编辑器会把插入图片从 Data URL 替换为受控文件 URL。 |
| AI 辅助撰写 | 真实集成 | 前端调用 `/api/ai/chat`，后端使用全局共用 Provider Key 代理 OpenAI 兼容 `/chat/completions`；需要有效 Provider 配置、模型和网络。 |
| AI 差异确认 | 真实可用 | 使用 `diff` 生成左右差异，确认后写入 AI 区域。 |
| 讯飞语音听写 | 真实集成 | 前端使用麦克风采集音频并连接 `/api/speech/iat`；后端读取讯飞配置、生成鉴权 URL、补齐首帧 APPID/业务参数并转发 IAT 结果。需要浏览器权限、安全上下文（`localhost` 或 HTTPS）、有效配置和网络；Docker 提供 `https://localhost:4443` 演示入口。 |
| AI/语音密钥管理 | 真实集成 | AI Key 和讯飞 APIKey/APISecret 均由后端代理读取和使用；普通用户读取设置时不返回真实密钥。 |
| 系统设置 | 真实集成 | `SystemSettings` 优先调用 `/api/settings/system` 读取和保存抽帧、默认模板、AI Provider、语音配置；“恢复演示出厂设置”会二次确认后调用后端 demo reset，清空报告/审计并恢复默认用户、模板和演示配置。只有开发/显式回退模式下 API 不可用才回退本地缓存。 |
| 审计日志查看 | 真实集成 | 超级管理员和管理员可进入审计日志页，调用 `GET /api/audit-logs` 查看登录、报告、模板、用户、部门、设置和文件等操作；管理员只看本部门或自己相关日志。 |
| Docker/Nginx 静态部署 | 真实可用 | 可构建静态文件并用 Nginx 托管 SPA。 |
| 后端服务 | 后端骨架 | 已新增 NestJS API：健康检查、认证接口、数据库 Session、Dashboard API、报告 API、报告媒体关系、模板 API、字段库 API、用户/部门 API、设置 API、通用文件/签名文件 API、视频/关键帧文件上传、AI 代理、讯飞语音代理、HTML 清洗、审计日志查询、Prisma/PostgreSQL 数据模型、默认 seed 和权限策略。 |
| 讯飞语音配置字段 | 真实可用 | 初始化、类型和系统设置统一使用 `xfSpeechConfig`。 |

## 测试覆盖对应

| 测试文件 | 覆盖范围 |
| --- | --- |
| `src/pages/Login.test.tsx` | 默认数据初始化、默认账号展示、后端禁用账号错误展示。 |
| `src/components/Sidebar.test.tsx` | 角色导航过滤。 |
| `src/api/client.test.ts` | API envelope 解包、Cookie credentials 和错误 envelope。 |
| `src/api/audit.test.ts` | 审计日志列表 API 封装和查询参数。 |
| `src/api/dashboard.test.ts` | Dashboard 统计 API 封装和响应校验。 |
| `src/api/speech.test.ts` | 语音 WebSocket 代理地址生成，含同源和显式 API Base URL。 |
| `src/api/library.test.ts` | 字段库 API 读取和更新封装。 |
| `src/api/files.test.ts` | 通用文件列表和上传 API 封装。 |
| `src/auth/backendUser.test.ts` | 后端用户 DTO 到前端兼容用户的角色和模板权限映射。 |
| `src/pages/ReportManage.test.tsx` | 医生/管理员报告可见范围。 |
| `src/utils/permissions.test.ts` | 报告权限、管理员本部门范围、医生个人模板和部门模板范围。 |
| `src/utils/storage.test.ts` | 本地存储、系统设置混淆兼容、会话恢复键、默认 Provider 不携带内置 Key 的契约。 |
| `src/utils/defaultContent.test.ts` | 默认模板结构、智能字段、图片占位符、AI 区域、字段和 Provider 配置。 |
| `src/utils/print.test.ts` | 浏览器打印导出入口。 |
| `server/src/permissions/permissions.policy.test.ts` | 后端报告、模板、用户管理和管理员创建权限策略。 |
| `server/src/reports/reports.schemas.test.ts` | 后端报告创建/更新 schema，覆盖草稿可空患者信息、完成报告必填患者姓名和住院号。 |
| `server/src/reports/report.mapper.test.ts` | 后端 Report 与前端兼容 Report 对象的 metadata、ReportMedia 和历史输出。 |
| `server/src/templates/template.mapper.test.ts` | 后端 Template 与前端兼容 Template 对象、模板权限资源的映射。 |
| `server/src/users/users.mapper.test.ts` | 后端 User 与前端兼容 User 对象、部门模板授权字段的映射。 |
| `server/src/settings/settings.schemas.test.ts` | 后端系统设置 schema 默认值和非法抽帧参数校验。 |
| `server/src/ai/ai.schemas.test.ts` | 后端 AI 代理入参 schema，含多模态消息与空消息校验。 |
| `server/src/speech/xf-frame.test.ts` | 后端讯飞代理首帧补齐 APPID/业务参数，后续帧和异常 payload 保持兼容。 |
| `server/src/http.integration.test.ts` | Nest HTTP 层集成测试，覆盖 API prefix、登录会话、未登录保护、受保护接口 actor 传递。 |

外部 AI、讯飞语音上游、真实浏览器视频抽帧和打印成 PDF 属于浏览器/第三方边界，单元测试中不直连外部服务；AI/语音代理已有 schema 或帧处理测试，后续需要 HTTP/WebSocket 集成测试和人工验收补充端到端验证。