480 lines
14 KiB
Markdown
480 lines
14 KiB
Markdown
# 作品上传和更新接口完整文档
|
||
|
||
## 📖 概述
|
||
|
||
本文档详细说明了工作流和课程的上传、更新接口，包括详情图集功能的完整使用方法。
|
||
|
||
## 🎯 功能特性
|
||
|
||
- ✅ **工作流上传**：支持JSON模式和文件模式
|
||
- ✅ **课程更新**：支持完整的课程信息更新
|
||
- ✅ **详情图集**：支持多张详情展示图片
|
||
- ✅ **OSS文件上传**：支持直接上传到阿里云OSS
|
||
- ✅ **向后兼容**：不破坏现有功能
|
||
|
||
---
|
||
|
||
## 🔧 OSS文件上传接口
|
||
|
||
### 1. 获取OSS上传签名
|
||
|
||
**接口信息**
|
||
- **请求方法**: `POST`
|
||
- **请求路径**: `/user/oss/post-signature/json`
|
||
- **接口描述**: 获取OSS POST签名，用于前端直接上传文件
|
||
|
||
**请求参数**
|
||
```json
|
||
{
|
||
"fileName": "example.jpg",
|
||
"userId": "17543607206742139"
|
||
}
|
||
```
|
||
|
||
**响应示例**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "POST签名生成成功",
|
||
"data": {
|
||
"url": "https://oss-1818ai-user-img.oss-cn-hangzhou.aliyuncs.com",
|
||
"dir": "user_imgs/17543607206742139/",
|
||
"policy": "eyJleHBpcmF0aW9uIjoi...",
|
||
"signature": "gM7d8D4zd+K...",
|
||
"x_oss_credential": "LTAI5t...",
|
||
"x_oss_date": "20241201T120000Z",
|
||
"version": "OSS4-HMAC-SHA256"
|
||
}
|
||
}
|
||
```
|
||
|
||
**支持文件类型**
|
||
- **图片格式**: jpg, jpeg, png, gif, bmp, webp
|
||
- **压缩包格式**: zip, rar, 7z, tar, gz, bz2, xz
|
||
- **文档格式**: pdf, txt, md, json, xml, csv
|
||
|
||
---
|
||
|
||
## 🚀 工作流上传接口
|
||
|
||
### 1. 工作流上传/创建
|
||
|
||
**接口信息**
|
||
- **请求方法**: `POST`
|
||
- **请求路径**: `/user/workflow/submit`
|
||
- **接口描述**: 支持JSON模式和文件模式的工作流上传
|
||
|
||
**请求参数 (Workflow)**
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 | 示例 |
|
||
|--------|------|------|------|------|
|
||
| **基本信息** |
|
||
| name | String | 否 | 工作流名称 | "智能图像生成工作流" |
|
||
| description | String | 否 | 工作流描述 | "基于AI的智能图像生成工作流" |
|
||
| coverUrl | String | 否 | 封面图片URL | "https://oss.../cover.jpg" |
|
||
| detailGallery | String | 否 | 详情图集(JSON数组字符串) | "[\"url1\",\"url2\"]" |
|
||
| category | String | 否 | 工作流分类 | "人工智能" |
|
||
| **数据内容 (二选一必填)** |
|
||
| data | String | 否* | 工作流JSON数据 | "{\"nodes\":[...],\"edges\":[...]}" |
|
||
| dataFileUrl | String | 否* | 工作流文件URL | "https://oss.../workflow.zip" |
|
||
| **视频信息 (必填)** |
|
||
| vodVideoId | String | 是 | 阿里云VOD视频ID | "a0776b0179bf71f0bea45017f1e90102" |
|
||
| videoId | String | 否 | 兼容字段(与vodVideoId同步) | "a0776b0179bf71f0bea45017f1e90102" |
|
||
| **权限和定价** |
|
||
| fullAccessRole | Integer | 否 | 查看权限角色(0-3) | 1 |
|
||
| copyAccessRole | Integer | 否 | 复制权限角色(0-3) | 1 |
|
||
| price | BigDecimal | 否 | 价格 | 29.99 |
|
||
| isFree | Integer | 否 | 是否免费(0/1) | 0 |
|
||
| isPublic | Integer | 否 | 是否公开(0/1) | 1 |
|
||
|
||
**完整请求示例**
|
||
|
||
**JSON模式上传：**
|
||
```json
|
||
{
|
||
"name": "智能图像生成工作流",
|
||
"description": "基于AI的智能图像生成工作流，支持多种图像风格转换",
|
||
"coverUrl": "https://oss-1818ai-user-img.oss-cn-hangzhou.aliyuncs.com/cover.jpg",
|
||
"detailGallery": "[\"https://oss-1818ai-user-img.oss-cn-hangzhou.aliyuncs.com/detail1.jpg\",\"https://oss-1818ai-user-img.oss-cn-hangzhou.aliyuncs.com/detail2.jpg\",\"https://oss-1818ai-user-img.oss-cn-hangzhou.aliyuncs.com/detail3.jpg\"]",
|
||
"vodVideoId": "a0776b0179bf71f0bea45017f1e90102",
|
||
"data": "{\"nodes\":[{\"id\":\"1\",\"type\":\"text\",\"data\":{\"text\":\"beautiful landscape\"}},{\"id\":\"2\",\"type\":\"image\",\"data\":{\"width\":512,\"height\":512}}],\"edges\":[{\"source\":\"1\",\"target\":\"2\"}]}",
|
||
"category": "人工智能",
|
||
"fullAccessRole": 1,
|
||
"copyAccessRole": 1,
|
||
"price": 29.99,
|
||
"isFree": 0,
|
||
"isPublic": 1
|
||
}
|
||
```
|
||
|
||
**文件模式上传：**
|
||
```json
|
||
{
|
||
"name": "ComfyUI工作流包",
|
||
"description": "包含完整依赖的ComfyUI工作流",
|
||
"coverUrl": "https://oss-1818ai-user-img.oss-cn-hangzhou.aliyuncs.com/cover.jpg",
|
||
"detailGallery": "[\"https://oss-1818ai-user-img.oss-cn-hangzhou.aliyuncs.com/detail1.jpg\",\"https://oss-1818ai-user-img.oss-cn-hangzhou.aliyuncs.com/detail2.jpg\"]",
|
||
"vodVideoId": "a0776b0179bf71f0bea45017f1e90102",
|
||
"dataFileUrl": "https://oss-1818ai-user-img.oss-cn-hangzhou.aliyuncs.com/workflows/comfyui_workflow.zip",
|
||
"category": "ComfyUI",
|
||
"fullAccessRole": 2,
|
||
"copyAccessRole": 2,
|
||
"price": 59.99,
|
||
"isFree": 0,
|
||
"isPublic": 1
|
||
}
|
||
```
|
||
|
||
**成功响应**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "提交成功",
|
||
"data": 12345
|
||
}
|
||
```
|
||
|
||
### 2. 工作流更新
|
||
|
||
**接口信息**
|
||
- **请求方法**: `PUT`
|
||
- **请求路径**: `/user/content/workflows/{id}`
|
||
- **接口描述**: 更新工作流信息，包括数据包和演示视频
|
||
|
||
**路径参数**
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | Long | 是 | 工作流数据库ID |
|
||
|
||
**请求参数 (WorkflowUpdateRequest)**
|
||
```json
|
||
{
|
||
"name": "更新的工作流名称",
|
||
"description": "更新的工作流描述",
|
||
"coverUrl": "https://oss.../new-cover.jpg",
|
||
"detailGallery": "[\"https://oss.../detail1.jpg\",\"https://oss.../detail2.jpg\"]",
|
||
"category": "新分类",
|
||
"isPublic": 1,
|
||
"fullAccessRole": 1,
|
||
"copyAccessRole": 2,
|
||
"price": 99.99,
|
||
"isFree": 0,
|
||
"data": "{\"nodes\":[...],\"edges\":[...]}",
|
||
"dataFileUrl": "https://oss.../updated-workflow.zip",
|
||
"vodVideoId": "new-video-id",
|
||
"videoId": "new-video-id"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 课程更新接口
|
||
|
||
### 1. 课程完整更新
|
||
|
||
**接口信息**
|
||
- **请求方法**: `PUT`
|
||
- **请求路径**: `/user/course/{id}`
|
||
- **接口描述**: 更新课程信息，包括章节和视频的完整更新
|
||
|
||
**路径参数**
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | Long | 是 | 课程ID |
|
||
|
||
**请求参数 (CourseUpdateDto)**
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 | 示例 |
|
||
|--------|------|------|------|------|
|
||
| **基本信息** |
|
||
| title | String | 否 | 课程标题 | "AI图像处理入门课程" |
|
||
| description | String | 否 | 课程描述 | "学习AI图像处理的基础知识" |
|
||
| coverUrl | String | 否 | 封面图URL | "https://oss.../cover.jpg" |
|
||
| detailGallery | String | 否 | 详情图集(JSON数组字符串) | "[\"url1\",\"url2\"]" |
|
||
| category | String | 否 | 课程分类 | "人工智能" |
|
||
| **权限与定价** |
|
||
| price | BigDecimal | 否 | 价格 | 99.99 |
|
||
| level | Integer | 否 | 访问级别(0-3) | 1 |
|
||
| isFree | Boolean | 否 | 是否免费 | false |
|
||
| **操作选项** |
|
||
| submitForAudit | Boolean | 否 | 是否提交审核 | false |
|
||
| deleteMissing | Boolean | 否 | 是否删除未提交的章节 | true |
|
||
| **章节信息** |
|
||
| chapters | List | 否 | 章节列表 | [...] |
|
||
|
||
**完整请求示例**
|
||
```json
|
||
{
|
||
"title": "AI图像处理完整教程",
|
||
"description": "从零开始学习AI图像处理技术，包含理论与实践",
|
||
"coverUrl": "https://oss-1818ai-user-img.oss-cn-hangzhou.aliyuncs.com/course-cover.jpg",
|
||
"detailGallery": "[\"https://oss-1818ai-user-img.oss-cn-hangzhou.aliyuncs.com/course-detail1.jpg\",\"https://oss-1818ai-user-img.oss-cn-hangzhou.aliyuncs.com/course-detail2.jpg\",\"https://oss-1818ai-user-img.oss-cn-hangzhou.aliyuncs.com/course-detail3.jpg\"]",
|
||
"price": 299.99,
|
||
"level": 1,
|
||
"category": "人工智能",
|
||
"isFree": false,
|
||
"submitForAudit": false,
|
||
"deleteMissing": true,
|
||
"chapters": [
|
||
{
|
||
"id": 123,
|
||
"title": "第一章：基础理论",
|
||
"description": "AI图像处理的基础理论知识",
|
||
"orderNum": 1,
|
||
"videos": [
|
||
{
|
||
"id": 456,
|
||
"title": "1.1 什么是AI图像处理",
|
||
"orderNum": 1,
|
||
"durationSec": 1800,
|
||
"vodVideoId": "vod-abc123"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 2. 课程简单更新
|
||
|
||
**接口信息**
|
||
- **请求方法**: `PUT`
|
||
- **请求路径**: `/user/content/courses`
|
||
- **接口描述**: 更新课程基本信息
|
||
|
||
**请求参数 (CourseUpdateRequest)**
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"title": "更新的课程标题",
|
||
"description": "更新的课程描述",
|
||
"coverUrl": "https://oss.../new-cover.jpg",
|
||
"detailGallery": "[\"https://oss.../detail1.jpg\",\"https://oss.../detail2.jpg\"]",
|
||
"category": "新分类",
|
||
"isFree": 0,
|
||
"level": 2
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🖼️ 详情图集使用指南
|
||
|
||
### 1. 详情图集字段说明
|
||
|
||
**字段名**: `detailGallery`
|
||
**数据类型**: `String` (JSON数组字符串格式)
|
||
**存储格式**: `["url1", "url2", "url3", ...]`
|
||
**用途**: 存储多张详情展示图片的URL
|
||
|
||
### 2. 前端处理示例
|
||
|
||
**上传详情图集流程**:
|
||
```javascript
|
||
// 1. 选择多张图片
|
||
const files = document.getElementById('detail-images').files;
|
||
|
||
// 2. 逐个上传到OSS
|
||
const uploadPromises = Array.from(files).map(async (file) => {
|
||
// 获取上传签名
|
||
const signResponse = await fetch('/user/oss/post-signature/json', {
|
||
method: 'POST',
|
||
headers: { 'Content-Type': 'application/json' },
|
||
body: JSON.stringify({
|
||
fileName: file.name,
|
||
userId: getCurrentUserId()
|
||
})
|
||
});
|
||
const signData = await signResponse.json();
|
||
|
||
// 上传文件到OSS
|
||
const formData = new FormData();
|
||
formData.append('key', signData.data.dir + file.name);
|
||
formData.append('policy', signData.data.policy);
|
||
formData.append('x-oss-credential', signData.data.x_oss_credential);
|
||
formData.append('x-oss-date', signData.data.x_oss_date);
|
||
formData.append('x-oss-signature-version', signData.data.version);
|
||
formData.append('x-oss-signature', signData.data.signature);
|
||
formData.append('success_action_status', '200');
|
||
formData.append('file', file);
|
||
|
||
await fetch(signData.data.url, {
|
||
method: 'POST',
|
||
body: formData
|
||
});
|
||
|
||
return signData.data.url + '/' + signData.data.dir + file.name;
|
||
});
|
||
|
||
// 3. 收集所有图片URL
|
||
const imageUrls = await Promise.all(uploadPromises);
|
||
|
||
// 4. 转换为JSON字符串
|
||
const detailGallery = JSON.stringify(imageUrls);
|
||
|
||
// 5. 提交工作流或课程
|
||
const submitData = {
|
||
name: "工作流名称",
|
||
detailGallery: detailGallery,
|
||
// ... 其他字段
|
||
};
|
||
```
|
||
|
||
**解析详情图集**:
|
||
```javascript
|
||
const parseDetailGallery = (detailGallery) => {
|
||
if (!detailGallery) return [];
|
||
try {
|
||
return JSON.parse(detailGallery);
|
||
} catch (e) {
|
||
console.error('解析详情图集失败:', e);
|
||
return [];
|
||
}
|
||
};
|
||
|
||
// 使用示例
|
||
const images = parseDetailGallery(workflow.detailGallery);
|
||
images.forEach(url => {
|
||
console.log('详情图片:', url);
|
||
});
|
||
```
|
||
|
||
### 3. 后端处理示例
|
||
|
||
```java
|
||
// 设置详情图集
|
||
List<String> imageUrls = Arrays.asList(
|
||
"https://oss.../detail1.jpg",
|
||
"https://oss.../detail2.jpg",
|
||
"https://oss.../detail3.jpg"
|
||
);
|
||
String detailGallery = objectMapper.writeValueAsString(imageUrls);
|
||
workflow.setDetailGallery(detailGallery);
|
||
|
||
// 解析详情图集
|
||
if (workflow.getDetailGallery() != null) {
|
||
List<String> imageUrls = objectMapper.readValue(
|
||
workflow.getDetailGallery(),
|
||
new TypeReference<List<String>>() {}
|
||
);
|
||
// 处理图片URL列表
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 角色权限说明
|
||
|
||
| 角色值 | 角色名称 | 说明 |
|
||
|--------|----------|------|
|
||
| 0 | 游客 | 未登录用户 |
|
||
| 1 | 普通用户 | 已注册登录用户 |
|
||
| 2 | VIP用户 | 付费会员用户 |
|
||
| 3 | SVIP用户 | 高级会员用户 |
|
||
|
||
---
|
||
|
||
## ⚠️ 重要注意事项
|
||
|
||
### 1. 数据验证
|
||
- **工作流上传**: `data` 或 `dataFileUrl` 必须提供其一
|
||
- **工作流上传**: `vodVideoId` 字段必填
|
||
- **详情图集**: 可选字段，支持空值
|
||
|
||
### 2. 文件限制
|
||
- **图片大小**: 建议不超过10MB
|
||
- **图片格式**: 支持jpg, jpeg, png, gif, bmp, webp
|
||
- **详情图集**: 建议2-5张图片
|
||
|
||
### 3. 审核机制
|
||
- **更新后重置**: 所有内容更新后将重置为待审核状态
|
||
- **审核通过**: 只有审核通过的内容才能正常展示
|
||
- **权限验证**: 只有内容所有者可以更新
|
||
|
||
### 4. 向后兼容
|
||
- ✅ 现有接口继续正常工作
|
||
- ✅ 现有数据不受影响
|
||
- ✅ 新字段为可选，不破坏现有功能
|
||
- ✅ API响应格式保持一致
|
||
|
||
---
|
||
|
||
## 🔍 调试和测试
|
||
|
||
### 1. 测试数据
|
||
数据库中已包含完整的测试数据：
|
||
- **工作流**: 4个工作流，包含详情图集示例
|
||
- **课程**: 16个课程，包含详情图集示例
|
||
- **用户**: 测试用户ID `17543607206742139`
|
||
|
||
### 2. 接口测试示例
|
||
|
||
**测试工作流上传**:
|
||
```bash
|
||
curl -X POST "http://localhost:8081/user/workflow/submit" \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer your-jwt-token" \
|
||
-d '{
|
||
"name": "测试工作流",
|
||
"detailGallery": "[\"https://example.com/1.jpg\"]",
|
||
"vodVideoId": "a0776b0179bf71f0bea45017f1e90102",
|
||
"data": "{\"nodes\":[],\"edges\":[]}",
|
||
"isFree": 1
|
||
}'
|
||
```
|
||
|
||
**测试课程更新**:
|
||
```bash
|
||
curl -X PUT "http://localhost:8081/user/course/1" \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer your-jwt-token" \
|
||
-d '{
|
||
"title": "更新的课程",
|
||
"detailGallery": "[\"https://example.com/1.jpg\",\"https://example.com/2.jpg\"]",
|
||
"price": 99.99
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
## 📈 功能扩展
|
||
|
||
### 1. 已实现功能
|
||
- ✅ 工作流上传和更新
|
||
- ✅ 课程更新
|
||
- ✅ 详情图集支持
|
||
- ✅ OSS文件上传
|
||
- ✅ 权限验证
|
||
- ✅ 审核流程
|
||
|
||
### 2. 后续扩展方向
|
||
- 🔄 批量图片处理
|
||
- 🔄 图片压缩优化
|
||
- 🔄 图片水印添加
|
||
- 🔄 图片CDN加速
|
||
|
||
---
|
||
|
||
## 🆘 常见问题
|
||
|
||
**Q: 详情图集可以上传多少张图片？**
|
||
A: 理论上无限制，建议2-5张图片以获得最佳用户体验。
|
||
|
||
**Q: 支持哪些图片格式？**
|
||
A: 支持 jpg, jpeg, png, gif, bmp, webp 格式。
|
||
|
||
**Q: 更新后为什么需要重新审核？**
|
||
A: 为确保内容质量，任何内容变更都需要重新审核。
|
||
|
||
**Q: 如何删除详情图集？**
|
||
A: 设置 `detailGallery` 为空字符串或null即可。
|
||
|
||
**Q: 接口是否支持批量操作？**
|
||
A: 目前支持单个内容的上传和更新，批量操作可通过多次调用实现。
|
||
|
||
---
|
||
|
||
**文档版本**: v1.0
|
||
**最后更新**: 2024-12-01
|
||
**维护团队**: 1818AI开发团队
|