Mdeical_Sur_Report/docs/features.md

功能盘点

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

状态定义

状态	含义
真实可用	在当前应用内已有完整交互和持久化；可能是本地存储或已接入后端。
真实集成	已调用浏览器能力或第三方接口，但需要浏览器权限、有效密钥、网络或用户手动操作。
前端演示	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 导出	已移除	用户可见的报告、模板和 AI 日志 JSON 导出入口已移除；模板导入仍兼容旧 JSON 模板包。
模板管理	真实集成	TemplateManage 优先调用 /api/templates?access=manage，新增/编辑/删除会写后端并清洗 HTML；新增后保存内容以当前页面模板列表为准并同步兼容缓存，避免旧本地缓存覆盖新模板；字段库优先调用 /api/library/fields，模板图片资源优先调用 /api/files。导出保留 HTML 模板包和 PDF 打印预览，HTML 模板包内嵌模板正文、模板字段和字段管理设置；导入兼容 HTML 模板包和旧 JSON 模板包，仍主要在前端处理。
模板权限	真实集成	后端按部门模板、部门授权和个人模板过滤 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；上游临时过载时会短暂重试并保留 429/5xx 状态供前端友好提示；AI 可编辑区域插入后会立即同步到目标下拉栏；需要有效 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/templateList.test.ts	模板列表合并，覆盖新增模板不被旧缓存覆盖。
src/utils/templateExport.test.ts	HTML 模板包生成、字段库元数据回导、旧 JSON 导入兼容和文件名清理。
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 集成测试和人工验收补充端到端验证。