# 需求文档

## 项目目标

手术图文病历报告系统用于医院或科室内网场景，提供手术记录的图文报告撰写、模板维护、报告管理、用户权限控制、视频关键帧抽取和 AI 辅助撰写能力。

当前实现处于后端化迁移期：登录认证、数据库 Session、工作台统计、报告、模板、字段库、模板图片资源、视频/关键帧文件、用户管理、部门模板授权、系统设置、签名文件、AI 对话和语音听写已接入后端，并已有第一版写操作审计。它适合演示、单机试用或迁移期验证，尚未具备完整生产运维能力。

## 用户角色

| 角色 | 代码值 | 当前能力 |
| --- | --- | --- |
| 超级管理员 | `super` | 管理全部用户、模板、系统设置和全部报告。 |
| 管理员 | `admin` | 管理同部门医生、管理授权模板、查看管理范围内功能。 |
| 医生 | `user` | 新建和管理本人报告，使用授权模板，配置默认模板。 |

## 功能需求

### 登录与初始化

- 首次进入登录页时初始化默认模板、默认用户、表单字段配置、图片资源和系统设置。
- 支持默认测试账号快捷登录。
- 登录调用后端 `/api/auth/login`，后端通过 Session Cookie 维持登录态。
- 用户状态为 `inactive` 时后端禁止登录，前端展示禁用提示。

### 图文报告生成

- 支持选择默认或可见模板创建报告。
- 支持基本信息表单与正文中的 `data-bind` 智能字段双向同步。
- 支持富文本编辑、表格、图片占位符和 AI 可编辑区域。
- 支持上传视频，按系统设置的百分比位置自动抽帧。
- 支持手动截帧、拖拽关键帧到报告占位符、自动插入选定关键帧。
- 支持 AI 对话和 AI 区域改写，改写前显示差异确认。
- 支持通过后端代理进行讯飞语音听写，把识别文本追加到 AI 输入框。
- 支持保存草稿、完成报告、打印和导出。

### 报告管理

- 支持按标题、患者姓名、住院号搜索。
- 支持按状态和时间范围筛选。
- 医生只能看到本人报告；管理员和超级管理员可看到更多报告。
- 支持查看、编辑、删除、历史版本恢复。
- 支持单份或批量通过浏览器打印导出 PDF。

### 模板管理

- 支持模板新增、编辑、删除、批量删除。
- 支持模板内容富文本编辑、智能字段插入、图片占位符、AI 可编辑区域。
- 支持模板导出可回导 HTML 模板包；HTML 包需包含模板正文、模板对应字段和字段管理设置，导入兼容 HTML 模板包和历史 JSON 模板包。
- 支持表单字段库维护，包括字段显示、选项、时间格式、默认值和下划线样式。
- 新增模板后会同步当前用户或部门用户的模板权限。

### 用户管理

- 超级管理员可管理系统用户，并给管理员分配可管理模板。
- 管理员只能管理同部门医生或自己。
- 同一部门只能存在一个管理员，后端创建或修改管理员时会校验。
- 支持上传用户签名图片到后端文件资源，报告中可通过 `surgeonSignature` 字段展示。
- 禁用管理员类账号需要授权密钥。

### 系统设置

- 超级管理员可配置抽帧数量、抽帧百分比、抽帧计算模式和自动插入策略。
- 超级管理员可配置 AI 服务商、接口地址、API Key 和模型名。
- 超级管理员可配置讯飞语音听写参数。
- 所有角色可设置默认报告模板。
- 超级管理员可恢复演示出厂设置；该操作会二次确认后清空当前租户报告、审计、自定义模板和非默认用户，并恢复默认演示账号、模板、AI 和语音配置。

## 非功能需求与约束

- 当前版本对报告、报告媒体引用、模板、字段库、模板图片、视频/关键帧文件、用户、部门权限、系统设置和签名支持多端后端同步。
- 视频仍以对象 URL 方式在浏览器内即时预览，同时后台优先上传服务器；大文件上传、断点续传和独立媒体关系表尚未完成。
- 报告内容使用 HTML 字符串存储，存在 XSS 和内容污染风险。
- 后端账号密码已使用哈希存储，AI/语音密钥已由后端代理使用；但开发回退模式和历史浏览器缓存中仍可能存在 `localStorage.users` 演示密码字段或旧版密钥，不满足生产安全要求。
- 医疗病历属于敏感数据，生产化前必须补齐完整服务端授权、审计、加密、备份和文件存储。