# 智慧医院 AI 影像诊断与电子病历辅助决策系统

## 项目详细文档

| 项目 | 说明 |
|------|------|
| 项目名称 | 智慧医院 AI 影像诊断与电子病历辅助决策系统（Smart Hospital） |
| 项目类型 | 高校/实训教学演示级 Web 应用 |
| 文档版本 | 1.0 |
| 文档日期 | 2026-07-27 |
| 代码根目录 | `smart-hospital/` |

---

## 目录

1. [项目主题](#一项目主题)
2. [需求分析](#二需求分析)
3. [项目功能](#三项目功能)
4. [技术栈](#四技术栈)
5. [系统架构](#五系统架构)
6. [目录与模块结构](#六目录与模块结构)
7. [核心业务流程](#七核心业务流程)
8. [数据模型概要](#八数据模型概要)
9. [接口与权限](#九接口与权限)
10. [部署与运行](#十部署与运行)
11. [演示账号与推荐路径](#十一演示账号与推荐路径)
12. [设计说明与边界](#十二设计说明与边界)

---

## 一、项目主题

### 1.1 主题定位

本项目以 **「智慧医院」** 为主题，围绕医院日常诊疗中的两条核心链路展开：

1. **医学影像检查 → AI 辅助读片 → 结构化诊断报告**
2. **电子病历录入 → AI 辅助决策（治疗 / 用药 / 护理 / 随访）→ 知识库引用**

在传统 HIS（医院信息系统）业务能力之上，引入 **计算机视觉（YOLO）** 与 **大语言模型 / RAG 知识检索**，形成「业务系统 + AI 微服务」的混合架构，用于实训教学、课程答辩与功能演示。

### 1.2 建设目标

| 目标 | 说明 |
|------|------|
| 业务闭环 | 覆盖登录鉴权、患者档案、影像检查、病历、预约挂号、用户管理等完整业务面 |
| AI 可演示 | 影像侧可真实跑 YOLO 权重检测；报告与决策侧可接 DeepSeek 等 OpenAI 兼容大模型，也可模板降级 |
| 前后端分离 | Vue 3 SPA + Spring Boot REST + FastAPI AI 服务，职责清晰、便于分模块讲解 |
| 可离线实训 | 默认 H2 内存库，无需强制安装 MySQL；AI 服务不可用时业务仍可降级运行 |
| 安全可讲 | JWT 无状态认证、角色权限（ADMIN / DOCTOR / RADIOLOGIST）、BCrypt 密码、前后端双重路由守卫 |

### 1.3 应用场景（教学/演示）

- 影像科：上传胸片等影像 → 一键 AI 诊断 → 查看 YOLO 标注框、置信度与分段报告
- 临床医生：书写病历（如含「高血压 / 肺炎 / 糖尿病 / 结节」等关键词）→ 获取治疗、护理、随访建议与知识库来源
- 管理员：配置 LLM 接口、管理知识库文档、切换/上传 YOLO 权重、管理系统用户
- 挂号窗口：预约登记与状态流转（预约 → 确认 → 完成 / 取消 / 未到诊）

### 1.4 项目声明

> 本系统输出内容 **仅供教学实训与辅助决策演示**，**不能替代执业医师的正式诊断与医疗文书**。涉及真实患者数据与临床部署时，需另行满足医疗信息化、隐私与合规要求。

---

## 二、需求分析

### 2.1 背景与问题

传统教学型医院管理系统往往只做 CRUD 与简单页面，存在以下不足：

| 问题 | 表现 |
|------|------|
| 业务割裂 | 患者、影像、病历、预约缺少统一档案视图 |
| AI 仅「假数据」 | 随机文案或关键字匹配，无法展示真实检测框与模型链路 |
| 技术栈陈旧 | 早期版本以 Thymeleaf 服务端渲染为主，前后端耦合 |
| 权限薄弱 | 仅 Session 判断登录，缺少角色级接口保护 |
| 不可降级 | 外部依赖一旦失败，整条演示链路中断 |

本项目在原始 Spring Boot + Thymeleaf 原型基础上完成改造，形成当前 **前后端分离 + AI 微服务** 版本，以解决上述问题。

### 2.2 用户角色与诉求

| 角色 | 代码枚举 | 核心诉求 |
|------|----------|----------|
| 系统管理员 | `ADMIN` | 用户管理、AI 大模型配置、YOLO 权重管理、全局运维 |
| 临床医生 | `DOCTOR` | 患者与病历、辅助决策、预约、查看影像报告 |
| 影像医师 | `RADIOLOGIST` | 影像登记、上传、触发 AI 诊断、审阅标注图与报告 |
| 访客/未登录 | — | 仅可访问登录页 |

### 2.3 功能需求（按优先级）

#### P0 — 必须具备

| 编号 | 需求 | 验收要点 |
|------|------|----------|
| F-01 | 用户登录 / 登出 / 修改密码 | JWT 签发与校验；密码 BCrypt；修改后需重新登录 |
| F-02 | 患者档案 CRUD + 搜索分页 | 姓名等关键字；360° 档案关联影像 / 病历 / 预约 |
| F-03 | 影像检查 CRUD + 文件上传 | 支持 X_RAY / CT / MRI / ULTRASOUND |
| F-04 | AI 影像诊断 | 异步状态机 `PENDING → ANALYZING → COMPLETED / ERROR`；可查看结果 |
| F-05 | 电子病历 CRUD + AI 辅助决策 | 治疗 / 用药 / 护理 / 随访 / 风险 / 冲突 / RAG 来源 |
| F-06 | 角色权限控制 | 前端路由 `meta.roles` + 后端 `@PreAuthorize` |

#### P1 — 重要增强

| 编号 | 需求 | 验收要点 |
|------|------|----------|
| F-07 | 预约挂号全流程 | 状态流转、按日筛选、统计卡片 |
| F-08 | 仪表盘可视化 | KPI、近 7 日趋势、检查类型/诊断状态分布 |
| F-09 | AI 对话助手 | 多轮对话、历史持久化（文件）、Markdown 渲染 |
| F-10 | 知识库管理 | 文档增删改查，供 RAG / 决策引用 |
| F-11 | AI 配置（管理员） | LLM Base URL / API Key / Model 配置，并同步至 FastAPI |
| F-12 | YOLO 权重管理（管理员） | 权重列表、激活、上传统计 |

#### P2 — 体验与健壮性

| 编号 | 需求 | 验收要点 |
|------|------|----------|
| F-13 | AI 服务不可用时业务降级 | Spring 侧本地规则模拟，页面仍可演示 |
| F-14 | 弹窗 / 抽屉不被布局裁切 | `append-to-body`、限高滚动、表单左右留白协调 |
| F-15 | 报告分段可读 | 影像所见 / 诊断印象 / 建议 / 声明分块展示 |
| F-16 | 页面切换过渡与仪表盘体验 | 路由过渡、半透明卡片叠背景图等 |

### 2.4 非功能需求

| 类别 | 要求 | 项目落地 |
|------|------|----------|
| 性能 | 诊断异步，避免阻塞 HTTP 线程 | `@Async` + 线程池；前端轮询（有上限，卸载时清理） |
| 可用性 | 无 MySQL 亦可演示 | 默认 H2 内存库 + `DataInitializer` 种子数据 |
| 安全 | 接口鉴权、密码加密、CORS 白名单 | Spring Security + JWT；`cors.allowed-origins` |
| 可维护 | 统一响应与异常 | `Result<T>` + `GlobalExceptionHandler` |
| 可扩展 | AI 与业务解耦 | FastAPI 独立进程；配置 `ai.service.base-url` |
| 兼容 | 大模型厂商可切换 | OpenAI 兼容协议（DeepSeek / Qwen 等） |

### 2.5 约束与假设

- 面向 **实训 / 课程设计 / 答辩演示**，非生产级 HIS 或 PACS 替代品。
- 医学影像以常见图片格式为主（JPG / PNG 等），DICOM 完整工作流未作为重点。
- YOLO 权重与检测类别为演示级配置，输出置信度与框选结果需医师复核。
- H2 内存模式下进程退出即丢库内业务数据；AI 配置与对话历史另存 `./data/ai/` 文件，可跨重启保留。

---

## 三、项目功能

### 3.1 功能总览

```
┌─────────────────────────────────────────────────────────────────┐
│                        智慧医院功能全景                           │
├──────────────┬──────────────┬──────────────┬────────────────────┤
│  身份与权限   │  业务主数据   │  诊疗业务     │  智能能力            │
├──────────────┼──────────────┼──────────────┼────────────────────┤
│ 登录 / JWT   │ 患者管理     │ 影像检查     │ YOLO 影像检测       │
│ 修改密码     │ 用户管理     │ 电子病历     │ AI 诊断报告         │
│ 角色菜单     │ 知识库文档   │ 预约挂号     │ EMR 辅助决策 + RAG  │
│ 头像上传     │              │ 仪表盘统计   │ AI 对话助手         │
│              │              │              │ LLM / YOLO 管理端   │
└──────────────┴──────────────┴──────────────┴────────────────────┘
```

### 3.2 功能模块详述

#### 3.2.1 登录与个人中心

- 账号密码登录，返回 JWT 与用户信息，前端 `localStorage` 持久化（约 24h 过期，见 `jwt.expiration-ms`）。
- 右上角用户菜单：修改密码、更换头像。
- 未登录访问业务页自动跳转登录；已登录访问登录页跳转仪表盘。

#### 3.2.2 仪表盘（Dashboard）

- 多项 KPI：患者数、影像数、病历数、预约数及状态分布等。
- 近 7 天业务趋势折线 / 柱状图（ECharts）。
- 检查类型分布、诊断状态分布饼图。
- 快捷入口与待办提示，便于演示导览。

#### 3.2.3 患者管理

- 分页列表、关键字搜索（姓名等）。
- 新增 / 编辑 / 删除：姓名、性别、年龄、身份证、电话、地址、既往病史。
- **患者 360° 档案**（抽屉）：基本信息 + 关联影像记录、电子病历、预约列表及计数统计。
- 表单弹窗采用顶栏标签与等宽两列布局，避免左右留白不均。

#### 3.2.4 影像诊断

- 检查登记：选择患者、检查类型（X 光 / CT / MRI / 超声）、部位、上传影像或填写路径。
- 列表筛选：关键字、状态、检查类型；状态 KPI 卡片可快速过滤。
- **AI 诊断**：触发后状态流转；完成后展示：
  - 诊断印象与置信度仪表盘
  - 原始影像 vs YOLO 标注图对比
  - 影像所见（分段段落）
  - 建议（编号列表）
  - 检测明细表（类别、置信度、bbox）
  - 完整报告（报告头 / 所见 / 印象 / 建议 / 声明 分块卡片）
- AI 服务不可用时，业务后端可降级为本地规则结果，保证演示不断链。

#### 3.2.5 电子病历

- 病历录入：患者、就诊日期、主诉、现病史、体格检查、诊断、治疗方案、用药、随访。
- 保存后可自动弹出 **AI 辅助决策**；列表亦可再次查看。
- 决策内容包括：治疗建议表、用药建议表、护理建议、随访计划、风险评估、药物冲突提示、知识库引用（RAG）。
- 诊断含「高血压 / 糖尿病 / 肺炎 / 结节」等关键词时，模板/RAG 效果更明显；配置 LLM 后由大模型增强。

#### 3.2.6 预约挂号

- 新建 / 编辑 / 删除预约。
- 状态流转：预约 → 确认 → 完成 / 取消 / 未到诊。
- 按日期筛选、统计卡片、详情抽屉。

#### 3.2.7 AI 助手

- 对话式问答界面，支持 Markdown 渲染（`marked` + `DOMPurify` 消毒）。
- 对话历史持久化到业务端 `./data/ai/chat-history.json`（不依赖 H2 是否清空）。

#### 3.2.8 知识库

- 知识文档的新增、编辑、查看、启用/停用。
- 与 AI 服务 RAG 管线配合；AI 服务内置医学相关 Markdown 知识片段（如高血压、肺炎、肺结节、糖尿病等）。

#### 3.2.9 AI 配置（仅管理员）

- 配置 OpenAI 兼容接口：Base URL、API Key、Model 等。
- 设置持久化到 `./data/ai/settings.json`。
- 启动或保存时通过同步机制推送到 FastAPI（`llm_config`），使报告生成与决策走大模型而非纯模板。

#### 3.2.10 YOLO 权重管理（仅管理员）

- 查看当前权重、模式（real / demo）、推理统计。
- 上传 / 激活权重文件，支撑影像检测能力切换。

#### 3.2.11 用户管理（仅管理员）

- 用户 CRUD：账号、密码、姓名、角色、科室、电话、邮箱、启用状态。
- 头像设置；禁止停用当前登录账号等业务保护。
- 前端菜单与路由按角色隐藏/拦截；后端接口权限校验。

### 3.3 前端页面与路由对照

| 路由 | 页面 | 权限 |
|------|------|------|
| `/login` | 登录 | 公开 |
| `/dashboard` | 仪表盘 | 已登录 |
| `/patients` | 患者管理 | 已登录 |
| `/imaging` | 影像诊断 | 已登录 |
| `/emrs` | 电子病历 | 已登录 |
| `/appointments` | 预约挂号 | 已登录 |
| `/ai-assistant` | AI 助手 | 已登录 |
| `/ai-knowledge` | 知识库 | 已登录 |
| `/ai-settings` | AI 配置 | ADMIN |
| `/ai-yolo` | YOLO 权重 | ADMIN |
| `/users` | 用户管理 | ADMIN |
| `/403` | 无权访问 | 已登录 |

### 3.4 与早期版本的能力对比

| 维度 | 早期（PROJECT_REPORT 描述） | 当前实现 |
|------|------------------------------|----------|
| 前端 | Thymeleaf + Bootstrap | Vue 3 + Element Plus + ECharts |
| 安全 | HttpSession | Spring Security + JWT |
| AI 影像 | 规则/随机模拟 | FastAPI + YOLO 实检 + 报告（LLM 或模板） |
| 决策 | 关键字规则 | RAG + 可选 LLM，失败回退模板 |
| 业务广度 | 患者 / 影像 / 病历 | 增加预约、仪表盘增强、知识库、AI 配置、YOLO 管理 |
| 数据库 | 依赖 MySQL | 默认 H2，可选 MySQL profile |

---

## 四、技术栈

### 4.1 总体一览

| 层级 | 技术 | 版本（项目实际） | 用途 |
|------|------|------------------|------|
| 前端框架 | Vue | 3.5.10 | SPA |
| 构建工具 | Vite | 5.4.8 | 开发与打包 |
| UI | Element Plus | 2.8.4 | 组件库 |
| 状态 | Pinia | 2.2.4 | 用户会话等 |
| 路由 | Vue Router | 4.4.5 | 前端路由与守卫 |
| HTTP | Axios | 1.7.7 | 调用 `/api` |
| 图表 | ECharts + vue-echarts | 5.5.1 / 7.0.3 | 仪表盘 |
| 文档渲染 | marked + DOMPurify | 18.x / 3.x | AI 对话 Markdown |
| 业务后端 | Spring Boot | 3.3.4 | REST / 安全 / JPA |
| 语言 | Java | 17 | 后端 |
| 安全 | Spring Security + jjwt | 0.12.6 | JWT |
| ORM | Spring Data JPA / Hibernate | 随 Boot 3.3 | 持久化 |
| 数据库 | H2（默认）/ MySQL（可选） | — | 业务数据 |
| 工具 | Lombok | — | 实体简化 |
| 构建 | Maven（含 mvnw） | — | 后端构建 |
| AI 服务 | FastAPI + Uvicorn | ≥0.110 / ≥0.27 | AI 微服务 |
| 视觉 | Ultralytics YOLO + OpenCV | — | 检测与标注 |
| 预处理 | OpenCV / 可选 MONAI | — | 影像预处理 |
| LLM / RAG | LangChain 生态 + httpx | ≥0.2 | 报告、决策、检索 |
| 大模型 | DeepSeek 等 OpenAI 兼容 API | 可配置 | 文本生成 |

### 4.2 前端技术细节

- **工程**：`frontend/`，`type: module`，Vite 开发服务器默认 **5173**。
- **代理**：开发态将 `/api` 代理到 `http://localhost:8080`。
- **自动导入**：`unplugin-auto-import`、`unplugin-vue-components` 简化 Element Plus 使用。
- **布局**：`BasicLayout` 侧边栏 + 顶栏 + 主内容滚动；Dialog/Drawer 普遍 `append-to-body`，避免被 `overflow` 裁切。
- **生产构建**：`npm run build` 产物可置于 Nginx 或由 Spring 静态资源 / SPA 回退托管。

### 4.3 业务后端技术细节

- **工程**：`smart-hospital/`（Maven 子工程）。
- **端口**：`8080`。
- **包结构**：`controller` / `service` / `repository` / `model` / `dto` / `security` / `config` / `common`。
- **统一响应**：`Result<T>`，`code == 0` 表示成功；全局异常处理业务码与校验错误。
- **异步诊断**：`AsyncConfig` 线程池 + `AIDiagnosisService` 异步分析。
- **文件存储**：影像与头像本地目录 `./uploads/`；AI 设置与聊天 `./data/ai/`。
- **AI 客户端**：`AiServiceClient` 调用 FastAPI；失败时服务内降级逻辑保证可用性。
- **LLM 同步**：`AiLlmSyncRunner` / `AiSettingsService` 将管理端配置同步到 AI 微服务。

### 4.4 AI 微服务技术细节

- **工程**：`ai-service/`，Python 3.10+（开发环境实测 3.12 可用）。
- **端口**：`8001`。
- **主要路由模块**：
  - `/health` — 健康与能力探测
  - `/imaging/analyze` — YOLO 检测 + 报告
  - `/report/imaging`、`/report/decision` — 报告与决策
  - `/rag/*` — 知识检索与写入
  - `/yolo/*` — 权重与统计
  - `/llm-config` — 运行时 LLM 配置
- **报告策略**：
  - 启用 LLM：结构化 JSON（所见 / 印象 / 建议），再由模板拼接分段 `full_report`
  - 未启用或失败：模板 / 规则文案
- **内置知识**：`app/knowledge/` 下高血压、糖尿病、肺炎、肺结节、骨折等 Markdown 片段。
- **权重目录**：`data/weights/`（如 `best.pt`、`yolov8n.pt` 等演示权重）。

### 4.5 数据库与配置

| 项 | 默认（H2） | MySQL Profile |
|----|------------|---------------|
| 连接 | `jdbc:h2:mem:smart_hospital` | `application-mysql.yml` |
| 控制台 | `/h2-console`（sa / 空密码） | — |
| DDL | `hibernate.ddl-auto: update` | 同左或按环境调整 |
| 种子数据 | `DataInitializer` 自动写入 | 同左 |

其他关键配置（`application.yml`）：

- `jwt.*`：密钥、过期时间、Header 前缀
- `cors.allowed-origins`：含 `http://localhost:5173`
- `ai.service.base-url`：`http://127.0.0.1:8001`
- `imaging.storage.path`：`./uploads/images`
- 上传限制：业务 multipart 最大约 500MB（兼容 YOLO 权重上传）

---

## 五、系统架构

### 5.1 逻辑架构

```
                 ┌──────────────────────┐
                 │   浏览器 Vue SPA     │
                 │   localhost:5173     │
                 └──────────┬───────────┘
                            │  /api  (Vite 代理)
                            ▼
                 ┌──────────────────────┐
                 │  Spring Boot 业务端  │
                 │  localhost:8080      │
                 │  JWT / JPA / 文件    │
                 └──────────┬───────────┘
                            │  HTTP（可选）
              ┌─────────────┴─────────────┐
              ▼                           ▼
     ┌────────────────┐          ┌─────────────────┐
     │  H2 / MySQL    │          │ FastAPI AI 服务  │
     │  业务库        │          │ localhost:8001  │
     └────────────────┘          │ YOLO / RAG / LLM│
                                 └────────┬────────┘
                                          │
                           ┌──────────────┼──────────────┐
                           ▼              ▼              ▼
                      本地权重 pt    知识 Markdown    外部 LLM API
```

### 5.2 调用关系原则

1. **浏览器只访问业务后端**（开发时经 Vite 代理），不直接依赖 AI 端口（管理端部分 YOLO 能力可经 Spring 转发）。
2. **AI 能力集中在 FastAPI**；Spring 负责鉴权、落库、任务状态与降级。
3. **配置单向同步**：管理端保存 LLM 配置 → 持久化 JSON → 同步 AI 运行时。
4. **失败可降级**：AI 超时或宕机时，诊断与决策仍可返回规则/模板结果。

### 5.3 部署形态（实训推荐）

| 进程 | 命令摘要 | 端口 |
|------|----------|------|
| AI | `uvicorn app.main:app --host 0.0.0.0 --port 8001` | 8001 |
| 业务 | `mvnw spring-boot:run` 或 `java -jar …jar` | 8080 |
| 前端 | `npm run dev` | 5173 |

生产可仅保留 AI + 业务 jar，前端 `build` 后由 Nginx 或 Spring 静态托管。

---

## 六、目录与模块结构

```
smart-hospital/                 # 仓库根
├── README.md                   # 启动与接口速览
├── PROJECT_REPORT.md           # 早期探索报告（历史参考）
├── 项目详细文档.md             # 本文件
├── smart-hospital.sql          # MySQL 初始化脚本（可选）
├── data/ai/                    # 根目录侧 AI 文件（若存在）
├── uploads/                    # 根目录侧上传样例（若存在）
│
├── frontend/                   # Vue 3 前端
│   ├── package.json
│   ├── vite.config.js
│   └── src/
│       ├── api/                # 按域划分的 HTTP 封装
│       ├── layouts/            # BasicLayout
│       ├── router/             # 路由与守卫
│       ├── stores/             # Pinia（用户）
│       ├── utils/              # 标签映射、Markdown 等
│       └── views/              # 各业务页面
│
├── smart-hospital/             # Spring Boot 业务后端
│   ├── pom.xml
│   ├── mvnw / mvnw.cmd
│   ├── data/ai/                # settings.json、chat-history.json
│   ├── uploads/                # 影像、头像、标注图
│   └── src/main/
│       ├── java/com/hospital/  # 应用代码
│       └── resources/
│           ├── application.yml
│           ├── application-mysql.yml
│           └── static/         # 可选内嵌前端构建产物
│
└── ai-service/                 # FastAPI AI 微服务
    ├── requirements.txt
    ├── README.md
    ├── data/weights/           # YOLO 权重
    ├── samples/                # 示例影像
    └── app/
        ├── main.py
        ├── api/                # imaging / report / rag / yolo / llm_config
        ├── services/           # yolo、report、rag、llm
        ├── schemas/
        └── knowledge/          # RAG 文档片段
```

---

## 七、核心业务流程

### 7.1 AI 影像诊断流程

```
医生/技师 新建影像记录（上传图片）
        │
        ▼
   状态 = PENDING
        │
        │  点击「AI 诊断」
        ▼
   状态 = ANALYZING  ──异步──► Spring AIDiagnosisService
        │                              │
        │                              ▼
        │                     调用 FastAPI /imaging/analyze
        │                              │
        │                    ┌─────────┴─────────┐
        │                    ▼                   ▼
        │              YOLO 检测框           报告生成
        │              绘制标注图         (LLM 或模板)
        │                    │                   │
        │                    └─────────┬─────────┘
        │                              ▼
        │                     写 AIDiagnosisResult
        │                     更新 ImagingRecord
        ▼
   状态 = COMPLETED / ERROR
        │
        ▼
  前端轮询 / 打开报告弹窗
  （所见 · 印象 · 建议 · 检测明细 · 完整报告）
```

### 7.2 电子病历辅助决策流程

```
医生填写并保存病历（含诊断等字段）
        │
        ▼
  Spring DecisionSupportService
        │
        ▼
  FastAPI /report/decision
        │
        ├─ RAG 检索 knowledge + 业务知识库
        ├─ 可选 LLM 生成结构化建议
        └─ 失败则按诊断关键词走模板
        │
        ▼
  返回治疗 / 用药 / 护理 / 随访 / 风险 / 冲突 / 来源
        │
        ▼
  前端 Dialog 分节展示
```

### 7.3 LLM 配置同步

```
管理员在「AI 配置」保存
        │
        ▼
  写入 ./data/ai/settings.json
        │
        ▼
  调用 AI 服务 llm_config 接口
        │
        ▼
  FastAPI 运行时启用/更新 LLM
  （报告与决策从模板切到大模型）
```

---

## 八、数据模型概要

### 8.1 主要业务实体

| 实体 | 表名 | 要点 |
|------|------|------|
| User | users | 角色 ADMIN/DOCTOR/RADIOLOGIST，BCrypt 密码，科室等 |
| Patient | patients | 姓名、性别、年龄、证件、联系方式、既往史 |
| ImagingRecord | imaging_records | 患者、医生、检查类型、部位、图像 URL、状态、AI 摘要字段 |
| AIDiagnosisResult | ai_diagnosis_results | 诊断文本、置信度、所见、建议、检测 JSON、标注图、完整报告、引擎与是否降级 |
| ElectronicMedicalRecord | electronic_medical_records | 主诉至随访全字段 + 关联患者/医生 |
| DecisionSupportRecord 等 | 决策相关表 | 辅助决策落库（按实现） |
| Appointment | appointments | 预约日、科室、事由、状态机 |
| AiKnowledgeDoc | 知识文档表 | 标题、分类、正文、启用 |
| AiSettings / 聊天 | 文件为主 | `settings.json`、`chat-history.json` |

### 8.2 影像状态机

| 状态 | 含义 |
|------|------|
| PENDING | 已登记，待诊断 |
| ANALYZING | 诊断进行中 |
| COMPLETED | 成功，可查看报告 |
| ERROR | 失败 |

### 8.3 检查类型

`X_RAY` · `CT` · `MRI` · `ULTRASOUND`

### 8.4 关系简图

```
User ──┬──< ImagingRecord >── Patient
       │         │
       │         └── AIDiagnosisResult
       │
       ├──< ElectronicMedicalRecord >── Patient
       │         │
       │         └── Decision / Suggestions（按实现落库）
       │
       └──< Appointment >── Patient
```

---

## 九、接口与权限

### 9.1 统一响应

```json
{
  "code": 0,
  "message": "OK",
  "data": {}
}
```

`code != 0` 时，前端 Axios 拦截器统一 `ElMessage` 提示。

### 9.2 业务 REST 一览（节选）

| 方法 | 路径 | 说明 | 权限 |
|------|------|------|------|
| POST | `/api/auth/login` | 登录 | 公开 |
| GET | `/api/auth/me` | 当前用户 | 已登录 |
| POST | `/api/auth/change-password` | 修改密码 | 已登录 |
| GET | `/api/stats/overview` | 统计概览 | 已登录 |
| * | `/api/patients/**` | 患者 CRUD / profile | 已登录 |
| * | `/api/imaging/**` | 影像 CRUD / 上传 | 已登录 |
| POST | `/api/ai-diagnosis/analyze/{id}` | 触发诊断 | 已登录 |
| GET | `/api/ai-diagnosis/result/{id}` | 诊断结果 | 已登录 |
| * | `/api/emrs/**` | 病历 CRUD | 已登录 |
| GET | `/api/emrs/{id}/ai-suggestions` | 辅助决策 | 已登录 |
| * | `/api/appointments/**` | 预约 CRUD / 状态 | 已登录 |
| * | `/api/users/**` | 用户管理 | ADMIN |
| * | AI 管理 / 聊天 / 知识库等 | 见对应 Controller | 已登录或 ADMIN |

### 9.3 AI 微服务接口（节选）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/health` | 健康检查 |
| POST | `/imaging/analyze` | 检测 + 报告 |
| POST | `/report/decision` | 病历决策 |
| POST | `/report/imaging` | 单独报告 |
| POST | `/rag/query` | 知识问答 |
| * | `/yolo/*` | 权重与统计 |
| * | `/llm-config` | 运行时 LLM 配置 |

完整 OpenAPI：`http://127.0.0.1:8001/docs`。

---

## 十、部署与运行

### 10.1 环境要求

| 组件 | 要求 |
|------|------|
| JDK | 17+ |
| Node.js | 18+ |
| Python | 3.10+（推荐 3.11/3.12） |
| 可选 | MySQL 8.x；NVIDIA GPU（非必须，CPU 可跑） |

### 10.2 启动顺序（推荐）

```text
1) ai-service :8001
2) smart-hospital :8080
3) frontend :5173
```

#### AI 服务

```bash
cd ai-service
python -m venv .venv
# Windows: .venv\Scripts\activate
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
pip install -r requirements.txt
# 可选：配置 .env 中 LLM_API_KEY
uvicorn app.main:app --host 0.0.0.0 --port 8001
```

#### 业务后端

```bash
cd smart-hospital
mvnw.cmd spring-boot:run
# 或
java -jar target/smart-hospital-1.0.0.jar
```

MySQL 模式：

```bash
mvnw.cmd spring-boot:run -Dspring-boot.run.profiles=mysql
```

#### 前端

```bash
cd frontend
npm install
npm run dev
```

浏览器访问：`http://localhost:5173`。

### 10.3 健康检查

| 服务 | 地址 |
|------|------|
| 前端 | http://localhost:5173 |
| 业务 API | http://localhost:8080/api/... |
| H2 控制台 | http://localhost:8080/h2-console |
| AI 健康 | http://127.0.0.1:8001/health |
| AI 文档 | http://127.0.0.1:8001/docs |

---

## 十一、演示账号与推荐路径

### 11.1 内置账号（DataInitializer）

| 用户名 | 密码 | 角色 | 说明 |
|--------|------|------|------|
| admin | admin123 | ADMIN | 用户管理、AI 配置、YOLO 权重 |
| doctor1 | pass123 | DOCTOR | 临床业务主演示账号 |
| radio1 | radio123 | RADIOLOGIST | 影像相关演示 |

### 11.2 推荐演示剧本

1. 使用 `doctor1 / pass123` 登录，浏览仪表盘 KPI 与图表。  
2. **患者管理**：查看列表 → 打开 360° 档案。  
3. **影像诊断**：新建检查并上传样例图 → AI 诊断 → 对比原图/标注图 → 阅读分段完整报告。  
4. **电子病历**：新建病历，诊断填写「高血压」或「肺炎」→ 查看 AI 建议与知识库引用。  
5. **预约挂号**：新建预约并切换状态。  
6. 切换 `admin`：进入 AI 配置（可填 DeepSeek Key）、YOLO 权重、用户管理。  
7. 对比：关闭 AI 服务后再次诊断，观察 **降级** 是否仍返回结果。

### 11.3 验证清单（节选）

- [ ] 三端均能启动，5173 可登录  
- [ ] admin 可见用户管理；doctor1 访问 `/users` 为 403  
- [ ] 患者增删改与档案抽屉正常  
- [ ] 影像 AI 状态能到 COMPLETED，报告分段清晰  
- [ ] 病历 AI 建议弹窗含多类内容  
- [ ] 预约状态可流转  
- [ ] 修改密码后需重新登录  

---

## 十二、设计说明与边界

### 12.1 关键设计取舍

| 取舍 | 原因 |
|------|------|
| 默认 H2 | 降低实训环境门槛，开箱即演示 |
| AI 独立进程 | 隔离 Python 视觉/LLM 依赖，避免撑爆 Java 工程 |
| JWT 无状态 | 适配前后端分离与多端调用 |
| LLM 可关 | 无 Key 时用模板/RAG，保证答辩可演示 |
| 报告强制分段拼接 | 避免大模型输出「墙文本」影响阅读 |
| Dialog append-to-body | Element Plus 2.8 默认不挂 body，易被布局 overflow 裁切 |

### 12.2 已知边界（非缺陷说明）

- 非完整 PACS/RIS/HIS 产品，无医保、收费、电子签名、CA 等模块。  
- YOLO 类别与权重为演示级，不保证临床敏感性/特异性。  
- H2 内存库重启丢失业务表数据；需持久化请改用 MySQL profile。  
- 大模型与外部 API 受网络、额度、延迟影响；超时有配置上限。  
- 早期 `PROJECT_REPORT.md` 描述的是改造前架构，**以本文档与当前代码为准**。

### 12.3 后续可扩展方向（建议）

- DICOM 解析与序列阅片  
- 报告 PDF 导出与医师电子签收工作流  
- 更细粒度的科室/数据权限与操作审计  
- 向量库（如 Chroma/FAISS）替换简易 RAG  
- Docker Compose 一键拉起三端  
- 接口自动化测试与 CI  

---

## 附录 A：技术栈版本速查表

| 名称 | 版本 |
|------|------|
| Spring Boot | 3.3.4 |
| Java | 17 |
| jjwt | 0.12.6 |
| Vue | 3.5.10 |
| Vite | 5.4.8 |
| Element Plus | 2.8.4 |
| Pinia | 2.2.4 |
| Vue Router | 4.4.5 |
| Axios | 1.7.7 |
| ECharts | 5.5.1 |
| FastAPI | ≥0.110 |
| Ultralytics | requirements 中指定 |
| LangChain | ≥0.2 |

## 附录 B：文档维护

| 项 | 说明 |
|----|------|
| 本文档路径 | `项目详细文档.md`（仓库根目录） |
| 快速启动 | 见 `README.md` |
| AI 专项 | 见 `ai-service/README.md` |
| 历史探索 | 见 `PROJECT_REPORT.md`（可能过时） |

---

**文档结束**