476 lines
11 KiB
Markdown
476 lines
11 KiB
Markdown
# 胜透叫号系统 - 项目说明文档
|
||
|
||
## 📋 项目概览
|
||
|
||
**胜透叫号系统** 是一个基于 Vue 3 + TypeScript + Vite 开发的医疗透析患者叫号和管理系统。该系统是从完整的 Vue 3 后台管理模板 `vue-next-admin` 中独立提取出来的单页面应用，专门用于显示和管理患者叫号信息。
|
||
|
||
### 核心特性
|
||
- 🎯 **患者实时叫号**：支持后端 TTS 服务和前端浏览器 TTS 双种语音播报方式
|
||
- 🔊 **音频播放**：集成 WAV 格式音频播放，支持等待播放完成再重置状态
|
||
- 📊 **实时数据展示**：通过 WebSocket 实时获取患者状态变化
|
||
- 🎨 **大屏展示**：支持全屏展示、字体大小调整、数据脱敏显示
|
||
- 🎬 **多媒体支持**：支持时段内容显示（视频/图片轮播）
|
||
- ⚙️ **灵活配置**：支持环境变量配置各项服务地址
|
||
|
||
---
|
||
|
||
## 🔧 技术栈
|
||
|
||
| 技术 | 版本 | 说明 |
|
||
|-----|------|------|
|
||
| Vue.js | 3.x | 前端框架 |
|
||
| TypeScript | 4.x+ | 类型系统 |
|
||
| Vite | 2.6.14 | 构建工具 |
|
||
| Element Plus | 1.2.0 | UI 组件库 |
|
||
| Vue Router | 4.x | 路由管理 |
|
||
| Vuex | 4.x | 状态管理 |
|
||
| Axios | 0.24.0 | HTTP 请求库 |
|
||
| WebSocket | 原生 | 实时通信 |
|
||
| speak-tts | - | 前端语音合成 |
|
||
|
||
---
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
pcWeb/
|
||
├── src/
|
||
│ ├── views/
|
||
│ │ └── listCurrentHemoMeds/ # 主叫号页面
|
||
│ │ └── index.vue # 叫号系统主组件
|
||
│ ├── components/
|
||
│ │ └── webSocket/index.vue # WebSocket 实时通信组件
|
||
│ ├── api/
|
||
│ │ └── comm/ # 通用 API 接口
|
||
│ │ └── index.ts # 患者数据和媒体接口
|
||
│ ├── router/
|
||
│ │ └── route.ts # 路由配置（已简化）
|
||
│ ├── store/ # Vuex 状态管理
|
||
│ ├── assets/ # 静态资源
|
||
│ ├── utils/ # 工具函数
|
||
│ ├── App.vue # 根组件
|
||
│ └── main.ts # 应用入口
|
||
├── .env.development # 开发环境配置
|
||
├── .env.production # 生产环境配置
|
||
├── vite.config.ts # Vite 配置
|
||
├── tsconfig.json # TypeScript 配置
|
||
└── package.json # 项目依赖
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
# 或
|
||
yarn install
|
||
# 或
|
||
cnpm install
|
||
```
|
||
|
||
### 开发模式运行
|
||
|
||
```bash
|
||
npm run dev
|
||
# 或
|
||
yarn dev
|
||
```
|
||
|
||
开发服务器将在 `http://localhost:8888` 启动
|
||
|
||
### 生产构建
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
输出目录：`dist/`
|
||
|
||
---
|
||
|
||
## ⚙️ 环境配置
|
||
|
||
### 开发环境 (.env.development)
|
||
|
||
```env
|
||
# API 服务地址
|
||
VITE_API_URL = 'https://testbs.ihemodialysis.com/'
|
||
|
||
# WebSocket 地址
|
||
VITE_API_WSS = 'ws://testbs.ihemodialysis.com/broadcast'
|
||
|
||
# TTS 语音服务地址
|
||
VITE_TTS_URL = 'http://ikuai.m-iot.tech:62335/tts'
|
||
|
||
# 是否显示 Logo（1=显示, 0=不显示）
|
||
VITE_SHOW_LOGO = '1'
|
||
```
|
||
|
||
### 生产环境 (.env.production)
|
||
|
||
```env
|
||
# 根据实际生产服务器地址配置
|
||
VITE_API_URL = 'https://bs.ihemodialysis.com/'
|
||
VITE_API_WSS = 'ws://bs.ihemodialysis.com/broadcast'
|
||
VITE_TTS_URL = 'http://ikuai.m-iot.tech:62335/tts'
|
||
```
|
||
|
||
### 环境变量加载
|
||
|
||
在代码中使用环境变量：
|
||
|
||
```typescript
|
||
// 获取 TTS 服务地址
|
||
const ttsUrl = import.meta.env.VITE_TTS_URL as string;
|
||
|
||
// 获取 API 地址
|
||
const apiUrl = import.meta.env.VITE_API_URL as string;
|
||
```
|
||
|
||
> **重要**：修改 `.env` 文件后需要重启开发服务器才能生效！
|
||
|
||
---
|
||
|
||
## 🎤 叫号系统详解
|
||
|
||
### 核心功能组件
|
||
|
||
#### 1. **叫号主页面** (`src/views/listCurrentHemoMeds/index.vue`)
|
||
|
||
该页面负责显示患者叫号信息，包含三个主要区域：
|
||
|
||
**左侧（1/4 宽度）**
|
||
- 当前叫号：显示当前正在叫号的患者信息
|
||
- 已叫号患者：滚动显示已叫过号的患者列表
|
||
|
||
**右侧（3/4 宽度）**
|
||
- 患者卡片列表：以卡片形式显示所有患者信息
|
||
- 支持 4 列响应式布局
|
||
- 已叫号患者显示为蓝色背景
|
||
|
||
**顶部**
|
||
- LOGO 和系统标题
|
||
- 日期时间显示
|
||
- 字体大小调整工具
|
||
|
||
#### 2. **叫号数据流**
|
||
|
||
```
|
||
WebSocket（患者叫号事件）
|
||
↓
|
||
alertBody 函数处理事件
|
||
↓
|
||
根据 大屏语音播报类型 选择播报方式
|
||
├── 0: 后端 TTS (ksjh0)
|
||
└── 1: 前端浏览器 TTS (ksjh1)
|
||
↓
|
||
播放语音
|
||
↓
|
||
等待播放完成
|
||
↓
|
||
重置 UI 状态
|
||
```
|
||
|
||
#### 3. **两种语音播报方式**
|
||
|
||
**方式一：后端 TTS 服务 (ksjh0)**
|
||
|
||
```typescript
|
||
// 发送 FormData 到 TTS 服务
|
||
const params = new URLSearchParams();
|
||
params.append('text', `当前叫号 ${patientName},${deviceGroupName} ${bedJh.value}`);
|
||
params.append('lang', 'zh'); // 中文
|
||
params.append('spk_id', '0'); // 发音人 ID
|
||
params.append('rate', '+10%'); // 语速 (+10%)
|
||
params.append('vol', '6'); // 音量
|
||
|
||
const response = await fetch(ttsUrl, {
|
||
method: 'POST',
|
||
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
|
||
body: params.toString(),
|
||
});
|
||
|
||
// 获取 WAV 音频，使用 HTML5 Audio 元素播放
|
||
const audioData = await response.arrayBuffer();
|
||
const audioBlob = new Blob([audioData], { type: 'audio/wav' });
|
||
// ... 播放逻辑
|
||
```
|
||
|
||
**方式二：前端浏览器 TTS (ksjh1)**
|
||
|
||
```typescript
|
||
// 使用 speak-tts 库进行本地语音合成
|
||
speech.value.speak({
|
||
text: `当前叫号 ${patientName},${deviceGroupName} ${bedJh.value}`,
|
||
rate: 10,
|
||
listeners: {
|
||
onstart: () => { /* 播放开始 */ },
|
||
onend: () => { /* 播放完成 */ },
|
||
},
|
||
});
|
||
```
|
||
|
||
#### 4. **状态管理关键变量**
|
||
|
||
| 变量名 | 类型 | 说明 |
|
||
|-------|------|------|
|
||
| `num` | ref | 0=空闲 1=播报中（防止重复播报） |
|
||
| `jhzhuangt` | ref | 显示/隐藏叫号大屏 |
|
||
| `xjzhuangtai` | ref | 显示/隐藏下机状态屏幕 |
|
||
| `patientNameJh` | ref | 当前叫号患者名 |
|
||
| `bedJh` | ref | 当前叫号患者床位 |
|
||
| `大屏语音播报类型` | ref | 0=后端TTS 1=前端TTS |
|
||
| `大屏展示数据脱敏` | ref | 是否脱敏显示患者信息 |
|
||
|
||
---
|
||
|
||
## 📡 API 接口
|
||
|
||
### 获取患者列表
|
||
|
||
**接口**：`GET /api/listCurrentHemoMeds`
|
||
|
||
**参数**：
|
||
```typescript
|
||
{
|
||
clientCode: string; // 机构代码
|
||
groupCode: string; // 分组代码（可选）
|
||
page: number; // 页码
|
||
size: number; // 每页条数
|
||
}
|
||
```
|
||
|
||
**响应**：
|
||
```typescript
|
||
{
|
||
data: {
|
||
clientName: string; // 机构名称
|
||
大屏展示数据脱敏选项: 0 | 1; // 是否脱敏
|
||
大屏语音播报类型: 0 | 1; // 播报类型
|
||
rows: {
|
||
list: PatientInfo[]; // 患者列表
|
||
pages: number; // 总页数
|
||
total: number; // 总条数
|
||
endRow: number; // 当前行尾
|
||
};
|
||
已叫号列表: PatientInfo[]; // 已叫过号的患者
|
||
当前叫号列表: PatientInfo[]; // 当前叫号患者
|
||
}
|
||
}
|
||
```
|
||
|
||
### 获取时段媒体内容
|
||
|
||
**接口**：`GET /api/listCurrentLcdMedia`
|
||
|
||
**参数**：
|
||
```typescript
|
||
{
|
||
clientCode: string; // 机构代码
|
||
}
|
||
```
|
||
|
||
**响应**：
|
||
```typescript
|
||
{
|
||
data: [
|
||
{
|
||
startHours: number; // 开始小时
|
||
endHours: number; // 结束小时
|
||
startMinutes: number; // 开始分钟
|
||
endMinutes: number; // 结束分钟
|
||
lcdMediaFilesList: [
|
||
{
|
||
filePath: string; // 文件路径
|
||
fileType: 'video' | 'image'; // 文件类型
|
||
}
|
||
];
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### WebSocket 实时通信
|
||
|
||
**连接地址**：由 `VITE_API_WSS` 配置
|
||
|
||
**收到的事件格式**：
|
||
```typescript
|
||
{
|
||
callType: '开始叫号' | '结束叫号' | '下机';
|
||
patientName: string; // 患者姓名
|
||
patPinyinCode: string; // 患者拼音代码（可选）
|
||
bedNo: string; // 床位号
|
||
deviceGroupName: string; // 设备分组名
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 使用场景
|
||
|
||
### 场景一：启动应用
|
||
|
||
1. 访问 `http://localhost:8888/?pagesize=10&clientCode=XXXXX`
|
||
2. 应用加载患者数据并显示
|
||
3. 与后端 WebSocket 建立连接
|
||
4. 等待患者叫号事件
|
||
|
||
### 场景二：接收叫号事件
|
||
|
||
1. WebSocket 接收 `callType='开始叫号'` 事件
|
||
2. 根据配置选择叫号方式（后端TTS 或 前端TTS）
|
||
3. 播放语音叫号
|
||
4. 显示全屏叫号大屏
|
||
5. 等待音频播放完成
|
||
6. 自动关闭大屏，重置 UI 状态
|
||
|
||
### 场景三：数据脱敏
|
||
|
||
如果后端返回 `大屏展示数据脱敏选项 = 1`，患者姓名将被脱敏处理：
|
||
|
||
```
|
||
原始：张三
|
||
脱敏：Z三
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 常见问题
|
||
|
||
### Q1: 如何修改 TTS 服务地址？
|
||
|
||
编辑 `.env.development` 或 `.env.production`：
|
||
|
||
```env
|
||
VITE_TTS_URL = 'http://your-tts-server:port/tts'
|
||
```
|
||
|
||
然后重启开发服务器。
|
||
|
||
### Q2: 语音播报没有声音？
|
||
|
||
1. 检查浏览器音量设置
|
||
2. 检查网络连接
|
||
3. 验证 TTS 服务地址是否正确
|
||
4. 查看浏览器控制台 (F12) 的错误信息
|
||
|
||
### Q3: 如何切换语音播报方式？
|
||
|
||
应用会自动根据后端返回的 `大屏语音播报类型` 字段选择：
|
||
- `0` = 使用后端 TTS 服务（推荐）
|
||
- `1` = 使用前端浏览器 TTS
|
||
|
||
后端无法配置时，联系管理员修改该配置。
|
||
|
||
### Q4: 如何调整叫号大屏的字体大小？
|
||
|
||
点击右下角 ⚙️ 工具图标，可调整：
|
||
- 叫号字体大小（20-200px）
|
||
- 已叫号字体大小（20-200px）
|
||
- 卡片字体大小（20-100px）
|
||
|
||
设置会保存到浏览器本地存储。
|
||
|
||
### Q5: 生产环境构建有什么注意事项？
|
||
|
||
```bash
|
||
# 生产构建
|
||
npm run build
|
||
|
||
# 生产构建前，需要确保：
|
||
# 1. .env.production 配置正确
|
||
# 2. 所有依赖已安装
|
||
# 3. 构建过程无错误
|
||
|
||
# 构建后生成 dist 目录，上传到服务器
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 开发注意事项
|
||
|
||
### 1. 代码风格
|
||
|
||
使用 TypeScript 编写，遵循以下规范：
|
||
|
||
```typescript
|
||
// ✅ 推荐
|
||
const patientName: string = ref('');
|
||
const ksjh = async (patientName: string, bedNo: string): Promise<void> => {
|
||
// ...
|
||
};
|
||
|
||
// ❌ 避免
|
||
const patientName = ref('');
|
||
const ksjh = async (patientName, bedNo) => {
|
||
// ...
|
||
};
|
||
```
|
||
|
||
### 2. 组件更新
|
||
|
||
修改页面后会自动热更新（HMR），无需手动刷新浏览器。
|
||
|
||
### 3. 调试技巧
|
||
|
||
在浏览器控制台查看关键日志：
|
||
|
||
```javascript
|
||
// 查看当前 TTS URL
|
||
console.log('TTS URL:', ttsUrl);
|
||
|
||
// 查看 WebSocket 事件
|
||
console.log('WebSocket 事件:', data);
|
||
|
||
// 查看音频大小
|
||
console.log('音频数据大小:', audioData.byteLength);
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 安全建议
|
||
|
||
1. **不要在前端代码中暴露敏感信息**
|
||
- API 密钥应由后端管理
|
||
- 个人患者信息应启用脱敏显示
|
||
|
||
2. **CORS 跨域处理**
|
||
- TTS 服务需配置 CORS 头允许浏览器跨域请求
|
||
- 或在生产环境使用同域转发
|
||
|
||
3. **WebSocket 连接安全**
|
||
- 生产环境应使用 WSS（加密WebSocket）
|
||
- 验证连接身份
|
||
|
||
---
|
||
|
||
## 📞 支持和反馈
|
||
|
||
- **项目仓库**：https://gitee.com/chenyincheng0624/pcWeb
|
||
- **技术栈**：Vue 3 + Vite + TypeScript + Element Plus
|
||
- **原始模板**：vue-next-admin
|
||
|
||
---
|
||
|
||
## 📄 许可证
|
||
|
||
MIT License
|
||
|
||
---
|
||
|
||
## 版本历史
|
||
|
||
| 版本 | 日期 | 说明 |
|
||
|-----|------|------|
|
||
| 1.0.0 | 2025-12-13 | 项目说明文档创建 |
|
||
|
||
---
|
||
|
||
**最后更新**：2025-12-13
|
||
**项目名称**：胜透叫号系统 (listCurrentHemoMeds)
|
||
**版本**：1.2.0
|