# HANDOFF — 设备模拟模块

> **生成时间**: 2026-08-05
> **当前分支**: `platform-auto-test`
> **最近提交**: `ae32844b` feat(device-sim): Excel批量导入设备功能

---

## 一、本次会话完成的工作

### 1. ✅ Excel 批量导入设备功能

**需求**: 通过 Excel 文件批量导入模拟设备，快速创建多台设备。

**实现**:
- **后端新增端点**:
  - `GET /api/device-sim/devices/import/template` — 下载导入模板
  - `POST /api/device-sim/devices/import` — 批量导入设备
- **Excel 表头格式**:
  - 环境配置名称（必填）— 后台按名称查找环境配置 ID
  - 设备名称（必填）
  - 设备ID（必填）— 同一环境下唯一
  - 授权码/app_token（可选，仅门口屏）— 填入 topic_params
  - 自动重连（可选）— 支持是/否、true/false
  - 启用定时上报（可选）
  - 上报间隔(秒)（可选）
- **前端**:
  - 新增"批量导入"按钮和导入弹窗
  - 支持拖拽上传 .xlsx 文件
  - 模板下载链接
  - 导入结果表格显示每行成功/失败及错误原因

**修改文件**:
- `backend/requirements.txt` — 添加 `openpyxl==3.1.2`
- `backend/app/schemas/device_sim.py` — 新增 `DeviceImportRowResult`、`DeviceImportResponse`
- `backend/app/services/device_sim_service.py` — 新增 `import_simulators_from_excel()` 方法
- `backend/app/routers/device_sim.py` — 新增导入和模板下载端点
- `frontend/src/types/device.ts` — 新增导入相关类型
- `frontend/src/api/deviceSim.ts` — 新增 `importDevices()`、`downloadImportTemplate()`
- `frontend/src/components/device/DeviceList.vue` — 新增导入按钮、弹窗、逻辑

### 2. ✅ 移除实时消息流组件

**需求**: 暂时移除实时消息流面板，简化界面。

**实现**:
- 四个设备模拟页面（门口屏/无纸化/中控/集控客户端）移除右侧消息流面板
- 只保留设备列表，全宽显示
- `MessageStream.vue` 组件保留但不再使用

**修改文件**:
- `frontend/src/views/device-sim/DoorSim.vue`
- `frontend/src/views/device-sim/PaperlessSim.vue`
- `frontend/src/views/device-sim/CentralSim.vue`
- `frontend/src/views/device-sim/ClientSim.vue`

### 3. ✅ 分页器增强

**需求**: 分页器支持选择每页条数。

**实现**:
- 新增每页条数选择：10/20/50/100 条/页
- 布局调整：总数 + 每页条数 + 分页 + 跳转
- 使用 `v-model:page-size` 替代固定的 `limit`

**修改文件**:
- `frontend/src/components/device/DeviceList.vue`

### 4. ✅ 全部启动/全部停止按钮

**需求**: 快捷操作当前页所有设备。

**实现**:
- 未勾选设备时显示"全部启动"、"全部停止"按钮
- 勾选设备后切换为"批量启动"、"批量停止"、"批量删除"
- 操作当前页显示的所有设备

**修改文件**:
- `frontend/src/components/device/DeviceList.vue`

### 5. ✅ 模板下载中文文件名修复

**问题**: 下载模板时，中文文件名导致 HTTP 头编码错误。

**修复**: 使用 `urllib.parse.quote()` 对文件名进行 URL 编码。

**修改文件**:
- `backend/app/routers/device_sim.py`

### 6. ✅ 部署到 192.168.5.60

**方式**: 使用 paramiko SSH + SFTP 上传前端 dist 和后端代码，容器内安装 openpyxl 依赖后重启。

---

## 二、已知问题

### P0 — 消息流页面显示"暂无消息"（已移除消息流 UI，问题暂缓）

**说明**: 实时消息流组件已移除，此问题暂不处理。后续如需恢复消息流功能，再排查消息队列入队问题。

---

## 三、修改文件清单

### 本次会话新增/修改

| 文件 | 变更类型 | 说明 |
|------|----------|------|
| `backend/requirements.txt` | 修改 | 添加 openpyxl==3.1.2 |
| `backend/app/schemas/device_sim.py` | 修改 | 新增 DeviceImportRowResult、DeviceImportResponse |
| `backend/app/services/device_sim_service.py` | 修改 | 新增 import_simulators_from_excel() 和辅助函数 |
| `backend/app/routers/device_sim.py` | 修改 | 新增导入和模板下载端点 |
| `frontend/src/types/device.ts` | 修改 | 新增导入相关类型定义 |
| `frontend/src/api/deviceSim.ts` | 修改 | 新增 importDevices、downloadImportTemplate API |
| `frontend/src/components/device/DeviceList.vue` | 修改 | 新增导入弹窗、全部启动/停止按钮、分页增强 |
| `frontend/src/views/device-sim/DoorSim.vue` | 修改 | 移除右侧消息流面板 |
| `frontend/src/views/device-sim/PaperlessSim.vue` | 修改 | 同上 |
| `frontend/src/views/device-sim/CentralSim.vue` | 修改 | 同上 |
| `frontend/src/views/device-sim/ClientSim.vue` | 修改 | 同上 |

---

## 四、后续待办

| 优先级 | 任务 | 说明 |
|--------|------|------|
| P1 | 中控/集控客户端主题确认 | 确认真实上报/订阅主题 |
| P2 | 环境配置统计功能 | 统计各环境下的设备数量 |

---

## 五、相关文档索引

| 文档 | 路径 |
|------|------|
| 设备模拟 PRD | `Docs/PRD/需求文档/设备模拟/_PRD_需求文档_设备模拟模块.md` |

---

## 六、部署信息

| 项目 | 值 |
|------|-----|
| 服务器 IP | `192.168.5.60` |
| SSH 用户/密码 | `ubains / Ubains@123` |
| 部署目录 | `/data/third_party/plat-auto-test/` |
| Docker 容器名 | `plat-auto-test-app` |
| MySQL 容器名 | `plat-auto-test-mysql` |
| 前端地址 | http://192.168.5.60 |

**部署方式**: 
- 后端：SFTP 上传 `backend/app/` 下修改的文件到服务器 `/data/third_party/plat-auto-test/backend/app/`
- 前端：本地 `npm run build` 后，SFTP 上传 `frontend/dist/` 到服务器 `/data/third_party/plat-auto-test/frontend/dist/`
- 重启容器：`docker restart plat-auto-test-app`

---

## 七、Excel 导入模板格式

| 列 | 表头 | 必填 | 说明 |
|----|------|------|------|
| A | 环境配置名称 | 是 | 需与已创建的环境配置名称完全一致 |
| B | 设备名称 | 是 | |
| C | 设备ID | 是 | 同一环境下唯一 |
| D | 授权码(app_token) | 否 | 仅门口屏需要，填入 topic_params |
| E | 自动重连 | 否 | 默认 true，支持 是/否、true/false |
| F | 启用定时上报 | 否 | 默认 true |
| G | 上报间隔(秒) | 否 | 默认 30，整数 >= 1 |

---

*本文档记录设备模拟模块开发状态，供下次会话快速恢复上下文。*