En 98e9ad1d28 feat(前端): 测试环境登录框支持自动填充测试账号

通过 VITE_AUTO_FILL_TEST 环境变量控制，在 .env.test 中启用，
使测试环境构建后登录框也能自动填充测试账号，方便测试人员使用。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-04-11 17:03:22 +08:00

10 KiB

Raw Blame History

终端设备接口文档

基础地址: http://{服务器IP}:8580/api 认证方式: Bearer Token（JWT） 数据格式: JSON 字符编码: UTF-8

接口详情

1. 发送短信验证码

向指定手机号发送6位数字验证码，验证码有效期 5分钟。

POST /device/auth/sms/send

请求头

参数	值
Content-Type	application/json

请求参数（Body）

字段	类型	必填	说明
phone	string	是	手机号，11位

请求示例

{
  "phone": "13800138000"
}

响应参数

字段	类型	说明
code	int	状态码，200=成功
message	string	描述信息
data	null	无数据返回

响应示例

{
  "code": 200,
  "message": "success",
  "data": null,
  "timestamp": "2026-04-11T12:00:00",
  "path": "/api/device/auth/sms/send"
}

注意事项

同一手机号 60秒内 只能发送一次
同一手机号每天最多发送 15次
验证码 5分钟 内有效，仅可使用一次

2. 手机验证码登录

使用手机号 + 短信验证码登录，成功返回 JWT Token 和用户信息。

POST /device/auth/login/sms

请求头

参数	值
Content-Type	application/json

请求参数（Body）

字段	类型	必填	说明
phone	string	是	手机号，11位
smsCode	string	是	6位数字验证码

请求示例

{
  "phone": "13800138000",
  "smsCode": "406436"
}

响应参数

字段	类型	说明
code	int	状态码，200=成功
message	string	描述信息
data	object	登录数据
data.token	string	JWT Token，后续接口需携带
data.userId	long	用户ID
data.username	string	用户名
data.nickname	string	昵称
data.avatar	string	头像URL，可为 null
data.phone	string	手机号（脱敏，如 138****8000）

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "token": "eyJhbGciOiJIUzM4NCJ9.eyJ0ZW5hbnRJZCI6OCwidXNlcm5hbWUiOiJkZW1vIiwic3ViIjoiOSIsImlhdCI6MTc3NTg4MjgwNywiZXhwIjoxNzc2NDg3NjA3fQ.xxx",
    "userId": 9,
    "username": "demo",
    "nickname": "小明",
    "avatar": "https://example.com/avatar.png",
    "phone": "137****9302"
  },
  "timestamp": "2026-04-11T12:00:00",
  "path": "/api/device/auth/login/sms"
}

错误情况

code	说明
404	该手机号未注册
403	账号已被禁用
400	验证码错误
400	验证码已过期
400	验证码不能为空

3. 用户作品列表

获取当前登录用户的创作作品列表（分页）。

GET /device/works

请求头

参数	值	必填	说明
Authorization	Bearer {token}	是	登录接口返回的 Token

请求参数（Query）

字段	类型	必填	默认值	说明
page	int	否	1	页码，从1开始
pageSize	int	否	10	每页条数
status	string	否	-	筛选状态：`draft`/`unpublished`/`pending_review`/`published`/`rejected`
keyword	string	否	-	标题关键词搜索

请求示例

GET /api/device/works?page=1&pageSize=10&status=unpublished&keyword=测试

响应参数

字段	类型	说明
code	int	状态码，200=成功
data	object	分页数据
data.list	array	作品列表
data.total	long	总记录数
data.page	long	当前页码
data.pageSize	long	每页条数

list 数组项字段

字段	类型	说明
id	long	作品ID
title	string	作品标题
coverUrl	string	封面图URL，可为 null
description	string	作品描述，可为 null
status	string	状态：`draft`（草稿）/ `unpublished`（待发布）/ `pending_review`（审核中）/ `published`（已发布）/ `rejected`（已拒绝）
authorName	string	作者名称
leaiStatus	int	AI创作进度：`-1`=失败, `0`=初始化, `1`=排队中, `2`=处理中, `3`=完成, `4`=已编目, `5`=已配音
pageCount	int	绘本页数，可为 null
createTime	string	创建时间，格式 `yyyy-MM-ddTHH:mm:ss`
modifyTime	string	修改时间，格式 `yyyy-MM-ddTHH:mm:ss`

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 38,
        "title": "我的绘本",
        "coverUrl": "https://oss.example.com/cover.png",
        "description": "一个有趣的故事",
        "status": "unpublished",
        "authorName": "小明",
        "leaiStatus": 5,
        "pageCount": 6,
        "createTime": "2026-04-10T17:07:00",
        "modifyTime": "2026-04-10T17:10:53"
      },
      {
        "id": 37,
        "title": "春天的故事",
        "coverUrl": "https://oss.example.com/cover2.png",
        "description": null,
        "status": "published",
        "authorName": "小红",
        "leaiStatus": 5,
        "pageCount": 6,
        "createTime": "2026-04-10T16:53:17",
        "modifyTime": "2026-04-10T16:58:54"
      }
    ],
    "total": 15,
    "page": 1,
    "pageSize": 10
  }
}

4. 作品详情

获取指定作品的完整信息，包含所有页面内容（图片、文字、音频）。

GET /device/works/{id}

请求头

参数	值	必填	说明
Authorization	Bearer {token}	是	登录接口返回的 Token

路径参数

字段	类型	必填	说明
id	long	是	作品ID

请求示例

GET /api/device/works/38

响应参数

字段	类型	说明
code	int	状态码，200=成功
data	object	作品详情
data.id	long	作品ID
data.title	string	作品标题
data.authorName	string	作者名称
data.coverUrl	string	封面图URL
data.description	string	作品描述，可为 null
data.status	string	状态
data.visibility	string	可见范围：`public`/`designated`/`internal`/`private`
data.createTime	string	创建时间
data.modifyTime	string	修改时间
data.pages	array	页面列表，按页码升序排列

pages 数组项字段

字段	类型	说明
pageNo	int	页码，从1开始
imageUrl	string	页面图片URL
text	string	页面文字内容，可为 null
audioUrl	string	页面音频URL，可为 null

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 38,
    "title": "我的绘本",
    "authorName": "小明",
    "coverUrl": "https://oss.example.com/cover.png",
    "description": "一个有趣的故事",
    "status": "unpublished",
    "visibility": "private",
    "createTime": "2026-04-10T17:07:00",
    "modifyTime": "2026-04-10T17:10:53",
    "pages": [
      {
        "pageNo": 1,
        "imageUrl": "https://oss.example.com/page_0.png",
        "text": "从前有一座山",
        "audioUrl": "https://oss.example.com/page_0.mp3"
      },
      {
        "pageNo": 2,
        "imageUrl": "https://oss.example.com/page_1.png",
        "text": "山里有一座庙",
        "audioUrl": "https://oss.example.com/page_1.mp3"
      },
      {
        "pageNo": 3,
        "imageUrl": "https://oss.example.com/page_2.png",
        "text": "庙里有一个老和尚",
        "audioUrl": null
      }
    ]
  }
}

错误情况

code	说明
404	作品不存在
403	无权访问该作品（非本人作品）

5. 通用错误码

所有接口统一响应格式：

{
  "code": 401,
  "message": "未登录或 Token 已过期",
  "timestamp": "2026-04-11T12:00:00",
  "path": "/api/device/works"
}

code	说明
200	成功
400	请求参数错误
401	未登录或 Token 已过期
403	无权限访问
404	资源不存在
429	请求过于频繁（触发限流）
500	服务器内部错误

调用流程

┌─────────────────────────────────────────────────────────┐
│                      终端设备调用流程                      │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  1. 发送验证码  POST /device/auth/sms/send              │
│     └─ 参数: { phone }                                  │
│                                                         │
│  2. 验证码登录  POST /device/auth/login/sms             │
│     └─ 参数: { phone, smsCode }                         │
│     └─ 返回: token ← 保存到本地                         │
│                                                         │
│  3. 作品列表    GET  /device/works                       │
│     └─ Header: Authorization: Bearer {token}            │
│     └─ 参数: page, pageSize, status(可选), keyword(可选) │
│                                                         │
│  4. 作品详情    GET  /device/works/{id}                  │
│     └─ Header: Authorization: Bearer {token}            │
│     └─ 返回: 完整页面数据（图片+文字+音频）              │
│                                                         │
└─────────────────────────────────────────────────────────┘

Token 有效期: 7天（604800秒），过期后需重新登录获取。

建议:

Token 存储在设备本地，每次启动时检查是否过期
过期后重新走发送验证码 → 登录流程
音频和图片资源使用返回的 URL 直接访问 OSS，无需经过本服务

10 KiB Raw Blame History Unescape Escape

终端设备接口文档

目录

接口详情

1. 发送短信验证码

2. 手机验证码登录

3. 用户作品列表

4. 作品详情

5. 通用错误码

调用流程

10 KiB

Raw Blame History