# IoT SaaS 平台 — 功能规划与实现路线图

> 更新时间: 2026-06-17  
> 当前版本: v0.9-alpha（基础框架完成，业务功能需补全）

---

## 一、现状总览

### 1.1 已完成的骨架（后端 4 大微服务）

| 服务 | 端口 | 完成度 | 说明 |
|------|------|--------|------|
| iot-device (设备管理) | 9081 | **60%** | CRUD有，但缺少分组管理、批量操作、固件升级 |
| iot-data (数据采集) | 9082 | **70%** | MQTT接收+InfluxDB存储OK，缺实时数据流推送 |
| iot-rule (规则引擎) | 9083 | **65%** | Aviator表达式引擎OK，缺可视化规则编辑器 |
| iot-alarm (告警服务) | 9084 | **65%** | 基本告警流程OK，缺告警升级策略、值班排班 |

### 1.2 已有的前端页面（7个）

| 页面 | 路径 | 完成度 | 缺失功能 |
|------|------|--------|----------|
| Dashboard | /dashboard | **20%** | 几乎空白，无数据卡片、图表、统计 |
| 设备列表 | /devices | **75%** | 列表CRUD OK，缺详情页内容、在线状态实时刷新 |
| 设备详情 | /devices/:id | **10%** | 页面存在但基本为空壳 |
| 数据采集 | /data | **30%** | 缺历史曲线图、数据导出 |
| 规则引擎 | /rules | **55%** | 列表OK，规则编辑器体验差（纯表单） |
| 告警列表 | /alarms | **50%** | 列表OK，缺实时WebSocket推送、统计面板 |
| 告警规则 | /alarm-rules | **55%** | CRUD OK，缺条件可视化配置 |
| 登录 | /login | **85%** | 基本OK |

### 1.3 完全缺失的模块

| 模块 | 重要性 | 说明 |
|------|--------|------|
| 🔴 用户/角色管理 | **P0** | 有sys_user/sys_role表但没有前端页面和管理接口 |
| 🔴 租户管理 | **P0** | 有tenant表但没有多租户隔离逻辑 |
| 🟡 设备分组管理 | **P1** | 有device_group表但前端无对应页面 |
| 🟡 操作日志 | **P1** | 有log_operation表但无查询页面 |
| 🟡 第三方设备适配器 | **P1** | 只有LocalDeviceAdapter模拟器 |
| 🟢 文件/图片上传 | **P2** | 无上传服务 |
| 🟢 个人中心 | **P2** | 无修改密码、个人信息页 |
| 🟢 UniApp移动端 | **P2** | 未开始开发 |
| ⚪ API网关 | **P3** | 单体阶段可暂缓 |
| ⚪ Matter协议 | **P3** | 可选扩展 |

---

## 二、按优先级划分的详细功能清单

### P0 — 必须立即实现（核心可用性）

#### 2.1 Dashboard 数据看板（当前几乎空白！）

```
目标：打开系统第一眼能看到全局运营状态
```

| 功能点 | 描述 | 复杂度 |
|--------|------|--------|
| 设备统计卡片 | 在线/离线/异常设备数，总设备数 | 低 |
| 今日告警概览 | 新增告警数、待处理数、已解决数 | 低 |
| 数据上报趋势 | 近7天数据量折线图（ECharts） | 中 |
| 设备类型分布饼图 | sensor/controller/gateway占比 | 低 |
| 最近告警列表 | 最新5条告警，点击跳转详情 | 低 |
| 设备状态地图 | 可选：设备地理位置分布 | 高（可选） |

#### 2.2 用户 & 权限管理（系统管理员必须能管人）

| 功能点 | 描述 | 复杂度 |
|--------|------|--------|
| 用户列表 | 分页、搜索、角色筛选 | 低 |
| 用户新增/编辑 | 用户名/密码/手机号/邮箱/分配角色 | 中 |
| 用户禁用/启用 | 冻结账户 | 低 |
| 重置密码 | 管理员重置用户密码 | 低 |
| 角色列表 | 角色 CRUD | 低 |
| 权限分配 | 给角色勾选菜单权限/按钮权限 | 中 |
| 菜单权限控制 | 根据角色动态显示菜单 | 中 |
| 按钮级权限 | v-permission指令控制按钮显隐 | 中 |

#### 2.3 设备详情页充实化（当前是空壳）

| 功能点 | 描述 | 复杂度 |
|--------|------|--------|
| 基本信息 | 设备属性表格展示（名称/类型/平台/型号/固件版本等） | 低 |
| 实时状态 | 在线/离线/最后通信时间 | 低 |
| 最新数据 | 最近一条设备数据（温度/湿度等key-value） | 中 |
| 历史数据曲线 | ECharts 折线图，选时间范围查InfluxDB | 高 |
| 控制面板 | 根据deviceType动态渲染控制组件（开关/滑块/输入框） | 高 |
| 操作记录 | 该设备的命令发送历史 | 中 |
| 告警历史 | 该设备关联的告警记录 | 低 |

#### 2.4 设备列表增强

| 功能点 | 描述 | 复杂度 |
|--------|------|--------|
| 批量操作 | 多选删除/批量启停/批量分配分组 | 中 |
| 导入/导出 | Excel模板导入设备、导出设备列表 | 中 |
| 设备影子 | 显示设备期望状态 vs 上报状态 | 中 |
| 快捷搜索 | 支持模糊搜索设备ID/名称 | 已有 ✅ |
| 在线状态标识 | 表格行用绿/灰/红圆点标示 | 低 |

---

### P1 — 短期内实现（产品完整性）

#### 2.5 设备分组管理

| 功能点 | 描述 | 复杂度 |
|--------|------|--------|
| 分组树形结构 | 左侧树 + 右侧列表 | 中 |
| 分组CRUD | 新增/编辑/删除/拖拽排序 | 中 |
| 分组下设备管理 | 将设备拖入/移出分组 | 中 |
| 分组统计 | 每组的设备数量、在线数 | 低 |

#### 2.6 数据采集模块增强

| 功能点 | 描述 | 复杂度 |
|--------|------|--------|
| 数据看板 | 选设备→选数据点→显示实时曲线 | 高 |
| 多设备对比 | 同一数据点多设备对比图 | 高 |
| 时间范围选择 | 近1小时/6小时/24小时/7天/30天/自定义 | 中 |
| 数据聚合 | 求平均值/最大值/最小值/求和 | 中 |
| 数据导出 | 导出CSV/Excel | 中 |
| 数据异常标记 | 超过阈值的数据点高亮 | 中 |

#### 2.7 告警管理增强

| 功能点 | 描述 | 复杂度 |
|--------|------|--------|
| 告警统计面板 | 按级别/状态/设备分布统计卡片 | 中 |
| 告警趋势图 | 每日新增告警柱状图 | 中 |
| 实时告警推送 | WebSocket连接 → 新告警弹窗提示 | 中 |
| 告警确认/处理备注 | 处理人填写处理意见 | 低 |
| 告警升级 | 超时未处理自动升级通知上级 | 高 |
| 值班排班 | 设置值班人员/时间段 | 高 |
| 告警静默 | 特定时段/特定规则暂停告警 | 中 |

#### 2.8 规则引擎增强

| 功能点 | 描述 | 复杂度 |
|--------|------|--------|
| 可视化规则编辑 | IF条件(下拉选设备+数据点+比较符) THEN动作(下拉) | 高 |
| 规则测试 | 编辑时模拟输入测试执行结果 | 高 |
| 规则执行日志 | 查看每次触发的时间/输入/输出/是否成功 | 中 |
| 场景联动 | 一键执行多个动作（如：开灯+开空调） | 高 |
| 定时任务触发 | cron表达式定时触发规则 | 中 |

#### 2.9 操作日志

| 功能点 | 描述 | 复杂度 |
|--------|------|--------|
| 日志列表 | 操作人/操作类型/操作内容/IP/时间 | 低 |
| 日志搜索 | 按用户/时间范围/操作类型过滤 | 低 |
| 日志详情 | 展示请求参数和响应 | 低 |

#### 2.10 第三方设备适配器（至少实现1个真实平台）

| 适配器 | 优先级 | 工作量 | 说明 |
|--------|--------|--------|------|
| 涂鸦智能(Tuya) | ⭐⭐⭐ | 5-7天 | OpenAPI成熟，文档齐全，推荐首选 |
| 小米IoT(MIOT) | ⭐⭐ | 5-7天 | 需要逆向或使用Home Assistant桥接 |
| Matter协议 | ⭐ | 8-10天 | Java SDK尚不成熟，建议后期再搞 |

---

### P2 — 中期优化（用户体验提升）

#### 2.11 文件/图片上传服务

- 设备头像/图片上传
- 附件上传（如设备说明书）
- 支持 OSS / MinIO / 本地存储

#### 2.12 个人中心

- 修改密码
- 修改个人信息（头像/昵称/手机号）
- 登录日志查看

#### 2.13 系统设置

- 平台基础配置（名称/Logo/公告）
- 告警通知渠道配置（邮件SMTP/短信API Key/钉钉Webhook）
- 数据保留策略配置

#### 2.14 UniApp 移动端

| 功能 | 说明 |
|------|------|
| 首页 | 设备快捷入口 + 最近告警 |
| 设备列表 | 我的设备，支持控制 |
| 设备控制 | 开关/滑块/状态查看 |
| 告警消息 | 消息列表 + 推送通知 |
| 个人中心 | 信息修改/退出登录 |

#### 2.15 固件管理（OTA）

- 固件版本管理
- 固件上传
- 设备固件升级任务
- 升级进度/结果记录

---

### P3 — 长期演进（架构升级）

| 功能 | 说明 |
|------|------|
| API网关 | Spring Cloud Gateway 统一入口、限流、鉴权 |
| 注册中心 | Nacos 服务注册与发现 |
| 配置中心 | Nacos 集中配置管理 |
| 链路追踪 | SkyWalking / Zipkin |
| ELK日志 | Elasticsearch + Logstash + Kibana |
| Prometheus监控 | 指标采集 + Grafana大屏 |
| 多租户完整隔离 | Schema隔离 / 字段级隔离 |
| 国际化(i18n) | 中英文切换 |

---

## 三、建议实施顺序

```
第1周 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
├── Dashboard数据看板（4张统计卡 + 1条趋势图 + 最近告警）
├── 设备详情页充实化（基本信息 + 最新数据 + 操作记录）
└── 设备列表增强（状态标识 + 批量操作）

第2周 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
├── 用户管理（CRUD + 启用禁用 + 重置密码）
├── 角色权限管理（角色CRUD + 菜单权限 + 按钮权限）
├── 动态路由（根据角色生成菜单）
└── 设备分组管理（树形结构 + 设备归属）

第3周 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
├── 数据采集增强（ECharts曲线图 + 时间范围 + 数据导出）
├── 告警管理增强（统计面板 + 实时WebSocket推送 + 确认处理）
├── 操作日志页面
└── 个人中心（改密码 + 个人信息）

第4周 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
├── 规则引擎可视化编辑器（IF-THEN拖拽式）
├── 告警规则条件可视化配置
├── 涂鸦智能适配器对接（如果需要）
└── UI整体打磨（响应式/交互细节/错误处理）

第5周+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
├── UniApp移动端开发
├── 固件OTA管理
├── 系统设置/文件上传
└── 部署优化/性能调优
```

---

## 四、各模块数据库补充

以下表可能还需要新增：

```sql
-- 操作日志表（可能已有log_operation，确认字段是否足够）
CREATE TABLE IF NOT EXISTS `operation_log` (
    `id` BIGINT PRIMARY KEY,
    `user_id` BIGINT COMMENT '操作人',
    `username` VARCHAR(64) COMMENT '操作人名',
    `module` VARCHAR(64) COMMENT '模块',
    `operation` VARCHAR(64) COMMENT '操作类型',
    `method` VARCHAR(256) COMMENT '请求方法',
    `request_url` VARCHAR(256) COMMENT '请求URL',
    `request_params` TEXT COMMENT '请求参数',
    `response_result` TEXT COMMENT '响应结果',
    `ip` VARCHAR(64) COMMENT 'IP地址',
    `status` TINYINT COMMENT '状态(0失败 1成功)',
    `error_msg` VARCHAR(512) COMMENT '错误信息',
    `execute_time` BIGINT COMMENT '执行时长(ms)',
    `create_time` DATETIME,
    INDEX `idx_user_id` (`user_id`),
    INDEX `idx_create_time` (`create_time`)
);

-- 系统配置表
CREATE TABLE IF NOT EXISTS `sys_config` (
    `id` BIGINT PRIMARY KEY,
    `config_key` VARCHAR(128) NOT NULL UNIQUE COMMENT '配置键',
    `config_value` TEXT COMMENT '配置值',
    `config_name` VARCHAR(128) COMMENT '配置名称',
    `remark` VARCHAR(256) COMMENT '备注',
    `create_time` DATETIME,
    `update_time` DATETIME
);

-- 固件版本表（OTA）
CREATE TABLE IF NOT EXISTS `firmware` (
    `id` BIGINT PRIMARY KEY,
    `name` VARCHAR(128) NOT NULL COMMENT '固件名称',
    `version` VARCHAR(32) NOT NULL COMMENT '版本号',
    `device_type` VARCHAR(32) COMMENT '适用设备类型',
    `file_url` VARCHAR(512) NOT NULL COMMENT '文件URL',
    `file_size` BIGINT COMMENT '文件大小(bytes)',
    `md5` VARCHAR(64) COMMENT '文件MD5校验',
    `changelog` TEXT COMMENT '更新说明',
    `status` TINYINT DEFAULT 1 COMMENT '状态(0草稿 1发布 2废弃)',
    `create_by` BIGINT,
    `create_time` DATETIME
);

-- 设备固件升级记录表
CREATE TABLE IF NOT EXISTS `device_upgrade_record` (
    `id` BIGINT PRIMARY KEY,
    `device_id` VARCHAR(64) NOT NULL,
    `firmware_id` BIGINT NOT NULL,
    `from_version` VARCHAR(32) COMMENT '升级前版本',
    `to_version` VARCHAR(32) NOT NULL COMMENT '目标版本',
    `status` TINYINT DEFAULT 0 COMMENT '状态(0待升级 1升级中 2成功 3失败)',
    `progress` INT DEFAULT 0 COMMENT '进度百分比',
    `error_msg` VARCHAR(512) COMMENT '失败原因',
    `upgrade_time` DATETIME COMMENT '升级完成时间',
    `create_time` DATETIME,
    INDEX `idx_device_id` (`device_id`)
);

-- 通知消息表（站内信/WebSocket推送）
CREATE TABLE IF NOT EXISTS `notification` (
    `id` BIGINT PRIMARY KEY,
    `user_id` BIGINT NOT NULL COMMENT '接收人',
    `title` VARCHAR(128) NOT NULL COMMENT '标题',
    `content` TEXT NOT NULL COMMENT '内容',
    `type` VARCHAR(32) DEFAULT 'system' COMMENT '类型(system/alarm/task)',
    `related_id` BIGINT COMMENT '关联业务ID',
    `is_read` TINYINT DEFAULT 0 COMMENT '是否已读',
    `create_time` DATETIME,
    INDEX `idx_user_id` (`user_id`),
    INDEX `idx_is_read` (`is_read`)
);
```

---

## 五、技术要点提醒

| 注意事项 | 说明 |
|----------|------|
| 租户隔离 | 当前BaseEntity有tenantId但Service层未做数据隔离，所有服务查询都需要加 `wrapper.eq(Device::getTenantId, currentTenantId)` |
| 前端代理 | vite.config.ts 的proxy是开发用的，生产环境需要Nginx反向代理或API网关 |
| WebSocket连接 | 告警实时推送需要在main.js建立全局WebSocket连接并维护重连机制 |
| ECharts响应式 | 图表容器resize监听，避免窗口变化变形 |
| Excel导入导出 | 推荐EasyExcel库（阿里开源），支持大数据量 |
| 文件上传 | 建议先做本地存储，后续无缝切换到MinIO/OSS |
| 涂鸦对接 | 需要涂鸦IoT开放平台的Access ID/Secret，走OAuth2获取token |

---

## 六、快速启动建议

如果你认同以上规划，建议**从这3件事开始**（效果最明显）：

1. **Dashboard数据看板** — 让系统"看起来像个产品"
2. **用户&角色管理** — 让系统"可以多人使用"
3. **设备详情页** — 让系统"每个功能都能用起来"

告诉我你想先从哪个模块开始？