lth/1818web-hoduan

Fork 0

Files

Claude Workbench 0f7bc05697 [Claude Workbench] Initial commit - preserving existing code

2025-11-14 17:41:15 +08:00

14 KiB

Raw Blame History

作品上传和更新接口完整文档

📖 概述

本文档详细说明了工作流和课程的上传、更新接口，包括详情图集功能的完整使用方法。

🎯 功能特性

✅ 工作流上传：支持JSON模式和文件模式
✅ 课程更新：支持完整的课程信息更新
✅ 详情图集：支持多张详情展示图片
✅ OSS文件上传：支持直接上传到阿里云OSS
✅ 向后兼容：不破坏现有功能

🔧 OSS文件上传接口

1. 获取OSS上传签名

接口信息

请求方法: POST
请求路径: /user/oss/post-signature/json
接口描述: 获取OSS POST签名，用于前端直接上传文件

请求参数

{
  "fileName": "example.jpg",
  "userId": "17543607206742139"
}

响应示例

{
  "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模式上传：

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

文件模式上传：

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

成功响应

{
  "code": 200,
  "message": "提交成功",
  "data": 12345
}

2. 工作流更新

接口信息

请求方法: PUT
请求路径: /user/content/workflows/{id}
接口描述: 更新工作流信息，包括数据包和演示视频

路径参数

参数名	类型	必填	说明
id	Long	是	工作流数据库ID

请求参数 (WorkflowUpdateRequest)

{
  "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	否	章节列表	[...]

完整请求示例

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

{
  "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. 前端处理示例

上传详情图集流程:

// 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,
  // ... 其他字段
};

解析详情图集:

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. 后端处理示例

// 设置详情图集
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. 接口测试示例

测试工作流上传:

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
  }'

测试课程更新:

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开发团队

14 KiB Raw Blame History Unescape Escape

作品上传和更新接口完整文档

📖 概述

🎯 功能特性

🔧 OSS文件上传接口

1. 获取OSS上传签名

🚀 工作流上传接口

1. 工作流上传/创建

2. 工作流更新

📚 课程更新接口

1. 课程完整更新

2. 课程简单更新

🖼️ 详情图集使用指南

1. 详情图集字段说明

2. 前端处理示例

3. 后端处理示例

📋 角色权限说明

⚠️ 重要注意事项

1. 数据验证

2. 文件限制

3. 审核机制

4. 向后兼容

🔍 调试和测试

1. 测试数据

2. 接口测试示例

📈 功能扩展

1. 已实现功能

2. 后续扩展方向

🆘 常见问题

14 KiB

Raw Blame History