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 调用示例

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

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

3.1.5 返回示例

{
  "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 调用示例

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

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 返回示例

{
  "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 调用示例

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"
}

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 成功返回示例

{
  "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 失败返回示例

设备编号不存在：

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

该用户已绑定此设备：

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

3.3.7 备注

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

app对接接口说明.md 9.2 KB Előzmények Nyers