iot-util/CLAUDE.md

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）

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