# iotApp

**Repository Path**: laterlove/iotApp

## Basic Information

- **Project Name**: iotApp
- **Description**: iotApp物联网app
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-06
- **Last Updated**: 2026-03-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


# 0. 开发说明
- 本工程为新建的空工程，帮我实现企业级的SDK封装与示例demo的开发演示

# 1. 实现的安卓app需求
- 开发语言：java,不用ktlion
- iot设备上报的json数据模板可能有多种，本文给出其中一种模板，见第二节说明
- 开发者根据json数据模板可以快速开发实现开发
- app采用模块化实现，即底层功能封装成SDK，解耦，开发者仅根据模板内容来快速实现ui界面的开发，不需要开发者关心
其他功能，仅关心ui的实现和数据的处理
- 具备的基本功能，其他功能可继续补充
- SDK需求
    1. 上限、下限报警阈值设置和通知报警
    2. 数据状态的总体预览
    3. 扫码绑定设备
    4. 注册登录
    5. 历史数据、曲线图表展示
    6. 按时间筛选数据
    7. 良好的UI展示,注意不要被系统顶部的状态栏遮挡，参考微信的UI风格，现代化、简洁、白色和浅绿色主题、扁平化设计
    8. 页面切换生命周期，数据不丢失
    9. 扫码界面参考微信扫一扫ui布局
    10. 字符串等资源统一管理
    11. 时间改为弹窗选择日期时间不是输入
    12. JSON数据模板统一模型，统一管理，快速开发
    13. 统一资源管理
    14. 统一消息提示、报警通知
    15. 封装日志打印方便调试
    16. 统一API调用
    17. 统一数据查询、管理
    18. 良好的开发文档和示例demo，json示例见第二节
    19. 兼容性：小米14等android手机
    20. 提供通用的UI组件，方便开发者调用
    21. 良好的权限管理和申请
    22. 增加设置页面，设置页面参考微信的逻辑，用户信息、关于、退出登录、修改服务器地址、修改报警通知间隔（首次报
  警开始到间隔结束期间不要再次报警)、api调试入口（方便调试api接口）；
    23. 绑定页面设备列表增加对应设备的解绑操作
总之核心需求就是封装好SDK，开发者仅需根据不同的需求模板快速实现APP的开发
# 2. iot设备上报的json数据
```json
{
  "gid": "12345678",
  "ts": 1738905600,
  "dev": [
    { "id": "sd01", "th": [23.6, 45.2], "rssi": -84 },
    { "id": "sd02", "th": [24.1, 41.8] }
  ]
}
```
字段gid：网关id
ts：时间戳
dev：包含多组id设备
    每组id设备上报温湿度，rssi信号质量（可选）
卡片形式展示每个设备的信息，
每组卡片从属与一个网关的关系要展示出来
- 测试用数据模板
{
  "id":"abc",
  "temp":23.1,
  "hum":55
}
# 3. 服务器支持的api

### HTTP API

**统一说明**
- 除 `/auth/*` 外，接口需要 `Authorization: Bearer <token>`
- 角色权限  
  - `admin`：可创建/删除客户端、管理激活码与 ACL，查看全部数据  
  - `user`：仅可查看“已绑定设备”的数据，可绑定/解绑设备
- 管理员账号由 `app_auth.admin_username/admin_password` 配置，服务启动时会确保账号存在并同步密码

#### 认证
```
POST /auth/register
Body: { "username": "admin", "password": "secret" }
Response: { "id": 1, "username": "admin", "role": "user", "created_at": 1700000000 }
```
```
POST /auth/login
Body: { "username": "admin", "password": "secret", "ttl_seconds": 86400 }
Response: { "token": "...", "expires_at": 1700086400, "role": "admin" }
```
```
GET /auth/me
Response: { "id": 1, "username": "admin", "role": "admin", "created_at": 1700000000 }
```

#### 客户端（设备）
```
GET /managed-clients
GET /managed-clients/{client_id}
POST /managed-clients
PUT /managed-clients/{client_id}
DELETE /managed-clients/{client_id}
```
示例：
```
POST /managed-clients
Body: { "client_id": "device001", "username": "u1", "password": "p1", "enabled": true, "description": "IoT Device" }
```

#### 激活码与绑定
```
POST /activation-codes
GET /activation-codes
GET /activation-codes/download
```
```
POST /device-bindings/activate
GET /device-bindings
DELETE /device-bindings/{client_id}
```
示例：
```
POST /device-bindings/activate
Body: { "code": "激活码" }
```

#### 消息记录与订阅
此api查询出来的记录中的消息内容是json文本，例如上报{"a":123}，查询出来的就是{"a":123}
```
GET /message-records?client_id=device001&start_time=1700000000&end_time=1700086399&limit=100&offset=0
GET /subscriptions?client_id=device001
```
参数：
- `client_id`: 可选，按客户端过滤
- `start_time/end_time`: 秒级时间戳
- `limit/offset`: 分页

####  ACL（仅 admin）
```
GET /acl-rules
GET /acl-rules/{client_id}
POST /acl-rules
DELETE /acl-rules/{client_id}
```

#### 实时推送（SSE）
```
GET /events?client_id=device001
Header: Authorization: Bearer <token>
```

#### 会话
```
GET /sessions
```

#### 快速流程示例
1. 管理员创建客户端：`POST /managed-clients`
2. 管理员生成激活码：`POST /activation-codes`
3. App 登录后扫码绑定：`POST /device-bindings/activate`
4. App 查询设备数据：`GET /managed-clients` / `GET /message-records`

####  API 速查
认证
- `POST /auth/register`
- `POST /auth/login`
- `GET /auth/me`

设备
- `GET /managed-clients`
- `GET /managed-clients/{client_id}`
- `POST /managed-clients` (admin)
- `PUT /managed-clients/{client_id}` (admin)
- `DELETE /managed-clients/{client_id}` (admin)

激活码与绑定
- `POST /activation-codes` (admin)
- `GET /activation-codes` (admin)
- `GET /activation-codes/download` (admin)
- `POST /device-bindings/activate`
- `GET /device-bindings`
- `DELETE /device-bindings/{client_id}`

消息与订阅
- `GET /message-records`
- `GET /subscriptions`
- `GET /events` (SSE)

ACL
- `GET /acl-rules` (admin)
- `GET /acl-rules/{client_id}` (admin)
- `POST /acl-rules` (admin)
- `DELETE /acl-rules/{client_id}` (admin)

会话
- `GET /sessions`

#### 详细使用示例与说明

基础说明  
所有非 `/auth/*` 接口需要 `Authorization: Bearer <token>`。普通用户仅能访问已绑定设备数据。

认证
```bash
curl -X POST http://127.0.0.1:8080/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"u1","password":"p1"}'
```
响应字段说明
- `id`: 用户 ID
- `username`: 用户名
- `role`: 角色（`user` 或 `admin`）
- `created_at`: 创建时间（秒级时间戳）

```bash
curl -X POST http://127.0.0.1:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123","ttl_seconds":86400}'
```
响应字段说明
- `token`: Bearer Token
- `expires_at`: 过期时间（秒级时间戳）
- `role`: 角色

```bash
curl http://127.0.0.1:8080/auth/me \
  -H "Authorization: Bearer $TOKEN"
```

设备（managed clients）
```bash
curl http://127.0.0.1:8080/managed-clients?limit=200&offset=0 \
  -H "Authorization: Bearer $TOKEN"
```
返回字段说明（每条设备）
- `id`
- `client_id`
- `username`
- `enabled`
- `description`
- `created_at`
- `updated_at`

```bash
curl -X POST http://127.0.0.1:8080/managed-clients \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"device001","username":"dev1","password":"pwd1","enabled":true,"description":"sensor"}'
```

```bash
curl -X PUT http://127.0.0.1:8080/managed-clients/device001 \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"dev1","password":"pwd2","enabled":true,"description":"sensor-v2"}'
```

```bash
curl -X DELETE http://127.0.0.1:8080/managed-clients/device001 \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

激活码
```bash
curl -X POST http://127.0.0.1:8080/activation-codes \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"device001","force":false}'
```
字段说明
- `force`: 为 `true` 时会覆盖已有激活码
返回字段说明
- `id`
- `client_id`
- `code`
- `enabled`
- `created_at`
- `updated_at`
- `bound` / `bound_user_id` / `bound_at`

```bash
curl http://127.0.0.1:8080/activation-codes \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

```bash
curl -o activation_codes.csv \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://127.0.0.1:8080/activation-codes/download
```

设备绑定
```bash
curl -X POST http://127.0.0.1:8080/device-bindings/activate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"abcd1234ef567890"}'
```
绑定失败错误码
- `INVALID_CODE`：激活码不存在
- `CODE_DISABLED`：激活码禁用
- `ALREADY_BOUND`：激活码已绑定
- `BIND_FAILED`：绑定失败（如已绑定其他用户）

```bash
curl http://127.0.0.1:8080/device-bindings \
  -H "Authorization: Bearer $TOKEN"
```

```bash
curl -X DELETE http://127.0.0.1:8080/device-bindings/device001 \
  -H "Authorization: Bearer $TOKEN"
```

消息记录
```bash
curl "http://127.0.0.1:8080/message-records?client_id=device001&start_time=1700000000&end_time=1700086399&limit=100&offset=0" \
  -H "Authorization: Bearer $TOKEN"
```
时间参数说明
- `start_time` / `end_time` 支持秒级时间戳
- 也支持 UTC 时间串 `YYYY-MM-DDTHH:mm:ssZ`
返回字段说明（每条记录）
- `id`
- `client_id`
- `topic`
- `payload`（十六进制字符串）
- `qos`
- `retain`
- `direction`（`inbound`/`outbound`）
- `created_at`

订阅
```bash
curl "http://127.0.0.1:8080/subscriptions?client_id=device001" \
  -H "Authorization: Bearer $TOKEN"
```
返回字段说明（每条订阅）
- `client_id`
- `topic_filter`
- `qos`

会话
```bash
curl "http://127.0.0.1:8080/sessions?connected=true" \
  -H "Authorization: Bearer $TOKEN"
```
返回字段说明（每条会话）
- `client_id`
- `clean_session`
- `connected`
- `updated_at`

ACL（仅 admin）
```bash
curl http://127.0.0.1:8080/acl-rules?limit=200&offset=0 \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

```bash
curl http://127.0.0.1:8080/acl-rules/device001 \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

```bash
curl -X POST http://127.0.0.1:8080/acl-rules \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"device001","topic_filter":"sensors/+","can_publish":true,"can_subscribe":true}'
```

```bash
curl -X DELETE http://127.0.0.1:8080/acl-rules/device001 \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

实时事件（SSE）
```bash
curl -N "http://127.0.0.1:8080/events?client_id=device001" \
  -H "Authorization: Bearer $TOKEN"
```
事件推送内容为消息记录 JSON，字段与 `GET /message-records` 一致。

指标
```bash
curl http://127.0.0.1:8080/metrics
```