# 进度文档

## 当前状态

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

- 登录已接入后端 Session API；Session 已持久化到 `AppSession` 表；默认业务数据初始化仅作为开发本地回退存在。
- 工作台统计已接入 `GET /api/dashboard/stats`。
- 报告编辑、模板选择、字段绑定、富文本编辑已实现。
- 视频上传、自动抽帧、手动截帧、关键帧插入已实现；视频和关键帧优先上传到后端 Files API。
- AI 对话、AI 区域改写、差异确认和调用日志已实现；AI 对话已改为后端 `/api/ai/chat` 代理。
- 讯飞语音听写入口已实现，并已改为后端 `/api/speech/iat` WebSocket 代理。
- 报告管理、查看、历史恢复、打印、JSON/PDF 导出已实现。
- 报告 API 已实现列表、详情、创建、保存、完成修订、历史记录和软删除；`ReportManage`、`ReportView`、`ReportEditor` 已优先调用后端，只有开发/显式回退模式下才保留本地回退。
- 模板管理、字段库、模板导入导出已实现；模板 API 已支持可用/可管理列表、详情、创建、更新、删除和个人模板；字段库已优先接入 `/api/library/fields`。
- 用户管理、部门管理员约束和部门模板授权已优先接入后端 Users/Departments API；签名上传和模板图片资源已通过 Files API 写入后端文件资源。
- 系统设置、抽帧策略、AI Provider、语音参数和默认模板已优先接入 Settings API，只有开发/显式回退模式下才保留本地缓存回退。
- Docker/Nginx 静态部署配置已存在。
- 开发端口已调整为 `3001`。
- 已补充 Vitest 测试框架和核心功能单元/组件测试。
- 已补充功能盘点，区分真实功能、外部集成、前端演示和预留项。
- 前端权限 mock 已对齐目标规则：超级管理员全部、管理员本部门、医生本人。
- 报告已增加修订版本号，已完成报告再次保存会递增版本。
- 报告编辑器已支持医生保存“我的个人模板”。
- 讯飞语音配置初始化字段已统一为 `xfSpeechConfig`。
- 已新增 Playwright E2E，用 localStorage 种子锁定登录、报告权限、报告修订版本和医生个人模板流程。
- 已新增 API 契约草案，为后端化接口、权限过滤和响应格式提供基线。
- 已启动后端化第一阶段：新增 NestJS API 骨架、Prisma/PostgreSQL 数据模型、默认 seed、健康检查、认证接口和后端权限策略测试。
- 已完成前端认证闭环第一步：新增 API client、Auth Context、后端用户兼容映射，`Login`/`Sidebar` 已接入后端认证并同步 `currentUser`。

## 已知风险

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

## 建议下一步

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

## 维护记录

| 日期 | 事项 |
| --- | --- |
| 2026-05-01 | 新增 `docs/` 文档结构，梳理当前需求、设计、模块和风险。 |
| 2026-05-01 | 本地开发端口从 `3000` 调整为 `3001`。 |
| 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 旧依赖。 |