# 胜透叫号系统 - 项目说明文档

## 📋 项目概览

**胜透叫号系统** 是一个基于 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