library-picturebook-activity/docs/api/public-leai-work-form.md

乐读派作品表单（本库快照）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 编码）

示例

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 为统一包装：

{
  "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

文档版本与接口行为以服务端代码为准；若行为变更请同步更新本文档。