Merge remote V1.2.0 and add local V1.2.1

AGENTS.md

@@ -1,208 +1,209 @@
-# 手术图文病历报告系统 —— AI 代理开发指南
+# 手术图文病历报告系统 —— Agent 开发指南
 
-> 本文档面向 AI 编码代理。若你正在阅读此文件，说明你对该项目一无所知，请仔细阅读后再修改代码。
+> 本文件面向 AI 编程助手。修改项目结构、构建流程或关键配置后，请同步更新本文档。
 
 ---
 
-## 1. 项目概述
+## 项目概览
 
-**手术图文病历报告系统**是一款基于 **React 19 + TypeScript + Vite + Tailwind CSS 4** 开发的纯前端医疗图文报告管理应用。所有数据持久化在浏览器 `localStorage` 中，无需后端服务即可独立运行。
+这是一个面向医院场景的**纯前端单页应用（SPA）**，用于手术记录图文报告的撰写、视频关键帧抽取、模板管理以及基于角色的用户权限控制。
 
-### 核心功能
-- **图文报告生成**：基于 `contentEditable` 的富文本编辑器，支持插入表格、图片占位符，可从本地或手术视频中截取关键帧插入报告。
-- **报告管理**：搜索、筛选、查看、编辑、打印、删除报告；支持历史版本回溯。
-- **模板管理**：创建和维护报告标准模板，新建报告时自动加载默认模板。
-- **用户管理**：基于角色的权限控制（超级管理员 / 管理员 / 医生）。
-- **系统设置**：配置视频自动抽帧百分比、AI API 接口地址、默认模板等全局参数。
-
-### 默认测试账号
-| 账号    | 密码   | 角色       |
-|---------|--------|------------|
-| admin   | 123456 | 超级管理员 |
-| manager | 123456 | 管理员     |
-| 0001    | 123456 | 医生       |
+- **名称**：手术图文病历报告生成终端 / 智能图文报告管理系统
+- **架构**：纯前端应用，无后端服务。所有数据（用户、报告、模板、设置、图片资源）均持久化在浏览器 `localStorage` / `sessionStorage` 中。
+- **技术栈**：React 19 + TypeScript 5.8 + Vite 6 + Tailwind CSS 4 + React Router DOM 7 + Lucide React（图标）
+- **语言**：项目界面、注释、文档均为中文。
+- **运行环境**：现代浏览器（依赖 `localStorage`、`URL.createObjectURL`、`contenteditable`、`MutationObserver` 等 Web API）。
 
 ---
 
-## 2. 技术栈与运行时架构
-
-### 技术栈
-- **框架**：React 19（函数组件 + Hooks）
-- **路由**：React Router DOM 7（`BrowserRouter`）
-- **构建工具**：Vite 6
-- **样式**：Tailwind CSS 4（使用 `@import "tailwindcss"` 和 `@theme` 语法）
-- **图标**：Lucide React
-- **动画**：Motion
-- **语言**：TypeScript 5.8（`tsconfig.json` 中 `jsx: "react-jsx"`、`moduleResolution: "bundler"`）
-- **其他依赖**：`@google/genai`（预留 AI 功能）
-
-### 运行时架构
-- **纯前端 SPA**：无后端 API，所有业务逻辑在浏览器端执行。
-- **数据存储**：全部使用 `localStorage`（通过 `src/utils/storage.ts` 封装）和少量 `sessionStorage`（用于版本恢复）。
-- **安全模型**：客户端认证授权，密码以**明文**形式保存在 `localStorage` 中。项目设计用于内网或受信任环境，**切勿直接暴露到公网**。
-
----
-
-## 3. 项目目录结构
+## 项目结构
 
 ```
 .
-├── docker-compose.yaml      # Docker Compose 配置（端口 4002:80）
-├── Dockerfile               # 多阶段构建：node:20-alpine -> nginx:alpine
-├── nginx.conf               # Nginx SPA 回退配置（try_files）
-├── package.json             # 依赖与脚本
-├── vite.config.ts           # Vite 配置（含 GEMINI_API_KEY 注入）
-├── tsconfig.json            # TypeScript 配置（paths: "@/*": "./*"）
-├── index.html               # Vite 入口 HTML
-├── public/                  # 静态资源（logo、favicon）
+├── docker-compose.yaml    # Docker Compose 配置（端口 4002:80）
+├── Dockerfile             # 多阶段构建：node:20-alpine 构建 → nginx:alpine 运行
+├── nginx.conf             # Nginx SPA 路由回退配置（try_files）
+├── package.json           # 项目依赖与脚本
+├── vite.config.ts         # Vite 配置（含 Tailwind CSS 插件、路径别名 @）
+├── tsconfig.json          # TypeScript 配置（ES2022、react-jsx、paths: {"@/*": ["./*"] }）
+├── index.html             # Vite 入口 HTML
+├── public/                # 静态资源（logo_square.png、favicon.ico）
 └── src/
-    ├── App.tsx              # 根组件与路由表
-    ├── main.tsx             # 应用入口（createRoot + StrictMode）
-    ├── index.css            # 全局样式、Tailwind 主题、打印样式、编辑器专用样式
-    ├── types.ts             # 核心 TypeScript 类型定义
+    ├── main.tsx           # 应用入口（React StrictMode + createRoot）
+    ├── App.tsx            # 根组件，定义所有路由（BrowserRouter）
+    ├── index.css          # 全局样式、Tailwind 主题变量、编辑器/打印专用样式
+    ├── types.ts           # TypeScript 类型定义与常量（User、Report、Template、SystemSettings、FormField 等）
     ├── components/
-    │   └── Sidebar.tsx      # 左侧导航栏（按角色过滤菜单）
+    │   └── Sidebar.tsx    # 侧边导航栏（角色过滤、折叠逻辑、退出登录）
     ├── pages/
-    │   ├── Login.tsx        # 登录页（初始化默认数据）
-    │   ├── Dashboard.tsx    # 工作台概览（统计图表 + 快捷入口）
-    │   ├── ReportEditor.tsx # 图文报告编辑器（最复杂的页面，约 1400+ 行）
-    │   ├── ReportManage.tsx # 报告列表管理
-    │   ├── ReportView.tsx   # 报告查看/打印
-    │   ├── TemplateManage.tsx # 模板管理
-    │   ├── UserManage.tsx   # 用户管理
-    │   └── SystemSettings.tsx # 系统设置
+    │   ├── Login.tsx          # 登录页 + 默认数据初始化（用户、模板、表单字段、系统设置）
+    │   ├── Dashboard.tsx      # 工作台概览（统计卡片、7 天趋势 SVG 图表、快捷入口）
+    │   ├── ReportEditor.tsx   # 图文报告编辑器（最核心、最复杂页面，2000+ 行）
+    │   ├── ReportManage.tsx   # 报告管理（搜索、筛选、查看、编辑、删除、历史、导出）
+    │   ├── ReportView.tsx     # 报告只读查看 + 打印
+    │   ├── TemplateManage.tsx # 模板管理（富文本编辑器、字段库管理、图片占位符）
+    │   ├── UserManage.tsx     # 用户管理（CRUD、签名上传、角色/模板权限分配）
+    │   └── SystemSettings.tsx # 系统设置（视频抽帧参数、API 地址、默认模板）
     └── utils/
-        ├── storage.ts       # localStorage/sessionStorage 封装
-        ├── print.ts         # 基于 iframe 的 A4 打印实现
-        └── defaultContent.ts # 默认手术报告模板 HTML 字符串
+        ├── storage.ts         # localStorage / sessionStorage 封装（JSON 自动序列化）
+        ├── print.ts           # 打印工具：通过隐藏 iframe 渲染 A4 内容并调用 window.print()
+        └── defaultContent.ts  # 默认报告模板 HTML（含智能字段绑定语法与图片占位符）
 ```
 
 ---
 
-## 4. 构建、运行与部署
+## 构建与运行命令
 
-### 本地开发
 ```bash
 # 安装依赖
 npm install
 
-# 启动开发服务器（端口 3000，监听 0.0.0.0）
+# 本地开发（端口 3000，监听 0.0.0.0）
 npm run dev
+
+# 生产构建（输出到 dist/）
+npm run build
+
+# 预览生产构建
+npm run preview
+
+# 类型检查（不输出文件）
+npm run lint
+
+# 清理构建产物
+npm run clean
 ```
 
-### 可用脚本（package.json）
-| 脚本      | 作用                              |
-|-----------|-----------------------------------|
-| `dev`     | `vite --port=3000 --host=0.0.0.0` |
-| `build`   | `vite build`（输出到 `dist/`）    |
-| `preview` | `vite preview`                    |
-| `lint`    | `tsc --noEmit`（类型检查）        |
-| `clean`   | `rm -rf dist`                     |
-
-### 环境变量
-复制 `.env.example` 为 `.env.local`（或 `.env`）：
-- `GEMINI_API_KEY`：Google Gemini API 密钥（预留 AI 功能，Vite 会在构建时通过 `define` 注入为 `process.env.GEMINI_API_KEY`）。
-- `APP_URL`：应用部署后的访问地址。
-
 ### Docker 部署
+
 ```bash
-# 构建并启动（访问 http://localhost:4002）
+# 构建并运行（访问 http://localhost:4002）
 docker-compose up -d --build
 
 # 停止
 docker-compose down
 ```
-- **构建阶段**：`node:20-alpine` 执行 `npm ci` + `npm run build`
-- **运行阶段**：`nginx:alpine` 托管 `dist/` 静态资源
-- **SPA 支持**：`nginx.conf` 已配置 `try_files $uri $uri/ /index.html;`
+
+构建流程：
+1. **构建阶段**：`node:20-alpine` 执行 `npm ci` + `npm run build`
+2. **运行阶段**：`nginx:alpine` 托管 `dist/` 静态文件，端口 80
+3. `nginx.conf` 已配置 `try_files` 回退，支持 SPA 前端路由刷新不 404。
 
 ---
 
-## 5. 代码组织与开发约定
+## 代码组织与模块划分
 
-### 路由结构
-所有路由定义在 `src/App.tsx`：
-- `/` → 登录页
-- `/dashboard` → 工作台
-- `/report-editor` → 新建报告（`?id=xxx` 为编辑）
-- `/report-view/:id` → 查看报告
-- `/report-manage` → 报告管理
-- `/template-manage` → 模板管理
-- `/user-manage` → 用户管理
-- `/system-settings` → 系统设置
+### 路由结构（`src/App.tsx`）
 
-### 权限模型
-角色分为三种：`super`（超级管理员）、`admin`（管理员）、`user`（医生）。
-- 各页面在 `useEffect` 中读取 `storage.get('currentUser')`，未登录则 `navigate('/')`。
-- `Sidebar.tsx` 的 `navItems` 按 `roles` 数组过滤菜单。
-- `user` 角色只能查看/编辑自己创建的报告；`super`/`admin` 可查看全院报告。
-- `admin` 只能管理同部门（`department`）的 `user` 角色用户，且一个部门只能有一个管理员。
-- 用户对象包含 `visibleTemplates`（可视模板）和 `manageableTemplates`（可管理模板）数组，用于细粒度模板权限控制。
+| 路径 | 页面 | 角色权限 |
+|------|------|----------|
+| `/` | Login | 公开 |
+| `/dashboard` | Dashboard | super / admin / user |
+| `/report-editor` | ReportEditor | super / admin / user |
+| `/report-manage` | ReportManage | super / admin / user |
+| `/report-view/:id` | ReportView | super / admin / user（user 只能看自己的） |
+| `/template-manage` | TemplateManage | super / admin |
+| `/user-manage` | UserManage | super / admin |
+| `/system-settings` | SystemSettings | super / admin / user |
 
-### 数据持久化约定
-- **禁止直接调用 `localStorage`**，统一使用 `src/utils/storage.ts` 中的 `storage.get / storage.set / storage.remove`。
-- localStorage 中存储的 key 包括：`users`、`reports`、`templates`、`systemSettings`、`currentUser`、`multiSelectOptions`、`anesthesiaOptions`、`reportEditorDraft_{username}`。
-- sessionStorage 中存储的 key 包括：`restore_{reportId}`（用于历史版本恢复）。
-- 报告编辑器会在 `beforeunload` 和 `visibilitychange` 时自动保存草稿到 `reportEditorDraft_{username}`。
+### 核心数据模型（`src/types.ts`）
 
-### 样式约定
-- 全局使用 Tailwind 工具类；自定义设计变量定义在 `src/index.css` 的 `@theme` 中（如 `--color-bg`、`--color-accent`）。
-- 通用组件类在 `index.css` 的 `@layer components` 中定义：`.btn-accent`、`.card-minimal`、`.input-minimal`。
-- **编辑器样式**（`.editor-content`、`.editor-content-wrapper`、`.image-placeholder`）和 **打印样式**（`@media print`）集中在 `index.css` 中维护。
-- A4 打印尺寸为 `210mm × 297mm`，打印时通过 `visibility` 控制只显示 `.print-content` 区域。
+- `User`：用户（`role: 'super' | 'admin' | 'user'`）
+- `Report`：报告（含患者信息、手术信息、富文本 `content`、视频数组、抽帧数组 `capturedFrames`、历史记录 `history`）
+- `Template`：模板（名称、描述、富文本 `content`）
+- `SystemSettings`：系统设置（抽帧数量/位置、API 端点、默认模板、自动插帧配置）
+- `FormField` / `FieldType`：表单字段配置（支持文本、单选、多选、时间、日期、签名、图片）
+- `CapturedFrame`：视频关键帧（含视频索引、时间戳、DataURL）
 
-### 编辑器实现细节
-- `ReportEditor.tsx` 和 `TemplateManage.tsx` 使用原生 `contentEditable` + `document.execCommand` 实现富文本，而非第三方编辑器。
-- 图片通过 `.image-placeholder` 占位符插入，支持两种填充方式：
-  1. 点击占位符上传本地图片（Base64 存入 HTML）。
-  2. 从右侧“视频分析”面板拖拽自动抽帧的截图到占位符中。
-- 视频中上传后会根据 `systemSettings.framePositions` 自动抽帧（通过 `<video>` + `<canvas>` 实现）。
-- 自动抽帧支持“自动帧插入”功能：开启后，抽得的帧会按延迟顺序自动填入编辑器中的空图片占位符。
+### 存储层（`src/utils/storage.ts`）
 
-### TypeScript 类型
-核心类型定义在 `src/types.ts`：
-- `User`：用户，角色为 `'super' | 'admin' | 'user'`，含 `visibleTemplates` 和 `manageableTemplates`
-- `Report`：报告，状态为 `'draft' | 'completed'`，含 `content`（HTML 字符串）、`videos`、`capturedFrames`、`history`
-- `Template`：模板，结构与报告内容类似
-- `SystemSettings`：系统设置，含 `frameCount`、`framePositions`、`apiEndpoint`、`apiKey`、`defaultTemplate`、`frameMode`、`autoInsertFrames`、`autoInsertFrameIndices`、`autoInsertDelay`
-- `CapturedFrame`：视频抽帧结果，含 `dataUrl`、`isManual` 等
+所有业务数据通过 `storage.get<T>(key, fallback)` / `storage.set<T>(key, value)` 读写 `localStorage`（或 `sessionStorage`）。**不存在任何后端 API 调用**。
 
-### 路径别名
-- `vite.config.ts` 和 `tsconfig.json` 均配置了 `@/` 指向项目根目录（`.`）。
-- 源码中导入使用相对路径（如 `../utils/storage`）或 `@/` 均可。
+关键存储键：
+- `users` — 用户列表
+- `currentUser` — 当前登录用户
+- `reports` — 报告列表
+- `templates` — 模板列表
+- `systemSettings` — 系统设置
+- `formFieldsConfig` — 表单字段配置
+- `multiSelectOptions` / `anesthesiaOptions` — 下拉选项缓存
+- `imageAssets` — 图片资源库（DataURL）
+- `reportEditorDraft_${username}` — 报告编辑器自动草稿
+- `restore_${reportId}` — 报告恢复临时内容（sessionStorage）
 
 ---
 
-## 6. 测试策略
+## 核心功能实现细节
 
-**当前项目没有单元测试或 E2E 测试框架。**
+### 1. 图文报告编辑器（`ReportEditor.tsx`）
 
-- 唯一可用的质量检查命令是 `npm run lint`，它执行 `tsc --noEmit` 进行全量类型检查。
-- 在修改代码后，**务必运行 `npm run lint` 确保无 TypeScript 编译错误**。
-- 若你引入了新依赖或修改了复杂交互逻辑，建议在本地通过 `npm run dev` 进行手工功能验证（可快速使用登录页的“快捷登录测试账号”）。
+- **富文本实现**：基于原生 `contenteditable` div，通过 `document.execCommand` 实现加粗、斜体、下划线、对齐、插入表格等。
+- **A4 纸模拟**：编辑器内容区固定宽度 `210mm`，最小高度 `297mm`，通过 `MutationObserver` 动态扩展为多页。
+- **图片占位符**：`.image-placeholder` 元素，支持点击上传、拖入视频关键帧、或自动插入抽帧结果。占位符分为 `data-mode="frame"`（可拖入关键帧）和 `data-mode="manual"`（仅手动上传，如 Logo、签名）。
+- **智能字段绑定**：模板中可插入 `<span class="smart-field-wrapper" data-bind="key">`，在报告编辑器左侧表单填写后，通过 DOM 查询同步更新编辑器内对应字段值。
+- **视频抽帧**：支持上传本地视频（`URL.createObjectURL`），可手动截图或按百分比位置自动均匀抽帧（`autoCaptureFrames`）。抽帧结果支持拖入编辑器占位符。
+- **自动草稿**：在 `beforeunload` / `visibilitychange` / 状态变更时自动保存草稿到 `localStorage`。
+- **打印**：调用 `printDocument()` 将编辑器 HTML 注入隐藏 iframe 并触发打印；`@media print` 样式隐藏所有非打印元素。
+
+### 2. 模板管理（`TemplateManage.tsx`）
+
+- 与报告编辑器共享相似的 `contenteditable` 编辑体验。
+- 额外支持**字段库管理**：可插入/编辑/删除表单字段，字段变更会同步到 `formFieldsConfig`。
+- 模板内容即为 HTML 字符串，存储在 `templates` localStorage 键中。
+
+### 3. 用户与权限（`Login.tsx`、`UserManage.tsx`、`Sidebar.tsx`）
+
+- **角色体系**：
+  - `super`（超级管理员）：拥有所有权限，可管理所有用户。
+  - `admin`（管理员）：可管理同科室的 `user` 角色用户。
+  - `user`（医生）：只能查看/编辑自己创建的报告。
+- **权限控制**：路由跳转前检查 `currentUser.role`；Sidebar 根据角色过滤导航项；页面内根据角色隐藏按钮或重定向。
+- **默认账号**（首次登录或数据缺失时自动初始化）：
+  - `admin` / `123456` — 超级管理员
+  - `manager` / `123456` — 管理员
+  - `0001` / `123456` — 医生
 
 ---
 
-## 7. 安全与部署注意事项
+## 代码风格指南
 
-### 安全警告（必读）
-1. **无后端哈希**：用户密码以明文保存在浏览器 `localStorage` 中。
-2. **客户端鉴权**：所有权限判断都在前端执行，易被绕过。
-3. **因此，该应用仅适合部署在医院内网、受信任的局域网或单人使用的环境中，严禁直接暴露于公网。**
-
-### 部署检查清单
-- [ ] `nginx.conf` 中的 `try_files` 确保 SPA 刷新不 404。
-- [ ] `dist/` 构建产物已包含在 Docker 镜像中。
-- [ ] 若启用 AI 功能，需正确配置 `GEMINI_API_KEY` 环境变量（Vite 在构建时注入，修改后需重新构建）。
-- [ ] 确保最终运行环境可访问 `https://fonts.googleapis.com/css2?family=Inter`（否则页面字体会降级为系统默认字体）。
+- **语言**：TypeScript，严格模式未开启（`noEmit: true`），但代码中广泛使用显式类型注解。
+- **组件风格**：函数组件 + React Hooks，所有页面组件默认导出。
+- **CSS**：Tailwind CSS 工具类为主，复杂样式（如 `contenteditable` 内部元素、打印样式）写在 `src/index.css` 的 `@layer components` 中。
+- **路径别名**：`@/` 指向项目根目录（`vite.config.ts` 与 `tsconfig.json` 均已配置）。
+- **图标**：统一使用 `lucide-react`。
+- **事件处理**：原生 DOM 事件与 React 事件混用（编辑器内大量直接使用 `document.execCommand`、`addEventListener`）。
+- **状态管理**：无 Redux/Zustand，所有状态以 React `useState` + `useRef` + `useEffect` 管理，复杂页面（如 ReportEditor）使用 `useRef` 保存最新状态快照以绕过闭包问题。
 
 ---
 
-## 8. 给 AI 代理的快速备忘
+## 测试说明
 
-- **不要直接操作 `localStorage`**，用 `src/utils/storage.ts`。
-- **不要引入重型富文本编辑器**，现有方案基于 `contentEditable` + `document.execCommand`，保持轻量。
-- **打印逻辑**已封装在 `src/utils/print.ts`，需要打印 A4 报告时直接调用 `printDocument(htmlContent)`。
-- **修改样式时优先检查 `src/index.css`**，Tailwind v4 的主题变量和打印样式都在那里。
-- **添加新页面后**，记得在 `src/App.tsx` 注册路由，并在 `src/components/Sidebar.tsx` 的 `navItems` 中配置菜单和可见角色。
-- **修改 Docker 端口映射时**，同步更新 `docker-compose.yaml` 和本文件中的说明。
+**本项目目前未配置任何测试框架**，没有单元测试、集成测试或 E2E 测试。
+
+如需添加测试，建议：
+- 单元测试：Vitest（与 Vite 生态一致）
+- 组件测试：React Testing Library
+- E2E 测试：Playwright（测试 `localStorage` 持久化、文件上传、打印流程等）
+
+---
+
+## 安全注意事项
+
+> ⚠️ **关键警告**：本应用为纯前端实现，所有认证与授权逻辑均在客户端执行。
+
+- 用户密码以**明文**形式存储在浏览器 `localStorage` 中，无任何哈希或加密处理。
+- 权限控制依赖客户端路由守卫和 UI 隐藏，可被技术手段绕过。
+- 所有报告数据、视频对象 URL、图片 DataURL 均保存在用户本地浏览器中，无云端备份。
+- **生产环境部署建议**：仅限内网或受信任环境使用，不要直接暴露于公网。
+- 环境变量 `.env.local` 中的 `GEMINI_API_KEY` 仅用于预留的 AI 功能，当前主业务逻辑未实际调用 Gemini API。
+
+---
+
+## 常见开发注意事项
+
+1. **编辑器内容初始化**：`ReportEditor.tsx` 中编辑器 `innerHTML` 的初始化逻辑分散在 `useEffect`（基于 reportId / draft）和 `useLayoutEffect`（安全兜底）中，修改时需注意两者优先级，避免内容被覆盖。
+2. **视频对象 URL 生命周期**：通过 `URL.createObjectURL()` 创建的视频 URL 仅在当前会话有效，刷新页面后视频需重新上传。报告保存时仅保留视频元数据（名称、时长），不保存视频文件本身。
+3. **打印样式**：`@media print` 规则定义在 `src/index.css` 中，修改编辑器内元素类名时，需同步检查打印样式是否失效。
+4. **Tailwind CSS v4**：本项目使用 Tailwind CSS 4（`@import "tailwindcss"` + `@theme`），与 v3 的 `tailwind.config.js` 方式不兼容，请勿混用旧版配置。
+5. **HMR 特殊处理**：`vite.config.ts` 中根据 `DISABLE_HMR` 环境变量控制 HMR 开关，该变量由 AI Studio 运行时注入，通常无需手动修改。