Open IoT Platform 产品需求文档 (PRD)
作者: 罗耀生 日期: 2026-01-10 版本: v0.3.0
1. 产品概述
1.1 产品定位
Open IoT Platform 是一个轻量级的开源 IoT 设备管理平台，提供从硬件固件、云端服务到移动端配网的完整解决方案。适用于智能家居、工业控制、传感器网络等物联网应用场景。
1.2 核心价值
| 价值点 | 说明 |
|---|---|
| 轻量部署 | 单容器部署，依赖最小化，降低运维成本 |
| 快速配网 | BLE 蓝牙配网，用户无需输入 WiFi 密码 |
| 统一管理 | 设备、产品、项目统一管理，支持多设备类型 |
| 开源可控 | GPL v3 协议，代码完全自主可控 |
| 扩展性强 | 动态控制面板，支持自定义设备类型 |
1.3 系统架构
┌─────────────────────────────────────────────────────────────┐
│ 移动端 APP │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ 设备列表 │ │ BLE 配网 │ │ 设备控制 │ │ 系统设置 │ │
│ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 服务端 (Go + Gin) │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ 设备管理 │ │ 产品管理 │ │ 用户管理 │ │ MQTT Broker│ │
│ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │
└─────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ MySQL │ │ Redis │ │ MQTT Broker │
│ (数据存储) │ │ (状态缓存) │ │ (消息路由) │
└──────────────┘ └──────────────┘ └──────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 设备端 │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ ESP32 智能开关 │ │ ESP32-S3 USB唤醒 │ │
│ │ (舵机控制) │ │ (HID 唤醒) │ │
│ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘1.4 技术栈
| 层级 | 技术选型 |
|---|---|
| 移动端 | Flutter 3.10.1 + Provider |
| 服务端 | Go 1.24 + Gin + GORM |
| 数据库 | MySQL 8.0 |
| 缓存 | Redis 7 (可选) |
| MQTT | 内置 Broker (mochi-mqtt) |
| 固件 | ESP32/ESP32-S3 (PlatformIO + Arduino) |
| 部署 | Docker + Docker Compose |
2. 功能模块
2.1 模块清单
| 模块 | 功能 | 状态 |
|---|---|---|
| 用户管理 | 注册、登录、Token 管理、API Key | ✅ 已实现 |
| 产品管理 | 产品定义、物模型、UI 配置 | ✅ 已实现 |
| 设备管理 | 设备激活、列表查询、状态管理 | ✅ 已实现 |
| 设备控制 | 远程控制、状态查询、历史记录 | ✅ 已实现 |
| BLE 配网 | 设备扫描、WiFi 配置、设备激活 | ✅ 已实现 |
| MQTT 服务 | 设备认证、消息路由、ACL 控制 | ✅ 已实现 |
| 动态面板 | 根据产品类型动态渲染控制界面 | ✅ 已实现 |
| 项目管理 | 项目分组、权限管理 | 🚧 部分实现 |
2.2 设备类型支持
| 设备类型 | Product Key | 控制模式 | UI 模板 |
|---|---|---|---|
| 舵机开关 | SW-SERVO-001 | toggle | servo_switch |
| USB 唤醒 | USB-WAKEUP-S3 | trigger | wakeup |
3. 核心流程
3.1 设备配网流程
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ 设备上电 │ ──> │ 检查配置 │ ──> │ 进入BLE │ ──> │ APP扫描 │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
│
┌─────────┐ ┌─────────┐ ┌─────────┐ ▼
│ 正常运行 │ <─── │ MQTT连接 │ <─── │ 设备激活 │ <───┤ 传输WiFi │
└─────────┘ └─────────┘ └─────────┘ └─────────┘3.2 设备控制流程
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ 用户操作 │ ──> │ APP发送 │ ──> │ 服务端 │ ──> │ MQTT发布 │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
│
┌─────────┐ ┌─────────┐ ┌─────────┐ ▼
│ 状态更新 │ <─── │ APP接收 │ <─── │ 服务端 │ <───┤ 设备执行 │
└─────────┘ └─────────┘ └─────────┘ └─────────┘3.3 设备状态同步
设备上线 → 更新 LastOnlineAt → 标记为在线 → 更新 Redis 缓存
│
│ (30秒无活动)
▼
离线检测 → 标记为离线 → 清除 Redis 缓存 → 通知前端4. 非功能性需求
4.1 性能指标
| 指标 | 要求 |
|---|---|
| API 响应时间 | < 200ms (P95) |
| MQTT 消息延迟 | < 100ms |
| 并发设备数 | 1000+ |
| 设备离线检测 | 30 秒 |
4.2 安全要求
| 安全点 | 措施 |
|---|---|
| 传输加密 | HTTPS (API) + TLS (MQTT) |
| 身份认证 | JWT Token + API Key |
| 设备认证 | MQTT Username/Password |
| 密码存储 | bcrypt 哈希 |
4.3 可用性要求
| 指标 | 要求 |
|---|---|
| 系统可用性 | 99.5% |
| 故障恢复 | 自动重启 |
| 数据备份 | 定时备份 |
5. 部署架构
5.1 生产环境
yaml
服务:
- IoT Platform (单容器)
- MySQL 8.0
- Redis 7 (可选)
端口:
- 48080: API 服务
- 1883: MQTT TCP
- 8083: MQTT WebSocket5.2 开发环境
yaml
服务:
- IoT Platform (本地构建)
- MySQL 8.0 (开启通用日志)
- Redis 7
额外功能:
- 代码热重载
- 详细日志输出6. 版本规划
6.1 当前版本 (v0.3.0)
- ✅ 内置 MQTT Broker
- ✅ Redis 设备状态缓存
- ✅ 动态控制面板
- ✅ 设备离线自动检测
- ✅ USB 唤醒设备支持
6.2 规划中功能
- [ ] Web 管理界面
- [ ] 设备固件 OTA 升级
- [ ] 定时任务/场景联动
- [ ] 设备分享功能
- [ ] 数据统计与分析
7. 参考文档
修改历史
| 日期 | 版本 | 修改内容 | 作者 |
|---|---|---|---|
| 2026-01-10 | v0.3.0 | 初始版本 | 罗耀生 |