803 lines
30 KiB
Markdown
803 lines
30 KiB
Markdown
# AI 绘本创作系统 — 企业定制对接指南 V3.1
|
||
|
||
> 版本: V3.1 | 更新日期: 2026-04-03
|
||
> 适用客户: 自有 C端 H5 + 管理后台，需嵌入乐读派 AI 创作能力
|
||
|
||
---
|
||
|
||
## 一、整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 客户自有 C端 H5 │
|
||
│ ┌──────┐ ┌──────────────┐ ┌──────┐ ┌──────┐ │
|
||
│ │ 广场 │ │ 创作(iframe)│ │ 作品 │ │ 我的 │ │
|
||
│ │ │ │ ┌──────────┐ │ │ │ │ │ │
|
||
│ │ 优秀 │ │ │乐读派H5 │ │ │ AI作品│ │ 个人 │ │
|
||
│ │ 作品 │ │ │上传→提取 │ │ │ + │ │ 设置 │ │
|
||
│ │ 展示 │ │ │→画风→创作│ │ │ 自有 │ │ │ │
|
||
│ │ │ │ │→预览→配音│ │ │ 作品 │ │ │ │
|
||
│ │ │ │ └──────────┘ │ │ │ │ │ │
|
||
│ └──────┘ └──────────────┘ └──────┘ └──────┘ │
|
||
│ ↑ ↑ │
|
||
│ │ 读取客户DB 读取客户DB │
|
||
└─────┼─────────────────────────────────┼────────────────────┘
|
||
│ │
|
||
┌─────┼─────────────────────────────────┼────────────────────┐
|
||
│ │ 客户后端 │ │
|
||
│ │ │ │
|
||
│ 客户DB ←──── Webhook回调 ←──── 乐读派后端 │
|
||
│ (AI作品 (创作完成后实时推送) │
|
||
│ + 自有作品) │
|
||
└────────────────────────────────────────────────────────────┘
|
||
|
||
┌────────────────────────────────────────────────────────────┐
|
||
│ Android APK（乐读派打包提供） │
|
||
│ 创作流程 → 完成 → Webhook回调 → 客户后端 │
|
||
│ "我的作品" → 调客户提供的API │
|
||
└────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 职责划分
|
||
|
||
| 功能 | 负责方 | 说明 |
|
||
|------|--------|------|
|
||
| AI 创作 H5 页面 | **乐读派** | 提供完整创作流程，客户 iframe 嵌入 |
|
||
| AI 创作后端 API | **乐读派** | A6 角色提取、A3 故事创作、A20 配音等 |
|
||
| Android APK | **乐读派** | 打包发布，客户提供"我的作品"接口即可 |
|
||
| 广场 / 作品库 / 我的 | **客户** | 客户自有 H5 + 后端 |
|
||
| 作品管理后台 | **客户** | 客户自有管理后台 |
|
||
| Webhook 接收 | **客户** | 接收乐读派推送的创作结果 |
|
||
| 数据存储 | **客户** | AI 作品数据存入客户自己的 DB |
|
||
|
||
---
|
||
|
||
## 二、对接前准备
|
||
|
||
### 2.1 乐读派提供
|
||
|
||
以下信息由乐读派管理后台创建机构后生成，正式对接时填入：
|
||
|
||
| 项目 | 值 | 说明 |
|
||
|------|------|------|
|
||
| orgId（机构ID） | `__________` | 机构唯一标识，所有 API 调用和数据归属依据此 ID |
|
||
| appSecret（机构密钥） | `__________` | API 认证密钥，**严禁泄露**，仅存于客户服务端 |
|
||
| H5 创作页地址 | `__________` | 乐读派 H5 前端 URL（iframe src 用） |
|
||
| API 服务地址 | `__________` | 乐读派后端 API 基地址 |
|
||
| Android APK | 另行交付 | 已内置上述配置的签名发布包 |
|
||
| 创作额度 | `__________` 次/周期 | 机构总创作额度（管理后台可调整） |
|
||
|
||
> **重要**：以上所有 `__________` 空白项将在正式开通机构后由乐读派填入并发送给客户。请勿使用测试值上线。
|
||
|
||
### 2.2 客户提供
|
||
|
||
| 项目 | 内容 | 说明 |
|
||
|------|------|------|
|
||
| Webhook 接收 URL | `https://客户域名/webhook/leai` | HTTPS，5 秒内返回 200 |
|
||
| H5 嵌入域名 | `https://客户h5域名` | 用于 CORS 和 iframe 白名单 |
|
||
| 机构查询接口（Android用） | `GET /api/org/by-device?mac=xx` | 根据设备MAC返回orgId（见 6.2） |
|
||
| 我的作品接口（Android用） | `GET /api/my-works?orgId=xx&phone=xx` | 返回作品列表+详情（见 6.3） |
|
||
|
||
---
|
||
|
||
## 三、C端 H5 嵌入（iframe 方案）
|
||
|
||
### 3.1 嵌入原理
|
||
|
||
客户的"创作"Tab 内放一个 iframe，加载乐读派 H5 创作页面。创作完成后，乐读派 H5 通过 `postMessage` 通知客户父页面。
|
||
|
||
```
|
||
客户H5页面 乐读派H5(iframe内)
|
||
│ │
|
||
│ 1. 客户后端换取 sessionToken │
|
||
│ │
|
||
│ 2. iframe.src = 乐读派H5 │
|
||
│ + token + orgId + phone │
|
||
│ ──────────────────────────────→ │
|
||
│ │
|
||
│ 用户在iframe内创作... │
|
||
│ │
|
||
│ 3. 创作完成: postMessage │
|
||
│ ←────────────────────────────── │
|
||
│ {type:'WORK_CREATED', │
|
||
│ workId:'xxx'} │
|
||
│ │
|
||
│ 4. 同时: Webhook推送到客户后端 │
|
||
│ │
|
||
│ 5. 客户刷新作品列表 │
|
||
```
|
||
|
||
### 3.2 客户 H5 嵌入代码（完整示例，可直接使用）
|
||
|
||
```html
|
||
<!-- 客户的"创作"Tab页面 -->
|
||
<template>
|
||
<div class="create-tab">
|
||
<!-- 乐读派创作iframe -->
|
||
<iframe
|
||
v-if="iframeSrc"
|
||
:src="iframeSrc"
|
||
ref="creationFrame"
|
||
class="creation-iframe"
|
||
allow="camera;microphone"
|
||
sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-modals"
|
||
/>
|
||
<div v-else class="loading">正在加载创作工具...</div>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup>
|
||
import { ref, onMounted, onBeforeUnmount } from 'vue'
|
||
import axios from 'axios'
|
||
|
||
// ★★★ 替换为乐读派提供的值（见第二章配置表）★★★
|
||
const LEAI_H5_URL = '__________ /* 乐读派H5创作页地址 */'
|
||
const CREATE_TOKEN_API = '/api/create-token' // 客户自己的后端接口（见3.3）
|
||
// ★★★ 替换结束 ★★★
|
||
|
||
const iframeSrc = ref('')
|
||
|
||
onMounted(async () => {
|
||
try {
|
||
// 1. 调客户自己的后端，获取 sessionToken
|
||
// 客户后端内部会调乐读派的 /api/v1/auth/session
|
||
const { data } = await axios.post(CREATE_TOKEN_API, {
|
||
phone: getCurrentUserPhone() // 从客户登录态获取当前用户手机号
|
||
})
|
||
|
||
// 2. 拼接 iframe URL
|
||
iframeSrc.value = `${LEAI_H5_URL}/?token=${data.token}&orgId=${data.orgId}&phone=${data.phone}&embed=1`
|
||
} catch (e) {
|
||
console.error('获取创作令牌失败', e)
|
||
}
|
||
|
||
// 3. 监听 postMessage（创作完成通知）
|
||
window.addEventListener('message', onCreationMessage)
|
||
})
|
||
|
||
onBeforeUnmount(() => {
|
||
window.removeEventListener('message', onCreationMessage)
|
||
})
|
||
|
||
function onCreationMessage(event) {
|
||
// 安全校验：只处理来自乐读派H5的消息
|
||
if (!event.origin.includes('leai')) return
|
||
const msg = event.data
|
||
if (msg?.type === 'WORK_CREATED') {
|
||
// 创作完成！workId 可用于跳转到作品详情
|
||
console.log('新作品创建成功:', msg.workId)
|
||
// 客户可以：刷新作品列表 / 跳转到作品Tab / 显示成功提示
|
||
refreshMyWorks()
|
||
}
|
||
}
|
||
|
||
function getCurrentUserPhone() {
|
||
// ★ 替换为客户自己的获取当前登录用户手机号的逻辑
|
||
return '13800001111'
|
||
}
|
||
|
||
function refreshMyWorks() {
|
||
// ★ 替换为客户自己的刷新作品列表逻辑
|
||
}
|
||
</script>
|
||
|
||
<style scoped>
|
||
.create-tab {
|
||
width: 100%;
|
||
height: 100%;
|
||
}
|
||
.creation-iframe {
|
||
width: 100%;
|
||
height: 100%;
|
||
border: none;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
### 3.3 客户后端：令牌交换接口（完整示例）
|
||
|
||
客户后端需要实现一个接口，内部调用乐读派的令牌交换 API：
|
||
|
||
**Java (Spring Boot):**
|
||
```java
|
||
@RestController
|
||
public class LeAiController {
|
||
|
||
// ★★★ 替换为乐读派提供的值（见第二章配置表）★★★
|
||
private static final String LEAI_API = "__________"; // API服务地址
|
||
private static final String ORG_ID = "__________"; // 机构ID
|
||
private static final String APP_SECRET = "__________"; // 机构密钥
|
||
|
||
private final RestTemplate restTemplate = new RestTemplate();
|
||
|
||
/**
|
||
* 客户前端调这个接口获取创作令牌
|
||
* POST /api/create-token
|
||
* Body: { "phone": "13800001111" }
|
||
*/
|
||
@PostMapping("/api/create-token")
|
||
public Map<String, String> createToken(@RequestBody Map<String, String> req) {
|
||
String phone = req.get("phone");
|
||
|
||
// 调乐读派令牌交换接口
|
||
Map<String, String> body = new HashMap<>();
|
||
body.put("orgId", ORG_ID);
|
||
body.put("appSecret", APP_SECRET);
|
||
body.put("phone", phone);
|
||
|
||
Map response = restTemplate.postForObject(
|
||
LEAI_API + "/api/v1/auth/session", body, Map.class);
|
||
Map data = (Map) response.get("data");
|
||
|
||
// 返回给前端
|
||
Map<String, String> result = new HashMap<>();
|
||
result.put("token", (String) data.get("sessionToken"));
|
||
result.put("orgId", ORG_ID);
|
||
result.put("phone", phone);
|
||
return result;
|
||
}
|
||
}
|
||
```
|
||
|
||
**Python (Flask):**
|
||
```python
|
||
import requests
|
||
from flask import Flask, request, jsonify
|
||
|
||
LEAI_API = "__________" # ★ API服务地址（见第二章配置表）
|
||
ORG_ID = "__________" # ★ 机构ID
|
||
APP_SECRET = "__________" # ★ 机构密钥
|
||
|
||
app = Flask(__name__)
|
||
|
||
@app.route("/api/create-token", methods=["POST"])
|
||
def create_token():
|
||
phone = request.json["phone"]
|
||
res = requests.post(f"{LEAI_API}/api/v1/auth/session", json={
|
||
"orgId": ORG_ID, "appSecret": APP_SECRET, "phone": phone
|
||
})
|
||
token = res.json()["data"]["sessionToken"]
|
||
return jsonify({"token": token, "orgId": ORG_ID, "phone": phone})
|
||
```
|
||
|
||
**Node.js (Express):**
|
||
```javascript
|
||
const axios = require('axios')
|
||
const LEAI_API = '__________' // ★ API服务地址（见第二章配置表）
|
||
const ORG_ID = '__________' // ★ 机构ID
|
||
const APP_SECRET = '__________' // ★ 机构密钥
|
||
|
||
app.post('/api/create-token', async (req, res) => {
|
||
const { phone } = req.body
|
||
const { data } = await axios.post(`${LEAI_API}/api/v1/auth/session`, {
|
||
orgId: ORG_ID, appSecret: APP_SECRET, phone
|
||
})
|
||
res.json({ token: data.data.sessionToken, orgId: ORG_ID, phone })
|
||
})
|
||
```
|
||
|
||
### 3.4 iframe 嵌入注意事项
|
||
|
||
| 事项 | 说明 |
|
||
|------|------|
|
||
| CORS 白名单 | 联系乐读派将客户 H5 域名加入 `allowed_origins` |
|
||
| HTTPS 必须 | iframe 父页面和乐读派 H5 都必须是 HTTPS |
|
||
| `embed=1` 参数 | 告诉乐读派 H5 处于嵌入模式（隐藏返回按钮等） |
|
||
| Token 有效期 | 2 小时，建议每次打开创作Tab时重新获取 |
|
||
| 相机权限 | iframe 需要 `allow="camera"` 属性才能拍照上传 |
|
||
|
||
---
|
||
|
||
## 四、Webhook 数据同步
|
||
|
||
### 4.1 同步机制全景图
|
||
|
||
```
|
||
用户在iframe中创作
|
||
│
|
||
↓
|
||
乐读派后端完成AI生成
|
||
│
|
||
├──→ postMessage通知iframe父页面（即时，用于前端刷新）
|
||
│
|
||
└──→ Webhook POST到客户后端（1-3秒，用于数据持久化）
|
||
│
|
||
↓
|
||
客户后端接收
|
||
│
|
||
├── 验签（确认来自乐读派）
|
||
├── 解析作品数据（标题/图片/音频/文字）
|
||
├── 存入客户DB（供 广场/作品库 使用）
|
||
└── 返回200
|
||
```
|
||
|
||
### 4.2 客户需要实现的 Webhook 接口
|
||
|
||
**只需要一个 POST 端点：**
|
||
|
||
```
|
||
POST https://客户域名/webhook/leai
|
||
Content-Type: application/json
|
||
```
|
||
|
||
**完整实现示例 (Java Spring Boot):**
|
||
|
||
```java
|
||
import javax.crypto.Mac;
|
||
import javax.crypto.spec.SecretKeySpec;
|
||
import org.apache.commons.codec.binary.Hex;
|
||
import java.security.MessageDigest;
|
||
|
||
@RestController
|
||
public class WebhookController {
|
||
|
||
private static final String APP_SECRET = "__________"; // ★ 机构密钥（见第二章配置表）
|
||
|
||
/**
|
||
* 接收乐读派Webhook回调
|
||
* 所有事件类型都走这一个接口
|
||
*/
|
||
@PostMapping("/webhook/leai")
|
||
public Map<String, String> handleWebhook(
|
||
@RequestBody String rawBody,
|
||
@RequestHeader("X-Webhook-Id") String webhookId,
|
||
@RequestHeader("X-Webhook-Timestamp") String timestamp,
|
||
@RequestHeader("X-Webhook-Signature") String signatureHeader) {
|
||
|
||
// 1. 时间窗口检查（防重放，5分钟有效）
|
||
long ts = Long.parseLong(timestamp);
|
||
if (Math.abs(System.currentTimeMillis() - ts) > 300_000) {
|
||
return Map.of("error", "expired");
|
||
}
|
||
|
||
// 2. 验证签名
|
||
String signData = webhookId + "." + timestamp + "." + rawBody;
|
||
Mac mac = Mac.getInstance("HmacSHA256");
|
||
mac.init(new SecretKeySpec(APP_SECRET.getBytes("UTF-8"), "HmacSHA256"));
|
||
String expected = "HMAC-SHA256=" + Hex.encodeHexString(
|
||
mac.doFinal(signData.getBytes("UTF-8")));
|
||
if (!MessageDigest.isEqual(expected.getBytes(), signatureHeader.getBytes())) {
|
||
return Map.of("error", "invalid signature");
|
||
}
|
||
|
||
// 3. 解析事件
|
||
JSONObject payload = JSON.parseObject(rawBody);
|
||
String eventId = payload.getString("id");
|
||
String event = payload.getString("event");
|
||
JSONObject data = payload.getJSONObject("data");
|
||
|
||
// 4. 幂等去重（用eventId判断是否已处理）
|
||
if (isProcessed(eventId)) {
|
||
return Map.of("status", "duplicate");
|
||
}
|
||
|
||
// 5. 按事件类型处理
|
||
switch (event) {
|
||
case "work.completed":
|
||
handleWorkCompleted(data);
|
||
break;
|
||
case "work.updated":
|
||
handleWorkUpdated(data);
|
||
break;
|
||
case "work.audio_updated":
|
||
handleAudioUpdated(data);
|
||
break;
|
||
case "work.failed":
|
||
handleWorkFailed(data);
|
||
break;
|
||
// 其他事件按需处理
|
||
}
|
||
|
||
markProcessed(eventId);
|
||
return Map.of("status", "ok");
|
||
}
|
||
|
||
/**
|
||
* 作品创作完成 — 最重要的事件
|
||
* 存入客户DB，供广场和作品库使用
|
||
*/
|
||
private void handleWorkCompleted(JSONObject data) {
|
||
String workId = data.getString("work_id");
|
||
String title = data.getString("title");
|
||
String author = data.getString("author");
|
||
String phone = data.getString("phone"); // 创作者手机号
|
||
String style = data.getString("style");
|
||
int completionStep = data.getIntValue("completion_step");
|
||
int dataVersion = data.getIntValue("data_version");
|
||
JSONArray pageList = data.getJSONArray("page_list");
|
||
|
||
// ★ 存入客户自己的作品表
|
||
// dataVersion门卫：只有新版本才更新
|
||
MyWork local = myWorkRepository.findByWorkId(workId);
|
||
if (local != null && dataVersion <= local.getDataVersion()) {
|
||
return; // 旧数据，跳过
|
||
}
|
||
|
||
MyWork work = local != null ? local : new MyWork();
|
||
work.setWorkId(workId);
|
||
work.setTitle(title);
|
||
work.setAuthor(author);
|
||
work.setPhone(phone);
|
||
work.setStyle(style);
|
||
work.setStatus("COMPLETED");
|
||
work.setCompletionStep(completionStep);
|
||
work.setDataVersion(dataVersion);
|
||
work.setSource("AI_CREATION"); // 标记来源：AI创作（区别于客户自有作品）
|
||
|
||
// 存储页面数据
|
||
if (pageList != null) {
|
||
work.setPageListJson(pageList.toJSONString());
|
||
// 封面图（第一页的图片URL）
|
||
if (pageList.size() > 0) {
|
||
work.setCoverUrl(pageList.getJSONObject(0).getString("image_url"));
|
||
}
|
||
}
|
||
|
||
myWorkRepository.save(work);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.3 Webhook 回调数据格式
|
||
|
||
**请求头：**
|
||
```
|
||
X-Webhook-Id: evt_1912345678901234567
|
||
X-Webhook-Timestamp: 1712000000000
|
||
X-Webhook-Signature: HMAC-SHA256=a3f8c2d1e5b7...
|
||
```
|
||
|
||
**请求体（work.completed 事件）：**
|
||
```json
|
||
{
|
||
"id": "evt_1912345678901234567",
|
||
"event": "work.completed",
|
||
"created_at": 1712000000000,
|
||
"data": {
|
||
"work_id": "1912345678901234567",
|
||
"org_id": "ORG001",
|
||
"status": "COMPLETED",
|
||
"title": "小兔子的冒险",
|
||
"author": "小明",
|
||
"phone": "13800001111",
|
||
"style": "watercolor",
|
||
"pages": 6,
|
||
"completion_step": 0,
|
||
"data_version": 1,
|
||
"page_list": [
|
||
{"page_num": 0, "text": "小兔子的冒险", "image_url": "https://oss.../p0.png", "audio_url": null},
|
||
{"page_num": 1, "text": "在一个阳光明媚的早晨...", "image_url": "https://oss.../p1.png", "audio_url": null}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.4 客户 DB 建表参考
|
||
|
||
```sql
|
||
CREATE TABLE my_works (
|
||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||
work_id VARCHAR(50) UNIQUE NOT NULL, -- 乐读派作品ID
|
||
|
||
-- 乐读派同步字段（Webhook写入，不要手动改）
|
||
title VARCHAR(200),
|
||
author VARCHAR(50),
|
||
phone VARCHAR(20), -- 创作者
|
||
status VARCHAR(20), -- COMPLETED/FAILED
|
||
style VARCHAR(50),
|
||
completion_step INT DEFAULT 0,
|
||
data_version INT NOT NULL DEFAULT 0, -- ★ 同步对比用
|
||
page_list_json MEDIUMTEXT, -- 页面JSON
|
||
cover_url VARCHAR(500), -- 封面图URL
|
||
|
||
-- 客户自有字段
|
||
source VARCHAR(20) DEFAULT 'AI_CREATION', -- AI_CREATION=AI创作 / USER_UPLOAD=用户自传
|
||
is_featured TINYINT DEFAULT 0, -- 是否精选（广场展示）
|
||
review_status VARCHAR(20) DEFAULT 'PENDING', -- 审核状态
|
||
user_id BIGINT, -- 客户系统的用户ID（通过phone关联）
|
||
|
||
created_at DATETIME DEFAULT NOW(),
|
||
updated_at DATETIME DEFAULT NOW() ON UPDATE NOW(),
|
||
INDEX idx_phone (phone),
|
||
INDEX idx_source (source),
|
||
INDEX idx_featured (is_featured)
|
||
);
|
||
```
|
||
|
||
### 4.5 签名验证依赖
|
||
|
||
Java 项目需要添加 Apache Commons Codec：
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>commons-codec</groupId>
|
||
<artifactId>commons-codec</artifactId>
|
||
<version>1.16.0</version>
|
||
</dependency>
|
||
```
|
||
|
||
---
|
||
|
||
## 五、postMessage 通信协议
|
||
|
||
### 5.1 乐读派 H5 → 客户父页面
|
||
|
||
当用户在 iframe 中完成创作流程，乐读派 H5 会通过 `window.parent.postMessage` 发送以下消息：
|
||
|
||
| 事件 | 触发时机 | 数据 |
|
||
|------|---------|------|
|
||
| `WORK_CREATED` | 作品创建成功（A3提交后） | `{type:'WORK_CREATED', workId:'xxx'}` |
|
||
| `WORK_COMPLETED` | 创作完成（图文生成完毕） | `{type:'WORK_COMPLETED', workId:'xxx'}` |
|
||
| `CREATION_ERROR` | 创作失败 | `{type:'CREATION_ERROR', message:'xxx'}` |
|
||
|
||
### 5.2 客户父页面监听示例
|
||
|
||
```javascript
|
||
window.addEventListener('message', (event) => {
|
||
// 安全校验
|
||
if (!event.origin.includes('leai域名')) return
|
||
|
||
const { type, workId } = event.data
|
||
switch (type) {
|
||
case 'WORK_COMPLETED':
|
||
// 创作完成，可以：
|
||
// 1. 切换到"作品"Tab
|
||
// 2. 刷新作品列表
|
||
// 3. 显示成功提示
|
||
showToast('创作完成！')
|
||
switchToWorksTab()
|
||
break
|
||
case 'CREATION_ERROR':
|
||
showToast('创作失败：' + event.data.message)
|
||
break
|
||
}
|
||
})
|
||
```
|
||
|
||
> **注意**: postMessage 用于前端即时通知（告诉客户H5"创作完了"）。完整的作品数据通过 Webhook 异步推送到客户后端，客户前端从自己的后端获取。
|
||
|
||
---
|
||
|
||
## 六、Android APK 对接
|
||
|
||
### 6.1 交付方式
|
||
|
||
乐读派打包签名的 APK 交付给客户。客户**不需要**源代码。
|
||
|
||
APK 中**不写死机构ID**，而是通过客户提供的接口动态获取（见 6.2）。
|
||
|
||
打包时，客户需提供以下信息（乐读派代入配置）：
|
||
|
||
| 配置项 | 示例 | 说明 |
|
||
|--------|------|------|
|
||
| 乐读派 API 地址 | `__________` | 乐读派后端（见第二章） |
|
||
| 机构密钥 | `__________` | 客户的 appSecret（见第二章） |
|
||
| 客户 API 基地址 | `https://客户域名/api` | 用于调 6.2/6.3 的接口 |
|
||
|
||
### 6.2 客户需提供的接口①：获取机构ID
|
||
|
||
Android 端启动时，通过设备 MAC 地址向客户后端查询所属机构。**机构ID 不写死在 APK 中**，支持同一 APK 部署到不同机构的设备。
|
||
|
||
```
|
||
GET https://客户域名/api/org/by-device?mac={设备MAC地址}
|
||
```
|
||
|
||
响应格式：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"orgId": "ORG001",
|
||
"orgName": "XX教育机构"
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| orgId | String | 乐读派分配的机构ID（必须与第二章配置表一致） |
|
||
| orgName | String | 机构名称（可选，用于 Android 端显示） |
|
||
|
||
> **流程**：Android 启动 → 读取设备 MAC → 调客户接口获取 orgId → 后续所有 API 调用使用该 orgId。
|
||
|
||
### 6.3 客户需提供的接口②：我的作品
|
||
|
||
Android 端"作品"Tab 展示当前用户在该机构下的作品列表。使用 **orgId + phone** 组合查询。
|
||
|
||
**作品列表：**
|
||
```
|
||
GET https://客户域名/api/my-works?orgId={orgId}&phone={phone}&page=1&size=20
|
||
```
|
||
|
||
响应格式（**字段名固定，乐读派 Android 端直接解析**）：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"total": 42,
|
||
"records": [
|
||
{
|
||
"workId": "1912345678901234567",
|
||
"title": "小兔子的冒险",
|
||
"coverUrl": "https://oss.../p0.png",
|
||
"status": "COMPLETED",
|
||
"createdAt": "2026-04-03 10:30:00"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**作品详情：**
|
||
```
|
||
GET https://客户域名/api/my-works/{workId}?orgId={orgId}
|
||
```
|
||
|
||
响应格式：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"workId": "1912345678901234567",
|
||
"title": "小兔子的冒险",
|
||
"author": "小明",
|
||
"pageList": [
|
||
{"pageNum": 0, "text": "封面", "imageUrl": "https://...", "audioUrl": null},
|
||
{"pageNum": 1, "text": "故事内容...", "imageUrl": "https://...", "audioUrl": "https://..."}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
> **注意**：
|
||
> - 字段名使用 **camelCase**（如果客户 DB 存的是 Webhook 的 snake_case，需在接口层转换）
|
||
> - `orgId` 必填，用于隔离不同机构的数据
|
||
> - `phone` 来自用户登录，Android 端自动携带
|
||
|
||
### 6.4 Android 端数据流
|
||
|
||
```
|
||
Android 启动
|
||
│
|
||
├── 读取设备MAC地址
|
||
│
|
||
├── GET /api/org/by-device?mac=xx:xx:xx → 获取 orgId
|
||
│
|
||
├── 用户登录 → 获取 phone
|
||
│
|
||
├── 创作流程 → 调乐读派API（orgId + appSecret + phone）
|
||
│ │
|
||
│ └── 创作完成 → Webhook推送到客户后端
|
||
│
|
||
└── "我的作品" → GET /api/my-works?orgId=xx&phone=xx → 客户后端返回
|
||
```
|
||
|
||
---
|
||
|
||
## 七、数据流全景与同步时序
|
||
|
||
### 7.1 用户创作一个作品的完整数据流
|
||
|
||
```
|
||
时间轴 →
|
||
|
||
用户操作 客户H5 乐读派H5(iframe) 乐读派后端 客户后端
|
||
│ │ │ │ │
|
||
│ 点击"创作" │ │ │ │
|
||
│ ──────────→ │ │ │ │
|
||
│ │ 换取token │ │ │
|
||
│ │ ──────────────────────────────→ │ │
|
||
│ │ ←─ sessionToken ────────────── │ │
|
||
│ │ │ │ │
|
||
│ │ 加载iframe │ │ │
|
||
│ │ ──────────→ │ │ │
|
||
│ │ │ │ │
|
||
│ 拍照上传 │ │ A6角色提取 │ │
|
||
│ ──────────────────────────→ │ ────────────→ │ │
|
||
│ │ │ ←── 角色列表 ── │ │
|
||
│ │ │ │ │
|
||
│ 选画风+写故事 │ │ A3创作 │ │
|
||
│ ──────────────────────────→ │ ────────────→ │ │
|
||
│ │ │ │ AI生成中... │
|
||
│ │ │ ←── 进度更新 ── │ │
|
||
│ │ │ │ │
|
||
│ │ │ ←── 创作完成 ── │ │
|
||
│ │ ← postMessage │ │ │
|
||
│ │ WORK_COMPLETED │ │ │
|
||
│ │ │ │ Webhook POST │
|
||
│ │ │ │ ────────────→ │
|
||
│ │ │ │ │ 验签+存DB
|
||
│ │ │ │ ← 200 ────── │
|
||
│ 看到"创作完成" │ │ │ │
|
||
│ │ 刷新作品列表 │ │ │
|
||
│ │ (从客户后端取) │ │ │
|
||
```
|
||
|
||
### 7.2 数据同步保障
|
||
|
||
| 层级 | 机制 | 说明 |
|
||
|------|------|------|
|
||
| 实时通知 | postMessage | iframe 创作完成后立即通知客户 H5 前端 |
|
||
| 数据同步 | Webhook | 创作完成后 1-3 秒推送到客户后端 |
|
||
| 重试保障 | 自动重试 5 次 | 10s/30s/2m/10m/30m，确保数据不丢 |
|
||
| 兜底对账 | B3 定时查询 | 建议每 5 分钟查一次，对比 data_version |
|
||
|
||
---
|
||
|
||
## 八、对接验证清单
|
||
|
||
按顺序逐步验证，每步都通过后再进行下一步：
|
||
|
||
### Phase 1: 后端连通（1天）
|
||
|
||
- [ ] 收到乐读派提供的 orgId + appSecret
|
||
- [ ] 调用令牌交换接口成功：`POST /api/v1/auth/session`
|
||
- [ ] 实现 Webhook 接收端点：`POST /webhook/leai`
|
||
- [ ] 管理后台配置回调 URL + 测试连通
|
||
|
||
### Phase 2: iframe 嵌入（1天）
|
||
|
||
- [ ] 客户 H5 域名加入 CORS 白名单（联系乐读派）
|
||
- [ ] iframe 加载乐读派 H5 正常显示
|
||
- [ ] iframe 内可拍照/选图上传
|
||
- [ ] iframe 内完整创作流程走通（上传→提取→画风→创作→预览）
|
||
|
||
### Phase 3: 数据同步（1天）
|
||
|
||
- [ ] Webhook 收到 `work.completed` 事件
|
||
- [ ] 签名验证通过
|
||
- [ ] 作品数据正确写入客户 DB
|
||
- [ ] 客户"作品库"能展示 AI 创作的作品
|
||
- [ ] postMessage 通知正常接收
|
||
|
||
### Phase 4: Android 交付（1天）
|
||
|
||
- [ ] 客户提供"我的作品"API 接口文档
|
||
- [ ] 乐读派打包 APK 配置客户参数
|
||
- [ ] APK 安装后创作流程正常
|
||
- [ ] "我的作品"展示客户接口返回的数据
|
||
- [ ] Webhook 正常推送
|
||
|
||
---
|
||
|
||
## 九、常见问题
|
||
|
||
**Q: iframe 内创作完成后，客户怎么知道？**
|
||
A: 两个通道同时通知：① postMessage 即时通知客户前端（用于刷新UI）；② Webhook 异步推送到客户后端（用于持久化数据）。
|
||
|
||
**Q: 客户的"广场"数据怎么来？**
|
||
A: 所有 AI 作品通过 Webhook 同步到客户 DB 后，客户在管理后台标记"精选"，广场从客户 DB 读取 `is_featured=1` 的作品展示。
|
||
|
||
**Q: 用户在 iframe 创作时网络断了怎么办？**
|
||
A: 创作请求已提交到乐读派后端的不受影响（后端异步生成）。Webhook 会在创作完成后推送。如果用户关闭了页面，下次打开"作品库"也能看到已完成的作品。
|
||
|
||
**Q: Token 过期了怎么办？**
|
||
A: 每次用户打开"创作"Tab 时重新获取 Token（2小时有效）。创作过程中 Token 过期不影响已提交的创作任务。
|
||
|
||
**Q: 客户想修改创作 UI 怎么办？**
|
||
A: 联系乐读派，我们修改 H5 代码后重新部署。客户不需要改任何代码，iframe 自动加载最新版本。
|
||
|
||
**Q: OSS 图片 URL 会过期吗？**
|
||
A: 不会。图片存储在乐读派 OSS，URL 永久有效（除非作品被删除）。客户可以直接在广场/作品库中使用这些 URL。
|
||
|
||
**Q: Android 端需要热更新怎么办？**
|
||
A: 目前需要重新打包 APK。创作流程的 UI/逻辑更新需乐读派重新打包后交付。
|
||
|
||
---
|
||
|
||
## 附录: 错误码速查
|
||
|
||
| 错误码 | 说明 | 处理 |
|
||
|--------|------|------|
|
||
| 200 | 成功 | - |
|
||
| 10006 | 请求过于频繁 | 降低频率 |
|
||
| 20002 | 账号锁定（5次密钥错误） | 等10分钟 |
|
||
| 20010 | 会话令牌无效/过期 | 重新换取 token |
|
||
| 30001 | 机构不存在 | 检查 orgId |
|
||
| 30002 | 机构未授权 | 联系乐读派 |
|
||
| 30003 | 创作额度不足 | 联系乐读派充值 |
|
||
|
||
---
|
||
|
||
> 乐读派 AI 绘本创作系统 | 企业定制对接指南 V3.1 | 2026-04-03
|