admin/Mdeical_Sur_Report

Fork 0

Files

admin 9362fa2b81 backup at 2026-04-16-16-39-42

2026-04-16 16:39:42 +08:00

9.9 KiB

Raw Blame History

手术图文病历报告系统 —— AI 代理开发指南

本文档面向 AI 编码代理。若你正在阅读此文件，说明你对该项目一无所知，请仔细阅读后再修改代码。

1. 项目概述

手术图文病历报告系统（Gemini-图文报告系统-V1.1）是一款基于 React 19 + TypeScript + Vite + Tailwind CSS 4 开发的纯前端医疗图文报告管理应用。所有数据持久化在浏览器 localStorage 中，无需后端服务即可独立运行。

核心功能

图文报告生成：基于 contentEditable 的富文本编辑器，支持插入表格、图片占位符，可从本地或手术视频中截取关键帧插入报告。
报告管理：搜索、筛选、查看、编辑、打印、删除报告；支持历史版本回溯。
模板管理：创建和维护报告标准模板，新建报告时自动加载默认模板。
用户管理：基于角色的权限控制（超级管理员 / 管理员 / 医生）。
系统设置：配置视频自动抽帧百分比、AI API 接口地址、默认模板等全局参数。

默认测试账号

账号	密码	角色
admin	123456	超级管理员
manager	123456	管理员
0001	123456	医生

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"）

运行时架构

纯前端 SPA：无后端 API，所有业务逻辑在浏览器端执行。
数据存储：全部使用 localStorage（通过 src/utils/storage.ts 封装）和少量 sessionStorage（用于版本恢复）。
安全模型：客户端认证授权，密码以明文形式保存在 localStorage 中。项目设计用于内网或受信任环境，切勿直接暴露到公网。

3. 项目目录结构

.
├── docker-compose.yaml      # Docker Compose 配置（端口 8080:80）
├── docker-compose.qnap.yml  # QNAP 专用 Docker Compose
├── 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）
└── src/
    ├── App.tsx              # 根组件与路由表
    ├── main.tsx             # 应用入口（createRoot + StrictMode）
    ├── index.css            # 全局样式、Tailwind 主题、打印样式、编辑器专用样式
    ├── types.ts             # 核心 TypeScript 类型定义
    ├── components/
    │   └── Sidebar.tsx      # 左侧导航栏（按角色过滤菜单）
    ├── pages/
    │   ├── Login.tsx        # 登录页（初始化默认数据）
    │   ├── Dashboard.tsx    # 工作台概览（统计图表 + 快捷入口）
    │   ├── ReportEditor.tsx # 图文报告编辑器（最复杂的页面）
    │   ├── ReportManage.tsx # 报告列表管理
    │   ├── ReportView.tsx   # 报告查看/打印
    │   ├── TemplateManage.tsx # 模板管理
    │   ├── UserManage.tsx   # 用户管理
    │   └── SystemSettings.tsx # 系统设置
    └── utils/
        ├── storage.ts       # localStorage/sessionStorage 封装
        ├── print.ts         # 基于 iframe 的 A4 打印实现
        └── defaultContent.ts # 默认手术报告模板 HTML 字符串

4. 构建、运行与部署

本地开发

# 安装依赖
npm install

# 启动开发服务器（端口 3000，监听 0.0.0.0）
npm run dev

可用脚本（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 部署

# 构建并启动（访问 http://localhost:8080）
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;

5. 代码组织与开发约定

路由结构

所有路由定义在 src/App.tsx：

/ → 登录页
/dashboard → 工作台
/report-editor → 新建报告（?id=xxx 为编辑）
/report-view/:id → 查看报告
/report-manage → 报告管理
/template-manage → 模板管理
/user-manage → 用户管理
/system-settings → 系统设置

权限模型

角色分为三种：super（超级管理员）、admin（管理员）、user（医生）。

各页面在 useEffect 中读取 storage.get('currentUser')，未登录则 navigate('/')。
Sidebar.tsx 的 navItems 按 roles 数组过滤菜单。
user 角色只能查看/编辑自己创建的报告；super/admin 可查看全院报告。

数据持久化约定

禁止直接调用 localStorage，统一使用 src/utils/storage.ts 中的 storage.get / storage.set / storage.remove。
localStorage 中存储的 key 包括：users、reports、templates、systemSettings、currentUser、multiSelectOptions、anesthesiaOptions、reportEditorDraft_{username}、restore_{reportId}（sessionStorage）。
报告编辑器会在 beforeunload 和 visibilitychange 时自动保存草稿到 reportEditorDraft_{username}。

样式约定

全局使用 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 区域。

编辑器实现细节

ReportEditor.tsx 使用原生 contentEditable + document.execCommand 实现富文本，而非第三方编辑器。
图片通过 .image-placeholder 占位符插入，支持两种填充方式：
1. 点击占位符上传本地图片（Base64 存入 HTML）。
2. 从右侧“视频分析”面板拖拽自动抽帧的截图到占位符中。
视频中上传后会根据 systemSettings.framePositions 自动抽帧（通过 <video> + <canvas> 实现）。

TypeScript 类型

核心类型定义在 src/types.ts：

User：用户，角色为 'super' | 'admin' | 'user'
Report：报告，状态为 'draft' | 'completed'，含 content（HTML 字符串）
Template：模板，结构与报告内容类似
SystemSettings：系统设置，含 frameCount、framePositions、apiEndpoint 等
CapturedFrame：视频抽帧结果

路径别名

vite.config.ts 和 tsconfig.json 均配置了 @/ 指向项目根目录（.）。
源码中导入使用相对路径（如 ../utils/storage）或 @/ 均可。

6. 测试策略

当前项目没有单元测试或 E2E 测试框架。

唯一可用的质量检查命令是 npm run lint，它执行 tsc --noEmit 进行全量类型检查。
在修改代码后，务必运行 npm run lint 确保无 TypeScript 编译错误。
若你引入了新依赖或修改了复杂交互逻辑，建议在本地通过 npm run dev 进行手工功能验证（可快速使用登录页的“快捷登录测试账号”）。

7. 安全与部署注意事项

安全警告（必读）

无后端哈希：用户密码以明文保存在浏览器 localStorage 中。
客户端鉴权：所有权限判断都在前端执行，易被绕过。
因此，该应用仅适合部署在医院内网、受信任的局域网或单人使用的环境中，严禁直接暴露于公网。

部署检查清单

nginx.conf 中的 try_files 确保 SPA 刷新不 404。
dist/ 构建产物已包含在 Docker 镜像中。
若启用 AI 功能，需正确配置 GEMINI_API_KEY 环境变量（Vite 在构建时注入，修改后需重新构建）。
确保最终运行环境可访问 https://fonts.googleapis.com/css2?family=Inter（否则页面字体会降级为系统默认字体）。

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 中配置菜单和可见角色。

9.9 KiB Raw Blame History Unescape Escape