WaiNao.AI

主题

用户设备 API ​

用户硬件设备管理接口，支持蓝牙设备的绑定、解绑、昵称修改等操作。

路由前缀：/user/devices

源码：apps/backend/src/routes/user/devices.ts

认证 ​

所有接口需要组合认证（JWT 或 API Key），但大部分端点仅支持 JWT 认证：

Authorization: Bearer <JWT>

端点 ​

1. 获取设备列表 ​

GET /user/devices

获取当前用户的所有活跃设备，包含产品型号和品牌信息。自动计算在线状态（5 分钟内有上报视为在线）。

认证方式：仅 JWT

响应 200 OK：

json
{
  "success": true,
  "devices": [
    {
      "id": "uuid",
      "nickname": "我的设备",
      "hardware_id": "HW-001",
      "bluetooth_name": "WN-Device-001",
      "last_online_at": "2026-03-07T10:00:00.000Z",
      "last_battery_level": 85,
      "last_signal_strength": -60,
      "created_at": "2026-03-01T00:00:00.000Z",
      "product_model": {
        "id": "uuid",
        "name": "WaiNao Device Pro",
        "cover_image_url": "https://example.com/image.jpg",
        "brand": {
          "id": "uuid",
          "name": "WaiNao"
        }
      },
      "is_online": true
    }
  ]
}

错误码：

HTTP错误说明
403仅支持 JWT 认证使用了非 JWT 认证方式
500Failed to fetch devices查询失败
500Internal server error服务端错误

2. 更新设备昵称 ​

PATCH /user/devices/:id

更新用户设备的昵称。

认证方式：仅 JWT

路径参数：

参数说明
id设备 ID

请求体：

字段类型必填说明
nicknamestring是新昵称（空字符串清空昵称，最长 50 字符）

响应 200 OK：

json
{
  "success": true,
  "device": {
    "id": "uuid",
    "nickname": "新昵称"
  }
}

错误码：

HTTP错误说明
400nickname 是必填项未提供 nickname
400昵称不能超过 50 个字符昵称过长
403仅支持 JWT 认证使用了非 JWT 认证方式
404设备不存在或无权访问设备不存在或不属于当前用户
500Failed to update device更新失败
500Internal server error服务端错误

3. 获取蓝牙过滤规则 ​

GET /user/devices/bluetooth-filters

获取蓝牙设备名前缀过滤规则，用于前端扫描蓝牙设备时过滤。从 hw_product_models 读取活跃型号的蓝牙前缀。

认证方式：JWT 或 API Key

响应 200 OK：

json
{
  "success": true,
  "filters": [
    {
      "namePrefix": "WN-",
      "productModelId": "uuid",
      "modelName": "WaiNao Device Pro",
      "requiresInventoryCheck": false
    }
  ]
}

错误码：

HTTP错误说明
500Failed to fetch bluetooth filters查询失败
500Internal server error服务端错误

4. 验证设备硬件 ID ​

GET /user/devices/verify/:hardwareId

查询设备的库存及绑定状态，用于绑定前的前置检查。

认证方式：仅 JWT

路径参数：

参数说明
hardwareId设备硬件 ID

响应 200 OK：

json
{
  "success": true,
  "inInventory": true,
  "bound": false,
  "boundBySelf": false,
  "productModel": {
    "id": "uuid",
    "name": "WaiNao Device Pro",
    "cover_image_url": "https://example.com/image.jpg"
  }
}
字段说明
inInventory设备是否在库存中
bound设备是否已被任何用户绑定
boundBySelf设备是否已被当前用户绑定
productModel产品型号信息（仅库存中存在时返回）

错误码：

HTTP错误说明
403仅支持 JWT 认证使用了非 JWT 认证方式
500Failed to verify device查询失败
500Internal server error服务端错误

5. 绑定蓝牙设备 ​

POST /user/devices/bind

通过蓝牙名自动匹配产品型号并绑定设备。如需库存校验，会检查 hw_inventory 表。

认证方式：仅 JWT

请求体：

字段类型必填说明
hardware_idstring是设备硬件 ID（最长 100 字符）
bluetooth_namestring是蓝牙设备名（最长 100 字符）
nicknamestring否设备昵称

响应 200 OK：

json
{
  "success": true,
  "device": {
    "id": "uuid",
    "nickname": "我的设备",
    "hardware_id": "HW-001",
    "bluetooth_name": "WN-Device-001",
    "created_at": "2026-03-07T10:00:00.000Z",
    "product_model": {
      "id": "uuid",
      "name": "WaiNao Device Pro",
      "cover_image_url": "https://example.com/image.jpg",
      "brand": {
        "id": "uuid",
        "name": "WaiNao"
      }
    },
    "is_online": false
  }
}

错误码：

HTTP错误码说明
400hardware_id 和 bluetooth_name 是必填项缺少必填字段
400hardware_id 或 bluetooth_name 长度超出限制字段超长
400UNKNOWN_DEVICE无法识别的设备型号（蓝牙名不匹配任何产品）
403仅支持 JWT 认证使用了非 JWT 认证方式
403NOT_IN_INVENTORY设备未在系统中注册（需库存校验的型号）
409ALREADY_BOUND_SELF当前用户已绑定此设备
409ALREADY_BOUND设备已被其他用户绑定
500Failed to bind device绑定失败
500Internal server error服务端错误

6. 解绑设备 ​

DELETE /user/devices/:id

解绑用户设备（软删除：设置 is_active = false），同时清除库存绑定关系。

认证方式：仅 JWT

路径参数：

参数说明
id设备 ID

响应 200 OK：

json
{
  "success": true
}

错误码：

HTTP错误说明
403仅支持 JWT 认证使用了非 JWT 认证方式
404设备不存在或无权访问设备不存在或不属于当前用户
500Failed to unbind device解绑失败
500Internal server error服务端错误

补充端点 ​

本节补充 plans/need-update-api.md 中尚未覆盖到 docs-site 的接口。端点标题保持严格的 METHOD /path 格式，便于后台文档覆盖率服务识别。

POST /user/devices/:deviceId/device-token ​

签发设备 token（明文一次性返回）

认证：JWT Bearer Token；设备 token 仅一次性返回。 路径参数

参数说明
deviceId用户设备 ID

请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

DELETE /user/devices/:deviceId/device-token ​

撤销设备 token

认证：JWT Bearer Token；设备 token 仅一次性返回。 路径参数

参数说明
deviceId用户设备 ID

请求：通常无请求体；删除类接口通过路径参数定位资源，部分接口会执行软删除、释放绑定或撤回流程。

响应：成功时返回 { "success": true } 或等价删除结果；资源不存在、无权限或存在依赖时返回 4xx。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

GET /user/devices/:deviceId/subdomain ​

查询设备子域名绑定

认证：JWT Bearer Token；设备 token 仅一次性返回。 路径参数

参数说明
deviceId用户设备 ID

请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。

响应：成功时返回目标资源详情、状态或配置对象。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

POST /user/devices/:deviceId/subdomain ​

为设备申请子域名（不收 IP，等首次心跳）

认证：JWT Bearer Token；设备 token 仅一次性返回。 路径参数

参数说明
deviceId用户设备 ID

请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

DELETE /user/devices/:deviceId/subdomain ​

释放设备子域名（tombstone 流程）

认证：JWT Bearer Token；设备 token 仅一次性返回。 路径参数

参数说明
deviceId用户设备 ID

请求：通常无请求体；删除类接口通过路径参数定位资源，部分接口会执行软删除、释放绑定或撤回流程。

响应：成功时返回 { "success": true } 或等价删除结果；资源不存在、无权限或存在依赖时返回 4xx。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

AI Workflow Editor

Copyright 2024-present WaiNao.AI