Mdeical_Sur_Report/docs/progress.md

进度文档

当前状态

项目已具备一套可运行的迁移期闭环：登录认证、数据库 Session、工作台统计、报告读写、报告媒体关系、模板读写、字段库、模板图片资源、视频/关键帧文件、用户管理、部门模板授权、系统设置、签名文件、AI 对话代理和讯飞语音代理已接入后端。

• 登录已接入后端 Session API；Session 已持久化到 AppSession 表；默认业务数据初始化仅作为开发本地回退存在。
• 工作台统计已接入 GET /api/dashboard/stats。
• 报告编辑、模板选择、字段绑定、富文本编辑已实现。
• 视频上传、自动抽帧、手动截帧、关键帧插入已实现；视频和关键帧优先上传到后端 Files API。
• AI 对话、AI 区域改写和差异确认已实现；AI 对话已改为后端 /api/ai/chat 代理。
• 报告编辑器会监听正文 AI 区域变化，新插入的 AI 可编辑区域会立即同步到 AI 撰写目标下拉栏。
• 讯飞语音听写入口已实现，并已改为后端 /api/speech/iat WebSocket 代理；前端启动前会检查麦克风采集能力和安全上下文。
• 报告管理、查看、历史恢复和打印/PDF 导出已实现；用户可见前端 JSON 导出入口已移除。
• 报告 API 已实现列表、详情、创建、保存、完成修订、历史记录和软删除；ReportManage、ReportView、ReportEditor 已优先调用后端，只有开发/显式回退模式下才保留本地回退。
• 后端报告校验已区分草稿和完成状态：草稿允许患者姓名/住院号暂空，完成报告仍强制要求。
• 模板管理、字段库、模板导入导出已实现；模板 API 已支持可用/可管理列表、详情、创建、更新、删除和个人模板；字段库已优先接入 /api/library/fields。
• 模板导出已增加可重新导入的 HTML 模板包，用于比 JSON 更完整地保留报告版式观感。
• 模板管理新增后保存内容已改为基于当前页面 state 更新，并与本地兼容缓存合并，避免旧缓存把新建模板从列表中冲掉。
• 用户管理、部门管理员约束和部门模板授权已优先接入后端 Users/Departments API；签名上传和模板图片资源已通过 Files API 写入后端文件资源。
• 系统设置、抽帧策略、AI Provider、语音参数和默认模板已优先接入 Settings API，只有开发/显式回退模式下才保留本地缓存回退。
• Docker/Nginx 静态部署配置已存在。
• Docker/Nginx 与 NestJS API 已把请求体上限统一到 100mb，避免图文报告和文件 Data URL 上传触发默认 413。
• Docker Nginx 已额外提供自签名 HTTPS 演示入口 4443，用于浏览器麦克风听写权限；普通局域网 HTTP 仍受浏览器限制。
• 开发端口已调整为 3001。
• 已补充 Vitest 测试框架和核心功能单元/组件测试。
• 已补充功能盘点，区分真实功能、外部集成、前端演示和预留项。
• 前端权限 mock 已对齐目标规则：超级管理员全部、管理员本部门、医生本人。
• 报告已增加修订版本号，已完成报告再次保存会递增版本。
• 报告编辑器已支持医生保存“我的个人模板”。
• 讯飞语音配置初始化字段已统一为 xfSpeechConfig。
• Playwright E2E 已改为启动真实后端 API，并通过 API seed 锁定登录、报告权限、报告修订版本、医生个人模板、路由守卫和审计日志流程。
• 已新增审计日志查询 API 和审计日志页面；超级管理员可看全部，管理员可看本部门或自己相关日志。
• 页面级权限已收敛到 Auth Context 路由守卫，医生不能直进模板管理、用户管理和审计日志页面。
• 已新增 API 契约草案，为后端化接口、权限过滤和响应格式提供基线。
• 已启动后端化第一阶段：新增 NestJS API 骨架、Prisma/PostgreSQL 数据模型、默认 seed、健康检查、认证接口和后端权限策略测试。
• 已完成前端认证闭环第一步：新增 API client、Auth Context、后端用户兼容映射，Login/Sidebar 已接入后端认证并同步 currentUser。

已知风险

• 前端仍有部分体验控制和兼容缓存依赖浏览器本地数据；后端已经承载主业务数据和第一版审计查询。
• 后端认证、Dashboard API、报告 API、报告媒体关系、模板 API、字段库 API、用户/部门 API、设置 API、通用文件/签名文件 API、AI 代理、语音代理和审计日志 API 已可用；第三方调用摘要、限流和后端导出仍待加强。
• 本地存储仍可能包含病历兼容缓存、旧演示密码字段、模板图片和关键帧，不适合生产；历史浏览器数据中也可能残留旧版语音服务密钥。
• systemSettings 的混淆存储不是加密。
• 当前 demo mode 后端默认值包含演示用第三方服务凭据；生产化前必须移除或替换，并轮换曾经暴露过的第三方密钥。
• 报告正文和模板正文保存时已做服务端白名单清洗，但仍以 HTML 字符串存储并通过 dangerouslySetInnerHTML 渲染，需要持续安全测试。
• 大视频和大量 Base64 图片会快速占满浏览器存储空间。
• document.execCommand 已是过时 API，但当前编辑器大量依赖它。
• README 曾与源码账号不一致，当前已同步为 0001 / 123456。

建议下一步

1. 逐步替换前端数据流：继续减少字段库、模板图片和报告编辑器草稿之外的本地回退依赖。
2. 补第三方代理调用摘要、后端导出 API 和限流；报告导出不要求专门导出审计。
3. 增加数据迁移：为 localStorage 或后端数据增加版本号和迁移脚本。
4. 增加生产运维能力：备份恢复、对象存储、监控告警和密钥轮换流程。

维护记录

日期	事项
2026-05-01	新增 docs/ 文档结构，梳理当前需求、设计、模块和风险。
2026-05-01	前端本地开发端口调整为 3001。
2026-05-02	统一端口配置：本地/API 容器监听 3100，Docker API 暴露 3002，Docker 前端暴露 4002，避免占用其他项目常用端口。
2026-05-01	新增功能盘点和测试文档，补充 Vitest 测试覆盖核心功能契约。
2026-05-01	对齐前端权限 mock、报告修订版本和医生个人模板，统一 xfSpeechConfig 字段。
2026-05-01	新增 Playwright E2E 和 API 契约草案，锁定后端化前的关键前端行为。
2026-05-01	新增 NestJS + Prisma 后端骨架、PostgreSQL schema、默认 seed、健康检查、认证接口和后端权限策略测试。
2026-05-01	前端新增 API client、Auth Context 和后端用户兼容映射，登录/退出/恢复会话接入后端认证。
2026-05-01	新增后端 Reports API、Report.metadata 兼容字段和报告前端 API 接入，报告读写优先走后端。
2026-05-01	新增后端 Templates API、默认模板 seed 和模板前端 API 接入，模板读写优先走后端。
2026-05-01	新增后端 Users/Departments API 和用户管理页 API 接入，部门模板授权优先由后端维护。
2026-05-02	新增后端 Settings API、签名文件 API 和前端接入，系统设置与电子签名优先走后端。
2026-05-02	新增后端 AI Proxy，报告编辑器和模型测试改为调用 /api/ai/chat 与 /api/ai/models。
2026-05-02	新增后端讯飞语音 WebSocket Proxy，报告编辑器改为调用 /api/speech/iat，普通用户读取设置时不返回语音密钥。
2026-05-02	新增后端字段库 API、通用文件 API 和 HTTP 集成测试，模板图片资源优先写入后端文件资源。
2026-05-02	报告编辑器视频和关键帧优先上传 Files API，新增真实 PostgreSQL 服务集成测试。
2026-05-02	新增 ReportMedia 表和迁移，报告视频/关键帧引用从 Report.metadata 拆出。
2026-05-02	新增 Dashboard API、数据库 Session Store、审计服务、HTML 白名单清洗、本地回退开关和 Docker 上传目录 volume，清理 Gemini 旧依赖。
2026-05-02	新增审计日志查询 API/页面、Auth Context 路由角色守卫，并把 Playwright E2E 改为真实后端 API seed。
2026-05-02	新增安装与初始设置文档，补充首次启动、端口规划、数据库初始化、验收步骤和常见问题。
2026-05-02	新增前端组件结构文档，梳理页面组件、公共组件、API/Auth/Utils 分层、数据流和大组件拆分边界。
2026-05-02	将默认“腹腔镜胆囊切除术报告”后端 seed 与前端默认报告内容对齐，并把系统设置重置改为演示模式恢复出厂设置。
2026-05-02	修正报告草稿后端校验和保存失败提示，补充麦克风启动前置检查。
2026-05-02	增加 Nginx 和 NestJS 请求体上限配置，修复大图文报告保存 request entity too large。
2026-05-02	新增 Docker HTTPS 演示入口和麦克风访问说明，解决非安全上下文下语音听写不可启动的问题。
2026-05-02	修复模板管理中新建模板后点击保存内容导致模板从列表消失的问题，并补充单元测试和 E2E。
2026-05-02	模板管理新增 HTML 模板包导出/导入。
2026-05-02	修复报告编辑器新增 AI 可编辑区域后 AI 撰写下拉栏不立即更新的问题，并补充 E2E。
2026-05-02	移除前端用户可见 JSON 导出入口，保留模板历史 JSON 导入兼容。
2026-05-02	模板 HTML 导出包补充模板字段和字段管理设置，导入时恢复字段库元数据。
2026-05-02	调整报告编辑器 AI Prompt 优先级，医生指令和结构化报告字段优先于默认模板旧术式内容。