135 lines
5.8 KiB
Markdown
135 lines
5.8 KiB
Markdown
# iot-util 项目开发规范
|
||
|
||
## 本地测试
|
||
|
||
- **规则**: 不进行本地启动测试，由用户自行在 IDEA 中运行验证。
|
||
- **约束**: 严禁使用任何方式启动或停止本地 Java 进程。
|
||
|
||
---
|
||
|
||
## 项目概述
|
||
|
||
IoT 设备管理工具，对接中国移动 OneNET 平台（iot-api.heclouds.com），提供产品详情、设备列表、设备属性、物模型、数据点等查询功能，并附带 Web 管理界面。
|
||
|
||
- **框架**: Solon 3.10.5
|
||
- **认证**: Sa-Token 1.44.0（登录鉴权）+ HMAC-SHA1（IoT 平台鉴权）
|
||
- **HTTP 客户端**: OkHttp 4.12.0
|
||
- **模板引擎**: FreeMarker
|
||
- **JSON**: Jackson（solon-serialization-jackson 3.10.5）
|
||
- **端口**: 8081（app.yml 配置）
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
src/main/java/com/yixiong/iot/
|
||
├── App.java # 启动类
|
||
├── config/
|
||
│ └── IotProperties.java # IoT 配置属性（对应 app.yml iot.* 节点）
|
||
├── controller/
|
||
│ ├── AuthController.java # 登录/登出页面路由
|
||
│ ├── PageController.java # 主页路由（注入 defaultProductId 到模板）
|
||
│ ├── ProductController.java # GET /product/detail
|
||
│ ├── DeviceController.java # GET /device/list|detail|event-log|datapoints
|
||
│ ├── ThingModelController.java # GET|POST /thingmodel/*
|
||
│ └── GlobalExceptionFilter.java # 全局异常过滤，统一返回 JSON
|
||
├── service/
|
||
│ ├── ProductService.java
|
||
│ ├── DeviceService.java
|
||
│ └── ThingModelService.java
|
||
├── model/
|
||
│ ├── IotResponse.java # 通用响应包装（code/msg/requestId/data）
|
||
│ ├── OldIotResponse.java # 旧版响应（errno/error/data，已备用）
|
||
│ ├── ProductDetailData.java
|
||
│ ├── DeviceItem.java # 设备列表项 & 设备详情复用
|
||
│ ├── DeviceListData.java
|
||
│ ├── DeviceEventItem.java
|
||
│ ├── DeviceEventListData.java
|
||
│ ├── DevicePropertyItem.java # 设备属性最新数据
|
||
│ ├── PropertyHistoryData.java # 属性历史包装（data.list）
|
||
│ ├── PropertyHistoryItem.java
|
||
│ ├── DatapointData.java # 数据点（含内部类 DatapointStream/DatapointItem）
|
||
│ └── ThingModelData.java # 物模型（含内部类 Property/Event/Service）
|
||
└── util/
|
||
├── IotHttpClient.java # OkHttp 封装，HMAC 鉴权，正常响应 DEBUG 日志
|
||
└── IotTokenUtil.java # HMAC-SHA1 Token 生成
|
||
src/main/resources/
|
||
├── app.yml
|
||
└── templates/
|
||
├── login.ftl # 登录页
|
||
└── index.ftl # 主页（产品详情 + 设备列表 Tab，多个弹窗）
|
||
```
|
||
|
||
---
|
||
|
||
## API 路由一览
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/` | 主页（需登录） |
|
||
| GET | `/auth/login` | 登录页 |
|
||
| POST | `/auth/doLogin` | 登录处理 |
|
||
| GET | `/auth/logout` | 登出 |
|
||
| GET | `/product/detail?product_id=` | 产品详情 |
|
||
| GET | `/device/list` | 设备列表（product_id 取配置默认值） |
|
||
| GET | `/device/detail?device_name=` | 设备详情（product_id 取配置默认值） |
|
||
| GET | `/device/event-log` | 设备事件记录 |
|
||
| GET | `/device/datapoints` | 设备历史数据点 |
|
||
| GET | `/thingmodel/query-thing-model` | 产品物模型（product_id 取配置默认值） |
|
||
| GET | `/thingmodel/query-device-property?device_name=` | 设备属性最新数据 |
|
||
| POST | `/thingmodel/query-device-property-detail` | 设备属性详情（下发命令） |
|
||
| GET | `/thingmodel/query-property-history` | 设备属性历史记录（data 为 Object，结构不固定） |
|
||
|
||
---
|
||
|
||
## 配置说明（app.yml）
|
||
|
||
```yaml
|
||
iot:
|
||
auth:
|
||
version: "2022-05-01"
|
||
resource-name: "userid/459810" # IoT 平台用户 ID
|
||
access-key: "..." # HMAC 密钥（Base64）
|
||
signature-method: "sha1"
|
||
expiration-seconds: 3600
|
||
http:
|
||
base-url: "https://iot-api.heclouds.com" # 新版 API（HMAC 鉴权）
|
||
default-product-id: "VGi8wC99jO" # 默认产品 ID，多数接口使用此值
|
||
old-base-url: "https://api.heclouds.com" # 旧版 API（api-key 鉴权，备用）
|
||
api-key: "..." # 旧版 Master Key
|
||
|
||
auth:
|
||
username: admin
|
||
password: ... # 登录密码
|
||
```
|
||
|
||
---
|
||
|
||
## 关键设计决策
|
||
|
||
### IoT 平台鉴权
|
||
- 新版接口（`iot-api.heclouds.com`）使用 HMAC-SHA1 Token，放在 `Authorization` 请求头
|
||
- Token 格式：`version=...&res=...&et=...&method=sha1&sign=...`（查询字符串格式）
|
||
- 每次请求实时生成 Token，避免过期
|
||
|
||
### HTTP 客户端
|
||
- `IotHttpClient.execute()` 不对非 2xx 状态码抛异常，始终返回响应体
|
||
- 正常响应打 DEBUG 日志，非 2xx 打 WARN，网络异常打 ERROR
|
||
- 全局日志级别 WARN，框架 INFO 日志屏蔽
|
||
|
||
### 响应反序列化
|
||
- 各 Service 使用独立 `ObjectMapper`，配置 `SNAKE_CASE` 命名策略 + 忽略未知字段
|
||
- 属性历史接口（`/thingmodel/query-property-history`）的 `data` 结构不固定，反序列化为 `Object` 透传
|
||
|
||
### 前端页面
|
||
- 纯原生 HTML/CSS/JS + FreeMarker，无第三方 UI 框架
|
||
- 主页两个 Tab：产品详情、设备列表；页面加载后自动触发两个查询
|
||
- 设备列表每行操作按钮：详情、数据点、事件记录、属性（均以弹窗展示）
|
||
- 属性弹窗支持二级跳转：属性列表 → 历史记录弹窗
|
||
- 产品详情页有"物模型"按钮，展示属性/事件/服务功能点
|
||
|
||
### 已知注意事项
|
||
- `DeviceDetailData.java` 和 `OldIotResponse.java` 为旧版 API 遗留，当前设备详情已改用新版接口（`/device/detail`），这两个类暂未删除
|
||
- `ThingModelData.ThingModelService` 内部类与 Spring 的 `@Service` 无关，是物模型的服务功能点 DTO
|