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

## 📖 概述

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

## 🎯 功能特性

- ✅ **工作流上传**：支持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开发团队