210 lines
11 KiB
Markdown
210 lines
11 KiB
Markdown
# 手术图文病历报告系统 —— Agent 开发指南
|
||
|
||
> 本文件面向 AI 编程助手。修改项目结构、构建流程或关键配置后，请同步更新本文档。
|
||
|
||
---
|
||
|
||
## 项目概览
|
||
|
||
这是一个面向医院场景的**纯前端单页应用（SPA）**，用于手术记录图文报告的撰写、视频关键帧抽取、模板管理以及基于角色的用户权限控制。
|
||
|
||
- **名称**：手术图文病历报告生成终端 / 智能图文报告管理系统
|
||
- **架构**：纯前端应用，无后端服务。所有数据（用户、报告、模板、设置、图片资源）均持久化在浏览器 `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）。
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
.
|
||
├── 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/
|
||
├── main.tsx # 应用入口（React StrictMode + createRoot）
|
||
├── App.tsx # 根组件，定义所有路由（BrowserRouter）
|
||
├── index.css # 全局样式、Tailwind 主题变量、编辑器/打印专用样式
|
||
├── types.ts # TypeScript 类型定义与常量（User、Report、Template、SystemSettings、FormField 等）
|
||
├── components/
|
||
│ └── Sidebar.tsx # 侧边导航栏（角色过滤、折叠逻辑、退出登录）
|
||
├── pages/
|
||
│ ├── 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 封装（JSON 自动序列化）
|
||
├── print.ts # 打印工具：通过隐藏 iframe 渲染 A4 内容并调用 window.print()
|
||
└── defaultContent.ts # 默认报告模板 HTML（含智能字段绑定语法与图片占位符）
|
||
```
|
||
|
||
---
|
||
|
||
## 构建与运行命令
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 本地开发（端口 3000，监听 0.0.0.0）
|
||
npm run dev
|
||
|
||
# 生产构建（输出到 dist/）
|
||
npm run build
|
||
|
||
# 预览生产构建
|
||
npm run preview
|
||
|
||
# 类型检查（不输出文件）
|
||
npm run lint
|
||
|
||
# 清理构建产物
|
||
npm run clean
|
||
```
|
||
|
||
### Docker 部署
|
||
|
||
```bash
|
||
# 构建并运行（访问 http://localhost:4002）
|
||
docker-compose up -d --build
|
||
|
||
# 停止
|
||
docker-compose down
|
||
```
|
||
|
||
构建流程：
|
||
1. **构建阶段**：`node:20-alpine` 执行 `npm ci` + `npm run build`
|
||
2. **运行阶段**：`nginx:alpine` 托管 `dist/` 静态文件，端口 80
|
||
3. `nginx.conf` 已配置 `try_files` 回退，支持 SPA 前端路由刷新不 404。
|
||
|
||
---
|
||
|
||
## 代码组织与模块划分
|
||
|
||
### 路由结构（`src/App.tsx`）
|
||
|
||
| 路径 | 页面 | 角色权限 |
|
||
|------|------|----------|
|
||
| `/` | 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 |
|
||
|
||
### 核心数据模型（`src/types.ts`）
|
||
|
||
- `User`：用户（`role: 'super' | 'admin' | 'user'`）
|
||
- `Report`：报告（含患者信息、手术信息、富文本 `content`、视频数组、抽帧数组 `capturedFrames`、历史记录 `history`）
|
||
- `Template`：模板（名称、描述、富文本 `content`）
|
||
- `SystemSettings`：系统设置（抽帧数量/位置、API 端点、默认模板、自动插帧配置）
|
||
- `FormField` / `FieldType`：表单字段配置（支持文本、单选、多选、时间、日期、签名、图片）
|
||
- `CapturedFrame`：视频关键帧（含视频索引、时间戳、DataURL）
|
||
|
||
### 存储层（`src/utils/storage.ts`）
|
||
|
||
所有业务数据通过 `storage.get<T>(key, fallback)` / `storage.set<T>(key, value)` 读写 `localStorage`（或 `sessionStorage`）。**不存在任何后端 API 调用**。
|
||
|
||
关键存储键：
|
||
- `users` — 用户列表
|
||
- `currentUser` — 当前登录用户
|
||
- `reports` — 报告列表
|
||
- `templates` — 模板列表
|
||
- `systemSettings` — 系统设置
|
||
- `formFieldsConfig` — 表单字段配置
|
||
- `multiSelectOptions` / `anesthesiaOptions` — 下拉选项缓存
|
||
- `imageAssets` — 图片资源库（DataURL）
|
||
- `reportEditorDraft_${username}` — 报告编辑器自动草稿
|
||
- `restore_${reportId}` — 报告恢复临时内容（sessionStorage）
|
||
|
||
---
|
||
|
||
## 核心功能实现细节
|
||
|
||
### 1. 图文报告编辑器（`ReportEditor.tsx`）
|
||
|
||
- **富文本实现**：基于原生 `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` — 医生
|
||
|
||
---
|
||
|
||
## 代码风格指南
|
||
|
||
- **语言**：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` 保存最新状态快照以绕过闭包问题。
|
||
|
||
---
|
||
|
||
## 测试说明
|
||
|
||
**本项目目前未配置任何测试框架**，没有单元测试、集成测试或 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 运行时注入，通常无需手动修改。
|