# iot

**Repository Path**: fakerlove/iot

## Basic Information

- **Project Name**: iot
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-31
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IoT 云端服务

基于 Spring Boot 的轻量 IoT 平台后端：提供 App 侧 REST API、设备 MQTT 上下行、设备影子与属性历史、JWT 鉴权。

## 功能概览

- 用户注册 / 登录（JWT）
- 产品与设备管理（绑定 / 解绑）
- MQTT 属性上报、上下线、控制下发与 ACK
- 设备影子、指令日志、属性历史（趋势图）
- 支持 `SWITCH` / `SENSOR` / `GATEWAY` / `SUB_DEVICE`
- Swagger / OpenAPI 在线文档

## 技术栈

| 组件 | 说明 |
|------|------|
| Java 17 | 运行时 |
| Spring Boot 4 | Web / Security / Validation |
| MyBatis-Plus | ORM |
| MySQL | 业务库 `aigc` |
| Eclipse Paho + Spring Integration MQTT | 设备通信 |
| JJWT | Token |
| springdoc-openapi | API 文档 |

## 架构

```
App --HTTP--> 云端 API --写库--> MySQL
                 |
                 +--publish down--> MQTT Broker <--+
                                                   |
设备/网关 --publish up-----------------------------+
                 |
云端 MQTT 订阅 --更新 status/shadow/指令 ACK--> MySQL
```

更多约定见 [docs/iot.md](docs/iot.md)。

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.9+（或使用项目自带 `mvnw`）
- MySQL 8+
- 可访问的 MQTT Broker

### 1. 初始化数据库

```bash
mysql -u<user> -p aigc < src/main/resources/db/schema.sql
```

表结构说明见 [docs/db.md](docs/db.md)。

### 2. 修改配置

编辑 `src/main/resources/application.yml`：

| 配置项 | 说明 |
|--------|------|
| `spring.datasource.*` | MySQL 连接 |
| `mqtt.broker-url` | MQTT Broker，如 `tcp://host:1883` |
| `mqtt.username` / `password` | Broker 鉴权（可选） |
| `server.port` | HTTP 端口，默认 `8086` |
| `iot.jwt.secret` | JWT 密钥（生产务必更换） |
| `iot.jwt.expire-hours` | Token 有效期（小时） |

### 3. 启动

```bash
# Windows
.\mvnw.cmd spring-boot:run

# macOS / Linux
./mvnw spring-boot:run
```

或：

```bash
./mvnw -DskipTests package
java -jar target/iot-0.0.1-SNAPSHOT.jar
```

服务默认地址：`http://localhost:8086`

### 4. 接口文档

| 入口 | 地址 |
|------|------|
| Swagger UI | http://localhost:8086/swagger-ui.html |
| OpenAPI JSON | http://localhost:8086/v3/api-docs |

除注册、登录与 Swagger 外，请求需携带：

```http
Authorization: Bearer <token>
```

## API 速览

统一响应：

```json
{ "code": 0, "message": "ok", "data": {} }
```

| 模块 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 认证 | POST | `/api/v1/auth/register` | 注册 |
| 认证 | POST | `/api/v1/auth/login` | 登录 |
| 认证 | GET | `/api/v1/auth/me` | 当前用户 |
| 产品 | POST | `/api/v1/products` | 创建产品 |
| 产品 | GET | `/api/v1/products` | 产品列表 |
| 设备 | POST | `/api/v1/devices` | 注册并绑定 |
| 设备 | GET | `/api/v1/devices` | 我的设备 |
| 设备 | GET | `/api/v1/devices/{id}` | 详情 |
| 设备 | POST | `/api/v1/devices/bind` | 绑定已有设备 |
| 设备 | DELETE | `/api/v1/devices/{id}/bind` | 解绑 |
| 设备 | POST | `/api/v1/devices/{id}/control` | 控制下发 |
| 设备 | GET | `/api/v1/devices/{id}/commands` | 指令记录 |
| 设备 | GET | `/api/v1/devices/{id}/history` | 属性历史 |

完整字段、错误码与 MQTT 信封说明见 [docs/iot.md](docs/iot.md)。

## MQTT 约定（摘要）

Topic 前缀：`iot/`

| 方向 | Topic |
|------|-------|
| 设备上报 | `iot/{productKey}/{deviceKey}/up` |
| 云端下发 | `iot/{productKey}/{deviceKey}/down` |
| 子设备上报 | `iot/{productKey}/{gatewayKey}/sub/{subDeviceKey}/up` |
| 子设备下发 | `iot/{productKey}/{gatewayKey}/sub/{subDeviceKey}/down` |

云端默认订阅：`iot/+/+/up`、`iot/+/+/sub/+/up`。

## 项目结构

```
iot/
├── docs/                 # 平台与数据库说明
├── src/main/java/org/example/iot/
│   ├── controller/       # REST 接口
│   ├── service/          # 业务逻辑
│   ├── mqtt/             # MQTT 收发
│   ├── security/         # JWT / 鉴权
│   ├── entity/           # 实体
│   ├── mapper/           # MyBatis Mapper
│   ├── dto/              # 请求/响应
│   └── config/           # 配置
├── src/main/resources/
│   ├── application.yml
│   └── db/schema.sql
└── pom.xml
```

## 文档

- [平台说明（API + MQTT）](docs/iot.md)
- [数据库设计](docs/db.md)

## 许可证

仅供学习与内部使用，未指定开源协议。