170 lines
5.6 KiB
Markdown
170 lines
5.6 KiB
Markdown
# 乐读派作品表单（本库快照）API
|
||
|
||
面向外部系统与本平台前端「创作壳」对齐：**不经过乐读派 B2 的 GET/PUT 作品详情**，直接读写本库 `t_ugc_work` / `t_ugc_work_page` 中的编目与分页快照。
|
||
|
||
| 项 | 说明 |
|
||
|----|------|
|
||
| Base URL | 部署域名 + **context-path `/api`**（见 `application.yml` `server.servlet.context-path`） |
|
||
| 完整路径前缀 | `/api/public/leai-works` |
|
||
| 认证 | **需要登录**。请求头携带 `Authorization: Bearer <JWT>`；与 Web 端一致时可加 `X-Tenant-Code`、`X-Tenant-Id`（见前端 `request.ts`） |
|
||
| 安全说明 | 该路径**不在** Spring Security 匿名白名单中，未带有效 Token 将返回 **401** |
|
||
|
||
---
|
||
|
||
## 1. 保存编目 / 分页快照
|
||
|
||
### 请求
|
||
|
||
| 项 | 值 |
|
||
|----|-----|
|
||
| Method | **PUT** |
|
||
| URL | `/api/public/leai-works/{remoteWorkId}/work-form` |
|
||
| Content-Type | `application/json` |
|
||
|
||
### 路径参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `remoteWorkId` | string | 是 | 乐读派侧作品 ID（可能为大整数，**建议按字符串传输**；路径中需 URL 编码） |
|
||
|
||
**示例**
|
||
|
||
```http
|
||
PUT /api/public/leai-works/2044362486899150848/work-form HTTP/1.1
|
||
Host: <your-host>
|
||
Authorization: Bearer <access_token>
|
||
Content-Type: application/json
|
||
|
||
```
|
||
|
||
### 请求体（JSON 对象）
|
||
|
||
- **不能为空**：`{}` 会返回 **400**（`请求体不能为空`）。
|
||
- 服务端从 body 中读取两类数据：
|
||
1. **编目字段**（可选子集）：仅处理以下键，其余顶层键若存在会被忽略（除 `pageList` 外）：
|
||
`author`、`title`、`subtitle`、`intro`、`tags`
|
||
2. **分页**：`pageList` 为数组时，按乐读派 `pageList` 形态写入本库分页表。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `title` | string | 标题 |
|
||
| `author` | string | 作者署名 |
|
||
| `subtitle` | string | 副标题 |
|
||
| `intro` | string | 简介 |
|
||
| `tags` | string[] | 标签列表 |
|
||
| `pageList` | object[] | 分页列表；元素字段见下表 |
|
||
|
||
`pageList` 元素：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `pageNum` | number | 页码（与后端 `page_no` 对应） |
|
||
| `imageUrl` | string | 插图 URL |
|
||
| `text` | string | 本页文案 |
|
||
| `audioUrl` | string | 配音 URL；可为空字符串表示未配 |
|
||
|
||
### 业务规则（摘要）
|
||
|
||
- 作品必须属于**当前登录用户**且 `remote_work_id` 匹配，否则 **404**（`作品不存在或无权操作`）。
|
||
- 若本次请求更新了编目，且作品为草稿、且乐读派进度已 ≥「生成完成」，可能将发布状态从草稿置为未发布（见 `PublicLeaiWorkFormService`）。
|
||
- 若 `pageList` 非空，且**每一页**的 `audioUrl` 均为非空白字符串，则将 `leai_status` 更新为 **已配音（5）**。
|
||
|
||
### 成功响应
|
||
|
||
HTTP **200**，Body 为统一包装：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
（`data` 可能为 `null`，以实际返回为准。）
|
||
|
||
### 错误响应
|
||
|
||
| HTTP | code（body） | 典型 message |
|
||
|------|----------------|--------------|
|
||
| 400 | 400 | `remoteWorkId 无效` / `请求体不能为空` |
|
||
| 401 | 401 | 未认证或 Token 无效 |
|
||
| 404 | 404 | `作品不存在或无权操作` |
|
||
|
||
错误体结构与项目统一 `Result` 一致（含 `message` 等字段）。
|
||
|
||
---
|
||
|
||
## 2. 查询本库作品详情（建议与 PUT 配合：先 GET 再改后 PUT）
|
||
|
||
便于外部系统做「读-改-写」合并，避免只提交部分字段时覆盖丢失其它字段。
|
||
|
||
| 项 | 值 |
|
||
|----|-----|
|
||
| Method | **GET** |
|
||
| URL | `/api/public/leai-works/{remoteWorkId}/work-form` |
|
||
| 认证 | 同 PUT，需 **Bearer JWT** |
|
||
|
||
### 成功响应 `data` 结构（对象）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `workId` | string | 与路径中 `remoteWorkId` 一致（乐读派 ID） |
|
||
| `status` | number | 乐读派创作进度 `leai_status`，见下表 |
|
||
| `title` | string | 标题 |
|
||
| `author` | string | 作者 |
|
||
| `coverUrl` | string | 封面 URL |
|
||
| `subtitle` | string | 副标题 |
|
||
| `intro` | string | 简介 |
|
||
| `tags` | array | 标签 |
|
||
| `pageList` | object[] | 分页；元素含 `pageNum`、`imageUrl`、`text`、`audioUrl` |
|
||
|
||
### `status`（`leai_status`）取值参考
|
||
|
||
| 值 | 含义 |
|
||
|----|------|
|
||
| -1 | 失败 |
|
||
| 0 | 草稿 |
|
||
| 1 | 待处理 |
|
||
| 2 | 处理中 |
|
||
| 3 | 生成完成 |
|
||
| 4 | 已编目 |
|
||
| 5 | 已配音 |
|
||
|
||
（定义见后端 `LeaiCreationStatus`。）
|
||
|
||
---
|
||
|
||
## 3. 对接建议
|
||
|
||
1. **大整数 ID**：`remoteWorkId` 在部分语言中超出 IEEE754 安全整数，**全程使用字符串**。
|
||
2. **合并提交**：若只改编目，可先 **GET** 全量，在内存中覆盖 `author`/`subtitle`/`intro`/`tags`/`title` 等字段后再 **PUT** 全量，与当前前端「快照 + 覆盖」策略一致，避免清空 `pageList`。
|
||
3. **仅改分页**：可只带 `pageList`（及必须的非空 body）；编目键可选。
|
||
4. **Swagger**：若服务开启 Knife4j，可在 `/doc.html` 查看 **公众端-乐读派作品表单** 分组（以部署为准）。
|
||
|
||
---
|
||
|
||
## 4. 实现位置（源码索引）
|
||
|
||
| 说明 | 路径 |
|
||
|------|------|
|
||
| Controller | `lesingle-creation-backend/.../pub/controller/PublicLeaiWorkController.java` |
|
||
| 业务 | `lesingle-creation-backend/.../pub/service/PublicLeaiWorkFormService.java` |
|
||
|
||
文档版本与接口行为以服务端代码为准；若行为变更请同步更新本文档。
|