diff --git a/docs/api/public-leai-work-form.md b/docs/api/public-leai-work-form.md deleted file mode 100644 index fcd0f25..0000000 --- a/docs/api/public-leai-work-form.md +++ /dev/null @@ -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 ` 时,后端会校验作品归属当前用户。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: -Authorization: Bearer -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` | - -文档版本与接口行为以服务端代码为准;若行为变更请同步更新本文档。