|
|
@@ -0,0 +1,300 @@
|
|
|
+# 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` 直接弹窗,例如设备编号不存在时提示“设备不存在”。
|