Guoguo
0feb900a1d
- 01-快速开始: local setup for all 3 modules, common issues - 02-配置说明: all env vars, WeChat/Pay/DB/COS config details - 03-架构说明: system overview, directory structure, data flows - 04-部署指南: Tencent Cloud SCF/COS deployment, launch checklist - 05-API接口文档: all 42 endpoints with params and response format - README index with audience guide and quick links
1298 行
31 KiB
Markdown
1298 行
31 KiB
Markdown
# API 接口文档
|
||
|
||
本文档列出 jw-beauty 后端所有 API 接口，供前端开发和调试参考。
|
||
|
||
**Base URL**: `https://api.vsai.net.cn`
|
||
|
||
---
|
||
|
||
## 通用约定
|
||
|
||
### 认证方式
|
||
|
||
需要认证的接口在请求头中携带 JWT：
|
||
|
||
```
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
- `requireUser`：需要用户 Token（通过 `/auth/login` 获取）
|
||
- `requireAdmin`：需要管理员 Token（通过 `/admin/login` 获取）
|
||
|
||
### 响应格式
|
||
|
||
所有接口返回统一 JSON 结构：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
| code | 含义 |
|
||
|------|------|
|
||
| 0 | 成功 |
|
||
| 1001 | Token 无效或过期 |
|
||
| 1002 | 管理员未授权 |
|
||
| 1004 | 用户不存在 |
|
||
| 1005 | 设备/记录不存在 |
|
||
| 1006 | 设备未绑定 |
|
||
| 2001 | 参数错误或业务限制 |
|
||
| 3001 | 服务端错误 |
|
||
|
||
### 公共请求头
|
||
|
||
| Header | 说明 |
|
||
|--------|------|
|
||
| `Authorization` | Bearer Token |
|
||
| `Content-Type` | `application/json`（除文件上传外） |
|
||
| `X-Device-Id` | 设备标识（可选） |
|
||
| `X-App-Version` | 应用版本号（可选） |
|
||
| `X-Platform` | 平台标识（可选） |
|
||
|
||
### 分页参数
|
||
|
||
支持分页的列表接口统一使用：
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `page` | number | 1 | 页码（从 1 开始） |
|
||
| `page_size` | number | 20 | 每页条数（最大 100） |
|
||
|
||
### Rate Limiting
|
||
|
||
| 路径 | 限制 |
|
||
|------|------|
|
||
| `POST /api/v1/auth/login` | 15 分钟内最多 10 次 |
|
||
| `POST /api/v1/admin/login` | 15 分钟内最多 5 次 |
|
||
| `POST /api/v1/user/avatar` | 15 分钟内最多 20 次 |
|
||
| `POST /api/v1/user/phone` | 15 分钟内最多 20 次 |
|
||
|
||
---
|
||
|
||
## 健康检查
|
||
|
||
### `GET /health`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | 无 |
|
||
| 说明 | 健康检查，用于部署验证和监控 |
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{ "code": 0, "message": "success", "data": { "status": "ok" } }
|
||
```
|
||
|
||
---
|
||
|
||
## 1. 认证模块
|
||
|
||
### 1.1 `POST /api/v1/auth/login`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | 无 |
|
||
| 说明 | 微信小程序登录。维护模式下拒绝登录。新用户自动注册。 |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `code` | string | 是 | `wx.login()` 返回的临时登录凭证 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `token` | string | JWT Token |
|
||
| `user_id` | string | 用户 ID |
|
||
| `is_new_user` | boolean | 是否新注册用户 |
|
||
| `user_info` | object | 用户基本信息 |
|
||
| `user_info.nickname` | string | 昵称 |
|
||
| `user_info.avatar` | string | 头像 URL |
|
||
| `user_info.phone` | string | 手机号 |
|
||
| `user_info.gender` | number | 性别（0=未知） |
|
||
| `expires_in` | number | Token 有效期（秒），固定 604800（7天） |
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"token": "eyJhbGci...",
|
||
"user_id": "1",
|
||
"is_new_user": false,
|
||
"user_info": {
|
||
"user_id": "1",
|
||
"nickname": "用户1",
|
||
"avatar": "",
|
||
"phone": "",
|
||
"gender": 0
|
||
},
|
||
"expires_in": 604800
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 1.2 `POST /api/v1/auth/refresh`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | Bearer Token（可过期不超过 1 天） |
|
||
| 说明 | 刷新用户 Token。Token 未过期且剩余有效期超过 7 天时原样返回。 |
|
||
|
||
**请求 Body**：无
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `token` | string | 新 Token（或原 Token） |
|
||
| `expires_in` | number | 有效期（秒） |
|
||
|
||
---
|
||
|
||
## 2. 用户模块
|
||
|
||
### 2.1 `GET /api/v1/user/profile`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 说明 | 获取当前用户资料 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `user_id` | string | 用户 ID |
|
||
| `nickname` | string | 昵称 |
|
||
| `avatar` | string | 头像 URL |
|
||
| `phone` | string | 手机号 |
|
||
| `gender` | number | 性别 |
|
||
| `bind_time` | null | 保留字段 |
|
||
| `device_count` | number | 已绑定设备数量 |
|
||
|
||
---
|
||
|
||
### 2.2 `PUT /api/v1/user/profile`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 说明 | 更新用户资料 |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `nickname` | string | 否 | 昵称 |
|
||
| `avatar` | string | 否 | 头像 URL（也接受 `avatar_url`） |
|
||
| `gender` | number | 否 | 性别 |
|
||
|
||
**响应 `data`**：
|
||
|
||
```json
|
||
{ "message": "success" }
|
||
```
|
||
|
||
---
|
||
|
||
### 2.3 `POST /api/v1/user/avatar`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| Content-Type | `multipart/form-data` |
|
||
| 说明 | 上传头像图片到 COS。限制 2MB，仅支持 jpg/png/gif/webp。 |
|
||
|
||
**请求**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `file` | file | 是 | 图片文件 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `avatar` | string | COS CDN 头像 URL |
|
||
|
||
---
|
||
|
||
### 2.4 `POST /api/v1/user/phone`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 说明 | 微信手机号授权绑定 |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `code` | string | 是 | 微信 `getPhoneNumber` 返回的 code |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `phone` | string | 完整手机号（带区号） |
|
||
| `pure_phone_number` | string | 不带区号的手机号 |
|
||
| `country_code` | string | 国家区号 |
|
||
|
||
---
|
||
|
||
## 3. 设备模块
|
||
|
||
### 3.1 `POST /api/v1/device/bind`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 说明 | 申请绑定设备。每个用户同时只能绑定一台设备。设备绑定功能可通过系统设置关闭。 |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `device_id` | string | 是 | 设备 ID（产品码） |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `device_id` | string | 设备 ID |
|
||
| `bind_token` | string | 绑定令牌（16 字符 hex），用于确认绑定 |
|
||
| `subscription` | object | 当前订阅状态 |
|
||
| `subscription.plan` | string | 订阅计划（none/trial/monthly/yearly） |
|
||
| `subscription.remaining_days` | number | 剩余天数 |
|
||
|
||
---
|
||
|
||
### 3.2 `POST /api/v1/device/bind/confirm`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 说明 | 确认绑定设备（蓝牙握手成功后调用） |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `device_id` | string | 是 | 设备 ID |
|
||
| `bind_token` | string | 是 | 绑定令牌 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `message` | string | "success" |
|
||
| `subscription` | object | 当前订阅状态 |
|
||
|
||
---
|
||
|
||
### 3.3 `POST /api/v1/device/mock-bind`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 环境 | 仅非 production 环境可用 |
|
||
| 说明 | 模拟绑定设备，跳过蓝牙确认流程。用于开发调试。 |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `device_id` | string | 是 | 设备 ID |
|
||
|
||
**响应 `data`**：
|
||
|
||
```json
|
||
{ "message": "success", "device_id": "DEV001" }
|
||
```
|
||
|
||
---
|
||
|
||
### 3.4 `POST /api/v1/device/unbind`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 说明 | 解绑设备 |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `device_id` | string | 否 | 指定设备 ID，不传则解绑当前设备 |
|
||
|
||
**响应 `data`**：
|
||
|
||
```json
|
||
{ "message": "success" }
|
||
```
|
||
|
||
---
|
||
|
||
### 3.5 `GET /api/v1/device/list`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 说明 | 获取当前用户的设备列表 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `devices` | array | 设备列表 |
|
||
| `total` | number | 设备数量 |
|
||
|
||
---
|
||
|
||
### 3.6 `GET /api/v1/device/:device_id`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 说明 | 获取已绑定设备详情。只能查看自己绑定的设备。 |
|
||
|
||
**路径参数**：
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `device_id` | 设备 ID |
|
||
|
||
**响应 `data`**：设备详情对象（含 device_id, device_name, firmware_version, battery, temperature 等）
|
||
|
||
---
|
||
|
||
### 3.7 `GET /api/v1/device/command/pending`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 说明 | 拉取设备待执行的远程指令。拉取后指令标记为已推送。 |
|
||
|
||
**Query 参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `device_id` | string | 是 | 设备 ID |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `commands` | array | 指令列表 |
|
||
| `commands[].seq` | number | 指令序号（command_id） |
|
||
| `commands[].opcode` | number | 操作码 |
|
||
| `commands[].payload` | object | 指令参数 |
|
||
|
||
---
|
||
|
||
### 3.8 `POST /api/v1/device/command/result`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 说明 | 上报指令执行结果 |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `command_id` 或 `seq` | number | 是 | 指令 ID |
|
||
| `success` | boolean | 否 | 是否成功，默认 true |
|
||
|
||
**响应 `data`**：
|
||
|
||
```json
|
||
{ "message": "success" }
|
||
```
|
||
|
||
---
|
||
|
||
### 3.9 `POST /api/v1/device/event`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 说明 | 上报设备事件（错误、温度异常等） |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `device_id` | string | 是 | 设备 ID |
|
||
| `event_type` | string | 否 | 事件类型，默认 `device_error` |
|
||
| `error_code` | number | 否 | 错误码 |
|
||
| `temperature` | number | 否 | 温度 |
|
||
|
||
**响应 `data`**：
|
||
|
||
```json
|
||
{ "message": "ok" }
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 订阅模块
|
||
|
||
### 4.1 `GET /api/v1/subscription/plans`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | 无 |
|
||
| 说明 | 获取可用订阅计划列表。价格和试用天数从系统设置读取。 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `plans` | array | 计划列表 |
|
||
| `plans[].key` | string | 计划标识（monthly/yearly/trial） |
|
||
| `plans[].name` | string | 名称（月卡/年卡/试用） |
|
||
| `plans[].price` | number | 价格（分） |
|
||
| `plans[].days` | number | 有效天数 |
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"plans": [
|
||
{ "key": "monthly", "name": "月卡", "price": 99, "days": 30 },
|
||
{ "key": "yearly", "name": "年卡", "price": 899, "days": 365 },
|
||
{ "key": "trial", "name": "试用", "price": 0, "days": 7 }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.2 `GET /api/v1/subscription`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 说明 | 获取当前用户的订阅状态 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `status` | string | `active` / `expired` / `inactive` |
|
||
| `plan` | string | 计划（none/trial/monthly/yearly） |
|
||
| `start_time` | string | 开始时间（无订阅时无此字段） |
|
||
| `expire_time` | string | 到期时间（无订阅时无此字段） |
|
||
| `remaining_days` | number | 剩余天数 |
|
||
| `trial_used` | boolean | 是否已使用过试用 |
|
||
|
||
---
|
||
|
||
### 4.3 `POST /api/v1/subscription/purchase`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 说明 | 创建购买订单。当前返回订单号和占位支付参数，支付集成待完成。 |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `plan` 或 `plan_type` | string | 是 | 计划标识（trial/monthly/yearly） |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `order_id` | string | 订单号 |
|
||
| `payment_params` | object | 支付参数（当前为空对象） |
|
||
| `plan` | string | 计划标识 |
|
||
| `amount` | number | 金额 |
|
||
|
||
---
|
||
|
||
### 4.4 `POST /api/v1/subscription/mock-purchase`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 环境 | 仅非 production 环境可用 |
|
||
| 说明 | 模拟购买订阅，直接激活。不支持 trial 计划（trial 请用 `/subscription/trial`）。 |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `plan` 或 `plan_type` | string | 是 | `monthly` 或 `yearly` |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `status` | string | `active` |
|
||
| `plan` | string | 计划标识 |
|
||
| `remaining_days` | number | 剩余天数 |
|
||
|
||
---
|
||
|
||
### 4.5 `POST /api/v1/subscription/trial`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 说明 | 激活试用订阅。每个用户仅可使用一次。已有有效订阅时不可激活。 |
|
||
|
||
**请求 Body**：无
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `status` | string | `active` |
|
||
| `plan` | string | `trial` |
|
||
| `remaining_days` | number | 试用天数（默认 7） |
|
||
|
||
---
|
||
|
||
### 4.6 `POST /api/v1/subscription/verify`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 管理员手动激活订阅（临时方案，支付集成前使用） |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `user_id` | number | 是 | 用户 ID |
|
||
| `plan` 或 `plan_type` | string | 否 | 计划，默认 `monthly` |
|
||
| `order_id` | string | 否 | 订单号，不传则自动生成 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `status` | string | `active` |
|
||
| `plan` | string | 计划标识 |
|
||
| `remaining_days` | number | 剩余天数 |
|
||
|
||
---
|
||
|
||
## 5. 护理模块
|
||
|
||
### 5.1 `GET /api/v1/treatment/history`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 说明 | 获取当前用户的护理记录列表，支持分页 |
|
||
|
||
**Query 参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `page` | number | 否 | 页码，默认 1 |
|
||
| `page_size` | number | 否 | 每页条数，默认 20 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `total` | number | 总记录数 |
|
||
| `page` | number | 当前页码 |
|
||
| `page_size` | number | 每页条数 |
|
||
| `records` | array | 护理记录列表 |
|
||
|
||
---
|
||
|
||
### 5.2 `POST /api/v1/treatment/sync`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 说明 | 同步护理记录。设备必须已绑定。同时更新设备的电量和温度。 |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `device_id` | string | 是 | 设备 ID |
|
||
| `session_id` | string | 否 | 会话 ID，不传自动生成 |
|
||
| `start_time` | string | 否 | 开始时间 |
|
||
| `end_time` | string | 否 | 结束时间 |
|
||
| `regions` | string/array | 否 | 护理区域（数组会用逗号拼接） |
|
||
| `total_duration_ms` | number | 否 | 总时长（毫秒） |
|
||
| `mode` | number | 否 | 护理模式 |
|
||
| `avg_pd` | number | 否 | 平均光密度 |
|
||
| `battery` | number | 否 | 电量 |
|
||
| `temperature` | number | 否 | 温度 |
|
||
| `wavelength` | number | 否 | 波长 |
|
||
| `brightness` | number | 否 | 亮度 |
|
||
| `pd_values` | object | 否 | PD 传感器数据 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `record_id` | string | 会话 ID（session_id） |
|
||
|
||
---
|
||
|
||
### 5.3 `GET /api/v1/treatment/:record_id`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 说明 | 获取单条护理记录详情。只能查看自己的记录。 |
|
||
|
||
**路径参数**：
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `record_id` | 会话 ID（session_id） |
|
||
|
||
**响应 `data`**：护理记录完整对象
|
||
|
||
---
|
||
|
||
## 6. 固件模块
|
||
|
||
### 6.1 `GET /api/v1/firmware/latest`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireUser |
|
||
| 说明 | 检查固件更新。返回最新固件信息和有时效的 COS 签名下载 URL。 |
|
||
|
||
**Query 参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `current_version` | string | 否 | 当前固件版本号 |
|
||
|
||
**响应 `data`**（有更新）：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `has_update` | boolean | `true` |
|
||
| `version` | string | 最新版本号 |
|
||
| `size_bytes` | number | 文件大小（字节） |
|
||
| `sha256` | string | 文件 SHA256 校验值 |
|
||
| `download_url` | string | 签名下载 URL（有效期 600 秒） |
|
||
|
||
**响应 `data`**（无更新）：
|
||
|
||
```json
|
||
{ "has_update": false }
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 管理后台模块
|
||
|
||
所有管理后台接口路径前缀为 `/api/v1/admin`，需要 `requireAdmin` 认证。
|
||
|
||
### 7.1 认证
|
||
|
||
#### `POST /api/v1/admin/login`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | 无 |
|
||
| 说明 | 管理员登录。支持 bcrypt 和旧版 salt 哈希两种密码格式（旧格式自动升级）。 |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `username` | string | 是 | 用户名 |
|
||
| `password` | string | 是 | 密码 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `token` | string | 管理员 JWT Token |
|
||
| `admin_id` | string | 管理员 ID |
|
||
| `username` | string | 用户名 |
|
||
| `real_name` | string | 真实姓名 |
|
||
| `role` | string | 角色 |
|
||
|
||
---
|
||
|
||
#### `POST /api/v1/admin/password`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 修改管理员密码。新密码最少 6 位。 |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `old_password` | string | 是 | 原密码 |
|
||
| `new_password` | string | 是 | 新密码（>=6 位） |
|
||
|
||
**响应 `data`**：
|
||
|
||
```json
|
||
{ "message": "success" }
|
||
```
|
||
|
||
---
|
||
|
||
### 7.2 仪表盘
|
||
|
||
#### `GET /api/v1/admin/dashboard`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 获取后台首页统计数据 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `device_count` | number | 设备总数 |
|
||
| `user_count` | number | 用户总数 |
|
||
| `treatment_count` | number | 护理记录总数 |
|
||
| `subscription_count` | number | 订阅总数 |
|
||
| `sub_stats` | object | 订阅统计详情 |
|
||
|
||
---
|
||
|
||
### 7.3 设备管理
|
||
|
||
#### `GET /api/v1/admin/devices`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 设备列表，支持关键词搜索和分页 |
|
||
|
||
**Query 参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `keyword` | string | 否 | 搜索关键词（设备 ID/名称） |
|
||
| `page` | number | 否 | 页码 |
|
||
| `page_size` | number | 否 | 每页条数 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `records` | array | 设备列表 |
|
||
| `total` | number | 总数 |
|
||
|
||
---
|
||
|
||
#### `POST /api/v1/admin/devices`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 预生成单个产品码（设备） |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `device_id` | string | 是 | 设备 ID |
|
||
| `product_id` | string | 否 | 产品型号，默认 `HOX_LIGHT_MASK` |
|
||
| `device_secret` | string | 否 | 设备密钥 |
|
||
| `device_name` | string | 否 | 设备名称，默认"光子美容仪" |
|
||
| `firmware_version` | string | 否 | 固件版本，默认 `1.0.0` |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `device_id` | string | 已创建的设备 ID |
|
||
|
||
---
|
||
|
||
#### `POST /api/v1/admin/devices/batch`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 批量预生成产品码，单次最多 500 个 |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `device_ids` | string[] | 是 | 设备 ID 数组（1-500 个） |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `created` | number | 成功创建数量 |
|
||
| `failed` | number | 失败数量 |
|
||
|
||
---
|
||
|
||
#### `GET /api/v1/admin/devices/:device_id`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 获取设备详情，含绑定历史和最近护理记录 |
|
||
|
||
**响应 `data`**：设备信息 + `binding_history`（绑定历史数组）+ `recent_treatments`（最近护理数组）
|
||
|
||
---
|
||
|
||
#### `POST /api/v1/admin/devices/:device_id/unbind`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 后台强制解绑设备 |
|
||
|
||
**响应 `data`**：
|
||
|
||
```json
|
||
{ "message": "success" }
|
||
```
|
||
|
||
---
|
||
|
||
#### `POST /api/v1/admin/devices/:device_id/command`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 向设备推送远程指令 |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `opcode` | number | 是 | 操作码 |
|
||
| 其他 | any | 否 | 指令参数（整个 body 存入 payload） |
|
||
|
||
**响应 `data`**：
|
||
|
||
```json
|
||
{ "message": "queued", "command": { ... } }
|
||
```
|
||
|
||
---
|
||
|
||
#### `GET /api/v1/admin/devices/:device_id/commands`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 获取设备的指令历史，支持分页 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `records` | array | 指令列表 |
|
||
| `total` | number | 总数 |
|
||
|
||
---
|
||
|
||
### 7.4 用户管理
|
||
|
||
#### `GET /api/v1/admin/users`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 用户列表，支持关键词搜索和分页 |
|
||
|
||
**Query 参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `keyword` | string | 否 | 搜索关键词 |
|
||
| `page` | number | 否 | 页码 |
|
||
| `page_size` | number | 否 | 每页条数 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `records` | array | 用户列表 |
|
||
| `total` | number | 总数 |
|
||
|
||
---
|
||
|
||
#### `GET /api/v1/admin/users/:user_id`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 获取用户详情（含订阅、设备等关联信息） |
|
||
|
||
**响应 `data`**：用户详情对象
|
||
|
||
---
|
||
|
||
#### `POST /api/v1/admin/users/:user_id/unbind`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 后台解绑用户的设备 |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `device_id` | string | 否 | 指定设备 ID，不传则解绑该用户所有设备 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `message` | string | "success" |
|
||
| `affected_rows` | number | 受影响行数 |
|
||
|
||
---
|
||
|
||
#### `POST /api/v1/admin/users/:user_id/deactivate`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 注销用户。同时解绑该用户的所有设备。 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `message` | string | "success" |
|
||
| `unbound_rows` | number | 解绑的设备数 |
|
||
|
||
---
|
||
|
||
### 7.5 订阅管理
|
||
|
||
#### `GET /api/v1/admin/subscriptions`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 订阅列表，支持按状态筛选和分页 |
|
||
|
||
**Query 参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `tab` | string | 否 | 筛选标签（如 active/expired） |
|
||
| `page` | number | 否 | 页码 |
|
||
| `page_size` | number | 否 | 每页条数 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `records` | array | 订阅列表 |
|
||
| `total` | number | 总数 |
|
||
| `stats` | object | 订阅统计 |
|
||
|
||
---
|
||
|
||
#### `POST /api/v1/admin/subscriptions`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 为指定用户创建订阅 |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `user_id` | number | 是 | 用户 ID |
|
||
| `plan` | string | 否 | 计划，默认 `monthly` |
|
||
| `amount` | number | 否 | 金额，默认 0 |
|
||
| `order_id` | string | 否 | 订单号，自动生成 |
|
||
| `days` | number | 否 | 有效天数，默认 30 |
|
||
|
||
**响应 `data`**：
|
||
|
||
```json
|
||
{ "message": "success" }
|
||
```
|
||
|
||
---
|
||
|
||
#### `POST /api/v1/admin/subscriptions/cancel`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 取消指定订阅 |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `subscription_id` | number | 是 | 订阅 ID |
|
||
|
||
**响应 `data`**：
|
||
|
||
```json
|
||
{ "message": "success" }
|
||
```
|
||
|
||
---
|
||
|
||
### 7.6 护理记录
|
||
|
||
#### `GET /api/v1/admin/records`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 护理记录列表，支持多条件筛选和分页 |
|
||
|
||
**Query 参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `keyword` | string | 否 | 搜索关键词 |
|
||
| `user_id` | number | 否 | 按用户筛选 |
|
||
| `date_from` | string | 否 | 起始日期 |
|
||
| `date_to` | string | 否 | 截止日期 |
|
||
| `page` | number | 否 | 页码 |
|
||
| `page_size` | number | 否 | 每页条数 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `records` | array | 护理记录列表 |
|
||
| `total` | number | 总数 |
|
||
|
||
---
|
||
|
||
### 7.7 操作日志
|
||
|
||
#### `GET /api/v1/admin/logs`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 操作日志列表，支持按类型和设备筛选 |
|
||
|
||
**Query 参数**：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `type` | string | 否 | 日志类型（action 字段） |
|
||
| `device_id` | string | 否 | 按设备筛选 |
|
||
| `page` | number | 否 | 页码 |
|
||
| `page_size` | number | 否 | 每页条数 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `records` | array | 日志列表 |
|
||
| `total` | number | 总数 |
|
||
|
||
---
|
||
|
||
### 7.8 系统设置
|
||
|
||
#### `GET /api/v1/admin/settings`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 获取所有系统设置 |
|
||
|
||
**响应 `data`**：KV 对象，包含以下设置项：
|
||
|
||
| Key | 类型 | 默认值 | 说明 |
|
||
|-----|------|--------|------|
|
||
| `system_name` | string | "光子美容仪后台" | 系统名称 |
|
||
| `admin_email` | string | - | 管理员邮箱 |
|
||
| `timezone` | string | - | 时区 |
|
||
| `monthly_price` | number | 99 | 月卡价格 |
|
||
| `yearly_price` | number | 899 | 年卡价格 |
|
||
| `trial_days` | number | 7 | 试用天数 |
|
||
| `enable_register` | boolean | true | 是否允许注册 |
|
||
| `enable_binding` | boolean | true | 是否允许设备绑定 |
|
||
| `enable_free_mode` | boolean | true | 是否启用自由模式 |
|
||
| `enable_smart_mode` | boolean | - | 是否启用智能模式 |
|
||
| `maintenance_mode` | boolean | false | 维护模式（开启后拒绝用户登录） |
|
||
|
||
---
|
||
|
||
#### `POST /api/v1/admin/settings`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 更新系统设置。仅接受白名单内的 key。更新后自动清除设置缓存。 |
|
||
|
||
**请求 Body**：KV 对象，key 为上表中允许的设置项名。
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"monthly_price": 129,
|
||
"trial_days": 14,
|
||
"maintenance_mode": false
|
||
}
|
||
```
|
||
|
||
**响应 `data`**：
|
||
|
||
```json
|
||
{ "message": "success" }
|
||
```
|
||
|
||
---
|
||
|
||
### 7.9 固件管理
|
||
|
||
#### `GET /api/v1/admin/firmware`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 获取所有固件版本列表 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `records` | array | 固件列表 |
|
||
| `total` | number | 总数 |
|
||
|
||
---
|
||
|
||
#### `POST /api/v1/admin/firmware`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 登记新固件版本（固件文件需先上传到 COS） |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `version` | string | 是 | 版本号 |
|
||
| `cos_key` | string | 是 | COS 对象 Key |
|
||
| `device_type` | string | 否 | 设备类型 |
|
||
| `size_bytes` | number | 否 | 文件大小 |
|
||
| `sha256` | string | 否 | SHA256 校验值 |
|
||
| `status` | number | 否 | 状态（0=禁用, 1=启用），默认 1 |
|
||
|
||
**响应 `data`**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `firmware_id` | number | 固件记录 ID |
|
||
|
||
---
|
||
|
||
#### `POST /api/v1/admin/firmware/:firmware_id/status`
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Auth | requireAdmin |
|
||
| 说明 | 更新固件启用/禁用状态 |
|
||
|
||
**请求 Body**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `status` | number | 是 | 0=禁用, 1=启用 |
|
||
|
||
**响应 `data`**：
|
||
|
||
```json
|
||
{ "message": "success" }
|
||
```
|
||
|
||
---
|
||
|
||
## 接口速查索引
|
||
|
||
| # | Method | Path | Auth | 说明 |
|
||
|---|--------|------|------|------|
|
||
| - | GET | `/health` | 无 | 健康检查 |
|
||
| 1.1 | POST | `/api/v1/auth/login` | 无 | 微信登录 |
|
||
| 1.2 | POST | `/api/v1/auth/refresh` | Bearer | Token 刷新 |
|
||
| 2.1 | GET | `/api/v1/user/profile` | User | 获取资料 |
|
||
| 2.2 | PUT | `/api/v1/user/profile` | User | 更新资料 |
|
||
| 2.3 | POST | `/api/v1/user/avatar` | User | 上传头像 |
|
||
| 2.4 | POST | `/api/v1/user/phone` | User | 绑定手机号 |
|
||
| 3.1 | POST | `/api/v1/device/bind` | User | 申请绑定设备 |
|
||
| 3.2 | POST | `/api/v1/device/bind/confirm` | User | 确认绑定 |
|
||
| 3.3 | POST | `/api/v1/device/mock-bind` | User | 模拟绑定（非生产） |
|
||
| 3.4 | POST | `/api/v1/device/unbind` | User | 解绑设备 |
|
||
| 3.5 | GET | `/api/v1/device/list` | User | 设备列表 |
|
||
| 3.6 | GET | `/api/v1/device/:device_id` | User | 设备详情 |
|
||
| 3.7 | GET | `/api/v1/device/command/pending` | User | 拉取待执行指令 |
|
||
| 3.8 | POST | `/api/v1/device/command/result` | User | 上报指令结果 |
|
||
| 3.9 | POST | `/api/v1/device/event` | User | 上报设备事件 |
|
||
| 4.1 | GET | `/api/v1/subscription/plans` | 无 | 订阅计划列表 |
|
||
| 4.2 | GET | `/api/v1/subscription` | User | 订阅状态 |
|
||
| 4.3 | POST | `/api/v1/subscription/purchase` | User | 创建购买订单 |
|
||
| 4.4 | POST | `/api/v1/subscription/mock-purchase` | User | 模拟购买（非生产） |
|
||
| 4.5 | POST | `/api/v1/subscription/trial` | User | 激活试用 |
|
||
| 4.6 | POST | `/api/v1/subscription/verify` | Admin | 手动激活订阅 |
|
||
| 5.1 | GET | `/api/v1/treatment/history` | User | 护理记录列表 |
|
||
| 5.2 | POST | `/api/v1/treatment/sync` | User | 同步护理记录 |
|
||
| 5.3 | GET | `/api/v1/treatment/:record_id` | User | 护理记录详情 |
|
||
| 6.1 | GET | `/api/v1/firmware/latest` | User | 检查固件更新 |
|
||
| 7.1 | POST | `/api/v1/admin/login` | 无 | 管理员登录 |
|
||
| 7.1 | POST | `/api/v1/admin/password` | Admin | 修改密码 |
|
||
| 7.2 | GET | `/api/v1/admin/dashboard` | Admin | 仪表盘统计 |
|
||
| 7.3 | GET | `/api/v1/admin/devices` | Admin | 设备列表 |
|
||
| 7.3 | POST | `/api/v1/admin/devices` | Admin | 创建设备 |
|
||
| 7.3 | POST | `/api/v1/admin/devices/batch` | Admin | 批量创建设备 |
|
||
| 7.3 | GET | `/api/v1/admin/devices/:id` | Admin | 设备详情 |
|
||
| 7.3 | POST | `/api/v1/admin/devices/:id/unbind` | Admin | 强制解绑 |
|
||
| 7.3 | POST | `/api/v1/admin/devices/:id/command` | Admin | 推送指令 |
|
||
| 7.3 | GET | `/api/v1/admin/devices/:id/commands` | Admin | 指令历史 |
|
||
| 7.4 | GET | `/api/v1/admin/users` | Admin | 用户列表 |
|
||
| 7.4 | GET | `/api/v1/admin/users/:id` | Admin | 用户详情 |
|
||
| 7.4 | POST | `/api/v1/admin/users/:id/unbind` | Admin | 解绑用户设备 |
|
||
| 7.4 | POST | `/api/v1/admin/users/:id/deactivate` | Admin | 注销用户 |
|
||
| 7.5 | GET | `/api/v1/admin/subscriptions` | Admin | 订阅列表 |
|
||
| 7.5 | POST | `/api/v1/admin/subscriptions` | Admin | 创建订阅 |
|
||
| 7.5 | POST | `/api/v1/admin/subscriptions/cancel` | Admin | 取消订阅 |
|
||
| 7.6 | GET | `/api/v1/admin/records` | Admin | 护理记录列表 |
|
||
| 7.7 | GET | `/api/v1/admin/logs` | Admin | 操作日志 |
|
||
| 7.8 | GET | `/api/v1/admin/settings` | Admin | 获取设置 |
|
||
| 7.8 | POST | `/api/v1/admin/settings` | Admin | 更新设置 |
|
||
| 7.9 | GET | `/api/v1/admin/firmware` | Admin | 固件列表 |
|
||
| 7.9 | POST | `/api/v1/admin/firmware` | Admin | 登记固件 |
|
||
| 7.9 | POST | `/api/v1/admin/firmware/:id/status` | Admin | 更新固件状态 |
|