APP 对接接口说明

1. 文档说明

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

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

2. 接口目录

序号	接口名称	方法	URI	说明
1	查询用户背部产品穴位坐标列表	`GET`	`/api/app/user/acupoint/{profileId}/product-back-coordinates`	查询指定子用户身体部位为背部且产品穴位为是的穴位坐标，仅供 APP 端调用
2	查询当前账号下的设备列表	`GET`	`/api/app/device/list`	通过 Token 获取当前 APP 账号可使用的设备列表
3	用户手动输入设备编号绑定设备	`POST`	`/api/app/user/device/bind-by-code`	APP 端按设备编号绑定到当前 Token 账号下，编号不存在返回错误提示
4	APP 端查询设备详情	`GET`	`/api/app/device/{id}`	APP 端查询当前账号可访问的设备详情（仅限已绑定的家庭/公共设备）
5	新增用户自定义方案	`POST`	`/api/app/custom-plan`	APP 端为指定子用户新增一个自定义模式方案（含穴位步骤），需传入 `profileId` 指定子用户，后端强制设置 modeType=3、authorType=2、authorId=子用户ID（user_profile.id）
6	查询当前用户的自定义方案列表	`GET`	`/api/app/custom-plan/list`	通过 Token 获取当前 APP 账号下创作人属于自己的自定义模式方案基本信息列表（不含穴位步骤），如需详情请调用第 7 个接口
7	查询用户自定义方案详情	`GET`	`/api/app/custom-plan/{id}`	查询当前用户自己的某个自定义方案详情，校验方案归属，含穴位步骤列表
8	查询专业模式方案列表	`GET`	`/api/app/professional-plan/list`	通过 Token 获取专业模式（`modeType=2`）系统方案基本信息列表，所有 APP 用户共享同一份方案，仅返回已发布方案；如需详情请调用第 9 个接口
9	查询专业模式方案详情	`GET`	`/api/app/professional-plan/{id}`	查询专业模式方案详情，校验模式为专业模式且已发布，含穴位步骤列表
10	查询延年圣手模式方案列表	`GET`	`/api/app/master-plan/list`	通过 Token 获取延年圣手模式（`modeType=4`）系统方案基本信息列表，所有 APP 用户共享同一份方案，仅返回已发布方案；如需详情请调用第 11 个接口
11	查询延年圣手模式方案详情	`GET`	`/api/app/master-plan/{id}`	查询延年圣手模式方案详情，校验模式为延年圣手模式且已发布，含穴位步骤列表
12	修改用户自定义方案	`PUT`	`/api/app/custom-plan`	当前账号修改自己创建的自定义方案（含穴位步骤），仅允许修改创作人为当前账号下子用户、模式为自定义模式的方案
13	删除用户自定义方案	`DELETE`	`/api/app/custom-plan/{id}`	当前账号删除自己的自定义方案，仅允许删除创作人为当前账号下子用户、模式为自定义模式的方案
14	查询群组成员列表	`GET`	`/api/app/group/{groupId}/members`	查询指定家庭设备群组下的成员列表，仅返回当前 APP 账号所属群组的成员
15	新增群组成员	`POST`	`/api/app/group/{groupId}/members`	当前 APP 账号向指定家庭设备群组添加新成员（包含用户档案信息），需校验群组归属
16	修改群组成员	`PUT`	`/api/app/group/{groupId}/members/{profileId}`	当前 APP 账号修改指定群组下已有成员的用户档案信息，需校验群组归属
17	删除群组成员	`DELETE`	`/api/app/group/{groupId}/members/{profileId}`	当前 APP 账号从指定家庭设备群组中移除成员（软删除），需校验群组归属且禁止删除自身
18	查询当前账号个人资料	`GET`	`/api/app/user/profile`	通过 Token 获取当前 APP 账号对应的个人资料（昵称、头像、用户档案等），适用于家庭设备和公共设备
19	修改当前账号个人资料	`PUT`	`/api/app/user/profile`	通过 Token 修改当前 APP 账号对应的个人资料，部分字段（昵称/头像）更新到 `app_user` 表，其余字段（体型、地址等）更新到 `user_profile` 表，适用于家庭设备和公共设备

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 接口用途

用于根据请求头 Token 查询当前登录 APP 账号下可使用的设备列表。

当前场景：APP 登录后不再额外传 userId、status 等查询参数，后端从 Token 中解析当前账号 ID，返回该账号可使用的家庭设备和公共设备，用于展示当前账号可选择或可使用的设备。

3.2.2 请求信息

请求方式：GET
URI：/api/app/device/list
完整示例：http://localhost:18888/api/app/device/list

3.2.3 请求参数

无查询参数。后端通过 Authorization 请求头中的 Token 获取当前 APP 账号。

3.2.4 调用示例

GET /api/app/device/list HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>

curl -X GET "http://localhost:18888/api/app/device/list" \
  -H "Authorization: Bearer <token>"

3.2.5 返回示例

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": 1001,
      "deviceId": 1001,
      "deviceCode": "AJY-0001",
      "deviceName": "艾灸椅一号",
      "deviceModel": "AJY-2026",
      "deviceType": 1,
      "deviceTypeName": "家庭设备",
      "serialNo": "SN202606020001",
      "firmwareVersion": "1.0.0",
      "onlineStatus": 0,
      "lastOnlineTime": "2026-06-02 10:30:00",
      "address": "广东省深圳市",
      "groupId": 2001,
      "memberId": 3001,
      "profileId": 123,
      "profileName": "张三",
      "profileComplete": true
    },
    {
      "id": 1002,
      "deviceId": 1002,
      "deviceCode": "AJY-0002",
      "deviceName": "共享艾灸椅",
      "deviceModel": "AJY-2026",
      "deviceType": 2,
      "deviceTypeName": "公共设备",
      "serialNo": "SN202606020002",
      "firmwareVersion": "1.0.0",
      "onlineStatus": 1,
      "lastOnlineTime": "2026-06-02 10:35:00",
      "address": "广东省深圳市",
      "groupId": null,
      "memberId": null,
      "profileId": 123,
      "profileName": "张三",
      "profileComplete": true
    }
  ]
}

3.2.6 字段说明

字段名	类型	说明
`id`	`number`	设备 ID，对应 `device.id`
`deviceId`	`number`	设备 ID，对应 `device.id`
`deviceCode`	`string`	设备编号
`deviceName`	`string`	设备名称
`deviceModel`	`string`	设备型号
`deviceType`	`number`	设备类型：`1=家庭设备`，`2=公共设备`
`deviceTypeName`	`string`	设备类型名称
`serialNo`	`string`	设备序列号
`firmwareVersion`	`string`	固件版本
`onlineStatus`	`number`	在线状态：`1=在线`，`0=离线`
`lastOnlineTime`	`string`	最近在线时间
`address`	`string`	设备地址
`groupId`	`number/null`	家庭设备所属群组 ID，公共设备返回 `null`
`memberId`	`number/null`	当前账号在家庭群组中的成员 ID，公共设备返回 `null`
`profileId`	`number/null`	当前设备默认关联的用户档案 ID，对应 `user_profile.id`
`profileName`	`string/null`	当前设备默认关联的用户档案名称
`profileComplete`	`boolean`	当前关联档案是否已补全设备使用所需资料

3.2.7 备注

APP 查询设备列表时只需要携带 Token，不需要传 userId、status、pageNum、pageSize。
后端会根据 Token 中的当前 APP 账号 ID 查询该账号可使用的设备，包含家庭设备和公共设备。
家庭设备来源于当前账号已加入的设备群组；公共设备来源于当前账号下用户档案已绑定的启用设备。
本接口返回数组，不返回分页结构。

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

3.3.1 接口用途

用于 APP 端让用户手动输入设备编号后，将设备绑定到当前登录账号下。

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

如果设备编号存在，则从 Token 中获取当前 APP 账号 ID，自动确认或创建当前账号档案，再带出设备名称、设备型号等信息，并新增用户设备绑定记录。
如果设备编号不存在，则返回错误码和错误信息，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

参数名	类型	是否必填	说明	示例
`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

{
  "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 "{\"deviceCode\":\"AJY-0001\"}"

3.3.5 成功返回示例

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 192837466,
    "deviceId": 1001,
    "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 端只需要传 deviceCode，不需要传 userId、deviceName、deviceModel。
后端从 Token 中获取当前 APP 账号 ID，并将设备绑定到当前账号对应的用户档案下。
成功响应中的 userId 为后端自动关联的用户档案 ID，对应 user_profile.id。
后端会用 deviceCode 查询设备主表，存在时自动写入 deviceName、deviceModel。
绑定成功后，绑定记录默认 status=1、isPrimary=0。
APP 可根据失败响应中的 message 直接弹窗，例如设备编号不存在时提示"设备不存在"。

3.4 APP 端查询设备详情

3.4.1 接口用途

用于 APP 端查询当前登录账号可访问的设备详情。

后端会根据 Token 中的 APP 账号 ID 校验访问权限：

家庭设备（deviceType=1）：校验当前 APP 账号是否在该设备的家庭群组内（device_group_member）
公共设备（deviceType=2）：校验当前 APP 账号下的用户档案是否已绑定该设备（user_device）
越权或设备不存在时返回 403 或 1300 错误

3.4.2 请求信息

请求方式：GET
URI：/api/app/device/{id}
完整示例：http://localhost:18888/api/app/device/1001

3.4.3 请求参数

参数名	类型	是否必填	说明	示例
`id`	`number`	是	设备 ID，对应 `device.id`，通过路径参数传递	`1001`

3.4.4 调用示例

GET /api/app/device/1001 HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>

curl -X GET "http://localhost:18888/api/app/device/1001" \
  -H "Authorization: Bearer <token>"

3.4.5 返回示例

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1001,
    "deviceCode": "AJY-0001",
    "deviceName": "艾灸椅一号",
    "deviceModel": "AJY-2026",
    "deviceType": 1,
    "serialNo": "SN202606020001",
    "firmwareVersion": "1.0.0",
    "onlineStatus": 0,
    "lastOnlineTime": "2026-06-02 10:30:00",
    "provinceCode": "440000",
    "cityCode": "440300",
    "districtCode": "440305",
    "address": "广东省深圳市南山区",
    "remark": "测试设备",
    "deleted": 0,
    "createTime": "2026-06-01 09:00:00",
    "updateTime": "2026-06-02 10:30:00"
  }
}

3.4.6 字段说明

字段名	类型	说明
`id`	`number`	设备 ID，对应 `device.id`
`deviceCode`	`string`	设备编号
`deviceName`	`string`	设备名称
`deviceModel`	`string`	设备型号
`deviceType`	`number`	设备类型：`1=家庭设备`，`2=公共设备`
`serialNo`	`string`	设备序列号
`firmwareVersion`	`string`	固件版本
`onlineStatus`	`number`	在线状态：`1=在线`，`0=离线`
`lastOnlineTime`	`string`	最后在线时间
`provinceCode`	`string`	省级行政区划编码（GB/T 2260）
`cityCode`	`string`	市级行政区划编码
`districtCode`	`string`	区/县级行政区划编码
`address`	`string`	详细地址
`remark`	`string`	备注
`deleted`	`number`	逻辑删除：`0=未删除`，`1=已删除`
`createTime`	`string`	创建时间
`updateTime`	`string`	更新时间

3.4.7 失败返回示例

设备不存在：

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

当前账号无权限访问该设备：

{
  "code": 403,
  "message": "无权访问该设备",
  "data": null
}

3.4.8 备注

本接口需要 APP 登录后的 Token，不接受后台管理员 Token。
越权校验在 Service 层完成，家庭设备校验 device_group_member.app_user_id，公共设备校验 user_device.user_id 是否归属当前 APP 账号下的用户档案。
后端不会返回 boundUserCount、boundUserNames、userIds 等聚合字段，避免暴露其他用户信息。
路径参数 id 为 device.id（主键），不是设备编号 deviceCode，APP 调用时需先通过列表接口获取设备主键。

3.5 新增用户自定义方案

3.5.1 接口用途

用于 APP 端用户新增一个自定义模式方案（含穴位步骤）。

后端强制设置：

modeType = 3（自定义模式）
authorType = 2（用户创作）
authorId = 子用户 ID（user_profile.id，由前端传入 profileId 指定）
authorName = 子用户名称（user_profile.name，后端根据 profileId 自动查询）
planCode = 系统自动生成（S + 6 位随机字符）

profileId 为必传参数，用于指定方案归属的子用户。后端会校验该子用户是否属于当前 APP 账号。其余字段前端无需传入，后端会忽略前端传值。

3.5.2 请求信息

请求方式：POST
URI：/api/app/custom-plan
完整示例：http://localhost:18888/api/app/custom-plan

3.5.3 请求参数

请求体格式：application/json

参数名	类型	是否必填	说明	示例
`profileId`	`number`	是	子用户档案 ID，对应 `user_profile.id`，用于指定方案归属的子用户	`4`
`name`	`string`	是	方案名称（最长 100 字符，同一子用户下不可重复）	`我的祛湿方案`
`symptoms`	`string`	否	适用症状（逗号分隔）	`关节酸痛,乏力`
`applicableGender`	`number`	否	适用人群：`0=不限`，`1=仅男`，`2=仅女`	`0`
`ageMin`	`number`	否	适用年龄最小值（岁）	`18`
`ageMax`	`number`	否	适用年龄最大值（岁）	`60`
`description`	`string`	否	方案描述（最长 500 字符）	`针对湿气重的人群定制`
`status`	`number`	否	状态：`0=草稿`，`1=已发布`。不传默认为 `1`	`1`
`steps`	`array`	是	穴位步骤列表，至少 1 个	见下方 `steps` 字段说明

steps 数组中每个元素字段：

参数名	类型	是否必填	说明
`acupointId`	`number`	是	穴位 ID，对应 `acupoint.id`
`side`	`number`	否	侧别：`1=中心`，`2=左侧`，`3=右侧`，`4=双侧`。不传则跟随穴位默认侧别（一般为 `1`）
`temperature`	`number`	否	温度（°C，范围 35-50）
`duration`	`number`	否	时长（分钟，范围 1-30）
`techniqueId`	`number`	否	艾灸手法 ID（对应 `moxibustion_technique.id`）
`remark`	`string`	否	步骤备注（最长 100 字符）

说明：

请求体中无需传 id、planId、stepOrder、acupointName、techniqueName 等字段，后端会按 steps 数组顺序自动重排 stepOrder（从 1 开始），并通过 acupointId 自动带出 acupointName、techniqueName。

修改接口（PUT /api/app/custom-plan）与本接口共用同一份步骤结构，请求示例保持一致。

3.5.4 调用示例

POST /api/app/custom-plan HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>
Content-Type: application/json

{
  "profileId": 4,
  "name": "我的祛湿方案",
  "symptoms": "关节酸痛,乏力",
  "applicableGender": 0,
  "ageMin": 18,
  "ageMax": 60,
  "description": "针对湿气重的人群定制",
  "status": 1,
  "steps": [
    {
      "acupointId": 371,
      "side": 1,
      "temperature": 42.00,
      "duration": 10,
      "techniqueId": 1,
      "remark": "核心穴位"
    },
    {
      "acupointId": 362,
      "side": 1,
      "temperature": 42.00,
      "duration": 10,
      "techniqueId": 1,
      "remark": ""
    }
  ]
}

curl -X POST "http://localhost:18888/api/app/custom-plan" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"profileId":4,"name":"我的祛湿方案","symptoms":"关节酸痛,乏力","applicableGender":0,"ageMin":18,"ageMax":60,"description":"针对湿气重的人群定制","status":1,"steps":[{"acupointId":371,"side":1,"temperature":42.00,"duration":10,"techniqueId":1,"remark":"核心穴位"},{"acupointId":362,"side":1,"temperature":42.00,"duration":10,"techniqueId":1,"remark":""}]}'

3.5.5 返回示例

{
  "code": 200,
  "message": "操作成功",
  "data": 2067138786800111618
}

3.5.6 失败返回示例

方案名称重复：

{
  "code": 1702,
  "message": "方案名称已存在",
  "data": null
}

步骤为空：

{
  "code": 1706,
  "message": "方案步骤至少保留1个",
  "data": null
}

子用户档案ID为空：

{
  "code": 400,
  "message": "子用户档案ID不能为空",
  "data": null
}

子用户档案不存在或不属于当前账号：

{
  "code": 400,
  "message": "子用户档案不存在或不属于当前账号",
  "data": null
}

3.5.7 备注

profileId 为必传参数，用于指定方案归属的子用户。后端会校验该子用户是否属于当前 APP 账号，不传或不属于当前账号均返回 400 错误。
modeType、effectType、planCode、authorId、authorName、authorType 等字段前端无需传入，后端统一设置。
方案名称在同一子用户范围内不可重复，若重复返回 1702 错误。
成功返回 data 为新方案的 ID，后续可用于详情查询、修改和删除。
steps 不能为空，至少包含 1 个穴位步骤。

3.6 查询当前用户的自定义方案列表

3.6.1 接口用途

用于 APP 端查询当前登录账号下，自己（作为创作人）创建的所有自定义模式（modeType=3）方案的基本信息。

当前场景：APP 中"我的方案"页面展示用户自己创建的自定义方案列表，用于查看、复用或继续编辑。

本接口只返回方案基本信息，不包含穴位步骤。查看方案详情（含穴位步骤）请使用第 7 个接口 GET /api/app/custom-plan/{id}。

3.6.2 请求信息

请求方式：GET
URI：/api/app/custom-plan/list
完整示例：http://localhost:18888/api/app/custom-plan/list

3.6.3 请求参数

无查询参数。后端通过 Authorization 请求头中的 Token 获取当前 APP 账号 ID，查询该账号下所有子用户（user_profile），返回创作人类型为用户（authorType=2）、模式为自定义模式（modeType=3）且创作人 ID 属于当前账号下子用户的方案。

3.6.4 调用示例

GET /api/app/custom-plan/list HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>

curl -X GET "http://localhost:18888/api/app/custom-plan/list" \
  -H "Authorization: Bearer <token>"

3.6.5 返回示例

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": 1001,
      "planCode": "SA1B2C3",
      "name": "我的颈椎调理方案",
      "modeType": 3,
      "effectType": "",
      "symptoms": "肩颈酸痛,头晕",
      "applicableGender": 0,
      "ageMin": 18,
      "ageMax": 60,
      "description": "针对长期伏案人群的颈椎调理方案",
      "authorId": 17320687382,
      "authorName": "张三",
      "authorType": 2,
      "useCount": 12,
      "avgRating": 4.80,
      "lastUseTime": "2026-06-15 08:30:00",
      "status": 1,
      "createTime": "2026-06-10 09:00:00",
      "updateTime": "2026-06-12 10:30:00"
    },
    {
      "id": 1002,
      "planCode": "S9X8Y7Z6",
      "name": "我的祛湿方案",
      "modeType": 3,
      "effectType": "",
      "symptoms": "关节酸痛,乏力",
      "applicableGender": 0,
      "ageMin": 20,
      "ageMax": 60,
      "description": "针对湿气重的人群定制",
      "authorId": 17320687382,
      "authorName": "张三",
      "authorType": 2,
      "useCount": 0,
      "avgRating": null,
      "lastUseTime": null,
      "status": 1,
      "createTime": "2026-06-13 14:00:00",
      "updateTime": "2026-06-13 14:00:00"
    }
  ]
}

3.6.6 字段说明

字段名	类型	说明
`id`	`number`	方案 ID，对应 `plan.id`
`planCode`	`string`	方案编码
`name`	`string`	方案名称
`modeType`	`number`	模式类型，本接口固定返回 `3`（自定义模式）
`effectType`	`string`	作用类型，自定义模式固定为空字符串
`symptoms`	`string`	适用症状（逗号分隔）
`applicableGender`	`number`	适用人群：`0=不限`，`1=仅男`，`2=仅女`
`ageMin`	`number/null`	适用年龄最小值（岁）
`ageMax`	`number/null`	适用年龄最大值（岁）
`description`	`string`	方案描述
`authorId`	`number`	创作人 ID，等于子用户 ID（`user_profile.id`）
`authorName`	`string`	创作人名称（冗余字段）
`authorType`	`number`	创作人类型，本接口固定返回 `2`（用户创作）
`useCount`	`number`	使用人数
`avgRating`	`number/null`	平均评分
`lastUseTime`	`string/null`	最后使用时间
`status`	`number`	状态：`0=草稿`，`1=已发布`，`2=已下架`
`createTime`	`string`	创建时间
`updateTime`	`string`	更新时间

3.6.7 备注

本接口不返回穴位步骤列表（steps），仅返回方案基本信息。如需查看方案详情和穴位步骤，请调用第 7 个接口 GET /api/app/custom-plan/{id}。
本接口仅返回当前 APP 账号下子用户作为"创作人"的自定义模式方案，不会返回系统方案或其他账号子用户创作的方案。
后端根据 Token 解析当前账号 ID，查询该账号下所有子用户 ID，按 authorType=2、modeType=3、authorId 为当前账号下子用户 ID 严格过滤。
useCount、avgRating 为方案被使用后的统计字段，新建方案的初始值为 0/null。
结果按 updateTime 倒序返回，最近修改或创建的方案排在前。

3.7 查询用户自定义方案详情

3.7.1 接口用途

用于 APP 端查询当前登录账号下，自己创建的某个自定义模式方案详情，校验方案归属权，避免越权访问。

3.7.2 请求信息

请求方式：GET
URI：/api/app/custom-plan/{id}
完整示例：http://localhost:18888/api/app/custom-plan/1001

3.7.3 请求参数

参数名	类型	是否必填	说明	示例
`id`	`number`	是	方案 ID，对应 `plan.id`，通过路径参数传递	`1001`

3.7.4 调用示例

GET /api/app/custom-plan/1001 HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>

curl -X GET "http://localhost:18888/api/app/custom-plan/1001" \
  -H "Authorization: Bearer <token>"

3.7.5 返回示例

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1001,
    "planCode": "SA1B2C3",
    "name": "我的颈椎调理方案",
    "modeType": 3,
    "symptoms": "肩颈酸痛,头晕",
    "applicableGender": 0,
    "ageMin": 18,
    "ageMax": 60,
    "description": "针对长期伏案人群的颈椎调理方案",
    "useCount": 12,
    "avgRating": 4.80,
    "status": 1,
    "createTime": "2026-06-10 09:00:00",
    "updateTime": "2026-06-12 10:30:00",
    "steps": [
      {
        "id": 5001,
        "planId": 1001,
        "stepOrder": 1,
        "acupointId": 371,
        "acupointName": "大椎穴",
        "side": 1,
        "temperature": 42.00,
        "duration": 10,
        "techniqueId": 1,
        "techniqueName": "温和灸",
        "remark": ""
      }
    ]
  }
}

3.7.6 字段说明

方案基本信息字段（id、planCode、name、modeType、effectType、symptoms、applicableGender、ageMin、ageMax、description、authorId、authorName、authorType、useCount、avgRating、lastUseTime、status、createTime、updateTime）定义同 3.6.6 节。

steps 穴位步骤列表字段：

字段名	类型	说明
`steps`	`array`	穴位步骤列表，按 `stepOrder` 升序
`steps[].id`	`number`	步骤 ID，对应 `plan_step.id`
`steps[].planId`	`number`	所属方案 ID
`steps[].stepOrder`	`number`	步骤序号（从 1 开始）
`steps[].acupointId`	`number`	穴位 ID，对应 `acupoint.id`
`steps[].acupointName`	`string`	穴位名称（冗余字段）
`steps[].side`	`number`	侧别：`1=中心`，`2=左侧`，`3=右侧`，`4=双侧`
`steps[].temperature`	`number`	温度（°C，范围 35-50）
`steps[].duration`	`number`	时长（分钟，范围 1-30）
`steps[].techniqueId`	`number/null`	艾灸手法 ID
`steps[].techniqueName`	`string/null`	艾灸手法名称（冗余字段）
`steps[].remark`	`string`	步骤备注

3.7.7 失败返回示例

方案不存在或非当前用户创建的自定义方案：

{
  "code": 1700,
  "message": "方案不存在",
  "data": null
}

3.7.8 备注

越权校验在 Service 层完成：仅当 modeType=3、authorType=2、authorId 为当前账号下子用户 ID 同时满足时才返回方案详情，否则按"方案不存在"处理。
不会返回其他用户创作的方案、系统预设方案（modeType=1/2/4）的详情。
APP 在编辑方案前应先调用本接口获取最新数据。

3.8 查询专业模式方案列表

3.8.1 接口用途

用于 APP 端查询专业模式（modeType=2）的系统方案列表。

专业模式方案由后台预置并在所有 APP 用户间共享，没有用户差异：例如方案 ABC 存在时，所有登录的 APP 用户都能看到 ABC 三个方案，不会因为账号不同而出现不同结果。

当前场景：APP 中"专业模式"页面展示系统预置的方案列表（驱寒、祛湿、祛风、化瘀、活血、化痰、养颜、扶阳等），供用户选择使用。

本接口只返回方案基本信息，不包含穴位步骤。查看方案详情（含穴位步骤）请使用第 9 个接口 GET /api/app/professional-plan/{id}。

3.8.2 请求信息

请求方式：GET
URI：/api/app/professional-plan/list
完整示例：http://localhost:18888/api/app/professional-plan/list

3.8.3 请求参数

无查询参数。后端通过 Authorization 请求头中的 Token 校验登录态，并按 modeType=2、status=1（已发布）返回专业模式方案列表，不区分用户。

3.8.4 调用示例

GET /api/app/professional-plan/list HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>

curl -X GET "http://localhost:18888/api/app/professional-plan/list" \
  -H "Authorization: Bearer <token>"

3.8.5 返回示例

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": 10001,
      "planCode": "S002",
      "name": "专业驱寒方案",
      "modeType": 2,
      "effectType": "驱寒",
      "symptoms": "怕冷,手脚冰凉,畏寒",
      "applicableGender": 0,
      "ageMin": 1,
      "ageMax": 120,
      "description": "针对阳虚畏寒人群的基础驱寒方案。",
      "authorId": 1,
      "authorName": "ADMIN",
      "authorType": 1,
      "useCount": 0,
      "avgRating": null,
      "lastUseTime": null,
      "status": 1,
      "createTime": "2026-06-01 09:00:00",
      "updateTime": "2026-06-01 09:00:00"
    },
    {
      "id": 10002,
      "planCode": "S003",
      "name": "专业祛湿方案",
      "modeType": 2,
      "effectType": "祛湿",
      "symptoms": "困倦,湿重,食欲差",
      "applicableGender": 0,
      "ageMin": 1,
      "ageMax": 120,
      "description": "围绕脾胃与膀胱经调理的祛湿方案。",
      "authorId": 1,
      "authorName": "ADMIN",
      "authorType": 1,
      "useCount": 0,
      "avgRating": null,
      "lastUseTime": null,
      "status": 1,
      "createTime": "2026-06-01 09:00:00",
      "updateTime": "2026-06-01 09:00:00"
    }
  ]
}

3.8.6 字段说明

字段名	类型	说明
`id`	`number`	方案 ID，对应 `plan.id`
`planCode`	`string`	方案编码
`name`	`string`	方案名称
`modeType`	`number`	模式类型，本接口固定返回 `2`（专业模式）
`effectType`	`string`	作用类型：驱寒/祛湿/祛风/化瘀/活血/化痰/养颜/扶阳
`symptoms`	`string`	适用症状（逗号分隔）
`applicableGender`	`number`	适用人群：`0=不限`，`1=仅男`，`2=仅女`
`ageMin`	`number`	适用年龄最小值（岁）
`ageMax`	`number`	适用年龄最大值（岁）
`description`	`string`	方案描述
`authorId`	`number`	创作人 ID
`authorName`	`string`	创作人名称（系统预置为 `ADMIN`）
`authorType`	`number`	创作人类型：`1=管理员`，`2=用户`，`3=专家`，系统预置方案固定为 `1`
`useCount`	`number`	使用人数
`avgRating`	`number/null`	平均评分
`lastUseTime`	`string/null`	最后使用时间
`status`	`number`	状态：本接口固定返回 `1`（已发布）
`createTime`	`string`	创建时间
`updateTime`	`string`	更新时间

3.8.7 备注

本接口不返回穴位步骤列表（steps），仅返回方案基本信息。如需查看方案详情和穴位步骤，请调用第 9 个接口 GET /api/app/professional-plan/{id}。
本接口返回的方案对所有 APP 用户共享，不因账号不同而出现不同结果。
后端按 modeType=2、status=1（已发布）、deleted=0 严格过滤，不会返回草稿、已下架或已删除的方案，也不会返回一键艾灸（modeType=1）、自定义模式（modeType=3）、延年圣手（modeType=4）的方案。
结果按 effectType 升序、id 升序返回，相同作用类型下按 ID 顺序展示。

3.9 查询专业模式方案详情

3.9.1 接口用途

用于 APP 端查询专业模式（modeType=2）的某个系统方案详情，含穴位步骤列表。

3.9.2 请求信息

请求方式：GET
URI：/api/app/professional-plan/{id}
完整示例：http://localhost:18888/api/app/professional-plan/10001

3.9.3 请求参数

参数名	类型	是否必填	说明	示例
`id`	`number`	是	方案 ID，对应 `plan.id`，通过路径参数传递	`10001`

3.9.4 调用示例

GET /api/app/professional-plan/10001 HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>

curl -X GET "http://localhost:18888/api/app/professional-plan/10001" \
  -H "Authorization: Bearer <token>"

3.9.5 返回示例

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 10001,
    "planCode": "S002",
    "name": "专业驱寒方案",
    "modeType": 2,
    "symptoms": "怕冷,手脚冰凉,畏寒",
    "applicableGender": 0,
    "ageMin": 1,
    "ageMax": 120,
    "description": "针对阳虚畏寒人群的基础驱寒方案。",
    "useCount": 0,
    "avgRating": null,
    "status": 1,
    "createTime": "2026-06-01 09:00:00",
    "updateTime": "2026-06-01 09:00:00",
    "steps": [
      {
        "id": 20001,
        "planId": 10001,
        "stepOrder": 1,
        "acupointId": 1,
        "acupointName": "大椎穴",
        "side": 1,
        "temperature": 44.00,
        "duration": 8,
        "techniqueId": 3,
        "techniqueName": "雀啄灸",
        "remark": "驱寒起始"
      }
    ]
  }
}

3.9.6 字段说明

steps 穴位步骤列表字段定义同 3.7.6 节。

3.9.7 失败返回示例

方案不存在、非专业模式、未发布或已删除：

{
  "code": 1700,
  "message": "方案不存在",
  "data": null
}

3.9.8 备注

越权校验在 Service 层完成：仅当 modeType=2、status=1（已发布）、deleted=0 同时满足时才返回方案详情，否则按"方案不存在"处理。
本接口为只读，不会修改任何数据。
方案对所有 APP 用户开放，任意登录用户均可查询。
不会返回自定义模式（modeType=3）、一键艾灸（modeType=1）、延年圣手（modeType=4）的方案详情，防止越权访问。

3.10 查询延年圣手模式方案列表

3.10.1 接口用途

用于 APP 端查询延年圣手模式（modeType=4）的系统方案列表。

延年圣手模式方案由后台预置并在所有 APP 用户间共享，没有用户差异：例如方案 XYZ 存在时，所有登录的 APP 用户都能看到 XYZ 三个方案。

当前场景：APP 中"延年圣手"页面展示系统预置方案列表，供用户选择使用。

本接口只返回方案基本信息，不包含穴位步骤。查看方案详情（含穴位步骤）请使用第 11 个接口 GET /api/app/master-plan/{id}。

3.10.2 请求信息

请求方式：GET
URI：/api/app/master-plan/list
完整示例：http://localhost:18888/api/app/master-plan/list

3.10.3 请求参数

无查询参数。后端通过 Authorization 请求头中的 Token 校验登录态，并按 modeType=4、status=1（已发布）返回延年圣手模式方案列表，不区分用户。

3.10.4 调用示例

GET /api/app/master-plan/list HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>

curl -X GET "http://localhost:18888/api/app/master-plan/list" \
  -H "Authorization: Bearer <token>"

3.10.5 返回示例

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": 20001,
      "planCode": "M001",
      "name": "延年圣手·扶阳固本",
      "modeType": 4,
      "effectType": "",
      "symptoms": "腰膝酸软,畏寒肢冷",
      "applicableGender": 0,
      "ageMin": 18,
      "ageMax": 80,
      "description": "针对中老年体虚人群的延年圣手方案。",
      "authorId": 1,
      "authorName": "ADMIN",
      "authorType": 1,
      "useCount": 0,
      "avgRating": null,
      "lastUseTime": null,
      "status": 1,
      "createTime": "2026-06-01 09:00:00",
      "updateTime": "2026-06-01 09:00:00"
    }
  ]
}

3.10.6 字段说明

字段名	类型	说明
`id`	`number`	方案 ID，对应 `plan.id`
`planCode`	`string`	方案编码
`name`	`string`	方案名称
`modeType`	`number`	模式类型，本接口固定返回 `4`（延年圣手）
`effectType`	`string`	作用类型，延年圣手模式可为空字符串
`symptoms`	`string`	适用症状（逗号分隔）
`applicableGender`	`number`	适用人群：`0=不限`，`1=仅男`，`2=仅女`
`ageMin`	`number/null`	适用年龄最小值（岁）
`ageMax`	`number/null`	适用年龄最大值（岁）
`description`	`string`	方案描述
`authorId`	`number`	创作人 ID
`authorName`	`string`	创作人名称
`authorType`	`number`	创作人类型
`useCount`	`number`	使用人数
`avgRating`	`number/null`	平均评分
`lastUseTime`	`string/null`	最后使用时间
`status`	`number`	状态：本接口固定返回 `1`（已发布）
`createTime`	`string`	创建时间
`updateTime`	`string`	更新时间

3.10.7 备注

本接口不返回穴位步骤列表（steps），仅返回方案基本信息。如需查看方案详情和穴位步骤，请调用第 11 个接口 GET /api/app/master-plan/{id}。
本接口返回的方案对所有 APP 用户共享，不因账号不同而出现不同结果。
后端按 modeType=4、status=1（已发布）、deleted=0 严格过滤，不会返回草稿、已下架或已删除的方案，也不会返回一键艾灸（modeType=1）、专业模式（modeType=2）、自定义模式（modeType=3）的方案。
结果按 id 升序返回。

3.11 查询延年圣手模式方案详情

3.11.1 接口用途

用于 APP 端查询延年圣手模式（modeType=4）的某个系统方案详情，含穴位步骤列表。

3.11.2 请求信息

请求方式：GET
URI：/api/app/master-plan/{id}
完整示例：http://localhost:18888/api/app/master-plan/20001

3.11.3 请求参数

参数名	类型	是否必填	说明	示例
`id`	`number`	是	方案 ID，对应 `plan.id`，通过路径参数传递	`20001`

3.11.4 调用示例

GET /api/app/master-plan/20001 HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>

curl -X GET "http://localhost:18888/api/app/master-plan/20001" \
  -H "Authorization: Bearer <token>"

3.11.5 返回示例

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 20001,
    "planCode": "M001",
    "name": "延年圣手·扶阳固本",
    "modeType": 4,
    "symptoms": "腰膝酸软,畏寒肢冷",
    "applicableGender": 0,
    "ageMin": 18,
    "ageMax": 80,
    "description": "针对中老年体虚人群的延年圣手方案。",
    "useCount": 0,
    "avgRating": null,
    "status": 1,
    "createTime": "2026-06-01 09:00:00",
    "updateTime": "2026-06-01 09:00:00",
    "steps": [
      {
        "id": 30001,
        "planId": 20001,
        "stepOrder": 1,
        "acupointId": 8,
        "acupointName": "肾俞穴",
        "side": 4,
        "temperature": 44.00,
        "duration": 10,
        "techniqueId": 2,
        "techniqueName": "温和灸",
        "remark": "补肾扶阳"
      }
    ]
  }
}

3.11.6 字段说明

steps 穴位步骤列表字段定义同 3.7.6 节。

3.11.7 失败返回示例

方案不存在、非延年圣手模式、未发布或已删除：

{
  "code": 1700,
  "message": "方案不存在",
  "data": null
}

3.11.8 备注

越权校验在 Service 层完成：仅当 modeType=4、status=1（已发布）、deleted=0 同时满足时才返回方案详情，否则按"方案不存在"处理。
本接口为只读，不会修改任何数据。
方案对所有 APP 用户开放，任意登录用户均可查询。
不会返回自定义模式（modeType=3）、一键艾灸（modeType=1）、专业模式（modeType=2）的方案详情，防止越权访问。

3.12 修改用户自定义方案

3.12.1 接口用途

用于 APP 端让用户修改自己创建的自定义模式方案，包括方案基本信息和穴位步骤列表。

请求体格式与"新增用户自定义方案"接口（POST /api/app/custom-plan，见 3.5 节）基本一致，区别如下：多一个 id 字段（必传）；不需要传 profileId（方案归属在创建时已确定，修改时不变更归属子用户）。steps 结构、字段含义、必填/可选规则与新增接口完全相同。

3.12.2 请求信息

请求方式：PUT
URI：/api/app/custom-plan
完整示例：http://localhost:18888/api/app/custom-plan

3.12.3 请求参数

请求体格式：application/json

参数名	类型	是否必填	说明	示例
`id`	`number`	是	方案 ID，对应 `plan.id`	`1001`
`name`	`string`	是	方案名称（最长 100 字符，同一子用户下不可重复）	`我的祛湿方案`
`symptoms`	`string`	否	适用症状（逗号分隔）	`关节酸痛,乏力`
`applicableGender`	`number`	否	适用人群：`0=不限`，`1=仅男`，`2=仅女`	`0`
`ageMin`	`number`	否	适用年龄最小值（岁）	`18`
`ageMax`	`number`	否	适用年龄最大值（岁）	`60`
`description`	`string`	否	方案描述（最长 500 字符）	`针对湿气重的人群定制`
`status`	`number`	否	状态：`0=草稿`，`1=已发布`，`2=已下架`	`1`
`steps`	`array`	是	穴位步骤列表，传 `[]` 表示清空所有步骤，传 `null` 表示保留原步骤	见下方 `steps` 字段说明

steps 数组中每个元素字段（与 3.5 节"新增用户自定义方案"完全一致）：

参数名	类型	是否必填	说明
`acupointId`	`number`	是	穴位 ID，对应 `acupoint.id`
`side`	`number`	否	侧别：`1=中心`，`2=左侧`，`3=右侧`，`4=双侧`。不传则跟随穴位默认侧别（一般为 `1`）
`temperature`	`number`	否	温度（°C，范围 35-50）
`duration`	`number`	否	时长（分钟，范围 1-30）
`techniqueId`	`number`	否	艾灸手法 ID（对应 `moxibustion_technique.id`）
`remark`	`string`	否	步骤备注（最长 100 字符）

说明：请求体中无需传 id（步骤）、planId、stepOrder、acupointName、techniqueName 等字段，后端会按 steps 数组顺序自动重排 stepOrder（从 1 开始），并通过 acupointId 自动带出 acupointName、techniqueName。

3.12.4 调用示例

PUT /api/app/custom-plan HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>
Content-Type: application/json

{
  "id": 1001,
  "name": "我的祛湿方案",
  "symptoms": "关节酸痛,乏力",
  "applicableGender": 0,
  "ageMin": 18,
  "ageMax": 60,
  "description": "针对湿气重的人群定制",
  "status": 1,
  "steps": [
    {
      "acupointId": 371,
      "side": 1,
      "temperature": 42.00,
      "duration": 10,
      "techniqueId": 1,
      "remark": "核心穴位"
    },
    {
      "acupointId": 362,
      "side": 1,
      "temperature": 42.00,
      "duration": 10,
      "techniqueId": 1,
      "remark": ""
    }
  ]
}

curl -X PUT "http://localhost:18888/api/app/custom-plan" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"id":1001,"name":"我的祛湿方案","symptoms":"关节酸痛,乏力","applicableGender":0,"ageMin":18,"ageMax":60,"description":"针对湿气重的人群定制","status":1,"steps":[{"acupointId":371,"side":1,"temperature":42.00,"duration":10,"techniqueId":1,"remark":"核心穴位"},{"acupointId":362,"side":1,"temperature":42.00,"duration":10,"techniqueId":1,"remark":""}]}'

3.12.5 成功返回示例

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

3.12.6 失败返回示例

方案不存在或非当前用户创建的自定义方案：

{
  "code": 1700,
  "message": "方案不存在",
  "data": null
}

方案名称已存在：

{
  "code": 1702,
  "message": "方案名称已存在",
  "data": null
}

穴位不存在或已停用：

{
  "code": 1400,
  "message": "穴位不存在",
  "data": null
}

3.12.7 备注

本接口需要 APP 登录后的 Token，不接受后台管理员 Token。
后端会自动校验 modeType=3、authorType=2、authorId 为当前账号下子用户 ID，不满足时按"方案不存在"处理，避免越权。
修改方案时后端使用"先删后增"的方式更新穴位步骤：steps 传 null 时保留原步骤；传 [] 时清空所有步骤；传非空数组时整体替换为新步骤并重新计算步骤序号。
方案名称在同一子用户范围内唯一，修改时不能与该子用户下其他方案重名。
穴位必须处于启用状态（acupoint.status=1）才能被引用。
modeType、effectType、planCode、authorId、authorName、authorType、useCount、avgRating 等字段为系统字段，APP 传入也会被忽略，不允许用户修改。

3.13 删除用户自定义方案

3.13.1 接口用途

用于 APP 端用户删除自己的自定义方案。

后端校验方案归属（modeType=3、authorType=2、authorId 为当前账号下子用户 ID），仅允许删除自己创建的自定义方案。删除为物理删除，会同步删除方案下的穴位步骤。

3.13.2 请求信息

请求方式：DELETE
URI：/api/app/custom-plan/{id}
完整示例：http://localhost:18888/api/app/custom-plan/2067138786800111618

3.13.3 请求参数

参数名	类型	是否必填	说明	示例
`id`	`number`	是	方案 ID，对应 `plan.id`，通过路径参数传递	`2067138786800111618`

3.13.4 调用示例

DELETE /api/app/custom-plan/2067138786800111618 HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>

curl -X DELETE "http://localhost:18888/api/app/custom-plan/2067138786800111618" \
  -H "Authorization: Bearer <token>"

3.13.5 返回示例

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

3.13.6 失败返回示例

方案不存在或不属于当前用户：

{
  "code": 1700,
  "message": "方案不存在",
  "data": null
}

3.13.7 备注

删除为物理删除，不可恢复，请谨慎操作。
仅允许删除创作人为当前账号下子用户的自定义模式方案，不存在或不属于当前账号的方案均返回 1700 错误。
删除方案时会同步删除该方案下的所有穴位步骤。

3.14 查询群组成员列表

3.14.1 接口用途

用于 APP 端查询指定家庭设备群组下的所有成员列表。

后端会校验当前 APP 账号是否属于该家庭设备群组（device_group_member.app_user_id = 当前账号ID），仅返回当前账号所属群组的成员，越权或群组不存在时返回 403 错误。

3.14.2 请求信息

请求方式：GET
URI：/api/app/group/{groupId}/members
完整示例：http://localhost:18888/api/app/group/2001/members

3.14.3 请求参数

参数名	类型	是否必填	说明	示例
`groupId`	`number`	是	家庭设备群组 ID，对应 `device_group.id`，通过路径参数传递	`2001`

3.14.4 调用示例

GET /api/app/group/2001/members HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>

curl -X GET "http://localhost:18888/api/app/group/2001/members" \
  -H "Authorization: Bearer <token>"

3.14.5 返回示例

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "memberId": 3001,
      "groupId": 2001,
      "profileId": 123,
      "appUserId": 17320687382,
      "status": 1,
      "joinTime": "2026-06-01 09:00:00",
      "profileComplete": true,
      "name": "张三",
      "gender": 1,
      "age": 35,
      "phone": "13800138000",
      "provinceCode": "440000",
      "cityCode": "440300",
      "districtCode": "440305",
      "address": "广东省深圳市南山区",
      "shoulderWidth": 42.50,
      "bodyHeight": 85.00,
      "spineLength": 48.00,
      "height": 175.00,
      "weight": 70.00,
      "fingerWidth1": 2.20,
      "fingerWidth15": 3.20,
      "fingerWidth3": 6.50,
      "acupointTableId": 5001,
      "profile": {
        "profileId": 123,
        "id": 123,
        "appUserId": 17320687382,
        "name": "张三",
        "gender": 1,
        "age": 35,
        "phone": "13800138000",
        "provinceCode": "440000",
        "cityCode": "440300",
        "districtCode": "440305",
        "address": "广东省深圳市南山区",
        "shoulderWidth": 42.50,
        "bodyHeight": 85.00,
        "spineLength": 48.00,
        "height": 175.00,
        "weight": 70.00,
        "fingerWidth1": 2.20,
        "fingerWidth15": 3.20,
        "fingerWidth3": 6.50,
        "acupointTableId": 5001,
        "profileComplete": true
      }
    }
  ]
}

3.14.6 字段说明

字段名	类型	说明
`memberId`	`number`	群组成员记录 ID，对应 `device_group_member.id`
`groupId`	`number`	所属群组 ID，对应 `device_group.id`
`profileId`	`number`	关联的用户档案 ID，对应 `user_profile.id`
`appUserId`	`number/null`	关联的 APP 账号 ID，对应 `app_user.id`，未关联账号时为 `null`
`status`	`number`	成员状态：`1=正常`，`0=已移除`
`joinTime`	`string`	加入时间
`profileComplete`	`boolean`	用户档案是否已补全设备使用所需资料
`name`	`string`	姓名
`gender`	`number`	性别：`1=男`，`2=女`
`age`	`number`	年龄
`phone`	`string`	手机号
`provinceCode`	`string`	省级行政区划编码
`cityCode`	`string`	市级行政区划编码
`districtCode`	`string`	区/县级行政区划编码
`address`	`string`	详细地址
`shoulderWidth`	`number`	肩宽（cm）
`bodyHeight`	`number`	身长/坐高（cm）
`spineLength`	`number`	C7-S4 脊柱长度（cm）
`height`	`number`	身高（cm）
`weight`	`number`	体重（kg）
`fingerWidth1`	`number`	一寸指宽（cm）
`fingerWidth15`	`number`	1.5 寸指宽（cm）
`fingerWidth3`	`number`	三寸指宽（cm）
`acupointTableId`	`number/null`	已生成的穴位对照表 ID，对应 `user_acupoint.id`
`userCategoryId`	`number/null`	用户分类 ID
`profile`	`object`	嵌套的完整用户档案对象，字段同上

3.14.7 失败返回示例

群组不存在或当前账号无权访问：

{
  "code": 403,
  "message": "无权访问该家庭群组",
  "data": null
}

3.14.8 备注

越权校验在 Service 层完成，仅当 device_group_member.app_user_id = 当前账号ID 且 status = 1 时才返回成员列表。
本接口不返回分页结构，按 joinTime 升序返回所有启用成员。
响应中同时包含扁平化的成员字段和嵌套的 profile 对象，内容一致。
该接口只服务于家庭设备（deviceType=1）对应的群组，公共设备（deviceType=2）没有群组概念。
不会返回 status=0（已移除）的成员记录。

3.15 新增群组成员

3.15.1 接口用途

用于 APP 端让当前登录账号向指定的家庭设备群组添加新成员。

后端校验：

当前 APP 账号必须属于该家庭设备群组（device_group_member.app_user_id = 当前账号ID）
同一群组内手机号不可重复
同一群组内同一 APP 账号不可重复
指宽数据需符合性别对应的合理范围

新增成员时：

若手机号已注册 APP 账号，自动关联已有 APP 账号，并复用其用户档案或在该账号下创建新档案
若手机号未注册，自动创建新 APP 账号和用户档案
自动维护 user_device 绑定记录和 user_acupoint 穴位对照表（档案完整时）

3.15.2 请求信息

请求方式：POST
URI：/api/app/group/{groupId}/members
完整示例：http://localhost:18888/api/app/group/2001/members

3.15.3 请求参数

请求体格式：application/json

参数名	类型	是否必填	说明	示例
`name`	`string`	是	姓名	`李四`
`gender`	`number`	否	性别：`1=男`，`2=女`	`1`
`age`	`number`	否	年龄	`30`
`phone`	`string`	否	手机号（11 位，1[3-9] 开头）；未传时不会关联 APP 账号	`13900139000`
`userCategoryId`	`number`	否	用户分类 ID，对应 `user_category.id`	`1`
`provinceCode`	`string`	否	省级行政区划编码	`440000`
`cityCode`	`string`	否	市级行政区划编码	`440300`
`districtCode`	`string`	否	区/县级行政区划编码	`440305`
`address`	`string`	否	详细地址	`广东省深圳市南山区`
`shoulderWidth`	`number`	否	肩宽（cm）	`42.50`
`bodyHeight`	`number`	否	身长/坐高（cm）	`85.00`
`spineLength`	`number`	否	C7-S4 脊柱长度（cm）	`48.00`
`height`	`number`	否	身高（cm）	`175.00`
`weight`	`number`	否	体重（kg）	`70.00`
`fingerWidth1`	`number`	否	一寸指宽（cm），男 1.5~2.8，女 1.3~2.4	`2.20`
`fingerWidth15`	`number`	否	1.5 寸指宽（cm），男 2.2~4.0，女 2.0~3.5	`3.20`
`fingerWidth3`	`number`	否	三寸指宽（cm），男 4.5~8.0，女 4.0~7.0	`6.50`
`acupointTableId`	`number`	否	已存在的穴位对照表 ID，一般由后端自动生成，无需传入	`null`

3.15.4 调用示例

POST /api/app/group/2001/members HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "李四",
  "gender": 1,
  "age": 30,
  "phone": "13900139000",
  "provinceCode": "440000",
  "cityCode": "440300",
  "districtCode": "440305",
  "address": "广东省深圳市南山区",
  "shoulderWidth": 42.50,
  "bodyHeight": 85.00,
  "spineLength": 48.00,
  "height": 175.00,
  "weight": 70.00,
  "fingerWidth1": 2.20,
  "fingerWidth15": 3.20,
  "fingerWidth3": 6.50
}

curl -X POST "http://localhost:18888/api/app/group/2001/members" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"李四","gender":1,"age":30,"phone":"13900139000","provinceCode":"440000","cityCode":"440300","districtCode":"440305","address":"广东省深圳市南山区","shoulderWidth":42.50,"bodyHeight":85.00,"spineLength":48.00,"height":175.00,"weight":70.00,"fingerWidth1":2.20,"fingerWidth15":3.20,"fingerWidth3":6.50}'

3.15.5 返回示例

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "memberId": 3002,
    "groupId": 2001,
    "profileId": 124,
    "appUserId": 17320687383,
    "status": 1,
    "joinTime": "2026-06-22 10:30:00",
    "profileComplete": true,
    "name": "李四",
    "gender": 1,
    "age": 30,
    "phone": "13900139000",
    "provinceCode": "440000",
    "cityCode": "440300",
    "districtCode": "440305",
    "address": "广东省深圳市南山区",
    "shoulderWidth": 42.50,
    "bodyHeight": 85.00,
    "spineLength": 48.00,
    "height": 175.00,
    "weight": 70.00,
    "fingerWidth1": 2.20,
    "fingerWidth15": 3.20,
    "fingerWidth3": 6.50,
    "acupointTableId": 5002,
    "profileComplete": true
  }
}

3.15.6 失败返回示例

群组不存在或当前账号无权访问：

{
  "code": 403,
  "message": "无权访问该家庭群组",
  "data": null
}

姓名不能为空：

{
  "code": 400,
  "message": "姓名不能为空",
  "data": null
}

手机号格式不正确：

{
  "code": 1108,
  "message": "手机号格式不正确",
  "data": null
}

同一群组内手机号重复：

{
  "code": 1202,
  "message": "同一群组内手机号不能重复",
  "data": null
}

指宽数据超出性别对应范围：

{
  "code": 1203,
  "message": "1寸指宽应在 1.5~2.8 cm 之间",
  "data": null
}

3.15.7 备注

越权校验在 Service 层完成，仅当 device_group_member.app_user_id = 当前账号ID 且 status = 1 时才允许新增。
当 phone 已注册时，后端会自动关联已有 APP 账号；当 phone 未注册时，后端会自动创建新 APP 账号（appId 格式：AJY + 8 位数字）。
当 phone 对应的 APP 账号已存在用户档案时，会复用该档案并更新字段；否则创建新档案。
同一群组内手机号、同一 APP 账号均不可重复。
当新增成员的用户档案完整（name、gender、age、shoulderWidth、bodyHeight、spineLength 都非空）时，后端会自动生成穴位对照表。
后端会自动维护新增成员与群组对应设备的 user_device 绑定记录。
name 字段必填且不可为空字符串。

3.16 修改群组成员

3.16.1 接口用途

用于 APP 端让当前登录账号修改指定家庭设备群组下已有成员的用户档案信息。

后端校验：

当前 APP 账号必须属于该家庭设备群组
profileId 必须是该群组下的有效成员
手机号、APP 账号在同一群组内不能与其他成员冲突
指宽数据需符合性别对应的合理范围

3.16.2 请求信息

请求方式：PUT
URI：/api/app/group/{groupId}/members/{profileId}
完整示例：http://localhost:18888/api/app/group/2001/members/124

3.16.3 请求参数

参数名	类型	是否必填	说明	示例
`groupId`	`number`	是	家庭设备群组 ID，对应 `device_group.id`，通过路径参数传递	`2001`
`profileId`	`number`	是	成员的用户档案 ID，对应 `user_profile.id`，通过路径参数传递	`124`

请求体格式：application/json，字段定义与 3.15.3 节"新增群组成员"完全一致，包括 name（必填）、gender、age、phone、userCategoryId、address、shoulderWidth、bodyHeight、spineLength、height、weight、fingerWidth1、fingerWidth15、fingerWidth3、acupointTableId 等字段。

3.16.4 调用示例

PUT /api/app/group/2001/members/124 HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "李四",
  "gender": 1,
  "age": 31,
  "phone": "13900139000",
  "shoulderWidth": 42.50,
  "bodyHeight": 85.00,
  "spineLength": 48.00,
  "height": 175.00,
  "weight": 71.00,
  "fingerWidth1": 2.20,
  "fingerWidth15": 3.20,
  "fingerWidth3": 6.50
}

curl -X PUT "http://localhost:18888/api/app/group/2001/members/124" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"李四","gender":1,"age":31,"phone":"13900139000","shoulderWidth":42.50,"bodyHeight":85.00,"spineLength":48.00,"height":175.00,"weight":71.00,"fingerWidth1":2.20,"fingerWidth15":3.20,"fingerWidth3":6.50}'

3.16.5 返回示例

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "memberId": 3002,
    "groupId": 2001,
    "profileId": 124,
    "appUserId": 17320687383,
    "status": 1,
    "joinTime": "2026-06-22 10:30:00",
    "profileComplete": true,
    "name": "李四",
    "gender": 1,
    "age": 31,
    "phone": "13900139000",
    "shoulderWidth": 42.50,
    "bodyHeight": 85.00,
    "spineLength": 48.00,
    "height": 175.00,
    "weight": 71.00,
    "fingerWidth1": 2.20,
    "fingerWidth15": 3.20,
    "fingerWidth3": 6.50,
    "acupointTableId": 5002,
    "profileComplete": true
  }
}

3.16.6 失败返回示例

群组不存在或当前账号无权访问：

{
  "code": 403,
  "message": "无权访问该家庭群组",
  "data": null
}

成员不存在：

{
  "code": 1200,
  "message": "子用户不存在",
  "data": null
}

手机号格式不正确：

{
  "code": 1108,
  "message": "手机号格式不正确",
  "data": null
}

手机号与其他成员冲突：

{
  "code": 1202,
  "message": "同一群组内手机号不能重复",
  "data": null
}

指宽数据超出性别对应范围：

{
  "code": 1203,
  "message": "1.5寸指宽应在 2.2~4.0 cm 之间",
  "data": null
}

3.16.7 备注

越权校验在 Service 层完成，仅当 device_group_member.app_user_id = 当前账号ID 且 status = 1 时才允许修改。
请求体字段语义与 3.15 节"新增群组成员"完全一致，区别在于"修改"语义：未传字段会以"覆盖式"方式写入数据库（null 即清空）。
修改手机号时若该手机号已注册 APP 账号，会自动关联；未注册则保持原关联或自动创建。
修改 phone 字段后，会同步更新 device_group_member.app_user_id。
当修改后档案完整时，后端会自动重新生成穴位对照表。
后端会自动维护成员与群组对应设备的 user_device 绑定记录。
name 字段必填。

3.17 删除群组成员

3.17.1 接口用途

用于 APP 端让当前登录账号从指定的家庭设备群组中移除成员。

后端校验：

当前 APP 账号必须属于该家庭设备群组
profileId 必须是该群组下的有效成员
禁止删除当前账号自身的成员记录（避免误操作把自己移除出群组）

删除采用软删除方式：将 device_group_member.status 置为 0，保留历史数据。

3.17.2 请求信息

请求方式：DELETE
URI：/api/app/group/{groupId}/members/{profileId}
完整示例：http://localhost:18888/api/app/group/2001/members/124

3.17.3 请求参数

参数名	类型	是否必填	说明	示例
`groupId`	`number`	是	家庭设备群组 ID，对应 `device_group.id`，通过路径参数传递	`2001`
`profileId`	`number`	是	待移除成员的用户档案 ID，对应 `user_profile.id`，通过路径参数传递	`124`

3.17.4 调用示例

DELETE /api/app/group/2001/members/124 HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>

curl -X DELETE "http://localhost:18888/api/app/group/2001/members/124" \
  -H "Authorization: Bearer <token>"

3.17.5 返回示例

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

3.17.6 失败返回示例

群组不存在或当前账号无权访问：

{
  "code": 403,
  "message": "无权访问该家庭群组",
  "data": null
}

成员不存在：

{
  "code": 1200,
  "message": "子用户不存在",
  "data": null
}

尝试删除自身成员记录：

{
  "code": 403,
  "message": "不能移除当前账号在群组中的成员记录",
  "data": null
}

3.17.7 备注

越权校验在 Service 层完成，仅当 device_group_member.app_user_id = 当前账号ID 且 status = 1 时才允许删除。
禁止删除 app_user_id = 当前账号ID 的成员记录，避免误操作把当前账号从群组中移除。
删除为软删除（status = 0），不会物理删除 device_group_member 表记录，便于审计和恢复。
删除后该成员将不再出现在"查询群组成员列表"接口（3.14 节）的返回结果中。
本接口不会级联删除用户的 user_profile 档案或 user_device 绑定记录；如需彻底清理用户档案，请使用其他档案管理接口。
已删除的成员记录若需要重新加入群组，请使用"新增群组成员"接口（3.15 节）重新创建。

3.18 查询当前账号个人资料

3.18.1 接口用途

用于 APP 端通过 Token 获取当前登录 APP 账号对应的个人资料。

后端从 Token 中解析当前账号 ID，若该账号下尚无用户档案，会自动创建一份空档案（app_user_id = 当前账号ID），并将该账号昵称、手机号写入档案，保证 APP 端"我的资料"页面始终有数据可展示。

本接口不区分家庭设备和公共设备，所有登录后的 APP 账号均可调用。

3.18.2 请求信息

请求方式：GET
URI：/api/app/user/profile
完整示例：http://localhost:18888/api/app/user/profile

3.18.3 请求参数

无路径参数、无查询参数、无请求体。请求头需携带登录后的 Token。

3.18.4 调用示例

GET /api/app/user/profile HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>

curl -X GET "http://localhost:18888/api/app/user/profile" \
  -H "Authorization: Bearer <token>"

3.18.5 返回示例

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "userId": 17320687382,
    "appUserId": 17320687382,
    "profileId": 123,
    "id": 123,
    "nickname": "张三",
    "avatar": "https://cdn.example.com/avatar/17320687382.png",
    "appId": "AJY00000001",
    "accountPhone": "13800138000",
    "phone": "13800138000",
    "name": "张三",
    "gender": 1,
    "age": 35,
    "provinceCode": "440000",
    "cityCode": "440300",
    "districtCode": "440305",
    "address": "广东省深圳市南山区",
    "shoulderWidth": 42.50,
    "bodyHeight": 85.00,
    "spineLength": 48.00,
    "height": 175.00,
    "weight": 70.00,
    "fingerWidth1": 2.20,
    "fingerWidth15": 3.20,
    "fingerWidth3": 6.50,
    "acupointTableId": 5001,
    "userCategoryId": 1,
    "profileComplete": true
  }
}

3.18.6 字段说明

字段名	类型	说明
`userId`	`number`	当前 APP 账号 ID，对应 `app_user.id`（同 `appUserId`）
`appUserId`	`number`	当前 APP 账号 ID，对应 `app_user.id`
`profileId`	`number`	用户档案 ID，对应 `user_profile.id`（同 `id`）
`id`	`number`	用户档案 ID，对应 `user_profile.id`
`nickname`	`string`	APP 账号昵称，对应 `app_user.nickname`
`avatar`	`string`	APP 账号头像 URL，对应 `app_user.avatar`
`appId`	`string`	APP 账号的 AppId，对应 `app_user.app_id`
`accountPhone`	`string`	APP 账号手机号，对应 `app_user.phone`
`phone`	`string`	用户档案手机号，对应 `user_profile.phone`（与 `accountPhone` 通常一致）
`name`	`string`	姓名
`gender`	`number/null`	性别：`1=男`，`2=女`
`age`	`number/null`	年龄
`provinceCode`	`string/null`	省级行政区划编码
`cityCode`	`string/null`	市级行政区划编码
`districtCode`	`string/null`	区/县级行政区划编码
`address`	`string/null`	详细地址
`shoulderWidth`	`number/null`	肩宽（cm）
`bodyHeight`	`number/null`	身长/坐高（cm）
`spineLength`	`number/null`	C7-S4 脊柱长度（cm）
`height`	`number/null`	身高（cm）
`weight`	`number/null`	体重（kg）
`fingerWidth1`	`number/null`	一寸指宽（cm），男 1.5~2.8，女 1.3~2.4
`fingerWidth15`	`number/null`	1.5 寸指宽（cm），男 2.2~4.0，女 2.0~3.5
`fingerWidth3`	`number/null`	三寸指宽（cm），男 4.5~8.0，女 4.0~7.0
`acupointTableId`	`number/null`	已生成的穴位对照表 ID，对应 `user_acupoint.id`
`userCategoryId`	`number/null`	用户分类 ID，对应 `user_category.id`
`profileComplete`	`boolean`	用户档案是否已补全设备使用所需资料（`name`/`gender`/`age`/`shoulderWidth`/`bodyHeight`/`spineLength` 均已填写）

3.18.7 失败返回示例

未登录或 Token 无效：

{
  "code": 401,
  "message": "请先登录",
  "data": null
}

APP 账号不存在或已禁用：

{
  "code": 1302,
  "message": "APP账号不存在",
  "data": null
}

3.18.8 备注

本接口不接受任何参数，仅通过 Token 识别当前账号；不允许通过 userId、appUserId、profileId 等参数指定他人档案。
若当前账号下无用户档案（user_profile），后端会自动创建一份以 app_user_id 关联的空档案，保证返回数据完整。
响应中 profileId 与 id 内容一致，便于前端按不同字段名取值。
该接口与"修改个人资料"（3.19 节）配套使用，修改后建议重新调用本接口刷新页面数据。

3.19 修改当前账号个人资料

3.19.1 接口用途

用于 APP 端通过 Token 修改当前登录 APP 账号对应的个人资料。

后端逻辑：

nickname、avatar 字段会更新到 app_user 表
其余字段（name、gender、age、phone、省市区/地址、肩宽、身长、脊柱长、身高、体重、指宽等）会更新到当前账号对应的 user_profile 表
若当前账号下尚无用户档案，后端会自动创建一份
修改后若档案已补全（name/gender/age/shoulderWidth/bodyHeight/spineLength 均已填写），会自动重新生成穴位对照表

本接口不区分家庭设备和公共设备，所有登录后的 APP 账号均可调用，是用户在公共设备场景下修改自己资料的主入口。

3.19.2 请求信息

请求方式：PUT
URI：/api/app/user/profile
完整示例：http://localhost:18888/api/app/user/profile

3.19.3 请求参数

请求体格式：application/json

参数名	类型	是否必填	说明	示例
`nickname`	`string`	否	APP 账号昵称，传空字符串视为不更新	`张三`
`avatar`	`string`	否	APP 账号头像 URL，传空字符串视为不更新	`https://cdn.example.com/avatar/xxx.png`
`name`	`string`	否	姓名，传空字符串视为不更新	`张三`
`gender`	`number`	否	性别：`1=男`，`2=女`	`1`
`age`	`number`	否	年龄	`35`
`phone`	`string`	否	手机号（11 位，1[3-9] 开头），传空字符串视为不更新	`13800138000`
`userCategoryId`	`number`	否	用户分类 ID，对应 `user_category.id`	`1`
`provinceCode`	`string/null`	否	省级行政区划编码	`440000`
`cityCode`	`string/null`	否	市级行政区划编码	`440300`
`districtCode`	`string/null`	否	区/县级行政区划编码	`440305`
`address`	`string/null`	否	详细地址	`广东省深圳市南山区`
`shoulderWidth`	`number/null`	否	肩宽（cm）	`42.50`
`bodyHeight`	`number/null`	否	身长/坐高（cm）	`85.00`
`spineLength`	`number/null`	否	C7-S4 脊柱长度（cm）	`48.00`
`height`	`number/null`	否	身高（cm）	`175.00`
`weight`	`number/null`	否	体重（kg）	`70.00`
`fingerWidth1`	`number/null`	否	一寸指宽（cm），男 1.5~2.8，女 1.3~2.4	`2.20`
`fingerWidth15`	`number/null`	否	1.5 寸指宽（cm），男 2.2~4.0，女 2.0~3.5	`3.20`
`fingerWidth3`	`number/null`	否	三寸指宽（cm），男 4.5~8.0，女 4.0~7.0	`6.50`
`acupointTableId`	`number/null`	否	已存在的穴位对照表 ID，一般由后端自动生成，无需传入	`null`

3.19.4 调用示例

PUT /api/app/user/profile HTTP/1.1
Host: localhost:18888
Authorization: Bearer <token>
Content-Type: application/json

{
  "nickname": "张三",
  "avatar": "https://cdn.example.com/avatar/17320687382.png",
  "name": "张三",
  "gender": 1,
  "age": 35,
  "phone": "13800138000",
  "provinceCode": "440000",
  "cityCode": "440300",
  "districtCode": "440305",
  "address": "广东省深圳市南山区",
  "shoulderWidth": 42.50,
  "bodyHeight": 85.00,
  "spineLength": 48.00,
  "height": 175.00,
  "weight": 70.00,
  "fingerWidth1": 2.20,
  "fingerWidth15": 3.20,
  "fingerWidth3": 6.50
}

curl -X PUT "http://localhost:18888/api/app/user/profile" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"nickname":"张三","avatar":"https://cdn.example.com/avatar/17320687382.png","name":"张三","gender":1,"age":35,"phone":"13800138000","shoulderWidth":42.50,"bodyHeight":85.00,"spineLength":48.00,"height":175.00,"weight":70.00,"fingerWidth1":2.20,"fingerWidth15":3.20,"fingerWidth3":6.50}'

3.19.5 返回示例

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "userId": 17320687382,
    "appUserId": 17320687382,
    "profileId": 123,
    "id": 123,
    "nickname": "张三",
    "avatar": "https://cdn.example.com/avatar/17320687382.png",
    "appId": "AJY00000001",
    "accountPhone": "13800138000",
    "phone": "13800138000",
    "name": "张三",
    "gender": 1,
    "age": 35,
    "provinceCode": "440000",
    "cityCode": "440300",
    "districtCode": "440305",
    "address": "广东省深圳市南山区",
    "shoulderWidth": 42.50,
    "bodyHeight": 85.00,
    "spineLength": 48.00,
    "height": 175.00,
    "weight": 70.00,
    "fingerWidth1": 2.20,
    "fingerWidth15": 3.20,
    "fingerWidth3": 6.50,
    "acupointTableId": 5001,
    "userCategoryId": 1,
    "profileComplete": true
  }
}

3.19.6 失败返回示例

未登录或 Token 无效：

{
  "code": 401,
  "message": "请先登录",
  "data": null
}

APP 账号不存在或已禁用：

{
  "code": 1302,
  "message": "APP账号不存在",
  "data": null
}

手机号格式不正确：

{
  "code": 1108,
  "message": "手机号格式不正确",
  "data": null
}

指宽数据超出性别对应范围：

{
  "code": 1203,
  "message": "1.5寸指宽应在 2.2~4.0 cm 之间",
  "data": null
}

3.19.7 备注

本接口不接受路径参数与查询参数，仅通过 Token 识别当前账号；不允许通过 userId/appUserId/profileId 等参数修改他人档案。
该接口与"修改群组成员"（3.16 节）的区别：
- 3.16 节需要 groupId + profileId，仅服务家庭设备群组，用于在群组维度编辑成员资料；
- 3.19 节只需要 Token，同时适用于家庭设备和公共设备，用于当前账号修改自己的资料；
- 公共设备场景下不能调用 3.16 节（无 groupId），应改用本接口。
字段更新语义：
- nickname / avatar：仅在传入非空字符串时更新到 app_user 表；
- 其余字段：仅在传入非 null 时更新到 user_profile 表（phone 还会进行手机号格式校验）。
当修改后档案完整时（name/gender/age/shoulderWidth/bodyHeight/spineLength 均已填写），后端会自动重新生成穴位对照表。
不会影响 device_group 或 user_device 绑定关系，仅修改账号与档案自身数据。
与"查询个人资料"（3.18 节）配套使用，修改成功后可直接复用返回结果刷新页面。

app对接接口说明.md 78 KB Trvalý odkaz Historie Surový

APP 对接接口说明

1. 文档说明

2. 接口目录

3. 接口详情

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

3.1.1 接口用途

3.1.2 请求信息

3.1.3 请求参数

3.1.4 调用示例

3.1.5 返回示例

3.1.6 字段说明

3.1.7 备注

3.2 查询当前账号下的设备列表

3.2.1 接口用途

3.2.2 请求信息

3.2.3 请求参数

3.2.4 调用示例

3.2.5 返回示例

3.2.6 字段说明

3.2.7 备注

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

3.3.1 接口用途

3.3.2 请求信息

3.3.3 请求参数

3.3.4 调用示例

3.3.5 成功返回示例

3.3.6 失败返回示例

3.3.7 备注

3.4 APP 端查询设备详情

3.4.1 接口用途

3.4.2 请求信息

3.4.3 请求参数

3.4.4 调用示例

3.4.5 返回示例

3.4.6 字段说明

3.4.7 失败返回示例

3.4.8 备注

3.5 新增用户自定义方案

3.5.1 接口用途

3.5.2 请求信息

3.5.3 请求参数

3.5.4 调用示例

3.5.5 返回示例

3.5.6 失败返回示例

3.5.7 备注

3.6 查询当前用户的自定义方案列表

3.6.1 接口用途

3.6.2 请求信息

3.6.3 请求参数

3.6.4 调用示例

3.6.5 返回示例

3.6.6 字段说明

3.6.7 备注

3.7 查询用户自定义方案详情

3.7.1 接口用途

3.7.2 请求信息

3.7.3 请求参数

3.7.4 调用示例

3.7.5 返回示例

3.7.6 字段说明

3.7.7 失败返回示例

3.7.8 备注

3.8 查询专业模式方案列表

3.8.1 接口用途

3.8.2 请求信息

3.8.3 请求参数

3.8.4 调用示例

3.8.5 返回示例

3.8.6 字段说明

3.8.7 备注

3.9 查询专业模式方案详情

3.9.1 接口用途

3.9.2 请求信息

3.9.3 请求参数

3.9.4 调用示例

3.9.5 返回示例

3.9.6 字段说明

3.9.7 失败返回示例

3.9.8 备注

app对接接口说明.md 78 KB

Trvalý odkaz Historie Surový