平台架构概览 (Platform Overview)
本章节旨在帮助新成员快速理解 YunStack-IoT 平台的设计理念、架构组成以及核心交互流程。
为了让您能够循序渐进地掌握平台技术，我们建议按照以下顺序阅读文档：
📚 阅读路径建议
第一阶段：认知与概览
目标：了解这套系统长什么样，解决什么问题。
- 01.系统架构设计
- 必读。包含系统逻辑分层图（设备端、接入层、服务层、应用层）及各模块职责说明。看完后您脑海中应该有一张系统的全景图。
- 02.核心业务流程
- 必读。通过时序图展示了最核心的两个场景："设备上报数据" 和 "用户控制设备"。理解了这两个流程，就理解了 IoT 平台 80% 的工作机制。
- 04.数据模型概览
- 必读。梳理了三个核心实体（产品 → 设备 → 遥测数据）的 ER 关系、双 ID 体系，以及 PostgreSQL + InfluxDB + Redis 的分层存储策略。从数据视角理解平台设计。
第二阶段：协议与接入
目标：掌握设备如何与平台通信，以及对外开放的 API 规范。
- 05.物模型设计规范
- 开发核心。定义了设备的能力模型（属性、事件、服务）。如果您要接入一个新设备，首先需要看这里如何用 JSON 描述设备。
- 06.MQTT通信协议
- 通信核心。规定了设备 Topic 和 Payload 格式、设备注册流程、认证方式和权限模型。嵌入式开发和后端开发都需要严格遵守此规范。
- 08.API接口规范
- 接口参考。完整的 REST API 文档，包含 Auth、User、Role、Product、Device 等接口组，以及统一响应格式和业务错误码体系。
第三阶段：深入与参考
目标：理解技术选型的理由和架构决策背后的权衡。
- 03.技术栈选型
- 列出了后端 (NestJS + Prisma)、数据库 (PostgreSQL + InfluxDB + Redis)、前端 (Vue 3 + UniApp) 等核心技术选型及其理由。
- 07.消息接入决策
- 进阶阅读。详细记录了"Webhook vs MQTT Client"方案的权衡过程，以及何时引入消息队列 (Kafka/RabbitMQ) 的评估结论。
⚡ 快速导航
| 编号 | 文档 | 说明 | 链接 |
|---|---|---|---|
| 01 | 系统架构设计 | 系统分层逻辑与部署架构 | 阅读 |
| 02 | 核心业务流程 | 设备上报/控制交互时序 | 阅读 |
| 03 | 技术栈选型 | 核心技术选型及理由 | 阅读 |
| 04 | 数据模型概览 | 核心实体、双ID、存储分层 | 阅读 |
| 05 | 物模型设计规范 | 设备能力 JSON 定义 | 阅读 |
| 06 | MQTT通信协议 | Topic/Payload/认证规范 | 阅读 |
| 07 | 消息接入决策 | Webhook vs MQTT Client 权衡 | 阅读 |
| 08 | API接口规范 | REST API 与错误码 | 阅读 |
| 09 | EMQX配置与安全 | Broker PostgreSQL认证/ACL/TLS/共享订阅 | 阅读 |
| 10 | WebSocket实时通信 | 前端实时推送架构 | 阅读 |
| 11 | OTA升级架构 | 固件远程升级端到端设计 | 阅读 |
| 12 | 缓存策略 | Redis 分层与 Key 设计规范 | 阅读 |