本司设备联网管理平台——整理后实施基线

本文件是 本司设备联网管理.md 的实施副本。原文件未修改，SHA-256 为 85D8501A9A36C2F04B1A168DC23F4A70259B3F95B6C6AE5DFEF6BC307D6AEC8E。

CHANGED_BRANCH=stack-migration-spring-monolith
CHANGED_FIELD=technology_stack: vanilla_js_node_json -> vue3_typescript_springboot_mysql_redis_kafka_emqx

1. 本期目标

先交付本司设备联网管理 MVP，打通以下闭环：

管理员维护产品、设备、用户、指令、告警和审计记录。
设备通过 MQTT 连接 EMQX；EMQX 与 Kafka 桥接设备上下行消息。
Spring Boot 后端只订阅和发布 Kafka Topic，不直接连接 MQTT。
用户通过微信小程序登录、绑定设备、查看本人设备和下发控制指令。
MySQL 保存业务数据和当前阶段遥测，Redis 保存登录会话并承担热点缓存。

2. 技术基线

层次	当前选择	实施说明
管理后台	Vue 3、TypeScript、Vite、Pinia、Vue Router	响应式单页应用，统一调用 `/api`
后端	Java 17、Spring Boot 3	先做模块化单体，按领域边界组织代码
数据访问	Spring Data JPA、Flyway	MySQL 表结构版本化，启动时校验迁移
业务数据库	MySQL	用户、产品、设备、遥测、指令、告警、审计
登录与缓存	Redis	`iot:session:{token}` 会话校验；产品等热点查询缓存
设备消息	Kafka	后端只消费上行/ACK Topic，只发布下行 Topic
MQTT 服务	EMQX	负责设备 MQTT 连接、认证/ACL及 MQTT↔Kafka 桥接
用户端	原生微信小程序	登录、设备绑定、设备列表、详情和控制

所有中间件地址、凭证、TLS/SASL 参数和 Topic 名均由环境变量注入。收到实际地址文档后，只补部署配置，不修改业务代码中的连接逻辑。

3. 消息拓扑

设备 --MQTT--> EMQX --规则/桥接--> Kafka 上行主题 --消费--> Spring Boot 单体
设备 <--MQTT-- EMQX <--规则/桥接-- Kafka 下行主题 <--发布-- Spring Boot 单体

Kafka Topic	方向	消息用途
`iot.device.telemetry.up`	EMQX → 后端	属性/遥测上报
`iot.device.event.up`	EMQX → 后端	故障、告警等设备事件
`iot.device.command.down`	后端 → EMQX	设备控制指令
`iot.device.command.ack`	EMQX → 后端	指令执行回执

Kafka 按至少一次投递设计。遥测以 (deviceId, messageId) 幂等，指令以 commandId 关联 ACK；HTTP 请求成功只表示指令已进入下行链路，设备 ACK 才决定最终成功或失败。

4. 单体模块边界

模块	当前职责	后续拆分触发点
IAM	后台/小程序登录、Redis 会话、角色权限	多租户或统一身份中心接入
产品与物模型	ProductKey、品类、协议、模型版本	物模型版本数量和协作团队增长
设备	注册、状态、归属、属性快照、绑定	设备规模需要独立伸缩
消息接入	Kafka 消费、校验、幂等、落库	吞吐量或消费组需独立扩缩容
控制	指令创建、发布、ACK 状态机	下行可靠性策略独立演进
告警	设备事件转告警、处置状态	规则引擎和通知渠道增加
审计	关键操作留痕	集中日志/合规平台接入

单体阶段共享一个部署单元和 MySQL 实例，但禁止跨模块直接依赖控制器或数据库实现细节。微服务化时优先拆消息接入与遥测，再拆控制和告警；API、Kafka 事件、表归属和版本必须明确。

5. 当前功能范围

5.1 管理后台

账号登录、退出和路由/角色守卫。
仪表盘：设备、在线数、用户、待处理告警、当日指令。
产品、设备、用户列表及产品/设备新增。
设备详情、属性、指令下发。
指令、告警和审计查询；告警处置。
桌面与窄屏响应式布局。

5.2 Spring Boot 后端

Bearer Token 认证、管理员/运维/个人用户权限边界。
Redis 会话写入、读取、续期边界和退出删除。
Redis 产品查询缓存。
MySQL/JPA 实体、Repository 和 Flyway 初始化脚本。
产品、设备、用户、指令、告警、审计 REST API。
Kafka 遥测/事件/ACK 消费与命令发布。
Actuator 健康、信息和指标端点。
测试 profile 使用 H2、内存 SessionStore 和 Noop Kafka Publisher，不访问已部署中间件。

5.3 微信小程序

微信登录接口封装和 Token 保存。
扫码或输入绑定码绑定设备。
仅查询当前用户拥有的设备。
查看状态与属性，下发本人在线设备指令。
登录失效统一清理会话并返回登录页。

6. 数据和状态约束

产品 product_key、设备序列号和绑定码唯一。
设备所有权查询必须同时校验当前用户和 owner_id。
设备状态使用 ONLINE / OFFLINE。
指令状态使用 PENDING → SENT → SUCCEEDED | FAILED | TIMEOUT | CANCELED。
告警状态使用 OPEN / PROCESSING / RESOLVED。
当前遥测写入 MySQL device_telemetry；后续可保持 Kafka 契约不变，将遥测模块迁往专用存储。

7. 配置待补项

实际中间件地址文档到位后，填写 backend/.env.example 对应部署环境变量：

MYSQL_URL / MYSQL_USERNAME / MYSQL_PASSWORD
REDIS_HOST / REDIS_PORT / REDIS_PASSWORD / REDIS_DATABASE
KAFKA_BOOTSTRAP_SERVERS / KAFKA_CONSUMER_GROUP
KAFKA_TOPIC_TELEMETRY_UP / EVENT_UP / COMMAND_DOWN / COMMAND_ACK
Kafka SASL/TLS 参数和证书挂载路径（若集群启用）
EMQX Bridge、规则名称、MQTT Topic 映射、设备认证和 ACL

EMQX_DASHBOARD_URL 仅用于运维信息。后端不得新增 MQTT 客户端来绕过 Kafka 桥接。

8. 目录与验证入口

物联网项目文档/
├─ 00～12、物联网项目文档.md、项目规划.md   整理后的文档集
└─ iot-platform-mvp/
   ├─ admin-web/      Vue 3 + TypeScript 管理后台
   ├─ backend/        Spring Boot 模块化单体
   └─ mini-program/   原生微信小程序

cd .\物联网项目文档\iot-platform-mvp\backend
.\mvnw.cmd clean test

cd ..\admin-web
npm run build

小程序使用微信开发者工具导入 mini-program。开发环境 API 默认指向 http://127.0.0.1:8080；实际联调时通过配置改为可访问的 HTTPS 地址。

9. 文档整理结果

核心文档已统一为 00～12 编号和一致命名。
已合并零散概念、重复需求、提问草稿和已过时的数据库选型内容。
已删除 9 个不再单独维护的冗余文档/图；物模型关系图继续保留。
架构、详细设计、测试、部署、用户、验收、API 和路线图均已改为当前 Vue/Spring/MySQL/Redis/Kafka/EMQX 基线。

📒 笔记文档