整理前文档快照：01.整体软件架构

这是历史资料，不作为当前操作说明；返回现行页面。原文按文本保存，保留当时方案及验证范围。

# 整体软件架构

## 1. 软件全景图

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

```mermaid
graph TD
    subgraph "用户端 (Client Side)"
        MiniApp["微信小程序\n(UniApp/Vue3)"]
        WebAdmin["管理后台\n(Vue3 + Element Plus)"]
    end

    subgraph "云服务端 (Server Side)"
        API_GW[Nginx 网关]
        NestServer[NestJS 核心服务]
        EMQX[EMQX MQTT Broker]

        DB_PG[(PostgreSQL)]
        DB_Influx[(InfluxDB)]
        DB_Redis[(Redis)]
    end

    subgraph "设备端 (Device Side)"
        ESP32["ESP32 固件\n(ESP-IDF / Arduino)"]
        Relay[四路继电器]
    end

    MiniApp -->|HTTPS| API_GW
    WebAdmin -->|HTTPS| API_GW

    API_GW --> NestServer
    NestServer --> DB_PG
    NestServer --> DB_Influx
    NestServer --> DB_Redis

    NestServer <-->|MQTT/TCP| EMQX

    ESP32 <-->|MQTT/TCP| EMQX
    ESP32 --- Relay
```

## 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 进行编排，确保“一键部署”。

```yaml
# docker-compose.yml 结构示意
services:
  # 1. 核心业务服务
  backend:
    image: yunstack/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 管理整个项目仓库：

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