清理文件
This commit is contained in:
zhonghua
parent
889be53346
commit
0a1bdccfb2
@ -1,172 +0,0 @@
|
|||||||
# 乐读派作品表单（本库快照）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` |
|
|
||||||
| 认证 | **可选**。未带 Token 时接口仍可访问（Spring Security 白名单 `/public/leai-works/**`），供外部系统对接；携带 `Authorization: Bearer <JWT>` 时，后端会校验作品归属当前用户。Web 端可继续加 `X-Tenant-Code`、`X-Tenant-Id`（见前端 `request.ts`） |
|
|
||||||
| 安全说明 | 无 Token 时**仅凭路径中的 `remoteWorkId` 定位作品**，请依赖 ID 保密性并在网络层做访问控制；带 Token 时仍按用户维度校验。 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 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
|
|
||||||
|
|
||||||
{
|
|
||||||
"title": "绘本标题",
|
|
||||||
"author": "作者署名",
|
|
||||||
"subtitle": "副标题",
|
|
||||||
"intro": "简介",
|
|
||||||
"tags": ["冒险", "成长"],
|
|
||||||
"pageList": [
|
|
||||||
{
|
|
||||||
"pageNum": 1,
|
|
||||||
"imageUrl": "https://...",
|
|
||||||
"text": "本页文案",
|
|
||||||
"audioUrl": "https://..."
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 请求体（JSON 对象）
|
|
||||||
|
|
||||||
- **不能为空**：`{}` 会返回 **400**（`请求体不能为空`）。
|
|
||||||
- 服务端从 body 中读取三类数据：
|
|
||||||
1. **编目字段**（可选子集）：仅处理以下键，其余顶层键若存在会被忽略（除 `pageList`、`status` 外）：
|
|
||||||
`author`、`title`、`subtitle`、`intro`、`tags`
|
|
||||||
2. **进度**：`status`（整数）原样写入本库 `leai_status`，与 GET 返回的 `status` 一致（不做区间收敛）。
|
|
||||||
3. **分页**：`pageList` 为数组时，按乐读派 `pageList` 形态写入本库分页表。
|
|
||||||
|
|
||||||
| 字段 | 类型 | 说明 |
|
|
||||||
|------|------|------|
|
|
||||||
| `title` | string | 标题 |
|
|
||||||
| `author` | string | 作者署名 |
|
|
||||||
| `subtitle` | string | 副标题 |
|
|
||||||
| `intro` | string | 简介 |
|
|
||||||
| `tags` | string[] | 标签列表 |
|
|
||||||
| `status` | number | 乐读派创作进度（`leai_status`），见下文「status 取值」 |
|
|
||||||
| `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（已配音）**，覆盖本次请求中的 `status` 值。
|
|
||||||
- 若 `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` |
|
|
||||||
|
|
||||||
文档版本与接口行为以服务端代码为准；若行为变更请同步更新本文档。
|
|
||||||
Loading…
Reference in New Issue
Block a user