用户设备 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 认证方式 |
| 500 | Failed to fetch devices | 查询失败 |
| 500 | Internal server error | 服务端错误 |
2. 更新设备昵称
PATCH /user/devices/:id更新用户设备的昵称。
认证方式：仅 JWT
路径参数：
| 参数 | 说明 |
|---|---|
id | 设备 ID |
请求体：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
nickname | string | 是 | 新昵称（空字符串清空昵称，最长 50 字符） |
响应 200 OK：
json
{
"success": true,
"device": {
"id": "uuid",
"nickname": "新昵称"
}
}错误码：
| HTTP | 错误 | 说明 |
|---|---|---|
| 400 | nickname 是必填项 | 未提供 nickname |
| 400 | 昵称不能超过 50 个字符 | 昵称过长 |
| 403 | 仅支持 JWT 认证 | 使用了非 JWT 认证方式 |
| 404 | 设备不存在或无权访问 | 设备不存在或不属于当前用户 |
| 500 | Failed to update device | 更新失败 |
| 500 | Internal 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 | 错误 | 说明 |
|---|---|---|
| 500 | Failed to fetch bluetooth filters | 查询失败 |
| 500 | Internal 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 认证方式 |
| 500 | Failed to verify device | 查询失败 |
| 500 | Internal server error | 服务端错误 |
5. 绑定蓝牙设备
POST /user/devices/bind通过蓝牙名自动匹配产品型号并绑定设备。如需库存校验，会检查 hw_inventory 表。
认证方式：仅 JWT
请求体：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
hardware_id | string | 是 | 设备硬件 ID（最长 100 字符） |
bluetooth_name | string | 是 | 蓝牙设备名（最长 100 字符） |
nickname | string | 否 | 设备昵称 |
响应 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 | 错误码 | 说明 |
|---|---|---|
| 400 | hardware_id 和 bluetooth_name 是必填项 | 缺少必填字段 |
| 400 | hardware_id 或 bluetooth_name 长度超出限制 | 字段超长 |
| 400 | UNKNOWN_DEVICE | 无法识别的设备型号（蓝牙名不匹配任何产品） |
| 403 | 仅支持 JWT 认证 | 使用了非 JWT 认证方式 |
| 403 | NOT_IN_INVENTORY | 设备未在系统中注册（需库存校验的型号） |
| 409 | ALREADY_BOUND_SELF | 当前用户已绑定此设备 |
| 409 | ALREADY_BOUND | 设备已被其他用户绑定 |
| 500 | Failed to bind device | 绑定失败 |
| 500 | Internal server error | 服务端错误 |
6. 解绑设备
DELETE /user/devices/:id解绑用户设备（软删除：设置 is_active = false），同时清除库存绑定关系。
认证方式：仅 JWT
路径参数：
| 参数 | 说明 |
|---|---|
id | 设备 ID |
响应 200 OK：
json
{
"success": true
}错误码：
| HTTP | 错误 | 说明 |
|---|---|---|
| 403 | 仅支持 JWT 认证 | 使用了非 JWT 认证方式 |
| 404 | 设备不存在或无权访问 | 设备不存在或不属于当前用户 |
| 500 | Failed to unbind device | 解绑失败 |
| 500 | Internal server error | 服务端错误 |