# APP 对接接口说明

## 1. 文档说明

本文档用于统一维护 APP 对接后台接口说明。

- 服务前缀：`/api`
- 本地开发示例地址：`http://localhost:18888`
- 鉴权方式：除登录等白名单接口外，请求头需携带后台登录后的 Token
- 通用返回结构：`code`、`message`、`data`

## 2. 接口目录

| 序号 | 接口名称 | 方法 | URI | 说明 |
| --- | --- | --- | --- | --- |
| 1 | 查询用户背部产品穴位坐标列表 | `GET` | `/api/user/acupoint/{profileId}/product-back-coordinates` | 查询指定子用户身体部位为背部且产品穴位为是的穴位坐标 |
| 2 | 查询用户拥有的设备列表 | `GET` | `/api/user/device/page` | 按 `userId` 查询用户当前已绑定设备，`status` 固定为 `1` |
| 3 | 用户手动输入设备编号绑定设备 | `POST` | `/api/app/user/device/bind-by-code` | APP 端按设备编号绑定设备，编号不存在返回错误提示 |

## 3. 接口详情

### 3.1 查询用户背部产品穴位坐标列表

#### 3.1.1 接口用途

用于查询指定子用户的穴位坐标列表，接口固定筛选身体部位为`背部`，且产品穴位为`是`的穴位。

当前场景：APP 根据用户档案 ID 获取该用户已计算出的背部产品穴位坐标，用于设备推送、坐标展示或调理方案匹配。

#### 3.1.2 请求信息

- 请求方式：`GET`
- URI：`/api/user/acupoint/{profileId}/product-back-coordinates`
- 完整示例：`http://localhost:18888/api/user/acupoint/123/product-back-coordinates`

#### 3.1.3 请求参数

| 参数名 | 类型 | 是否必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `profileId` | `number` | 是 | 子用户 ID，对应 `user_profile.id`，通过路径参数传递 | `123` |

#### 3.1.4 调用示例

```http
GET /api/user/acupoint/123/product-back-coordinates HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>
```

```bash
curl -X GET "http://localhost:18888/api/user/acupoint/123/product-back-coordinates" \
  -H "Authorization: Bearer <token>"
```

#### 3.1.5 返回示例

```json
{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": 192837465,
      "userId": 123,
      "acupointId": 371,
      "acupointCode": "dumai-14",
      "acupointName": "大椎",
      "acupointSide": "center",
      "bodyPart": "背部",
      "productAcupoint": 1,
      "coordinateX": 0.00,
      "coordinateY": 0.00,
      "coordinateZ": 0.00,
      "confidence": "high"
    },
    {
      "id": 192837466,
      "userId": 123,
      "acupointId": 362,
      "acupointCode": "dumai-04",
      "acupointName": "命门",
      "acupointSide": "center",
      "bodyPart": "背部",
      "productAcupoint": 1,
      "coordinateX": 0.00,
      "coordinateY": 245.30,
      "coordinateZ": 0.00,
      "confidence": "medium"
    }
  ]
}
```

#### 3.1.6 字段说明

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| `id` | `number` | 用户穴位坐标记录 ID，对应 `user_acupoint.id` |
| `userId` | `number` | 子用户 ID，对应 `user_profile.id` |
| `acupointId` | `number` | 穴位 ID，对应 `acupoint.id` |
| `acupointCode` | `string` | 穴位编码 |
| `acupointName` | `string` | 穴位名称 |
| `acupointSide` | `string` | 坐标侧别：`center=中心`，`left=左侧`，`right=右侧` |
| `bodyPart` | `string` | 身体部位，本接口固定返回 `背部` |
| `productAcupoint` | `number` | 是否产品穴位，本接口固定返回 `1` |
| `coordinateX` | `number` | X 坐标，单位 mm，相对大椎穴中心，向右为正 |
| `coordinateY` | `number` | Y 坐标，单位 mm，相对大椎穴中心，向下为正 |
| `coordinateZ` | `number` | Z 坐标，单位 mm，当前体表坐标为 `0` |
| `confidence` | `string` | 坐标置信度：`high`、`medium`、`low` |

#### 3.1.7 备注

- 本接口不需要传 `bodyPart` 和 `productAcupoint`，后端固定按 `bodyPart=背部`、`productAcupoint=1` 查询。
- 本接口只返回启用且未删除的穴位坐标，即 `acupoint.status=1` 且 `acupoint.deleted=0`。
- 如果该子用户尚未生成穴位坐标表，后端会先自动生成用户穴位坐标，再返回查询结果。
- `profileId` 使用子用户档案 ID，即 `user_profile.id`，不是后台管理员 ID。

### 3.2 查询用户拥有的设备列表

#### 3.2.1 接口用途

用于查询指定用户当前拥有的设备列表。

当前场景：APP 根据用户档案 ID 查询该用户已绑定且未解绑的设备，用于展示用户可使用的设备。

#### 3.2.2 请求信息

- 请求方式：`GET`
- URI：`/api/user/device/page`
- 完整示例：`http://localhost:18888/api/user/device/page`

#### 3.2.3 请求参数

| 参数名 | 类型 | 是否必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `userId` | `number` | 是 | 用户档案 ID，对应 `user_profile.id` | `123` |
| `status` | `number` | 是 | 绑定状态，固定传 `1`，表示只查询当前已绑定设备 | `1` |
| `pageNum` | `number` | 否 | 页码，默认 `1` | `1` |
| `pageSize` | `number` | 否 | 每页条数，默认 `10` | `10` |

#### 3.2.4 调用示例

```http
GET /api/user/device/page?userId=123&status=1&pageNum=1&pageSize=10 HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>
```

```bash
curl -X GET "http://localhost:18888/api/user/device/page?userId=123&status=1&pageNum=1&pageSize=10" \
  -H "Authorization: Bearer <token>"
```

#### 3.2.5 返回示例

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 192837465,
        "userId": 123,
        "deviceCode": "AJY-0001",
        "deviceName": "艾灸椅一号",
        "deviceModel": "AJY-2026",
        "isPrimary": 1,
        "onlineStatus": 0,
        "status": 1,
        "bindTime": "2026-06-02 10:30:00",
        "createTime": "2026-06-02 10:30:00",
        "updateTime": "2026-06-02 10:30:00"
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "pages": 1
  }
}
```

#### 3.2.6 字段说明

| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| `id` | `number` | 用户设备绑定记录 ID，对应 `user_device.id` |
| `userId` | `number` | 用户档案 ID，对应 `user_profile.id` |
| `deviceCode` | `string` | 设备编号 |
| `deviceName` | `string` | 设备名称 |
| `deviceModel` | `string` | 设备型号 |
| `isPrimary` | `number` | 是否主设备：`1=是`，`0=否` |
| `onlineStatus` | `number` | 在线状态：`1=在线`，`0=离线` |
| `status` | `number` | 绑定状态：`1=已绑定`，`0=已解绑` |
| `bindTime` | `string` | 绑定时间 |

#### 3.2.7 备注

- APP 查询用户拥有的设备列表时，`status` 固定传 `1`，不查询已解绑设备。
- `userId` 使用用户档案 ID，即 `user_profile.id`，不是后台管理员 ID。
- 返回数据来自用户设备绑定记录表 `user_device`，用于展示该用户当前已绑定设备。

### 3.3 用户手动输入设备编号绑定设备

#### 3.3.1 接口用途

用于 APP 端让用户手动输入设备编号后绑定设备。

后端会先根据设备编号查询设备主表 `device`：

- 如果设备编号存在，则自动带出设备名称、设备型号等信息，并新增用户设备绑定记录。
- 如果设备编号不存在，则返回错误码和错误信息，APP 可直接弹窗提示。

#### 3.3.2 请求信息

- 请求方式：`POST`
- URI：`/api/app/user/device/bind-by-code`
- 完整示例：`http://localhost:18888/api/app/user/device/bind-by-code`

#### 3.3.3 请求参数

请求体格式：`application/json`

| 参数名 | 类型 | 是否必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `userId` | `number` | 是 | 用户档案 ID，对应 `user_profile.id` | `123` |
| `deviceCode` | `string` | 是 | 用户手动输入的设备编号，对应 `device.device_code` | `AJY-0001` |

#### 3.3.4 调用示例

```http
POST /api/app/user/device/bind-by-code HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>
Content-Type: application/json

{
  "userId": 123,
  "deviceCode": "AJY-0001"
}
```

```bash
curl -X POST "http://localhost:18888/api/app/user/device/bind-by-code" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{\"userId\":123,\"deviceCode\":\"AJY-0001\"}"
```

#### 3.3.5 成功返回示例

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 192837466,
    "userId": 123,
    "deviceCode": "AJY-0001",
    "deviceName": "艾灸椅一号",
    "deviceModel": "AJY-2026",
    "isPrimary": 0,
    "onlineStatus": 0,
    "status": 1,
    "bindTime": "2026-06-02 10:35:00",
    "createTime": "2026-06-02 10:35:00",
    "updateTime": "2026-06-02 10:35:00"
  }
}
```

#### 3.3.6 失败返回示例

设备编号不存在：

```json
{
  "code": 1300,
  "message": "设备不存在",
  "data": null
}
```

该用户已绑定此设备：

```json
{
  "code": 1304,
  "message": "该用户已绑定此设备",
  "data": null
}
```

#### 3.3.7 备注

- APP 端只需要传 `userId` 和 `deviceCode`，不需要传 `deviceName`、`deviceModel`。
- 后端会用 `deviceCode` 查询设备主表，存在时自动写入 `deviceName`、`deviceModel`。
- 绑定成功后，绑定记录默认 `status=1`、`isPrimary=0`。
- APP 可根据失败响应中的 `message` 直接弹窗，例如设备编号不存在时提示“设备不存在”。