整体软件架构

1. 软件全景图

YunStack-IoT 的软件体系由云端、边缘端（设备）和用户端三部分组成。

2. 关键交互协议

2.1 客户端 <-> 服务端 (HTTP/WebSocket)

• RESTful API: 用于常规业务操作，如用户登录、设备列表查询、修改设备名称。
• WebSocket / SSE: 用于服务端向客户端主动推送设备状态变更（如设备上线、继电器状态跳变）。

2.2 服务端 <-> 设备端 (MQTT)

• 协议版本: MQTT 3.1.1 (兼容性最好) 或 MQTT 5.0。
• 鉴权: 设备连接时使用 ClientId + Username + Password。
• 数据格式: JSON。

3. 部署架构 (容器化)

所有服务端组件均通过 Docker Compose 进行编排，确保“一键部署”。

# docker-compose.yml 结构示意
services:
  # 1. 核心业务服务
  backend:
    image: iotforgex/backend:latest
    ports: ["3000:3000"]
    depends_on: [postgres, redis, emqx]

  # 2. 消息中间件
  emqx:
    image: emqx/emqx:5.x
    ports: ["1883:1883", "8083:8083", "18083:18083"]

  # 3. 数据库
  postgres:
    image: postgres:15
    volumes: ["./data/pg:/var/lib/postgresql/data"]
    
  influxdb:
    image: influxdb:2.x
    
  redis:
    image: redis:7

4. 目录结构规划 (Monorepo)

建议采用 pnpm workspace 管理整个项目仓库：

YunStack-IoT/
├── iotx-backend/       # NestJS 后端
├── iotx-admin-web/     # Web 管理后台
├── iotx-miniapp/       # 小程序 (UniApp)
├── iotx-firmware/      # ESP32 固件代码
├── iotx-docs/          # 文档 (VitePress)
├── docker/             # 部署脚本与配置
└── package.json        # Workspace 根配置