# 智能飞禽物联平台 APP 端 API 接口文档

> 文档版本：v2.0  
> 生成日期：2026-09-20  
> 面向对象：Android、iOS、跨端 APP 前端开发人员  
> 代码基线：`bird_monitoring` 当前 `HEAD`（`bc1074d`）  
> 接口范围：APP 认证、个人中心、设备、直播、版本检查、消息中心  
> 接口数量：35 个 APP 业务接口，其中 34 个可用、1 个旧接口已停用；另说明动态返回的 MJPEG 播放地址

本文档以当前后端 Controller、BO、VO、Service、统一异常处理和 Jackson 配置为事实来源。它不包含后台管理端、工作流、代码生成器、演示模块和设备 MQTT 上下行协议。

---

## 1. 接入约定

### 1.1 Base URL

本地后端默认地址：

```text
http://localhost:8081
```

当前 Servlet Context Path 为 `/`，因此完整示例为：

```text
POST http://localhost:8081/app/auth/login
GET  http://localhost:8081/app/device/list
```

生产环境只替换协议、域名和端口，本文中的接口路径不变。建议 APP 只在一个环境配置项中维护 Base URL，不要在页面中拼接域名。

### 1.2 请求头与登录态

建议所有 APP JSON 请求统一发送：

```http
Content-Type: application/json;charset=utf-8
clientid: app
```

登录后的受保护接口还必须发送：

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

| 请求头 | 是否必填 | 使用范围 | 说明 |
|---|---:|---|---|
| `Content-Type` | 有 JSON Body 时是 | `POST`、`PUT` | 固定为 `application/json;charset=utf-8` |
| `Authorization` | 受保护接口是 | 登录后接口 | 必须是 `Bearer`、一个空格、再接登录返回的 token |
| `clientid` | 受保护接口是 | 登录后接口 | 当前固定值 `app`，必须与 token 内的客户端标识一致 |
| `Content-Language` | 否 | 全部 | 可传 `zh_CN`；部分校验文案支持国际化 |

公共接口：

- `/app/auth/**` 全部使用 `@SaIgnore`，不要求登录。
- `GET /app/version/latest` 使用 `@SaIgnore`，不要求登录。
- 公共接口当前不会校验 token 与 `clientid`，但建议请求封装仍统一携带 `clientid: app`。
- `POST /app/auth/logout` 本身允许未登录调用；若要注销当前会话，必须携带当前 token。

受保护接口：

- `/app/user/**`
- `/app/device/**`
- `/app/stream/**`
- `/app/message/**`

APP token 只允许访问 `/app/**`。拿 APP token 调后台 `/system/**`、`/device/**` 等路径会被拒绝。

当前默认 token 固定有效期和活跃超时均为 30 天；允许同一账号多端同时登录，每次登录生成独立 token。普通退出只注销当前 token，注销账号会清理该账号的全部会话。

### 1.3 统一响应结构

除 MJPEG 图片/视频流外，所有接口都返回：

```ts
export interface ApiResponse<T> {
  code: number;
  msg: string;
  data: T | null;
}
```

带业务数据的成功响应：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "token": "eyJ..."
  }
}
```

只返回操作结果的成功响应：

```json
{
  "code": 200,
  "msg": "修改成功",
  "data": null
}
```

业务失败响应：

```json
{
  "code": 500,
  "msg": "验证码错误",
  "data": null
}
```

| `code` | 含义 | APP 处理建议 |
|---:|---|---|
| `200` | 成功 | 使用 `data`；操作类接口可展示 `msg` |
| `400` | JSON 或参数格式错误 | 展示 `msg`，保留当前表单 |
| `401` | 未登录、token 失效、`clientid` 不匹配 | 清 token，停止重试，跳转登录页 |
| `403` | token 无权访问当前路径 | 展示 `msg`，不要循环重试 |
| `405` | HTTP Method 错误 | 作为客户端版本缺陷上报 |
| `500` | Bean Validation 或业务校验失败 | `msg` 通常可直接展示给用户 |
| `601` | 警告 | 使用警告样式展示 `msg` |

重要：业务异常和多数鉴权异常会包装在响应体中，HTTP 状态不一定同步为失败状态。APP 必须判断响应体 `code`，不能只依赖 HTTP 2xx。

### 1.4 JSON 类型与空值

当前全局 Jackson 配置对前端类型有以下影响：

| Java 类型 | JSON 表现 | APP 建议类型 |
|---|---|---|
| `Long` | 安全整数范围内为 number，超出后为 string | `string \| number` |
| 雪花 ID | 通常超出 JS 安全整数，实际通常为 string | `string \| number`，业务中按 string 使用 |
| `BigDecimal` | 固定序列化为 string | `string \| null` |
| `Integer` | number | `number` |
| `Boolean` | boolean | `boolean` |
| `LocalDateTime` | `yyyy-MM-dd HH:mm:ss` | `string` |

因此：

- `lng`、`lat` 是十进制字符串，例如 `"116.397128"`，不是 JSON number。
- `messageId`、`alertId` 等雪花 ID 不得转成 JavaScript `number` 后再回传，否则可能丢精度。
- `fileSize`、`expireAt`、未读数等较小 `Long` 当前通常是 number，但客户端仍建议兼容 `string | number`。
- 可空字段会返回 `null`；不要把 `null`、空字符串和 `0` 混为一类。
- 日期时间不含时区偏移，按服务端本地时区解释；若 APP 需要跨时区展示，应在客户端明确约定时区。

### 1.5 分页结构

消息列表使用分页响应：

```ts
export interface PageResult<T> {
  total: number;
  rows: T[];
}
```

示例：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 26,
    "rows": []
  }
}
```

设备列表不分页，直接返回数组。

### 1.6 通用输入规则

| 数据 | 当前规则 |
|---|---|
| 中国大陆手机号 | `13800138000`、`+8613800138000`、`008613800138000` 均可；服务端统一保存为 11 位号码 |
| 国际手机号 | 必须带 `+` 或 `00` 国家码，总数字长度 7-15 位，如 `+14155552671` |
| 手机号字符 | 请求 DTO 校验不接受空格、括号或连字符，提交前必须清理 |
| 邮箱 | 最长 50 字符；服务端去首尾空白并转小写；可通过配置限制允许域名 |
| 验证码 | 6 位数字、5 分钟有效、验证成功后立即失效 |
| 密码 | 8-20 位，同时包含大写字母、小写字母和数字，不允许空白字符 |
| IMEI | 15 位数字 |
| 设备名称 | 1-20 个字符，中文按一个字符计算 |
| `deviceNo` | 路径参数；使用时应做 URL 编码 |

短信和邮箱验证码均按“通道 + 场景 + 账号”隔离：不同场景的验证码不能混用。同一目标、同一场景 60 秒内只能发送一次。错误验证码在 60 秒窗口内超过 5 次后会短暂限速；正确验证码仍可通过，不会被错误尝试主动销毁。

### 1.7 前端错误处理原则

1. `code === 200` 才进入成功分支。
2. `code === 401` 时清理本地登录态，不自动无限重放请求。
3. `code === 500` 时优先展示后端 `msg`，不要替换成笼统的“请求失败”。
4. 网络超时、DNS、TLS、网关错误与业务错误分开处理。
5. 对眼罩控制、直播控制等物理动作，不做成功态的乐观更新，以服务端确认结果为准。
6. 所有 ID 在 URL 中按原始字符串传递，不执行 `Number(id)`。

---

## 2. 认证接口

基础路径：`/app/auth`。本组接口免登录。

> APP 只能使用本章的 `/app/auth/sms/code` 和 `/app/auth/email/code` 获取验证码。仓库中的
> `/resource/sms/code`、`/resource/email/code`、`/resource/gmail/code`、`/sendInternational`
> 属于框架或后台兼容入口，验证码位数、场景和 Redis 缓存键都与 APP 认证链路不同。
> 混用后即使验证码发送成功，APP 注册、登录或找回密码仍会校验失败。

### 2.1 发送短信验证码

```http
POST /app/auth/sms/code
```

请求体：

```json
{
  "phoneNumber": "+8613800138000",
  "scene": "login"
}
```

| 字段 | 类型 | 必填 | 规则 |
|---|---|---:|---|
| `phoneNumber` | string | 是 | 见 1.6 手机号规则 |
| `scene` | string | 是 | `register`、`login`、`resetPwd`、`bind`、`rebind` |

| `scene` | 后续接口 | 使用场景 |
|---|---|---|
| `register` | `POST /app/auth/register` | 手机号注册 |
| `login` | `POST /app/auth/sms-login` | 短信验证码登录 |
| `resetPwd` | `POST /app/auth/reset-pwd` | 手机号找回密码 |
| `bind` | `PUT /app/user/phone` | 邮箱注册账号首次绑定手机号 |
| `rebind` | `PUT /app/user/phone` | 已有手机号的账号更换手机号 |

真实短信模式成功：

```json
{
  "code": 200,
  "msg": "验证码已发送",
  "data": null
}
```

开发环境 `device.app.sms.mock=true` 时，验证码会直接放在 `msg` 中，例如 `"123456"`，仅用于联调。生产环境不会在响应中返回验证码。

常见失败：`验证码场景不合法`、`验证码发送过于频繁，请稍后再试`、`验证码短信发送失败`。

### 2.2 手机号注册

```http
POST /app/auth/register
```

请求体：

```json
{
  "phoneNumber": "13800138000",
  "code": "123456",
  "password": "Password1",
  "nickName": "小明"
}
```

| 字段 | 类型 | 必填 | 规则 |
|---|---|---:|---|
| `phoneNumber` | string | 是 | 手机号 |
| `code` | string | 是 | `scene=register` 获取的 6 位验证码 |
| `password` | string | 是 | 8-20 位，含大小写字母和数字 |
| `nickName` | string | 否 | 最长 30 字符，不允许脚本内容；空时默认使用手机号 |

成功：`msg = "注册成功"`，`data = null`。注册接口不自动登录，前端注册成功后仍需调用登录接口。

协议勾选状态由 APP 本地校验，当前服务端不接收也不保存协议勾选字段。

常见失败：`手机号已注册`、`验证码错误`、`验证码已过期`、密码或昵称格式提示。

### 2.3 手机号密码登录

```http
POST /app/auth/login
```

```json
{
  "phoneNumber": "13800138000",
  "password": "Password1"
}
```

登录成功：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "token": "eyJ..."
  }
}
```

密码登录只要求密码非空，不在登录阶段用“新密码规则”拦截历史密码。

常见失败：`账号不存在`、`手机号或密码错误`、`账号已被停用`。

### 2.4 短信验证码登录

```http
POST /app/auth/sms-login
```

```json
{
  "phoneNumber": "13800138000",
  "code": "123456"
}
```

验证码必须由 `scene=login` 获取。成功响应与 2.3 相同。

服务端先判断账号存在且可用，再验证验证码。短信登录不会自动注册新账号。

### 2.5 手机号找回密码

```http
POST /app/auth/reset-pwd
```

```json
{
  "phoneNumber": "13800138000",
  "code": "123456",
  "newPassword": "NewPassword1"
}
```

验证码必须由 `scene=resetPwd` 获取。成功：`msg = "密码重置成功"`。

### 2.6 退出登录

```http
POST /app/auth/logout
Authorization: Bearer <token>
clientid: app
```

无请求体。成功：`msg = "退出成功"`。

该接口幂等：未登录或 token 已失效时调用仍按成功处理。它只退出当前 token，不影响同一账号的其他设备会话。APP 收到成功后应立即删除本地 token。

### 2.7 发送邮箱验证码

```http
POST /app/auth/email/code
```

```json
{
  "email": "User@gmail.com",
  "scene": "register"
}
```

| 字段 | 类型 | 必填 | 规则 |
|---|---|---:|---|
| `email` | string | 是 | 合法邮箱，最长 50 字符；服务端统一转为小写 |
| `scene` | string | 是 | 仅支持 `register`、`login`、`resetPwd` |

成功：`msg = "验证码已发送至邮箱"`。

邮箱 mock 模式也不会把验证码返回给 APP，只会写开发日志。若配置了邮箱域名白名单，不在白名单内会返回 `该邮箱域名暂不支持注册`。

### 2.8 邮箱注册

```http
POST /app/auth/email/register
```

```json
{
  "email": "user@gmail.com",
  "code": "123456",
  "password": "Password1",
  "nickName": "小明"
}
```

| 字段 | 类型 | 必填 | 规则 |
|---|---|---:|---|
| `email` | string | 是 | 合法邮箱，最长 50 字符 |
| `code` | string | 是 | `scene=register` 获取的邮箱验证码 |
| `password` | string | 是 | 8-20 位，含大小写字母和数字 |
| `nickName` | string | 否 | 最长 30 字符；空时默认使用邮箱 |

成功：`msg = "注册成功，请绑定手机号"`。

邮箱注册不会自动登录，也不会同时创建手机号。登录后 `profile.phoneBound` 为 `false`，此时服务端会禁止绑定设备，APP 必须先走 3.3 首次绑定手机号。

### 2.9 邮箱密码登录

```http
POST /app/auth/email/login
```

```json
{
  "email": "user@gmail.com",
  "password": "Password1"
}
```

成功响应与 2.3 相同。常见失败：`账号不存在`、`邮箱或密码错误`、`账号已被停用`。

### 2.10 邮箱验证码登录

```http
POST /app/auth/email/code-login
```

```json
{
  "email": "user@gmail.com",
  "code": "123456"
}
```

验证码必须由 `scene=login` 获取。成功响应与 2.3 相同，不会自动注册账号。

### 2.11 邮箱找回密码

```http
POST /app/auth/email/reset-pwd
```

```json
{
  "email": "user@gmail.com",
  "code": "123456",
  "newPassword": "NewPassword1"
}
```

验证码必须由 `scene=resetPwd` 获取。成功：`msg = "密码重置成功"`。

---

## 3. 个人中心接口

基础路径：`/app/user`。本组全部需要登录，只能操作当前账号。

### 3.1 获取当前用户资料

```http
GET /app/user/profile
```

响应：`ApiResponse<AppUserProfile>`。

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "userName": "app_1900000000000000000",
    "nickName": "小明",
    "phoneNumber": "138****8000",
    "email": "u***@gmail.com",
    "phoneBound": true,
    "userType": "app_user",
    "createTime": "2026-09-20 10:30:00"
  }
}
```

| 字段 | 类型 | 可空 | 说明 |
|---|---|---:|---|
| `userName` | string | 否 | 服务端账号标识，不是手机号或邮箱 |
| `nickName` | string | 否 | 用户昵称 |
| `phoneNumber` | string | 是 | 脱敏手机号；尚未绑定时为 `null` |
| `email` | string | 是 | 脱敏邮箱；手机号注册账号通常为 `null` |
| `phoneBound` | boolean | 否 | 是否已绑定手机号 |
| `userType` | string | 否 | 固定为 `app_user` |
| `createTime` | string | 否 | 注册时间 |

登录成功后建议立即拉取本接口。`phoneBound=false` 时应引导绑定手机号，并禁止进入设备绑定流程。

### 3.2 修改密码

```http
PUT /app/user/password
```

```json
{
  "oldPassword": "Password1",
  "newPassword": "NewPassword1"
}
```

| 字段 | 类型 | 必填 | 规则 |
|---|---|---:|---|
| `oldPassword` | string | 是 | 当前密码 |
| `newPassword` | string | 是 | 8-20 位，含大小写字母和数字；不能与旧密码相同 |

成功：`msg = "密码修改成功"`。当前实现不会在改密成功后自动退出本设备，APP 可按产品要求主动重新登录。

### 3.3 首次绑定或更换手机号

```http
PUT /app/user/phone
```

```json
{
  "newPhoneNumber": "13900139000",
  "code": "123456"
}
```

发送验证码前必须根据 `profile.phoneBound` 选择场景：

| `phoneBound` | 短信 `scene` | 含义 |
|---:|---|---|
| `false` | `bind` | 邮箱账号首次绑定手机号 |
| `true` | `rebind` | 更换已有手机号 |

验证码发送到新手机号。成功：`msg = "手机号更换成功"`，首次绑定也使用该文案。

常见失败：`新手机号与当前手机号相同`、`手机号已注册`、`验证码错误`、`验证码已过期`。

### 3.4 注销账号

```http
DELETE /app/user/account
```

无请求体。服务端依次执行：解绑全部设备、停用账号、注销该账号全部会话。成功：`msg = "注销成功"`。

这是不可在 APP 内直接撤销的账号操作。前端应二次确认；成功后清除 token、用户缓存、设备缓存并返回登录页。

### 3.5 查询用户协议或隐私政策

```http
GET /app/user/agreements?type=user
```

| Query 参数 | 类型 | 必填 | 取值 |
|---|---|---:|---|
| `type` | string | 是 | `user` 或 `privacy`，区分大小写 |

响应：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "type": "user",
    "url": "https://example.com/agreement/user",
    "version": "v1.0",
    "updateTime": "2026-09-20"
  }
}
```

注意：当前接口需要登录。如果登录页也要展示协议，应由产品/后端另行提供公开入口，前端不要假定本接口可匿名访问。
协议内容来自服务端配置，默认 `url` 和 `updateTime` 可以是空字符串；APP 应为未配置状态准备占位提示，不要直接打开空 URL。

---

## 4. 设备接口

基础路径：`/app/device`。全部需要登录。按设备编号查询或操作时，服务端同时校验设备属于当前用户；设备不存在、未绑定或属于他人统一返回 `设备不存在`，防止枚举设备归属。

### 4.1 我的设备列表

```http
GET /app/device/list
```

无 Query 参数，不分页，按绑定时间倒序。没有设备时 `data = []`。

响应项字段：

| 字段 | 类型 | 可空 | 说明 |
|---|---|---:|---|
| `deviceNo` | string | 否 | 设备业务编号 |
| `name` | string | 否 | 用户设置的名称 |
| `imei` | string | 否 | 脱敏值，如 `1234****5678` |
| `model` | string | 是 | 设备型号 |
| `status` | string | 否 | `0` 未激活、`1` 在线、`2` 离线 |
| `signalLevel` | number | 是 | `0` 离线、`1` 弱、`2` 一般、`3` 强 |
| `signalText` | string | 是 | 服务端派生的信号文案 |
| `hoodConnected` | string | 是 | `0` 已断开、`1` 已连接 |
| `hoodConnectedText` | string | 是 | 服务端派生的连接文案 |
| `hoodBattery` | number | 是 | 头套电量，0-100 |
| `ringBattery` | number | 是 | 脚环电量，0-100 |
| `lng` | string | 是 | 最新经度；`BigDecimal` 以字符串返回 |
| `lat` | string | 是 | 最新纬度；`BigDecimal` 以字符串返回 |
| `address` | string | 是 | 最新地址 |

示例：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "deviceNo": "BM202609200001",
      "name": "客厅设备",
      "imei": "1234****2345",
      "model": "BM-A1",
      "status": "1",
      "signalLevel": 3,
      "signalText": "强",
      "hoodConnected": "1",
      "hoodConnectedText": "已连接",
      "hoodBattery": 82,
      "ringBattery": 76,
      "lng": "116.397128",
      "lat": "39.916527",
      "address": "北京市东城区"
    }
  ]
}
```

### 4.2 设备详情

```http
GET /app/device/{deviceNo}
```

响应字段与列表项相同，额外返回：

| 字段 | 类型 | 说明 |
|---|---|---|
| `hoodCoverOn` | string | `0` 打开、`1` 遮盖；可能因设备尚未上报而为 `null` |

### 4.3 绑定设备

```http
POST /app/device/bind
```

```json
{
  "imei": "123456789012345",
  "name": "客厅设备"
}
```

| 字段 | 类型 | 必填 | 规则 |
|---|---|---:|---|
| `imei` | string | 是 | 15 位数字，通常来自扫码 |
| `name` | string | 是 | 1-20 个字符 |

成功：`msg = "添加成功"`。

前置条件：当前账号必须已绑定手机号。常见失败：`请先绑定手机号`、`设备不存在`、`重复绑定`、`设备已被绑定`。

### 4.4 重命名设备

```http
PUT /app/device/{deviceNo}/name
```

```json
{
  "name": "新的设备名称"
}
```

Body 只传 `name`，不要重复传 `deviceNo`。成功：`msg = "修改成功"`。

### 4.5 解绑设备

```http
DELETE /app/device/{deviceNo}
```

无请求体。成功：`msg = "解绑成功"`。

解绑后设备回到未激活状态，但设备建档与历史告警仍保留。历史消息归告警发生时的用户，不会转给下一位绑定用户。

### 4.6 控制眼罩

```http
PUT /app/device/{deviceNo}/hood
```

```json
{
  "coverOn": true
}
```

| `coverOn` | 物理动作 |
|---:|---|
| `true` | 遮盖眼罩 |
| `false` | 打开眼罩 |

`coverOn` 必须显式传入，不能省略。

成功响应：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "deviceNo": "BM202609200001",
    "hoodCoverOn": "1",
    "hoodCoverOnText": "遮盖"
  }
}
```

接口会等待设备回执，默认最长 5 秒，另有很短的服务端宽限时间。前端建议：

- 单次请求超时设置为至少 8-10 秒。
- 请求期间展示 loading 并禁用重复点击。
- 只有收到 `code=200` 后才用 `data.hoodCoverOn` 更新页面。
- 设备离线时两个方向都拒绝；低电只拒绝“遮盖”，不阻止“打开”。

常见失败：`设备不存在`、`设备已离线`、`电量过低`、`指令下发失败`。

### 4.7 获取设备定位

```http
GET /app/device/{deviceNo}/location
```

响应：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "deviceNo": "BM202609200001",
    "lng": "116.397128",
    "lat": "39.916527",
    "address": "北京市东城区",
    "lastOnlineTime": "2026-09-20 11:30:00"
  }
}
```

| 字段 | 类型 | 可空 | 说明 |
|---|---|---:|---|
| `deviceNo` | string | 否 | 设备编号 |
| `lng` | string | 是 | 最新经度 |
| `lat` | string | 是 | 最新纬度 |
| `address` | string | 是 | 设备上报地址 |
| `lastOnlineTime` | string | 是 | 最后在线时间 |

从未上报定位时接口仍成功，`lng`、`lat` 为 `null`。APP 应展示“暂无定位”空态，不要把空坐标传给地图 SDK。

### 4.8 获取直播播放信息

```http
GET /app/device/{deviceNo}/live
```

该接口等价于获取播放地址，不会通知设备开始推流。响应结构与 5.1 的 `AppStreamPlay` 相同。正常开播流程应先调用 `POST /app/stream/start`。

---

## 5. 直播接口

基础路径：`/app/stream`。全部需要登录，只能操作当前用户绑定的设备。

当前默认 `mjpeg.enabled=true`，直播走 HTTP MJPEG；关闭该配置后切换为 ZLMediaKit。APP 不应硬编码播放协议，应从 `playUrls` 中选择非空地址。

### 5.1 开始推流

```http
POST /app/stream/start
```

```json
{
  "deviceNo": "BM202609200001"
}
```

前置条件：设备属于当前用户且 `status=1`。接口向设备发送开始推流指令，然后立即返回播放信息；它不等待第一帧，因此刚开播时 `online` 可能为 `false`。

当前 MJPEG 模式响应示例：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "deviceNo": "BM202609200001",
    "streamId": "BM202609200001",
    "app": "live",
    "online": false,
    "pushUrl": "https://stream.example.com/mjpeg/ingest/BM202609200001",
    "playToken": "7f2d...",
    "expireAt": 1789875123456,
    "expireSeconds": 120,
    "playUrls": {
      "flv": null,
      "hls": null,
      "rtmp": null,
      "rtsp": null,
      "webrtc": null,
      "mjpeg": "https://stream.example.com/mjpeg/play/BM202609200001?token=..."
    }
  }
}
```

| 字段 | 类型 | 说明 |
|---|---|---|
| `deviceNo` | string | 设备编号 |
| `streamId` | string | 当前与 `deviceNo` 相同 |
| `app` | string | 流媒体应用名，当前默认 `live` |
| `online` | boolean | 当前是否已经存在有效流/最近帧 |
| `pushUrl` | string | 设备侧推流地址，APP 播放器不要使用 |
| `playToken` | string | 播放凭证；一般无需单独拼接 |
| `expireAt` | number \| string | 播放凭证过期时间，epoch 毫秒 |
| `expireSeconds` | number | 有效期秒数，当前默认 120 |
| `playUrls` | object | 各协议播放地址，token 已附在 URL 中 |

限流：同一设备控制维度、同一 IP 60 秒内最多 30 次。

播放 token 同时绑定 `streamId` 和签发时客户端 IP，不能分享给其他设备或网络出口。网络切换、token 临近过期或收到播放端 `401` 时，应重新调用播放信息接口获取新 URL。

### 5.2 停止推流

```http
POST /app/stream/stop/{deviceNo}
```

通知设备停止推流，并关闭服务端当前流。响应：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "deviceNo": "BM202609200001",
    "streamId": "BM202609200001",
    "online": false
  }
}
```

限流：同一设备控制维度、同一 IP 60 秒内最多 20 次。离开直播页时建议调用一次，但不要在组件反复渲染时重复调用。

### 5.3 获取播放地址

```http
GET /app/stream/play-url/{deviceNo}
```

只签发新的播放 token 和地址，不通知设备开播。响应结构与 5.1 相同。限流：同一设备、同一 IP 60 秒内最多 60 次。

适用场景：

- 播放 URL 即将过期时刷新。
- APP 从后台回到前台后重新获取凭证。
- 已开播但播放器重连。

### 5.4 仅关闭服务端流

```http
POST /app/stream/close/{deviceNo}
```

只关闭当前直播后端的流或 MJPEG 会话，不通知设备停止推流。正常用户流程优先使用 5.2 `stop`。

成功：`data = null`。限流：同一设备、同一 IP 60 秒内最多 20 次。

### 5.5 查询流状态

```http
GET /app/stream/status/{deviceNo}
```

响应：`ApiResponse<AppStreamStatus>`，结构见 5.2。限流：同一设备、同一 IP 60 秒内最多 60 次。

若需要等待第一帧，可每 2-3 秒轮询一次，成功在线或达到客户端等待上限后停止轮询。

### 5.6 已停用的旧接口

```http
POST /app/stream/open
```

此接口固定失败：`msg = "客户端自定义视频源已停用"`。新 APP 不得调用，也不要允许用户输入自定义拉流地址。

### 5.7 MJPEG 播放地址说明

`playUrls.mjpeg` 指向：

```http
GET /mjpeg/play/{deviceNo}?token=<playToken>
```

它返回 `multipart/x-mixed-replace` 长连接，不返回统一 JSON。APP 可使用支持 MJPEG 的图片/流组件直接打开完整 URL。

调试单帧地址：

```http
GET /mjpeg/play/{deviceNo}/snapshot?token=<playToken>
```

| HTTP 状态 | 含义 |
|---:|---|
| `200` | 有流或有最新帧 |
| `401` | token 无效、过期、IP 不匹配或 MJPEG 未启用 |
| `404` | 当前没有活动流或尚无帧 |

不要自行构造或长期缓存播放 URL，始终使用业务接口返回的完整地址。

---

## 6. APP 版本检查

基础路径：`/app/version`。本组免登录，供冷启动最早阶段调用。

### 6.1 检查最新版本

```http
GET /app/version/latest?platform=android&versionCode=100&versionName=1.0.0&deviceModel=Pixel%208&osVersion=15
```

| Query 参数 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `platform` | string | 是 | 严格取 `android` 或 `ios`，区分大小写 |
| `versionCode` | number | 是 | 当前构建号，必须为正整数；唯一比较依据 |
| `versionName` | string | 否 | 当前实现接收但不参与比较、不落库、也不在响应中回显 |
| `deviceModel` | string | 否 | 当前实现接收但不参与判定、不落库 |
| `osVersion` | string | 否 | 当前实现接收但不参与判定、不落库 |

比较规则只使用整数 `versionCode`。不要使用字符串 `versionName` 比较大小。

无更新响应：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "platform": "android",
    "hasUpdate": false,
    "forceUpdate": false,
    "latestVersionCode": null,
    "latestVersionName": null,
    "changelog": null,
    "fileSize": null,
    "md5": null,
    "downloadUrl": null,
    "storeUrl": null,
    "currentVersionCode": 100
  }
}
```

有更新响应：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "platform": "android",
    "hasUpdate": true,
    "forceUpdate": true,
    "latestVersionCode": 101,
    "latestVersionName": "1.0.1",
    "changelog": "修复已知问题并提升直播稳定性",
    "fileSize": 52428800,
    "md5": null,
    "downloadUrl": "https://oss.example.com/app.apk?...",
    "storeUrl": null,
    "currentVersionCode": 100
  }
}
```

| 字段 | 类型 | 可空 | 说明 |
|---|---|---:|---|
| `platform` | string | 否 | 回显平台 |
| `hasUpdate` | boolean | 否 | 更新弹窗主开关 |
| `forceUpdate` | boolean | 否 | 是否强制更新；无更新时恒为 `false` |
| `latestVersionCode` | number | 是 | 最新构建号 |
| `latestVersionName` | string | 是 | 最新展示版本号 |
| `changelog` | string | 是 | 更新说明 |
| `fileSize` | number \| string | 是 | 安装包字节数；使用前执行 `Number(fileSize)` |
| `md5` | string | 是 | 预留字段，本期通常为 `null` |
| `downloadUrl` | string | 是 | 动态解析出的安装包 URL |
| `storeUrl` | string | 是 | App Store 等引导地址，后台未填时为 `null` |
| `currentVersionCode` | number | 否 | 回显当前构建号 |

三态处理：

| 条件 | APP 行为 |
|---|---|
| `hasUpdate=false` | 不弹更新框 |
| `hasUpdate=true && forceUpdate=false` | 展示可关闭的可选更新弹窗 |
| `hasUpdate=true && forceUpdate=true` | 展示不可跳过的强更弹窗 |

补充规则：

- 没有启用版本、当前构建号大于等于最新构建号、或安装包 URL 无法解析时，都返回“无更新”。
- 下载地址针对私有 OSS 每次检查时重新解析，当前有效期为 24 小时；失败或过期后重新检查，不要永久缓存。
- Android 与 iOS 都可能返回 `downloadUrl`；iOS 是否可安装取决于 App Store、TestFlight、企业签等实际分发方式。
- `storeUrl` 有值时优先用于系统商店跳转；无值时根据平台和实际分发方案处理。

常见失败：`平台参数不合法`、`版本号不合法`。

---

## 7. 消息中心接口

基础路径：`/app/message`。全部需要登录，只能读写当前用户消息。

一期消息仅包含设备告警：设备离线、头套低电、脚环低电。消息由服务端生成，APP 不提供新增、修改内容或删除接口。

### 7.1 消息分页列表

```http
GET /app/message/list?pageNum=1&pageSize=20&readFlag=0
```

| Query 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---:|---:|---|
| `pageNum` | number | 否 | `1` | 小于 1 时回落为 1 |
| `pageSize` | number | 否 | `20` | 小于 1 时回落为 20，大于 100 时截为 100 |
| `readFlag` | string | 否 | 全部 | `0` 未读、`1` 已读；其他值通常得到空结果 |

排序：`createTime` 倒序，再按 `messageId` 倒序。

响应项：

| 字段 | 类型 | 可空 | 说明 |
|---|---|---:|---|
| `messageId` | string \| number | 否 | 雪花 ID，按字符串保存和回传 |
| `deviceNo` | string | 是 | 关联设备编号，可用于跳详情 |
| `alertId` | string \| number | 是 | 关联告警 ID |
| `alertType` | string | 是 | 告警类型 |
| `alertLevel` | string | 是 | `0` 提示、`1` 警告、`2` 严重 |
| `title` | string | 否 | 消息标题 |
| `content` | string | 是 | 消息内容 |
| `readFlag` | string | 否 | `0` 未读、`1` 已读 |
| `readTime` | string | 是 | 首次标记已读时间 |
| `createTime` | string | 否 | 消息产生时间 |

示例：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 1,
    "rows": [
      {
        "messageId": "1970000000000000001",
        "deviceNo": "BM202609200001",
        "alertId": "1970000000000000000",
        "alertType": "low_battery_hood",
        "alertLevel": "1",
        "title": "头套电量过低",
        "content": "头套电量过低（当前 18%）",
        "readFlag": "0",
        "readTime": null,
        "createTime": "2026-09-20 12:00:00"
      }
    ]
  }
}
```

### 7.2 查询未读数

```http
GET /app/message/unread-count
```

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": 3
}
```

返回当前用户未读消息总数。APP 可在启动、进入消息页、下拉刷新、标记已读后重新获取。当前 APP 接口没有实时推送连接，角标实时性取决于客户端刷新策略。

### 7.3 标记单条已读

```http
PUT /app/message/{messageId}/read
```

无请求体。成功：`data = null`。

该接口幂等：重复调用不修改首次 `readTime`。消息不存在或不属于当前用户时也返回成功，不暴露其他用户的消息 ID 是否存在。

### 7.4 全部标记已读

```http
PUT /app/message/read-all
```

无请求体。仅更新当前用户的未读消息；没有未读消息时仍成功。

### 7.5 告警枚举与点击行为

| `alertType` | 标题/含义 | 默认 `alertLevel` |
|---|---|---|
| `offline` | 设备离线 | `2` 严重 |
| `low_battery_hood` | 头套电量过低 | `1` 警告 |
| `low_battery_ring` | 脚环电量过低 | `1` 警告 |

点击消息建议流程：

```text
消息列表
  -> 本地先标记已读
  -> GET /app/device/{deviceNo}
  -> 成功则进入设备详情
  -> 返回“设备不存在”则提示设备已解绑或不可访问，留在消息页
```

历史消息归告警发生时的用户，即使设备后来解绑或换绑也不会迁移。

---

## 8. TypeScript 契约

以下类型按当前真实序列化行为编写，可直接作为 APP API 层的基础定义。

```ts
/** Java Long 可能按 number 或 string 返回，雪花 ID 应始终按字符串语义使用。 */
export type JsonLong = string | number;

export interface ApiResponse<T> {
  code: number;
  msg: string;
  data: T | null;
}

export interface PageResult<T> {
  total: number;
  rows: T[];
}

export type SmsScene = 'register' | 'login' | 'resetPwd' | 'bind' | 'rebind';
export type EmailScene = 'register' | 'login' | 'resetPwd';
export type DeviceStatus = '0' | '1' | '2';
export type HoodState = '0' | '1';
export type ReadFlag = '0' | '1';
export type AlertLevel = '0' | '1' | '2';
export type AppPlatform = 'android' | 'ios';

export interface AppToken {
  token: string;
}

export interface AppUserProfile {
  userName: string;
  nickName: string;
  phoneNumber: string | null;
  email: string | null;
  phoneBound: boolean;
  userType: 'app_user';
  createTime: string;
}

export interface AppAgreement {
  type: 'user' | 'privacy';
  url: string;
  version: string;
  updateTime: string;
}

export interface AppDevice {
  deviceNo: string;
  name: string;
  imei: string;
  model: string | null;
  status: DeviceStatus;
  signalLevel: 0 | 1 | 2 | 3 | null;
  signalText: string | null;
  hoodConnected: HoodState | null;
  hoodConnectedText: string | null;
  hoodBattery: number | null;
  ringBattery: number | null;
  /** BigDecimal 经全局 Jackson 配置固定返回字符串。 */
  lng: string | null;
  /** BigDecimal 经全局 Jackson 配置固定返回字符串。 */
  lat: string | null;
  address: string | null;
}

export interface AppDeviceDetail extends AppDevice {
  hoodCoverOn: HoodState | null;
}

export interface AppHoodResult {
  deviceNo: string;
  hoodCoverOn: HoodState;
  hoodCoverOnText: '打开' | '遮盖';
}

export interface DeviceLocation {
  deviceNo: string;
  lng: string | null;
  lat: string | null;
  address: string | null;
  lastOnlineTime: string | null;
}

export interface AppStreamPlayUrls {
  flv: string | null;
  hls: string | null;
  rtmp: string | null;
  rtsp: string | null;
  webrtc: string | null;
  mjpeg: string | null;
}

export interface AppStreamPlay {
  deviceNo: string;
  streamId: string;
  app: string;
  online: boolean;
  /** 设备侧地址，仅用于诊断，APP 播放器不使用。 */
  pushUrl: string;
  playToken: string;
  expireAt: JsonLong;
  expireSeconds: number;
  playUrls: AppStreamPlayUrls;
}

export interface AppStreamStatus {
  deviceNo: string;
  streamId: string;
  online: boolean;
}

export interface AppVersionLatest {
  platform: AppPlatform;
  hasUpdate: boolean;
  forceUpdate: boolean;
  latestVersionCode: number | null;
  latestVersionName: string | null;
  changelog: string | null;
  fileSize: JsonLong | null;
  md5: string | null;
  downloadUrl: string | null;
  storeUrl: string | null;
  currentVersionCode: number;
}

export interface AppMessage {
  messageId: JsonLong;
  deviceNo: string | null;
  alertId: JsonLong | null;
  alertType: 'offline' | 'low_battery_hood' | 'low_battery_ring' | string;
  alertLevel: AlertLevel | null;
  title: string;
  content: string | null;
  readFlag: ReadFlag;
  readTime: string | null;
  createTime: string;
}
```

请求 DTO：

```ts
export interface SmsCodeRequest {
  phoneNumber: string;
  scene: SmsScene;
}

export interface PhoneRegisterRequest {
  phoneNumber: string;
  code: string;
  password: string;
  nickName?: string;
}

export interface PhoneLoginRequest {
  phoneNumber: string;
  password: string;
}

export interface PhoneCodeLoginRequest {
  phoneNumber: string;
  code: string;
}

export interface PhoneResetPasswordRequest {
  phoneNumber: string;
  code: string;
  newPassword: string;
}

export interface EmailCodeRequest {
  email: string;
  scene: EmailScene;
}

export interface EmailRegisterRequest {
  email: string;
  code: string;
  password: string;
  nickName?: string;
}

export interface EmailLoginRequest {
  email: string;
  password: string;
}

export interface EmailCodeLoginRequest {
  email: string;
  code: string;
}

export interface EmailResetPasswordRequest {
  email: string;
  code: string;
  newPassword: string;
}

export interface ChangePasswordRequest {
  oldPassword: string;
  newPassword: string;
}

export interface BindPhoneRequest {
  newPhoneNumber: string;
  code: string;
}

export interface BindDeviceRequest {
  imei: string;
  name: string;
}

export interface RenameDeviceRequest {
  name: string;
}

export interface HoodControlRequest {
  coverOn: boolean;
}

export interface StreamStartRequest {
  deviceNo: string;
}

export interface VersionCheckQuery {
  platform: AppPlatform;
  versionCode: number;
  versionName?: string;
  deviceModel?: string;
  osVersion?: string;
}

export interface MessageQuery {
  pageNum?: number;
  pageSize?: number;
  readFlag?: ReadFlag;
}
```

### 8.1 Axios 请求封装示例

```ts
import axios, { type AxiosRequestConfig } from 'axios';

export class ApiError extends Error {
  constructor(
    public readonly code: number,
    message: string
  ) {
    super(message);
  }
}

const http = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL,
  timeout: 15_000,
  headers: {
    'Content-Type': 'application/json;charset=utf-8',
    clientid: 'app'
  }
});

http.interceptors.request.use(config => {
  const token = localStorage.getItem('app_token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

export async function request<T>(config: AxiosRequestConfig): Promise<T> {
  const response = await http.request<ApiResponse<T>>(config);
  const body = response.data;

  // 业务异常大多仍是 HTTP 200，必须检查响应体 code。
  if (body.code === 401) {
    localStorage.removeItem('app_token');
    // 这里通知路由层跳转登录页，避免 API 层直接依赖具体导航实现。
    throw new ApiError(body.code, body.msg);
  }
  if (body.code !== 200) {
    throw new ApiError(body.code, body.msg);
  }

  return body.data as T;
}
```

眼罩接口可单独覆盖超时：

```ts
export function controlHood(deviceNo: string, coverOn: boolean) {
  return request<AppHoodResult>({
    method: 'PUT',
    url: `/app/device/${encodeURIComponent(deviceNo)}/hood`,
    data: { coverOn },
    // 服务端默认等待设备回执 5 秒，客户端应预留网络开销。
    timeout: 10_000
  });
}
```

---

## 9. 推荐业务流程

### 9.1 手机号注册与登录

```text
POST /app/auth/sms/code (scene=register)
  -> POST /app/auth/register
  -> POST /app/auth/login 或 /app/auth/sms-login
  -> 保存 data.token
  -> GET /app/user/profile
  -> GET /app/device/list
```

### 9.2 邮箱注册与首次绑定手机号

```text
POST /app/auth/email/code (scene=register)
  -> POST /app/auth/email/register
  -> POST /app/auth/email/login 或 /app/auth/email/code-login
  -> 保存 data.token
  -> GET /app/user/profile
  -> phoneBound=false
  -> POST /app/auth/sms/code (scene=bind，目标是新手机号)
  -> PUT /app/user/phone
  -> 重新 GET /app/user/profile
  -> phoneBound=true 后允许绑定设备
```

### 9.3 绑定设备

```text
GET /app/user/profile
  -> 确认 phoneBound=true
  -> 扫码取得 15 位 IMEI
  -> POST /app/device/bind
  -> GET /app/device/list 刷新设备卡片
```

### 9.4 眼罩控制

```text
禁用按钮并展示 loading
  -> PUT /app/device/{deviceNo}/hood
  -> code=200：使用 data.hoodCoverOn 更新界面
  -> 失败：保持原状态，直接展示 msg
  -> 恢复按钮
```

### 9.5 直播

```text
POST /app/stream/start
  -> 从 playUrls 选择非空且客户端支持的协议
  -> online=false 时每 2-3 秒查询 status
  -> 播放 token 即将过期或网络切换时调用 play-url
  -> 离开直播页调用 stop
```

### 9.6 冷启动检查更新

```text
GET /app/version/latest（无需登录）
  -> hasUpdate=false：继续启动
  -> 可选更新：可关闭弹窗
  -> 强制更新：不可跳过，使用 storeUrl 或 downloadUrl
  -> 下载 URL 失效：重新调用 latest 获取新地址
```

### 9.7 消息角标

```text
APP 启动/回前台 -> GET /app/message/unread-count
进入消息页       -> GET /app/message/list?pageNum=1&pageSize=20
点击消息         -> PUT /app/message/{id}/read
                 -> 重新获取未读数
                 -> 尝试进入对应设备详情
```

---

## 10. 常见业务提示

| 模块 | 常见 `msg` |
|---|---|
| 验证码 | `验证码发送过于频繁，请稍后再试`、`验证码错误`、`验证码已过期`、`验证码错误次数过多，请稍后再试` |
| 注册登录 | `手机号已注册`、`邮箱已注册`、`账号不存在`、`手机号或密码错误`、`邮箱或密码错误`、`账号已被停用` |
| 密码 | `原密码错误`、`新密码不能与原密码相同`、`密码需为 8-20 位，且包含大小写字母和数字` |
| 手机号绑定 | `请先绑定手机号`、`新手机号与当前手机号相同`、`手机号已注册` |
| 设备 | `设备不存在`、`设备已被绑定`、`重复绑定`、`设备已离线`、`电量过低`、`指令下发失败` |
| 直播 | `MJPEG 直播地址未配置`、`ZLM 地址未配置`、`操作过于频繁，请稍后再试`、`客户端自定义视频源已停用` |
| 版本 | `平台参数不合法`、`版本号不合法` |

前端不要根据 `msg` 反推业务状态或做程序分支；程序逻辑应优先根据 `code` 和响应字段处理，`msg` 只用于用户提示。当前后端尚未为业务异常提供更细的稳定错误码，这是现有契约的限制。

---

## 11. 完整接口索引

| # | 方法 | 路径 | 登录 | 状态 |
|---:|---|---|---:|---|
| 1 | POST | `/app/auth/sms/code` | 否 | 可用 |
| 2 | POST | `/app/auth/register` | 否 | 可用 |
| 3 | POST | `/app/auth/login` | 否 | 可用 |
| 4 | POST | `/app/auth/sms-login` | 否 | 可用 |
| 5 | POST | `/app/auth/reset-pwd` | 否 | 可用 |
| 6 | POST | `/app/auth/logout` | 否；退出当前会话时带 token | 可用 |
| 7 | POST | `/app/auth/email/code` | 否 | 可用 |
| 8 | POST | `/app/auth/email/register` | 否 | 可用 |
| 9 | POST | `/app/auth/email/login` | 否 | 可用 |
| 10 | POST | `/app/auth/email/code-login` | 否 | 可用 |
| 11 | POST | `/app/auth/email/reset-pwd` | 否 | 可用 |
| 12 | GET | `/app/user/profile` | 是 | 可用 |
| 13 | PUT | `/app/user/password` | 是 | 可用 |
| 14 | PUT | `/app/user/phone` | 是 | 可用 |
| 15 | DELETE | `/app/user/account` | 是 | 可用 |
| 16 | GET | `/app/user/agreements` | 是 | 可用 |
| 17 | GET | `/app/device/list` | 是 | 可用 |
| 18 | GET | `/app/device/{deviceNo}` | 是 | 可用 |
| 19 | POST | `/app/device/bind` | 是 | 可用 |
| 20 | PUT | `/app/device/{deviceNo}/name` | 是 | 可用 |
| 21 | DELETE | `/app/device/{deviceNo}` | 是 | 可用 |
| 22 | PUT | `/app/device/{deviceNo}/hood` | 是 | 可用 |
| 23 | GET | `/app/device/{deviceNo}/location` | 是 | 可用 |
| 24 | GET | `/app/device/{deviceNo}/live` | 是 | 可用 |
| 25 | POST | `/app/stream/start` | 是 | 可用 |
| 26 | POST | `/app/stream/stop/{deviceNo}` | 是 | 可用 |
| 27 | GET | `/app/stream/play-url/{deviceNo}` | 是 | 可用 |
| 28 | POST | `/app/stream/open` | 是 | 已停用，固定失败 |
| 29 | POST | `/app/stream/close/{deviceNo}` | 是 | 可用 |
| 30 | GET | `/app/stream/status/{deviceNo}` | 是 | 可用 |
| 31 | GET | `/app/version/latest` | 否 | 可用 |
| 32 | GET | `/app/message/list` | 是 | 可用 |
| 33 | GET | `/app/message/unread-count` | 是 | 可用 |
| 34 | PUT | `/app/message/{messageId}/read` | 是 | 可用 |
| 35 | PUT | `/app/message/read-all` | 是 | 可用 |

动态媒体端点不计入上述 35 个业务接口：

| 方法 | 路径 | 鉴权 | 返回 |
|---|---|---|---|
| GET | `/mjpeg/play/{deviceNo}?token=...` | 播放 token | MJPEG multipart 流 |
| GET | `/mjpeg/play/{deviceNo}/snapshot?token=...` | 播放 token | 单帧 JPEG |

---

## 12. 代码事实来源

接口路径和鉴权：

- `ruoyi-modules/ruoyi-device/src/main/java/org/dromara/device/controller/app/AppAuthController.java`
- `ruoyi-modules/ruoyi-device/src/main/java/org/dromara/device/controller/app/AppUserController.java`
- `ruoyi-modules/ruoyi-device/src/main/java/org/dromara/device/controller/app/AppDeviceController.java`
- `ruoyi-modules/ruoyi-device/src/main/java/org/dromara/device/controller/app/AppVersionAppController.java`
- `ruoyi-modules/ruoyi-device/src/main/java/org/dromara/device/controller/app/AppMessageController.java`
- `ruoyi-modules/ruoyi-device/src/main/java/org/dromara/device/zlm/controller/AppStreamController.java`
- `ruoyi-modules/ruoyi-device/src/main/java/org/dromara/device/mjpeg/MjpegStreamController.java`

请求与响应字段：

- `ruoyi-modules/ruoyi-device/src/main/java/org/dromara/device/domain/bo/`
- `ruoyi-modules/ruoyi-device/src/main/java/org/dromara/device/domain/vo/`

业务规则：

- `ruoyi-modules/ruoyi-device/src/main/java/org/dromara/device/service/impl/`
- `ruoyi-modules/ruoyi-device/src/main/java/org/dromara/device/sms/AppSmsService.java`
- `ruoyi-modules/ruoyi-device/src/main/java/org/dromara/device/email/AppEmailService.java`
- `ruoyi-modules/ruoyi-device/src/main/java/org/dromara/device/stream/`

公共契约：

- `ruoyi-common/ruoyi-common-core/src/main/java/org/dromara/common/core/domain/R.java`
- `ruoyi-common/ruoyi-common-core/src/main/java/org/dromara/common/core/domain/PageResult.java`
- `ruoyi-common/ruoyi-common-json/src/main/java/org/dromara/common/json/config/JacksonConfig.java`
- `ruoyi-common/ruoyi-common-json/src/main/java/org/dromara/common/json/handler/BigNumberSerializer.java`
- `ruoyi-common/ruoyi-common-security/src/main/java/org/dromara/common/security/config/SecurityConfig.java`
- `ruoyi-common/ruoyi-common-satoken/src/main/resources/common-satoken.yml`