# HANDOFF — 设备模拟模块开发进度

> **生成时间**: 2026-08-03
> **当前分支**: `platform-auto-test`
> **状态**: 🟡 基础功能完成，主题配置待改造

---

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

### 1. ✅ 数据库表未创建问题修复

**问题**：`backend/app/models/__init__.py` 中没有导入设备模拟模型，导致 SQLAlchemy 的 `Base.metadata` 没有注册这些表

**修复**：
```python
# backend/app/models/__init__.py
from app.models.device_sim import EnvConfig, DeviceSimulator, ReportLog
```

**结果**：服务器重启后自动创建 3 张表
- `device_env_configs`（环境配置）
- `device_simulators`（模拟设备）
- `device_report_logs`（上报记录）

---

### 2. ✅ 嵌套路由无法渲染问题修复

**问题**：`/device-sim` 和 `/system` 父路由缺少组件，没有 `<router-view />` 渲染子路由

**修复**：
- 创建 `frontend/src/views/device-sim/index.vue`（父级容器）
- 创建 `frontend/src/views/system/index.vue`（父级容器）
- 更新 `frontend/src/router/index.ts`，为父路由添加 `component` 属性

---

### 3. ✅ 列表不显示数据问题修复

**问题**：`frontend/src/utils/request.ts` 响应拦截器返回 `response` 而不是 `response.data`

**修复**：
```typescript
// 之前
return response

// 修复后
return response.data
```

---

### 4. ✅ MQTT 连接测试失败修复

**问题**：容器中未安装 `paho-mqtt`

**修复**：
```bash
docker exec plat-auto-test-app pip install paho-mqtt==2.1.0
```

**注意**：需要将 `paho-mqtt==2.1.0` 添加到 `requirements.txt` 并重建镜像才能持久化

---

### 5. ✅ 测试连接后状态不更新问题修复

**问题**：
1. `test_env_connection` 调用 `get_env_config`，后者用内存状态覆盖了数据库状态
2. `list_env_configs` 每次都用内存状态覆盖数据库状态

**修复**：
- `test_env_connection` 直接查询数据库，不走 `get_env_config`
- 测试成功后更新数据库状态为 `connected`，并记录 `last_connected_at`
- `list_env_configs` 只在内存有活跃连接时覆盖，否则保留数据库状态

---

### 6. ✅ 前端环境配置页面优化

**优化内容**：
- MQTT 账号密码设置默认值：`mqtt@cmdb` / `mqtt@webpassw0RD`
- 去掉"主题配置"列和折叠面板，简化界面
- 列表显示：配置名称、Broker 地址、端口、状态、最后连接、操作

---

### 7. ✅ Schema 字段名冲突修复

**问题**：`SimulatorResponse` 中 `metadata` 字段与 SQLAlchemy 的 `MetaData` 对象冲突

**修复**：
- Schema 字段名改为 `extra_attrs`，通过 `alias_generator=to_camel` 映射为前端 `extraAttrs`
- 前端 TypeScript 类型同步更新

---

## 二、服务器部署状态

| 项目 | 状态 |
|------|------|
| 数据库表 | ✅ 3 张表已创建 |
| 环境配置数据 | ✅ 1 条配置（192.168.5.44，状态：已连接） |
| paho-mqtt | ✅ 已安装（需重建镜像持久化） |
| 前端代码 | ✅ 已部署（41 个文件） |
| 后端代码 | ✅ 已部署 |

**服务器信息**：
- IP: 192.168.5.60
- SSH: ubains / Ubains@123
- 部署目录: `/data/third_party/plat-auto-test/`
- 前端: http://192.168.5.60
- API: http://192.168.5.60/docs

---

## 三、待提交的代码修改

### 后端文件

| 文件 | 修改说明 |
|------|----------|
| `backend/app/models/__init__.py` | 导入设备模拟模型 |
| `backend/app/schemas/device_sim.py` | 1. TestConnectionResponse 添加 latencyMs 别名<br>2. SimulatorBase/SimulatorUpdate 字段名 metadata → extra_attrs |
| `backend/app/services/device_sim_service.py` | 1. test_env_connection 直接查数据库<br>2. 测试成功后更新状态<br>3. list_env_configs 保留数据库状态 |

### 前端文件

| 文件 | 修改说明 |
|------|----------|
| `frontend/src/utils/request.ts` | 响应拦截器返回 response.data |
| `frontend/src/router/index.ts` | 为 /device-sim 和 /system 添加父路由组件 |
| `frontend/src/views/device-sim/index.vue` | 新建父级容器 |
| `frontend/src/views/system/index.vue` | 新建父级容器 |
| `frontend/src/views/device-sim/EnvConfig.vue` | 简化界面，去掉主题配置，添加默认账号密码 |
| `frontend/src/types/device.ts` | metadata → extraAttrs |

---

## 四、待处理任务

### P0 - 必须处理

| 任务 | 说明 |
|------|------|
| **paho-mqtt 持久化** | 当前是手动安装，需在 `requirements.txt` 中添加并重建镜像 |
| **Git 提交** | 上述修改都未提交，建议尽快提交 |

### P1 - 主题配置改造

**背景**：当前模拟器使用 `{prefix}/{device_type}/{device_id}/{action}` 格式拼接主题，但真实系统使用固定主题路径，部分包含动态参数。

**真实主题列表**：

**门口屏（7-8 个）**：
```
/meeting/conference/{会议室编号}/
/material/client/{设备ID}/
/iot/v1/conference/service/request/{公司编号}/{会议室编号}/
/doorscreen/v5/{设备ID}/face/extractFeature/imageBase64/list/up
/iot/v1/device/event/request/millimeterhaveRadar/{会议室编号}/
/meeting/message/{会议室编号}/
rebootResponseTopic
/iot/v1/device/service/request/{公司编号}/{设备ID}/
```

**无纸化（6 个）**：
```
/meeting/message/{会议室编号}/
/iot/v1/meeting/service/request/meetingControl/{公司编号}/{mid}/
/androidPanel/
/iot/v1/meeting/service/request/{会议室编号}/
/message/paperLessService/callService
```

**动态参数**：
- `{会议室编号}` - 用户填写
- `{设备ID}` - 用户填写
- `{公司编号}` - 用户填写
- `{mid}` - 会议ID，用户填写

**改造方案**（待确认）：
1. 数据模型：在 `device_simulators` 表中增加 `topic_params` JSON 字段存储参数
2. 模拟器：读取设备类型对应的固定主题模板，替换参数后使用
3. 前端：创建/编辑设备时展示该设备类型的主题列表，填写动态参数

---

## 五、环境配置说明

### MQTT 默认账号密码

创建环境配置时，账号密码已设置默认值：
- 用户名: `mqtt@cmdb`
- 密码: `mqtt@webpassw0RD`

### 当前环境配置

| 配置名称 | Broker 地址 | 端口 | 状态 |
|----------|------------|------|------|
| 192.168.5.44 | 192.168.5.44 | 1883 | 已连接 |

---

## 六、快速运维命令

### 更新后端代码

```bash
# 单个文件
scp backend/app/services/device_sim_service.py ubains@192.168.5.60:/data/third_party/plat-auto-test/backend/app/services/
ssh ubains@192.168.5.60 'cd /data/third_party/plat-auto-test/deploy && docker compose restart app'

# 全部后端
scp -r backend/app ubains@192.168.5.60:/data/third_party/plat-auto-test/backend/
ssh ubains@192.168.5.60 'cd /data/third_party/plat-auto-test/deploy && docker compose restart app'
```

### 更新前端代码

```bash
cd frontend && npm run build
scp -r dist/* ubains@192.168.5.60:/data/third_party/plat-auto-test/frontend/dist/
```

### 查看日志

```bash
ssh ubains@192.168.5.60 'cd /data/third_party/plat-auto-test/deploy && docker compose logs -f app --tail=100'
```

---

## 七、相关文档索引

| 文档 | 路径 |
|------|------|
| 设备模拟 PRD | `Docs/PRD/需求文档/设备模拟/_PRD_需求文档_设备模拟模块.md` |
| 设备模拟执行计划 | `Docs/PRD/需求文档/设备模拟/_执行计划_设备模拟模块.md` |
| 多主题配置优化 PRD | `Docs/PRD/需求文档/设备模拟/_PRD_需求优化_环境配置多主题与设备接收记录.md` |
| 项目总交接 | `HANDOFF.md` |

---

*本文档由 Claude Code 生成，记录设备模拟模块开发进度，供下次会话快速恢复上下文。*