# device-simulation

**Repository Path**: zhoulvvv/device-simulation

## Basic Information

- **Project Name**: device-simulation
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-28
- **Last Updated**: 2026-07-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 设备模拟平台（SUB1G 门锁 MQTT 模拟器）

基于 Go + React 的 IoT 设备模拟控制台，当前内置 **SUB1G 集群联网门锁** 插件。可创建网关/门锁、连接 MQTT Broker、模拟开门/门磁等事件、下发平台指令、管理授权，并通过 WebSocket 实时推送状态与消息日志。

协议说明见 [`docs/SUB1G集群联网门锁MQTT通讯协议(JSON格式).md`](docs/SUB1G集群联网门锁MQTT通讯协议(JSON格式).md)。

---

## 功能概览

- **网关**：创建 / 删除 / 全局 MQTT 配置并重连
- **设备**：在网关下或独立创建门锁；移动、删除、绑定
- **门锁模拟**：刷卡 / 密码 / 指纹 / 人脸 / 门磁等事件；记录三态（pending → pushed → confirmed）
- **平台指令**：`configLock`、`readRecord`、`authCard` 等（由 DeviceSpec 声明，前端按 spec 渲染）
- **授权管理**：卡 / 密码 / 指纹 / 人脸增删改查
- **消息日志**：MQTT 上行 / 下行（心跳默认不记入前端日志）
- **前端控制台**：中文 UI，总览 + 侧栏设备树 + 详情 Tabs + 底部消息面板

---

## 技术栈

| 层 | 技术 |
|---|---|
| 后端 | Go 1.25、paho MQTT、gorilla/websocket、modernc.org/sqlite |
| 前端 | React 18、TypeScript、Vite 6、antd 6 |
| 通信 | HTTP 静态资源 + REST；业务主路径为 WebSocket `/api/ws` |

---

## 目录结构

```
device-simulation/
├── main.go                 # 入口：DB / Hub / Manager / 路由 / 优雅停机
├── handlers/               # HTTP + WebSocket 处理器
│   ├── handlers.go         # Setup、公共 helper、查询类 API
│   ├── ws.go               # WebSocket 升级与全部 action
│   ├── gateway.go          # 网关 HTTP
│   └── device.go           # 设备 HTTP
├── core/                   # 设备抽象：Device / Spec / Registry / Connector
├── devices/
│   └── lock/               # 门锁插件（协议、状态机、spec 注册）
├── sim/                    # 运行时：Manager、Gateway 生命周期
├── store/                  # SQLite 持久化
├── mqtt/                   # MQTT 客户端封装
├── ws/                     # WebSocket Hub（广播、ping/pong）
├── frontend/               # 控制台前端（构建产物 frontend/dist）
└── docs/                   # 协议文档
```

### 架构关系

```
前端 (React)
    │  WebSocket /api/ws  +  静态资源 /
    ▼
handlers  ──►  sim.Manager  ──►  Gateway / Device
                    │                 │
                    ▼                 ▼
                 store (SQLite)    mqtt.Client
                                      │
                                      ▼
                                 MQTT Broker
```

- **core**：与业务无关的设备接口与声明式 `DeviceSpec`；插件通过 `init()` 注册。
- **devices/lock**：门锁协议实现，`_ "device-simulation/devices/lock"` 空白导入自动注册。
- **sim**：网关绑定状态机、设备挂载、下行分发、状态聚合。
- **handlers**：只做参数解析与调用 Manager，不写业务状态。

---

## 快速开始

### 1. 准备 MQTT Broker

本机需有可连接的 Broker（例如 Mosquitto / EMQX / aedes），默认配置为：

- Broker：`localhost`
- 端口：`1883`
- 用户名 / 密码：空

可在控制台「网关详情 → MQTT 配置」中修改（全局共用）。

### 2. 构建前端

```bash
cd frontend
npm install
npm run build
```

后端会托管 `./frontend/dist`。开发时也可单独 `npm run dev`，但需自行代理 `/api`。

### 3. 启动服务

```bash
# 内存库（重启丢失）
go run .

# 持久化
go run . -db data/sim.db -port 7777
```

| 参数 | 默认 | 说明 |
|---|---|---|
| `-db` | 空（内存） | SQLite 文件路径 |
| `-port` | `7777` | HTTP 监听端口 |

打开：http://localhost:7777

WebSocket：`ws://localhost:7777/api/ws`

Ctrl+C / SIGTERM 会优雅停机：停设备、断 MQTT、关 HTTP、关 DB。

### 4. 测试

```bash
go test ./core/ ./store/ ./devices/lock/
```

---

## WebSocket 协议（主路径）

客户端发送：

```json
{ "action": "<name>", "data": { ... } }
```

服务端推送：

```json
{ "type": "<event>", ... }
```

### 常用 action

| action | 说明 |
|---|---|
| `get_status` / `get_specs` | 拉取运行状态、设备类型 spec |
| `create_gateway` / `delete_gateway` | 创建 / 删除网关 |
| `update_gateway_mqtt` | 更新 MQTT 并重连 |
| `create_device` / `delete_device` / `move_device` | 设备 CRUD |
| `bind_device` | 网关绑定模式下绑定门锁 |
| `simulate_event` | 模拟开门等事件 |
| `send_command` | 下发平台指令 |
| `device_action` | 设备专用动作 |
| `get_device_auths` / `add_device_auth` / `delete_device_auth` / `clear_device_auths` / `clear_all_device_auths` | 授权 |

### 常用推送 type

| type | 说明 |
|---|---|
| `status` / `specs` | 全量状态、类型定义 |
| `gateway_created` / `gateway_deleted` / `gateway_mqtt_updated` | 网关变更 |
| `device_created` / `device_deleted` / `device_moved` / `device_bound` | 设备变更 |
| `event_simulated` / `command_sent` / `device_action_result` | 操作回执 |
| `device_auths` | 授权列表刷新 |
| `message_log` | MQTT 上下行日志（不含心跳） |
| `error` | 错误（`message` 字段；前端会中文映射） |

事件驱动刷新：多数写操作成功后前端再拉 `get_status`，不依赖 correlation id。

---

## HTTP API（辅助）

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/status` | 运行状态 |
| GET | `/api/specs` | 设备类型列表 |
| GET | `/api/mqtt_config` | 全局 MQTT 配置 |
| GET | `/api/message_log` | 最近消息日志 |
| POST | `/api/gateway/create` | 创建网关 |
| POST | `/api/gateway/delete` | 删除网关 |
| POST | `/api/gateway/mqtt` | 更新 MQTT |
| POST | `/api/device/create` | 创建设备 |
| POST | `/api/device/delete` | 删除设备 |
| POST | `/api/device/move` | 移动设备 |
| POST | `/api/device/bind` | 绑定设备 |
| POST | `/api/device/simulate` | 模拟事件 |
| POST | `/api/device/action` | 设备动作 |
| GET | `/api/device/auths?deviceId=` | 授权列表 |
| GET | `/api/ws` | WebSocket 升级 |
| GET | `/` | 前端静态资源 |

---

## 门锁插件要点

- **子型号**（config `type`）：90 卡密 / 91 卡密+指纹 / 92 卡密+扫码 / 93 卡密+人脸 / 94 卡密+指纹+人脸
- **绑定**：网关进入绑定模式后，对目标门锁执行绑定；`IsBound()` 以 DB 为准
- **记录**：模拟事件写入 pending；`readRecord` 按协议推进 pushed / confirmed；可分批 `more`
- **心跳**：SUB1G 双速（约 6s → 60s），前端消息日志默认过滤心跳
- **主题**（默认）：上行 `device/{clientId}`，下行 `smartHouse/{clientId}`

---

## 扩展新设备类型

1. 在 `devices/<name>/` 实现 `core.Device`，并提供 `DeviceSpec`
2. `init()` 中 `core.Register(...)`
3. 在 `main.go` 增加空白导入：`_ "device-simulation/devices/<name>"`
4. 前端按 spec 自动渲染命令 / 事件 / 状态 / 授权，一般无需改 UI

---

## 开发提示

- 改前端后需重新 `npm run build`，或使用 Vite 开发服务器
- 全局变量 `handlers` 包内 `hub` / `mgr` 由 `handlers.Setup` 注入，勿在 Setup 前访问
- 数据库迁移在 `store` 启动时执行（例如历史 `gateway_id=''` → `NULL`）
- Windows 下优雅停机对 SIGINT 行为与 Unix 略有差异；生产环境建议发 SIGTERM

---

## License

内部项目，按团队约定使用。