# medical-ui

**Repository Path**: cotmier_1/medical-ui

## Basic Information

- **Project Name**: medical-ui
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-15
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 医疗小智（Medical Xiaozhi）

面向「北京协和医院」场景的 **AI 预约挂号助手**：用户在对话页用自然语言完成分导诊、查号、预约与取消；管理员在后台维护科室、医生、号源与系统配置。

---

## 1. 项目背景与简介

传统挂号依赖 App / 窗口排队，患者常常「不知挂哪科、不知有没有号」。本项目将大模型 Agent 与医院业务数据打通：

- **前台**：医疗小智对话助手（默认首页 `/`），手机号验证码登录后可流式对话，并保留历史会话。
- **后台**：管理端（`/admin`），独立管理员账号，维护预约、科室、医生、排班与运行参数。

核心价值：用自然语言降低挂号门槛，用结构化数据（MySQL）保证可预约、可管理，用会话记忆（MongoDB）保证多轮连续咨询。

| 项目 | 说明 |
|------|------|
| 中文名 | 医疗小智 |
| 后端工程 | `medical-server` |
| 前端工程 | `medical-ui` |
| 对话页 | http://localhost:5173/ |
| 管理后台 | http://localhost:5173/admin |
| 后端 API | http://localhost:8080 |
| API 文档（开发环境） | http://localhost:8080/doc.html |

---

## 2. 技术栈与组件

### 2.1 后端（`medical-server`）

| 类别 | 技术 / 组件 | 作用 |
|------|-------------|------|
| 基础框架 | Spring Boot 3.2.6、JDK 17 | Web API、配置与依赖注入 |
| AI Agent | LangChain4j 1.0.0-beta4 | Agent、Tools、记忆、流式输出 |
| 大模型 | 阿里百炼 DashScope（如 `glm-5.2`） | 对话推理与工具调用 |
| 向量 / Embedding | DashScope `text-embedding-v3` + 内存向量库 | 未指定医生时按专长推荐医生 |
| 持久化 | MyBatis-Plus 3.5.11、MySQL Connector | 业务表 CRUD、分页 |
| 文档记忆 | Spring Data MongoDB | 多轮聊天记忆存储 |
| 接口文档 | Knife4j 4.3.0（OpenAPI3） | 开发环境接口调试（生产可关闭） |
| 校验 | spring-boot-starter-validation | 入参校验 |
| 环境变量 | spring-dotenv | 从 `.env` 加载百炼 Key 等 |
| 其他 | Lombok、WebFlux/Reactor（配合流式） | 简化代码、SSE 流式对话 |

### 2.2 前端（`medical-ui`）

| 类别 | 技术 / 组件 | 作用 |
|------|-------------|------|
| 框架 | Vue 3 + Vite 6 | SPA 构建与热更新 |
| UI | Element Plus、@element-plus/icons-vue | 后台表格/表单/分页；部分交互组件 |
| 路由 | Vue Router 4 | `/` 对话页、`/admin/*` 管理端 |
| 请求 | Axios | REST 调用；管理端 Token 拦截 |
| 对话交互 | Fetch + SSE（`text/event-stream`） | 流式打字机效果 |
| 样式 | 自定义 CSS 变量（青绿主题） | 品牌色统一；覆盖 Element Plus 主色 |

### 2.3 模型与 Agent 能力

- **系统角色**：北京协和医院智能客服「医疗小智」，支持分导诊与挂号伴诊。
- **工具约定**（摘要）：
  1. 查号 / 预约前先查号源，向用户确认信息后再预约；
  2. 未提供医生时，从向量库推荐；
  3. 取消需姓名、身份证、科室、日期、时段等关键要素。

---

## 3. 数据库与存储

项目采用 **MySQL + MongoDB** 双存储：结构化业务在 MySQL，对话记忆在 MongoDB。

### 3.1 MySQL（库名 `medical`）

用途：科室 / 医生 / 号源 / 预约、前台用户与会话索引、后台管理员与配置。

| 表名 | 作用 |
|------|------|
| `department` | 科室（含常见症状关键词，辅助分导诊） |
| `doctor` | 医生（科室、职称、擅长等；变更后同步向量库） |
| `schedule` | 号源排班（日期、上午/下午、余号） |
| `appointment` | 预约挂号记录（状态 BOOKED / CANCELLED） |
| `sys_config` | 系统配置（如记忆轮数、短信验证码） |
| `app_user` | 前台用户（手机号） |
| `user_token` | 前台登录 Token |
| `chat_session` | 用户历史会话列表（侧边栏） |
| `admin_user` | 后台管理员账号 |
| `admin_token` | 后台登录 Token |

初始化脚本：

```bash
mysql -uroot -proot < medical-server/sql/init.sql
mysql -uroot -proot medical < medical-server/sql/auth_session.sql
mysql -uroot -proot medical < medical-server/sql/admin_auth.sql
# 可选：三甲级科室/医生扩充
mysql -uroot -proot medical < medical-server/sql/seed_3a_hospital.sql
```

默认管理员：`admin` / `admin123`（上线后请立即修改）。

### 3.2 MongoDB

| 集合 / 用途 | 说明 |
|-------------|------|
| 聊天记忆（如 `chat_memory`） | 按会话 ID 存储多轮 User/AI 消息，供 LangChain4j `ChatMemory` 使用 |
| 连接 | 开发环境默认 `mongodb://localhost:27017`；生产 URI 需含账号密码 |

记忆最大消息数由 MySQL `sys_config.chat_memory_max_messages` 控制（默认约 20，后台可改）。

### 3.3 其他本地存储

| 位置 | 作用 |
|------|------|
| 浏览器 `localStorage` | 前台会话 ID、用户 Token；后台管理员 Token / 资料缓存 |
| 内存向量库 | 医生专长 Embedding，运行时加载，医生变更后刷新 |

---

## 4. 功能说明（含页面截图）

### 4.1 用户对话首页

![对话首页](./screenshots/01-chat-home.png)

路径：`/`。未登录可浏览能力介绍与快捷提问，发送消息前需登录。左侧为新对话与历史会话区，中间为欢迎语与示例问题，底部为输入框。支持 AI 分导诊、查号源、预约挂号、取消预约。

### 4.2 手机号登录 / 注册

![手机号登录](./screenshots/02-chat-login.png)

点击「登录」或输入框弹出登录层。手机号 + 验证码，未注册自动建号。测试环境默认验证码 `666666`（可在后台「系统配置」修改 `sms_verify_code`）。

### 4.3 登录后对话与历史会话

![登录后对话](./screenshots/03-chat-logged-in.png)

登录后可发送消息，SSE 流式回复；左侧可查看、切换、删除历史会话；消息支持一键复制。会话列表存 MySQL，消息正文存 MongoDB。

### 4.4 管理后台登录

![后台登录](./screenshots/04-admin-login.png)

路径：`/admin/login`。与前台用户体系隔离，仅管理员可进入。默认账号 `admin` / `admin123`（上线后请修改）。

### 4.5 预约管理

![预约管理](./screenshots/05-admin-appointments.png)

支持按患者姓名、状态查询；可取消或删除预约；身份证号脱敏展示。

### 4.6 科室管理

![科室管理](./screenshots/06-admin-departments.png)

维护科室名称、简介、常见症状关键词，供对话分导诊匹配科室。

### 4.7 医生管理

![医生管理](./screenshots/07-admin-doctors.png)

维护医生所属科室、职称、擅长等；保存后刷新向量库，便于未指定医生时智能推荐。

### 4.8 号源排班

![号源排班](./screenshots/08-admin-schedules.png)

按科室、日期查询排班；支持新增、修改号源、删除与批量生成。

### 4.9 系统配置

![系统配置](./screenshots/09-admin-configs.png)

动态调整运行参数，例如 `chat_memory_max_messages`（聊天记忆最大消息数）、`sms_verify_code`（前台登录验证码）。

### 4.10 管理员个人主页

![个人主页](./screenshots/10-admin-profile.png)

顶栏右上角显示欢迎语与头像；点击头像进入个人主页，可修改显示名称、重置密码（改密后需重新登录）。

---

## 5. 快速启动

### 5.1 环境要求

1. JDK 17+
2. MySQL（示例账号密码均为 `root`）
3. MongoDB（开发可用无密码本地实例）
4. 阿里百炼 API Key（写入 `medical-server/.env`）
5. Node.js 18+

### 5.2 配置 API Key

```bash
cd medical-server
cp .env.example .env
# 编辑 .env：
# XIAOZHI_DASH_SCOPE_API_KEY=sk-你的百炼密钥
```

说明：

1. 使用 `XIAOZHI_DASH_SCOPE_API_KEY`，避免被系统残留的 `DASH_SCOPE_API_KEY` 覆盖。
2. 向量模型须为 `text-embedding-v3`。
3. 修改 `.env` 后需重启后端。`.env` 已加入 `.gitignore`。

### 5.3 启动后端

```bash
cd medical-server
unset DASH_SCOPE_API_KEY
mvn spring-boot:run
```

### 5.4 启动前端

```bash
cd medical-ui
npm install
npm run dev
```

前端通过 Vite 将 `/api` 代理到 `8080`。

---

## 6. 目录结构（简要）

```
agent/
├── medical-server/          # Spring Boot 后端
│   ├── sql/                 # MySQL 初始化与种子数据
│   └── src/main/java/...    # Agent、Tools、管理端 API
├── medical-ui/              # Vue3 前端
│   └── src/views/           # ChatView、admin/*
├── screenshots/             # README 功能截图（预览 README 时可见）
├── 需求文档.md
└── 开发规范.md
```

---

## 7. 刷新截图（可选）

前后端本地已启动时：

```bash
cd medical-ui
npm i -D playwright@1.49.1
npx playwright install chromium
node ../docs/capture-screenshots.mjs
```

输出目录：`screenshots/`。