461 lines
13 KiB
Markdown
461 lines
13 KiB
Markdown
# 终端设备接口文档
|
||
|
||
> **基础地址**: `http://{服务器IP}:8580/api`
|
||
> **认证方式**: Bearer Token（JWT）
|
||
> **数据格式**: JSON
|
||
> **字符编码**: UTF-8
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [发送短信验证码](#1-发送短信验证码)
|
||
2. [手机验证码登录](#2-手机验证码登录)
|
||
3. [用户作品列表](#3-用户作品列表)
|
||
4. [查询乐读派作品表单](#4-查询乐读派作品表单)
|
||
5. [保存乐读派作品表单](#5-保存乐读派作品表单)
|
||
6. [通用错误码](#6-通用错误码)
|
||
|
||
---
|
||
|
||
## 接口详情
|
||
|
||
### 1. 发送短信验证码
|
||
|
||
向指定手机号发送6位数字验证码，验证码有效期 **5分钟**。
|
||
|
||
```
|
||
POST /device/auth/sms/send
|
||
```
|
||
|
||
**请求头**
|
||
|
||
| 参数 | 值 |
|
||
|------|------|
|
||
| Content-Type | application/json |
|
||
|
||
**请求参数（Body）**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| phone | string | 是 | 手机号，11位 |
|
||
|
||
**请求示例**
|
||
|
||
```json
|
||
{
|
||
"phone": "13800138000"
|
||
}
|
||
```
|
||
|
||
**响应参数**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| code | int | 状态码，200=成功 |
|
||
| message | string | 描述信息 |
|
||
| data | null | 无数据返回 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"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位数字验证码 |
|
||
|
||
**请求示例**
|
||
|
||
```json
|
||
{
|
||
"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） |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"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（本库主键） |
|
||
| remoteWorkId | string | 乐读派作品 ID，用于调用下文 `GET/PUT /device/leai-works/{remoteWorkId}/work-form`；可能为 null |
|
||
| 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` |
|
||
|
||
列表项中的 `remoteWorkId` 与乐读派创作链路一致；编目/分页快照读写请使用 [§4 / §5](#4-查询乐读派作品表单)。
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 38,
|
||
"remoteWorkId": "2044624699115311104",
|
||
"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,
|
||
"remoteWorkId": "2044624699115310999",
|
||
"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. 查询乐读派作品表单
|
||
|
||
获取本库中该乐读派作品的编目/分页快照（不经乐读派 B2 GET）。**必须携带 Token**；仅可操作当前登录用户本人的作品。
|
||
|
||
```
|
||
GET /device/leai-works/{remoteWorkId}/work-form
|
||
```
|
||
|
||
**请求头**
|
||
|
||
| 参数 | 值 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| Authorization | Bearer {token} | 是 | 登录接口返回的 Token |
|
||
|
||
**路径参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| remoteWorkId | string | 是 | 乐读派作品 ID（可能为大整数，建议按字符串传递；URL 需编码） |
|
||
|
||
**请求示例**
|
||
|
||
```
|
||
GET /api/device/leai-works/2044624699115311104/work-form
|
||
```
|
||
|
||
**成功响应 `data` 字段说明**（与公众端 `GET /public/leai-works/{remoteWorkId}/work-form` 语义一致；设备端以结构化对象返回，字段名与下表一致）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| workId | string | 与 remoteWorkId 一致 |
|
||
| status | int | 乐读派创作进度 `leai_status` |
|
||
| title | string | 标题，可为 null |
|
||
| author | string | 作者署名，可为 null |
|
||
| coverUrl | string | 封面 URL，可为 null |
|
||
| subtitle | string | 副标题，可为 null |
|
||
| intro | string | 简介，可为 null |
|
||
| tags | array | 标签列表，元素类型由业务决定，可为 null |
|
||
| pageList | array | 分页快照，见下表 |
|
||
|
||
**`pageList` 数组项字段**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| pageNum | int | 页码 |
|
||
| imageUrl | string | 页图 URL，可为 null |
|
||
| text | string | 页文案，可为 null |
|
||
| audioUrl | string | 页音频 URL，可为 null |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"workId": "2044624699115311104",
|
||
"status": 5,
|
||
"title": "我的绘本",
|
||
"author": "小明",
|
||
"coverUrl": "https://oss.example.com/cover.png",
|
||
"subtitle": null,
|
||
"intro": "简介内容",
|
||
"tags": ["童话", "原创"],
|
||
"pageList": [
|
||
{
|
||
"pageNum": 1,
|
||
"imageUrl": "https://oss.example.com/p1.png",
|
||
"text": "从前有一座山",
|
||
"audioUrl": "https://oss.example.com/p1.mp3"
|
||
}
|
||
]
|
||
},
|
||
"timestamp": "2026-04-11T12:00:00",
|
||
"path": "/api/device/leai-works/2044624699115311104/work-form"
|
||
}
|
||
```
|
||
|
||
**错误情况**
|
||
|
||
| code | 说明 |
|
||
|------|------|
|
||
| 401 | 未登录或 Token 无效 |
|
||
| 404 | 作品不存在或无权操作（非本人） |
|
||
|
||
---
|
||
|
||
### 5. 保存乐读派作品表单
|
||
|
||
保存编目与分页快照至本库（不经乐读派 PUT）。**必须携带 Token**；请求体非空。
|
||
|
||
```
|
||
PUT /device/leai-works/{remoteWorkId}/work-form
|
||
```
|
||
|
||
**请求头**
|
||
|
||
| 参数 | 值 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| Authorization | Bearer {token} | 是 | 登录接口返回的 Token |
|
||
| Content-Type | application/json | 是 | JSON 请求体 |
|
||
|
||
**路径参数**：同 [§4](#4-查询乐读派作品表单)。
|
||
|
||
**请求体（JSON）**：字段均可选，但**至少需一项非空**；服务端将非 null 字段组装为内部 Map 再落库，与 [public-leai-work-form.md](./public-leai-work-form.md) 中 PUT 语义一致。发送 `{}` 或全部为 null 的等价体将返回 **400**（`请求体不能为空`）。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| author | string | 作者署名 |
|
||
| title | string | 标题 |
|
||
| subtitle | string | 副标题 |
|
||
| intro | string | 简介 |
|
||
| tags | array | 标签 |
|
||
| status | int | 乐读派进度，写入 `leai_status` |
|
||
| pageList | array | 分页快照，见下表 |
|
||
|
||
**`pageList` 数组项字段**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| pageNum | int | 页码 |
|
||
| imageUrl | string | 页图 URL |
|
||
| text | string | 页文案 |
|
||
| audioUrl | string | 页音频 URL |
|
||
|
||
**请求示例**
|
||
|
||
```json
|
||
{
|
||
"title": "我的绘本",
|
||
"author": "小明",
|
||
"status": 4,
|
||
"pageList": [
|
||
{
|
||
"pageNum": 1,
|
||
"imageUrl": "https://oss.example.com/p1.png",
|
||
"text": "从前有一座山",
|
||
"audioUrl": "https://oss.example.com/p1.mp3"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**成功响应**：`code=200`，`data` 通常为 null。
|
||
|
||
**错误情况**：同 §4，另含参数校验失败或空请求体时 **400**。
|
||
|
||
---
|
||
|
||
## 6. 通用错误码
|
||
|
||
所有接口统一响应格式：
|
||
|
||
```json
|
||
{
|
||
"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/PUT /device/leai-works/{remoteWorkId}/work-form │
|
||
│ └─ 列表项中的 remoteWorkId 作为路径参数 │
|
||
│ └─ 用于编目/分页快照同步（与创作壳 work-form 一致） │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**Token 有效期**: 7天（604800秒），过期后需重新登录获取。
|
||
|
||
**建议**:
|
||
- Token 存储在设备本地，每次启动时检查是否过期
|
||
- 过期后重新走 发送验证码 → 登录 流程
|
||
- 音频和图片资源使用返回的 URL 直接访问 OSS，无需经过本服务
|