# Jointo（jointo）API 对接设计规范文档

> **目标**：基于产品需求、数据库设计和 API 设计原则，提供完整、规范、可对接的 API 接口设计文档  
> **文档版本**：v1.0  
> **创建日期**：2025-01-27  
> **参考文档**：
>
> - `prd-super-video-workbench.md` - 产品需求与原始 API 定义
> - `prd-jointo-requirements.md` - 产品功能需求
> - `database-design.md` - PostgreSQL 数据库设计

---

## 目录

1. [API 设计原则](#1-api-设计原则)
2. [基础规范](#2-基础规范)
3. [数据模型映射](#3-数据模型映射)
4. [API 接口详细定义](#4-api-接口详细定义)
5. [错误处理规范](#5-错误处理规范)
6. [认证与授权](#6-认证与授权)
7. [性能优化建议](#7-性能优化建议)
8. [API 版本管理](#8-api-版本管理)
9. [接口清单](#9-接口清单)

---

## 1. API 设计原则

### 1.1 RESTful 设计原则

遵循 RESTful API 设计最佳实践：

- **资源导向**：URL 表示资源（名词），HTTP 方法表示操作（动词）
- **统一接口**：使用标准 HTTP 方法（GET、POST、PUT、PATCH、DELETE）
- **无状态**：每个请求包含所有必要信息，不依赖服务器状态
- **分层系统**：支持缓存、负载均衡等中间层
- **统一响应格式**：所有接口使用统一的响应结构

### 1.2 命名规范

- **资源名称**：使用复数形式（`/projects`、`/storyboards`）
- **URL 层级**：反映资源关系（`/projects/{id}/storyboards`）
- **字段命名**：使用 camelCase（与前端保持一致）
- **时间字段**：统一使用 ISO 8601 格式（`2025-01-27T10:30:00Z`）

### 1.3 HTTP 方法语义

| 方法   | 用途         | 幂等性 | 安全 |
| ------ | ------------ | ------ | ---- |
| GET    | 获取资源     | ✅     | ✅   |
| POST   | 创建资源     | ❌     | ❌   |
| PUT    | 完整更新资源 | ✅     | ❌   |
| PATCH  | 部分更新资源 | ❌     | ❌   |
| DELETE | 删除资源     | ✅     | ❌   |

---

## 2. 基础规范

### 2.1 协议与格式

- **协议**：HTTPS（生产环境）
- **数据格式**：JSON
- **字符编码**：UTF-8
- **API 版本**：URL 路径版本化（`/api/v1/`）

### 2.2 统一响应结构

#### 成功响应

```typescript
interface ApiSuccessResponse<T> {
  success: true;
  data: T;
  message?: string;
  meta?: {
    timestamp: string;
    requestId: string;
  };
}
```

#### 错误响应

```typescript
interface ApiErrorResponse {
  success: false;
  error: {
    code: string;
    message: string;
    details?: Record<string, any>;
    field?: string; // 字段级错误时使用
  };
  meta?: {
    timestamp: string;
    requestId: string;
  };
}
```

#### 分页响应

```typescript
interface ApiPaginatedResponse<T> {
  success: true;
  data: T[];
  pagination: {
    page: number;
    pageSize: number;
    total: number;
    totalPages: number;
    hasNext: boolean;
    hasPrev: boolean;
  };
  meta?: {
    timestamp: string;
    requestId: string;
  };
}
```

### 2.3 HTTP 状态码

| 状态码 | 含义                  | 使用场景                 |
| ------ | --------------------- | ------------------------ |
| 200    | OK                    | 成功获取资源             |
| 201    | Created               | 成功创建资源             |
| 204    | No Content            | 成功删除资源（无返回体） |
| 400    | Bad Request           | 请求参数错误             |
| 401    | Unauthorized          | 未认证                   |
| 403    | Forbidden             | 无权限                   |
| 404    | Not Found             | 资源不存在               |
| 409    | Conflict              | 资源冲突（如重复创建）   |
| 422    | Unprocessable Entity  | 业务逻辑验证失败         |
| 429    | Too Many Requests     | 请求频率超限             |
| 500    | Internal Server Error | 服务器错误               |
| 503    | Service Unavailable   | 服务不可用               |

### 2.4 请求头规范

```http
Authorization: Bearer {jwt_token}
Content-Type: application/json
Accept: application/json
X-Request-ID: {uuid}  # 可选，用于追踪请求
```

### 2.5 分页参数

所有列表接口支持分页：

```typescript
interface PaginationParams {
  page?: number; // 页码，从 1 开始，默认 1
  pageSize?: number; // 每页数量，默认 20，最大 100
  sortBy?: string; // 排序字段
  sortOrder?: "asc" | "desc"; // 排序方向，默认 'desc'
}
```

### 2.6 过滤参数

支持通用过滤参数：

```typescript
interface FilterParams {
  search?: string; // 全文搜索
  createdAfter?: string; // ISO 8601 时间
  createdBefore?: string; // ISO 8601 时间
  updatedAfter?: string; // ISO 8601 时间
  updatedBefore?: string; // ISO 8601 时间
}
```

---

## 3. 数据模型映射

### 3.1 数据库表与 API 资源映射

| 数据库表               | API 资源           | 端点前缀                                |
| ---------------------- | ------------------ | --------------------------------------- |
| `users`                | User               | `/api/v1/users`                         |
| `folders`              | Folder             | `/api/v1/folders`                       |
| `folder_members`       | FolderMember       | `/api/v1/folders/{id}/members`          |
| `projects`             | Project            | `/api/v1/projects`                      |
| `project_members`      | ProjectMember      | `/api/v1/projects/{id}/members`         |
| `storyboards`          | Storyboard         | `/api/v1/storyboards`                   |
| `resources`            | Resource           | `/api/v1/resources`                     |
| `storyboard_resources` | StoryboardResource | `/api/v1/storyboards/{id}/resources`    |
| `videos`               | Video              | `/api/v1/videos`                        |
| `sound_effects`        | SoundEffect        | `/api/v1/sound-effects`                 |
| `subtitles`            | Subtitle           | `/api/v1/subtitles`                     |
| `voiceovers`           | Voiceover          | `/api/v1/voiceovers`                    |
| `timeline_tracks`      | TimelineTrack      | `/api/v1/projects/{id}/timeline/tracks` |
| `timeline_items`       | TimelineItem       | `/api/v1/projects/{id}/timeline/items`  |
| `ai_jobs`              | AIJob              | `/api/v1/ai/jobs`                       |
| `comments`             | Comment            | `/api/v1/comments`                      |
| `notifications`        | Notification       | `/api/v1/notifications`                 |
| `export_jobs`          | ExportJob          | `/api/v1/projects/{id}/exports`         |

### 3.2 字段映射规则

- **数据库字段**：使用 snake_case（`created_at`、`user_id`）
- **API 字段**：使用 camelCase（`createdAt`、`userId`）
- **时间字段**：数据库存储 `TIMESTAMPTZ`，API 返回 ISO 8601 字符串
- **枚举类型**：数据库使用 ENUM，API 使用字符串字面量类型

---

## 4. API 接口详细定义

### 4.1 认证相关

#### 4.1.1 用户登录

```http
POST /api/v1/auth/login
Content-Type: application/json

Request Body:
{
  "email": "user@example.com",
  "password": "password123"
}

Response 200:
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "refresh_token_string",
    "expiresIn": 3600,
    "user": {
      "id": 1,
      "email": "user@example.com",
      "username": "username",
      "avatarUrl": "https://...",
      "subscriptionTier": "pro"
    }
  }
}
```

#### 4.1.2 刷新 Token

```http
POST /api/v1/auth/refresh
Content-Type: application/json

Request Body:
{
  "refreshToken": "refresh_token_string"
}

Response 200:
{
  "success": true,
  "data": {
    "token": "new_jwt_token",
    "expiresIn": 3600
  }
}
```

### 4.3 文件夹管理

#### 4.15.1 获取文件夹列表

```http
GET /api/v1/folders?parentId=1&includeProjects=true&page=1&pageSize=20
Authorization: Bearer {token}

Query Parameters:
- parentId?: number        // 父文件夹ID，不传则获取根文件夹
- includeProjects?: boolean // 是否包含文件夹内的项目，默认false
- includeSubfolders?: boolean // 是否包含子文件夹，默认true
- page?: number            // 页码，默认1
- pageSize?: number        // 每页数量，默认20
- search?: string          // 搜索文件夹名称

Response 200:
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "工作项目",
      "description": "工作相关的项目文件夹",
      "parentFolderId": null,
      "ownerId": 1,
      "path": "/工作项目",
      "level": 0,
      "sortOrder": 0,
      "color": "#3B82F6",
      "icon": "folder-work",
      "isShared": false,
      "createdAt": "2025-01-27T10:00:00Z",
      "updatedAt": "2025-01-27T10:00:00Z",
      "subfolders": [
        {
          "id": 2,
          "name": "客户A项目",
          "parentFolderId": 1,
          "path": "/工作项目/客户A项目",
          "level": 1,
          "projectCount": 3
        }
      ],
      "projects": [
        {
          "id": 1,
          "name": "宣传视频",
          "thumbnailUrl": "https://...",
          "updatedAt": "2025-01-27T12:00:00Z"
        }
      ],
      "projectCount": 5,
      "subfolderCount": 2
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 10,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}
```

#### 4.15.2 获取文件夹树形结构

```http
GET /api/v1/folders/tree?maxDepth=3&includeProjects=false
Authorization: Bearer {token}

Query Parameters:
- maxDepth?: number        // 最大深度，默认无限制
- includeProjects?: boolean // 是否包含项目，默认false
- folderId?: number        // 指定根文件夹ID，默认从用户根目录开始

Response 200:
{
  "success": true,
  "data": {
    "folders": [
      {
        "id": 1,
        "name": "工作项目",
        "path": "/工作项目",
        "level": 0,
        "color": "#3B82F6",
        "icon": "folder-work",
        "children": [
          {
            "id": 2,
            "name": "客户A项目",
            "path": "/工作项目/客户A项目",
            "level": 1,
            "children": []
          }
        ]
      }
    ]
  }
}
```

#### 4.15.3 获取文件夹详情

```http
GET /api/v1/folders/{folderId}
Authorization: Bearer {token}

Response 200:
{
  "success": true,
  "data": {
    "id": 1,
    "name": "工作项目",
    "description": "工作相关的项目文件夹",
    "parentFolderId": null,
    "ownerId": 1,
    "path": "/工作项目",
    "level": 0,
    "sortOrder": 0,
    "color": "#3B82F6",
    "icon": "folder-work",
    "isShared": false,
    "permissions": {
      "canEdit": true,
      "canDelete": true,
      "canShare": true,
      "canCreateSubfolder": true,
      "canCreateProject": true
    },
    "statistics": {
      "projectCount": 5,
      "subfolderCount": 2,
      "totalSize": 1024000000
    },
    "createdAt": "2025-01-27T10:00:00Z",
    "updatedAt": "2025-01-27T10:00:00Z",
    "_links": {
      "parent": "/api/v1/folders/0",
      "subfolders": "/api/v1/folders?parentId=1",
      "projects": "/api/v1/projects?folderId=1",
      "members": "/api/v1/folders/1/members"
    }
  }
}
```

#### 4.15.4 创建文件夹

```http
POST /api/v1/folders
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "name": "新文件夹",
  "description": "文件夹描述",
  "parentFolderId": 1,
  "color": "#10B981",
  "icon": "folder-custom",
  "sortOrder": 0
}

Response 201:
{
  "success": true,
  "data": {
    "id": 3,
    "name": "新文件夹",
    "description": "文件夹描述",
    "parentFolderId": 1,
    "ownerId": 1,
    "path": "/工作项目/新文件夹",
    "level": 1,
    "sortOrder": 0,
    "color": "#10B981",
    "icon": "folder-custom",
    "isShared": false,
    "createdAt": "2025-01-27T10:00:00Z",
    "updatedAt": "2025-01-27T10:00:00Z"
  },
  "message": "文件夹创建成功"
}
```

#### 4.15.5 更新文件夹

```http
PATCH /api/v1/folders/{folderId}
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "name": "更新后的文件夹名",
  "description": "更新后的描述",
  "color": "#EF4444",
  "icon": "folder-important",
  "sortOrder": 1
}

Response 200:
{
  "success": true,
  "data": {
    "id": 3,
    "name": "更新后的文件夹名",
    "description": "更新后的描述",
    "path": "/工作项目/更新后的文件夹名",
    "color": "#EF4444",
    "icon": "folder-important",
    "sortOrder": 1,
    "updatedAt": "2025-01-27T13:00:00Z"
  }
}
```

#### 4.15.6 移动文件夹

```http
POST /api/v1/folders/{folderId}/move
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "parentFolderId": 2,  // 新的父文件夹ID，null表示移动到根目录
  "sortOrder": 0        // 可选，在新位置的排序
}

Response 200:
{
  "success": true,
  "data": {
    "id": 3,
    "name": "移动的文件夹",
    "parentFolderId": 2,
    "path": "/工作项目/客户A项目/移动的文件夹",
    "level": 2,
    "sortOrder": 0,
    "updatedAt": "2025-01-27T13:00:00Z"
  },
  "message": "文件夹移动成功"
}
```

#### 4.15.7 删除文件夹

```http
DELETE /api/v1/folders/{folderId}?force=false
Authorization: Bearer {token}

Query Parameters:
- force?: boolean  // 是否强制删除（包含子文件夹和项目），默认false

Response 200 (软删除):
{
  "success": true,
  "message": "文件夹已删除，可在回收站中恢复"
}

Response 204 (强制删除):
No Content
```

#### 4.15.8 批量操作文件夹

```http
POST /api/v1/folders/batch
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "action": "move",  // 'move' | 'delete' | 'copy'
  "folderIds": [1, 2, 3],
  "targetFolderId": 4,  // 目标文件夹ID（move/copy操作）
  "force": false        // 是否强制操作（delete操作）
}

Response 200:
{
  "success": true,
  "data": {
    "processed": 3,
    "succeeded": 2,
    "failed": 1,
    "errors": [
      {
        "folderId": 3,
        "error": "权限不足"
      }
    ]
  },
  "message": "批量操作完成"
}
```

### 4.16 文件夹成员管理

#### 4.16.1 获取文件夹成员

```http
GET /api/v1/folders/{folderId}/members
Authorization: Bearer {token}

Response 200:
{
  "success": true,
  "data": {
    "members": [
      {
        "id": 1,
        "folderId": 1,
        "userId": 2,
        "user": {
          "id": 2,
          "username": "collaborator",
          "email": "collab@example.com",
          "avatarUrl": "https://..."
        },
        "role": "editor",
        "inherited": false,
        "invitedBy": 1,
        "joinedAt": "2025-01-27T10:00:00Z",
        "createdAt": "2025-01-27T10:00:00Z"
      }
    ]
  }
}
```

#### 4.16.2 添加文件夹成员

```http
POST /api/v1/folders/{folderId}/members
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "userId": 2,
  "role": "editor",
  "applyToSubfolders": true,  // 是否应用到子文件夹
  "applyToProjects": true     // 是否应用到文件夹内项目
}

Response 201:
{
  "success": true,
  "data": {
    "id": 1,
    "folderId": 1,
    "userId": 2,
    "role": "editor",
    "inherited": false,
    "createdAt": "2025-01-27T10:00:00Z"
  },
  "message": "成员添加成功"
}
```

#### 4.16.3 更新成员角色

```http
PATCH /api/v1/folders/{folderId}/members/{memberId}
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "role": "viewer",
  "applyToSubfolders": true,
  "applyToProjects": true
}

Response 200:
{
  "success": true,
  "data": {
    "id": 1,
    "role": "viewer",
    "updatedAt": "2025-01-27T13:00:00Z"
  }
}
```

#### 4.16.4 移除文件夹成员

```http
DELETE /api/v1/folders/{folderId}/members/{memberId}?removeFromSubfolders=true&removeFromProjects=false
Authorization: Bearer {token}

Query Parameters:
- removeFromSubfolders?: boolean  // 是否从子文件夹中移除
- removeFromProjects?: boolean    // 是否从项目中移除

Response 204 No Content
```

### 4.14 项目管理（更新）

#### 4.14.1 获取项目列表

```http
GET /api/v1/projects?type=mine&folderId=1&page=1&pageSize=20&sortBy=updatedAt&sortOrder=desc
Authorization: Bearer {token}

Query Parameters:
- type?: 'mine' | 'collab'  // 项目类型
- folderId?: number         // 文件夹ID，null表示根目录项目
- page?: number            // 页码，默认 1
- pageSize?: number        // 每页数量，默认 20
- sortBy?: string          // 排序字段，默认 'updatedAt'
- sortOrder?: 'asc' | 'desc'  // 排序方向，默认 'desc'
- search?: string          // 搜索项目名称

Response 200:
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "西游记之大圣归来",
      "description": "项目描述",
      "type": "mine",
      "ownerId": 1,
      "folderId": 1,
      "folderPath": "/工作项目",
      "thumbnailUrl": "https://...",
      "settings": {
        "resolution": { "width": 1920, "height": 1080 },
        "frameRate": 30,
        "duration": 60,
        "exportFormat": "mp4",
        "exportQuality": "high"
      },
      "status": "active",
      "createdAt": "2025-01-27T10:00:00Z",
      "updatedAt": "2025-01-27T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 100,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": false
  }
}
```

#### 4.14.2 获取项目详情

```http
GET /api/v1/projects/{projectId}
Authorization: Bearer {token}

Response 200:
{
  "success": true,
  "data": {
    "id": 1,
    "name": "西游记之大圣归来",
    "description": "项目描述",
    "type": "mine",
    "ownerId": 1,
    "folderId": 1,
    "folder": {
      "id": 1,
      "name": "工作项目",
      "path": "/工作项目"
    },
    "thumbnailUrl": "https://...",
    "settings": {
      "resolution": { "width": 1920, "height": 1080 },
      "frameRate": 30,
      "duration": 60
    },
    "status": "active",
    "createdAt": "2025-01-27T10:00:00Z",
    "updatedAt": "2025-01-27T12:00:00Z",
    "_links": {
      "storyboards": "/api/v1/projects/1/storyboards",
      "members": "/api/v1/projects/1/members",
      "timeline": "/api/v1/projects/1/timeline",
      "folder": "/api/v1/folders/1"
    }
  }
}
```

#### 4.14.3 创建项目

```http
POST /api/v1/projects
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "name": "新项目",
  "description": "项目描述",
  "type": "mine",
  "folderId": 1,  // 可选，指定文件夹
  "settings": {
    "resolution": { "width": 1920, "height": 1080 },
    "frameRate": 30,
    "duration": 60
  }
}

Response 201:
{
  "success": true,
  "data": {
    "id": 1,
    "name": "新项目",
    "description": "项目描述",
    "type": "mine",
    "ownerId": 1,
    "folderId": 1,
    "settings": { ... },
    "createdAt": "2025-01-27T10:00:00Z",
    "updatedAt": "2025-01-27T10:00:00Z"
  },
  "message": "项目创建成功"
}
```

#### 4.14.4 移动项目到文件夹

```http
POST /api/v1/projects/{projectId}/move
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "folderId": 2  // 目标文件夹ID，null表示移动到根目录
}

Response 200:
{
  "success": true,
  "data": {
    "id": 1,
    "name": "项目名称",
    "folderId": 2,
    "folderPath": "/工作项目/客户A项目",
    "updatedAt": "2025-01-27T13:00:00Z"
  },
  "message": "项目移动成功"
}
```

#### 4.14.5 批量移动项目

```http
POST /api/v1/projects/batch/move
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "projectIds": [1, 2, 3],
  "folderId": 2
}

Response 200:
{
  "success": true,
  "data": {
    "processed": 3,
    "succeeded": 3,
    "failed": 0
  },
  "message": "批量移动完成"
}
```

#### 4.14.6 更新项目

```http
PATCH /api/v1/projects/{projectId}
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "name": "更新后的项目名",
  "description": "更新后的描述",
  "folderId": 2,  // 可选，移动到新文件夹
  "settings": {
    "resolution": { "width": 3840, "height": 2160 }
  }
}

Response 200:
{
  "success": true,
  "data": {
    "id": 1,
    "name": "更新后的项目名",
    "folderId": 2,
    "folderPath": "/工作项目/客户A项目",
    ...
    "updatedAt": "2025-01-27T13:00:00Z"
  }
}
```

#### 4.14.7 删除项目

```http
DELETE /api/v1/projects/{projectId}
Authorization: Bearer {token}

Response 204 No Content
```

#### 4.14.8 导出项目

```http
POST /api/v1/projects/{projectId}/exports
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "format": "mp4",
  "quality": "high",
  "resolution": { "width": 1920, "height": 1080 },
  "includeWatermark": false
}

Response 202 Accepted:
{
  "success": true,
  "data": {
    "jobId": "export_123456",
    "status": "pending",
    "estimatedCompletionAt": "2025-01-27T14:00:00Z"
  },
  "message": "导出任务已创建"
}
```

### 4.15 分镜管理

#### 4.15.1 获取项目分镜列表

```http
GET /api/v1/projects/{projectId}/storyboards?sortBy=orderIndex&sortOrder=asc
Authorization: Bearer {token}

Response 200:
{
  "success": true,
  "data": [
    {
      "id": 1,
      "projectId": 1,
      "title": "分镜1",
      "description": "清晨的阳光照进窗户...",
      "thumbnailUrl": "https://...",
      "orderIndex": 1,
      "startTime": 0.000,
      "endTime": 10.000,
      "transitionType": "fade",
      "transitionDuration": 0.5,
      "createdAt": "2025-01-27T10:00:00Z",
      "updatedAt": "2025-01-27T10:00:00Z"
    }
  ]
}
```

#### 4.15.2 获取分镜详情

```http
GET /api/v1/storyboards/{storyboardId}
Authorization: Bearer {token}

Response 200:
{
  "success": true,
  "data": {
    "id": 1,
    "projectId": 1,
    "title": "分镜1",
    "description": "详细描述",
    "thumbnailUrl": "https://...",
    "orderIndex": 1,
    "startTime": 0.000,
    "endTime": 10.000,
    "transitionType": "fade",
    "transitionDuration": 0.5,
    "resources": {
      "characters": [...],
      "scenes": [...],
      "props": [...]
    },
    "createdAt": "2025-01-27T10:00:00Z",
    "updatedAt": "2025-01-27T10:00:00Z"
  }
}
```

#### 4.15.3 创建分镜

```http
POST /api/v1/projects/{projectId}/storyboards
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "title": "分镜7",
  "description": "新分镜描述",
  "orderIndex": 7,  // 可选，不传则追加到最后
  "startTime": 60.000,
  "endTime": 70.000
}

Response 201:
{
  "success": true,
  "data": {
    "id": 7,
    "projectId": 1,
    "title": "分镜7",
    "description": "新分镜描述",
    "orderIndex": 7,
    "startTime": 60.000,
    "endTime": 70.000,
    "createdAt": "2025-01-27T10:00:00Z",
    "updatedAt": "2025-01-27T10:00:00Z"
  }
}
```

#### 4.15.4 更新分镜

```http
PATCH /api/v1/storyboards/{storyboardId}
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "title": "更新后的标题",
  "description": "更新后的描述",
  "startTime": 5.000,
  "endTime": 15.000,
  "orderIndex": 2
}

Response 200:
{
  "success": true,
  "data": {
    "id": 1,
    "title": "更新后的标题",
    ...
    "updatedAt": "2025-01-27T13:00:00Z"
  }
}
```

#### 4.15.5 删除分镜

```http
DELETE /api/v1/storyboards/{storyboardId}
Authorization: Bearer {token}

Response 204 No Content
```

#### 4.15.6 更新分镜资源

```http
PUT /api/v1/storyboards/{storyboardId}/resources
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "characters": [
    { "resourceId": 1, "displayOrder": 0 }
  ],
  "scenes": [
    { "resourceId": 2, "displayOrder": 0 }
  ],
  "props": [
    { "resourceId": 3, "displayOrder": 0 },
    { "resourceId": 4, "displayOrder": 1 }
  ]
}

Response 200:
{
  "success": true,
  "data": {
    "characters": [...],
    "scenes": [...],
    "props": [...]
  }
}
```

### 4.16 资源管理

#### 4.16.1 获取资源列表

```http
GET /api/v1/resources?type=character&projectId=1&page=1&pageSize=20&search=主角
Authorization: Bearer {token}

Query Parameters:
- type?: 'character' | 'scene' | 'prop'
- projectId?: number
- storyboardId?: number
- search?: string
- page?: number
- pageSize?: number

Response 200:
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "主角-睡姿",
      "type": "character",
      "fileUrl": "https://...",
      "thumbnailUrl": "https://...",
      "fileSize": 1024000,
      "mimeType": "image/png",
      "width": 1920,
      "height": 1080,
      "metadata": {},
      "createdBy": 1,
      "isPublic": false,
      "createdAt": "2025-01-27T10:00:00Z",
      "updatedAt": "2025-01-27T10:00:00Z"
    }
  ],
  "pagination": { ... }
}
```

#### 4.16.2 上传资源

```http
POST /api/v1/resources
Authorization: Bearer {token}
Content-Type: multipart/form-data

Form Data:
- file: File
- name: string
- type: 'character' | 'scene' | 'prop'
- projectId?: number
- storyboardId?: number

Response 201:
{
  "success": true,
  "data": {
    "id": 1,
    "name": "新资源",
    "type": "character",
    "fileUrl": "https://...",
    "thumbnailUrl": "https://...",
    ...
    "createdAt": "2025-01-27T10:00:00Z"
  }
}
```

#### 4.16.3 删除资源

```http
DELETE /api/v1/resources/{resourceId}
Authorization: Bearer {token}

Response 204 No Content
```

### 4.14 视频管理

#### 4.14.1 获取视频列表

```http
GET /api/v1/videos?projectId=1&storyboardId=1&page=1&pageSize=20
Authorization: Bearer {token}

Response 200:
{
  "success": true,
  "data": [
    {
      "id": 1,
      "projectId": 1,
      "storyboardId": 1,
      "name": "睁眼",
      "type": "img2video",
      "videoUrl": "https://...",
      "thumbnailUrl": "https://...",
      "duration": 2.000,
      "fileSize": 10240000,
      "width": 1920,
      "height": 1080,
      "frameRate": 30.0,
      "startTime": 0.000,
      "endTime": 2.000,
      "metadata": {
        "prompt": "...",
        "model": "model_name",
        "aiJobId": 123
      },
      "status": "completed",
      "createdBy": 1,
      "createdAt": "2025-01-27T10:00:00Z",
      "updatedAt": "2025-01-27T10:00:00Z"
    }
  ],
  "pagination": { ... }
}
```

#### 4.14.2 创建视频

```http
POST /api/v1/videos
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "projectId": 1,
  "storyboardId": 1,
  "name": "新视频",
  "type": "img2video",
  "startTime": 0.000,
  "endTime": 5.000,
  "metadata": {
    "prompt": "视频描述",
    "model": "model_name"
  }
}

Response 201:
{
  "success": true,
  "data": {
    "id": 1,
    "name": "新视频",
    "type": "img2video",
    "status": "pending",
    ...
    "createdAt": "2025-01-27T10:00:00Z"
  }
}
```

#### 4.14.3 更新视频

```http
PATCH /api/v1/videos/{videoId}
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "name": "更新后的视频名",
  "startTime": 2.000,
  "endTime": 7.000,
  "thumbnailUrl": "https://..."
}

Response 200:
{
  "success": true,
  "data": {
    "id": 1,
    "name": "更新后的视频名",
    ...
    "updatedAt": "2025-01-27T13:00:00Z"
  }
}
```

#### 4.14.4 删除视频

```http
DELETE /api/v1/videos/{videoId}
Authorization: Bearer {token}

Response 204 No Content
```

### 4.15 音效管理

#### 4.15.1 获取音效列表

```http
GET /api/v1/sound-effects?projectId=1&page=1&pageSize=20
Authorization: Bearer {token}

Response 200:
{
  "success": true,
  "data": [
    {
      "id": 1,
      "projectId": 1,
      "name": "鸟叫",
      "audioUrl": "https://...",
      "duration": 3.000,
      "fileSize": 512000,
      "startTime": 0.000,
      "endTime": 3.000,
      "volume": 80,
      "fadeIn": 0.5,
      "fadeOut": 0.5,
      "metadata": {},
      "status": "completed",
      "createdBy": 1,
      "createdAt": "2025-01-27T10:00:00Z",
      "updatedAt": "2025-01-27T10:00:00Z"
    }
  ],
  "pagination": { ... }
}
```

#### 4.15.2 创建音效

```http
POST /api/v1/sound-effects
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "projectId": 1,
  "name": "新音效",
  "startTime": 0.000,
  "endTime": 5.000,
  "volume": 100,
  "fadeIn": 0.5,
  "fadeOut": 0.5,
  "audioUrl": "https://..."  // 或通过上传接口获取
}

Response 201:
{
  "success": true,
  "data": {
    "id": 1,
    "name": "新音效",
    ...
    "createdAt": "2025-01-27T10:00:00Z"
  }
}
```

#### 4.15.3 更新音效

```http
PATCH /api/v1/sound-effects/{soundEffectId}
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "name": "更新后的音效名",
  "startTime": 2.000,
  "endTime": 7.000,
  "volume": 90
}

Response 200:
{
  "success": true,
  "data": {
    "id": 1,
    "name": "更新后的音效名",
    ...
    "updatedAt": "2025-01-27T13:00:00Z"
  }
}
```

#### 4.15.4 删除音效

```http
DELETE /api/v1/sound-effects/{soundEffectId}
Authorization: Bearer {token}

Response 204 No Content
```

### 4.16 字幕管理

#### 4.16.1 获取字幕列表

```http
GET /api/v1/subtitles?projectId=1&page=1&pageSize=20
Authorization: Bearer {token}

Response 200:
{
  "success": true,
  "data": [
    {
      "id": 1,
      "projectId": 1,
      "text": "早安",
      "startTime": 0.000,
      "endTime": 2.000,
      "style": {
        "fontSize": 16,
        "color": "#FFFFFF",
        "position": "bottom",
        "backgroundColor": "#000000",
        "fontFamily": "Arial"
      },
      "metadata": {},
      "status": "completed",
      "createdBy": 1,
      "createdAt": "2025-01-27T10:00:00Z",
      "updatedAt": "2025-01-27T10:00:00Z"
    }
  ],
  "pagination": { ... }
}
```

#### 4.16.2 创建字幕

```http
POST /api/v1/subtitles
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "projectId": 1,
  "text": "新字幕",
  "startTime": 0.000,
  "endTime": 3.000,
  "style": {
    "fontSize": 18,
    "color": "#FFFFFF",
    "position": "bottom"
  }
}

Response 201:
{
  "success": true,
  "data": {
    "id": 1,
    "text": "新字幕",
    ...
    "createdAt": "2025-01-27T10:00:00Z"
  }
}
```

#### 4.16.3 更新字幕

```http
PATCH /api/v1/subtitles/{subtitleId}
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "text": "更新后的字幕",
  "startTime": 1.000,
  "endTime": 4.000,
  "style": {
    "fontSize": 20
  }
}

Response 200:
{
  "success": true,
  "data": {
    "id": 1,
    "text": "更新后的字幕",
    ...
    "updatedAt": "2025-01-27T13:00:00Z"
  }
}
```

#### 4.16.4 删除字幕

```http
DELETE /api/v1/subtitles/{subtitleId}
Authorization: Bearer {token}

Response 204 No Content
```

### 4.14 配音管理

#### 4.14.1 获取配音列表

```http
GET /api/v1/voiceovers?projectId=1&page=1&pageSize=20
Authorization: Bearer {token}

Response 200:
{
  "success": true,
  "data": [
    {
      "id": 1,
      "projectId": 1,
      "text": "旁白1：清晨醒来",
      "audioUrl": "https://...",
      "duration": 5.000,
      "fileSize": 256000,
      "startTime": 0.000,
      "endTime": 5.000,
      "voiceType": "male_01",
      "voiceSpeed": 1.0,
      "volume": 100,
      "metadata": {},
      "status": "completed",
      "createdBy": 1,
      "createdAt": "2025-01-27T10:00:00Z",
      "updatedAt": "2025-01-27T10:00:00Z"
    }
  ],
  "pagination": { ... }
}
```

#### 4.14.2 创建配音

```http
POST /api/v1/voiceovers
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "projectId": 1,
  "text": "旁白文本",
  "startTime": 0.000,
  "endTime": 5.000,
  "voiceType": "male_01",
  "voiceSpeed": 1.0,
  "volume": 100
}

Response 201:
{
  "success": true,
  "data": {
    "id": 1,
    "text": "旁白文本",
    "status": "pending",
    ...
    "createdAt": "2025-01-27T10:00:00Z"
  }
}
```

#### 4.14.3 更新配音

```http
PATCH /api/v1/voiceovers/{voiceoverId}
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "text": "更新后的旁白",
  "startTime": 2.000,
  "endTime": 7.000,
  "voiceType": "female_01",
  "volume": 90
}

Response 200:
{
  "success": true,
  "data": {
    "id": 1,
    "text": "更新后的旁白",
    ...
    "updatedAt": "2025-01-27T13:00:00Z"
  }
}
```

#### 4.14.4 删除配音

```http
DELETE /api/v1/voiceovers/{voiceoverId}
Authorization: Bearer {token}

Response 204 No Content
```

### 4.15 AI 生成 API

#### 4.15.1 生成图片

```http
POST /api/v1/ai/generate-image
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "prompt": "一位中年男性,穿着正装,站在办公室里",
  "model": "stable-diffusion-v2",
  "parameters": {
    "width": 1920,
    "height": 1080,
    "style": "realistic",
    "negativePrompt": "blurry, low quality"
  },
  "storyboardId": 1
}

Response 202 Accepted:
{
  "success": true,
  "data": {
    "jobId": "ai_job_123456",
    "status": "pending",
    "estimatedCompletionAt": "2025-01-27T10:05:00Z"
  }
}
```

#### 4.15.2 角度变换

```http
POST /api/v1/ai/transform-angle
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "imageUrl": "https://...",
  "angle": "side",
  "model": "angle-transformer-v1"
}

Response 202 Accepted:
{
  "success": true,
  "data": {
    "jobId": "ai_job_123457",
    "status": "pending"
  }
}
```

#### 4.15.3 镜头调整

```http
POST /api/v1/ai/adjust-lens
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "imageUrl": "https://...",
  "lensType": "wide",
  "model": "lens-adjuster-v1"
}

Response 202 Accepted:
{
  "success": true,
  "data": {
    "jobId": "ai_job_123458",
    "status": "pending"
  }
}
```

#### 4.15.4 生成资源素材

```http
POST /api/v1/ai/generate-resource
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "type": "character",
  "prompt": "主角-睡姿",
  "storyboardId": 1,
  "model": "resource-generator-v1"
}

Response 202 Accepted:
{
  "success": true,
  "data": {
    "jobId": "ai_job_123459",
    "status": "pending"
  }
}
```

#### 4.15.5 生成视频

```http
POST /api/v1/ai/generate-video
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "type": "img2video",
  "imageUrl": "https://...",
  "prompt": "视频描述",
  "storyboardId": 1,
  "model": "video-generator-v1",
  "parameters": {
    "duration": 5.0,
    "fps": 30
  }
}

Response 202 Accepted:
{
  "success": true,
  "data": {
    "jobId": "ai_job_123460",
    "status": "pending",
    "estimatedCompletionAt": "2025-01-27T10:10:00Z"
  }
}
```

#### 4.15.6 生成音效

```http
POST /api/v1/ai/generate-sound
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "prompt": "鸟叫声",
  "duration": 3.0,
  "model": "sound-generator-v1"
}

Response 202 Accepted:
{
  "success": true,
  "data": {
    "jobId": "ai_job_123461",
    "status": "pending"
  }
}
```

#### 4.15.7 生成字幕

```http
POST /api/v1/ai/generate-subtitle
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "videoId": 1,
  "prompt": "生成字幕",
  "startTime": 0.000,
  "endTime": 5.000,
  "model": "subtitle-generator-v1"
}

Response 201:
{
  "success": true,
  "data": {
    "id": 1,
    "text": "生成的字幕文本",
    "startTime": 0.000,
    "endTime": 5.000,
    ...
    "createdAt": "2025-01-27T10:00:00Z"
  }
}
```

#### 4.15.8 生成配音

```http
POST /api/v1/ai/generate-voiceover
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "text": "旁白文本",
  "voiceType": "male_01",
  "startTime": 0.000,
  "endTime": 5.000,
  "model": "voice-generator-v1"
}

Response 202 Accepted:
{
  "success": true,
  "data": {
    "jobId": "ai_job_123462",
    "status": "pending"
  }
}
```

#### 4.15.9 查询 AI 任务状态

```http
GET /api/v1/ai/jobs/{jobId}
Authorization: Bearer {token}

Response 200:
{
  "success": true,
  "data": {
    "jobId": "ai_job_123456",
    "userId": 1,
    "projectId": 1,
    "storyboardId": 1,
    "jobType": "image",
    "status": "processing",
    "progress": 65,
    "prompt": "生成图片",
    "model": "stable-diffusion-v2",
    "parameters": {},
    "result": {
      "imageUrl": "https://...",
      "thumbnailUrl": "https://..."
    },
    "errorMessage": null,
    "estimatedCompletionAt": "2025-01-27T10:05:00Z",
    "startedAt": "2025-01-27T10:00:00Z",
    "completedAt": null,
    "cost": 0.05,
    "creditsUsed": 1,
    "createdAt": "2025-01-27T10:00:00Z",
    "updatedAt": "2025-01-27T10:03:00Z"
  }
}
```

### 4.16 分镜看板管理

#### 4.16.1 获取项目分镜看板

```http
GET /api/v1/projects/{projectId}/timeline
Authorization: Bearer {token}

Response 200:
{
  "success": true,
  "data": {
    "tracks": [
      {
        "id": 1,
        "projectId": 1,
        "type": "storyboard",
        "name": "分镜轨道",
        "displayOrder": 0,
        "visible": true,
        "locked": false,
        "height": 60,
        "createdAt": "2025-01-27T10:00:00Z",
        "updatedAt": "2025-01-27T10:00:00Z"
      }
    ],
    "items": [
      {
        "id": 1,
        "trackId": 1,
        "itemType": "storyboard",
        "storyboardId": 1,
        "startTime": 0.000,
        "endTime": 10.000,
        "displayOrder": 0,
        "createdAt": "2025-01-27T10:00:00Z",
        "updatedAt": "2025-01-27T10:00:00Z"
      }
    ]
  }
}
```

#### 4.16.2 更新分镜看板

```http
PUT /api/v1/projects/{projectId}/timeline
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "tracks": [
    {
      "id": 1,
      "type": "storyboard",
      "name": "分镜轨道",
      "displayOrder": 0,
      "visible": true,
      "locked": false,
      "height": 60
    }
  ],
  "items": [
    {
      "id": 1,
      "trackId": 1,
      "itemType": "storyboard",
      "storyboardId": 1,
      "startTime": 0.000,
      "endTime": 10.000,
      "displayOrder": 0
    }
  ]
}

Response 200:
{
  "success": true,
  "data": {
    "tracks": [...],
    "items": [...]
  }
}
```

### 4.14 项目成员管理

#### 4.14.1 获取项目成员

```http
GET /api/v1/projects/{projectId}/members
Authorization: Bearer {token}

Response 200:
{
  "success": true,
  "data": {
    "members": [
      {
        "id": 1,
        "projectId": 1,
        "userId": 2,
        "user": {
          "id": 2,
          "username": "collaborator",
          "email": "collab@example.com",
          "avatarUrl": "https://..."
        },
        "role": "editor",
        "invitedBy": 1,
        "joinedAt": "2025-01-27T10:00:00Z",
        "createdAt": "2025-01-27T10:00:00Z"
      }
    ]
  }
}
```

#### 4.14.2 添加项目成员

```http
POST /api/v1/projects/{projectId}/members
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "userId": 2,
  "role": "editor"
}

Response 201:
{
  "success": true,
  "data": {
    "id": 1,
    "projectId": 1,
    "userId": 2,
    "role": "editor",
    ...
    "createdAt": "2025-01-27T10:00:00Z"
  }
}
```

#### 4.14.3 更新成员角色

```http
PATCH /api/v1/projects/{projectId}/members/{memberId}
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "role": "viewer"
}

Response 200:
{
  "success": true,
  "data": {
    "id": 1,
    "role": "viewer",
    ...
    "updatedAt": "2025-01-27T13:00:00Z"
  }
}
```

#### 4.14.4 移除项目成员

```http
DELETE /api/v1/projects/{projectId}/members/{memberId}
Authorization: Bearer {token}

Response 204 No Content
```

### 4.15 评论管理

#### 4.15.1 获取评论列表

```http
GET /api/v1/comments?projectId=1&storyboardId=1&page=1&pageSize=20
Authorization: Bearer {token}

Response 200:
{
  "success": true,
  "data": [
    {
      "id": 1,
      "projectId": 1,
      "storyboardId": 1,
      "content": "这个分镜需要调整",
      "parentCommentId": null,
      "mentionedUserIds": [2],
      "author": {
        "id": 1,
        "username": "author",
        "avatarUrl": "https://..."
      },
      "timePosition": 5.000,
      "isResolved": false,
      "resolvedBy": null,
      "resolvedAt": null,
      "createdAt": "2025-01-27T10:00:00Z",
      "updatedAt": "2025-01-27T10:00:00Z"
    }
  ],
  "pagination": { ... }
}
```

#### 4.15.2 创建评论

```http
POST /api/v1/comments
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "projectId": 1,
  "storyboardId": 1,
  "content": "新评论",
  "timePosition": 5.000,
  "mentionedUserIds": [2]
}

Response 201:
{
  "success": true,
  "data": {
    "id": 1,
    "content": "新评论",
    ...
    "createdAt": "2025-01-27T10:00:00Z"
  }
}
```

### 4.16 通知管理

#### 4.16.1 获取通知列表

```http
GET /api/v1/notifications?unreadOnly=true&page=1&pageSize=20
Authorization: Bearer {token}

Response 200:
{
  "success": true,
  "data": [
    {
      "id": 1,
      "userId": 1,
      "type": "comment",
      "title": "新评论",
      "content": "用户 @collaborator 评论了你的项目",
      "relatedData": {
        "projectId": 1,
        "commentId": 1
      },
      "isRead": false,
      "readAt": null,
      "createdAt": "2025-01-27T10:00:00Z"
    }
  ],
  "pagination": { ... }
}
```

#### 4.16.2 标记通知为已读

```http
PATCH /api/v1/notifications/{notificationId}/read
Authorization: Bearer {token}

Response 200:
{
  "success": true,
  "data": {
    "id": 1,
    "isRead": true,
    "readAt": "2025-01-27T13:00:00Z"
  }
}
```

---

## 5. 错误处理规范

### 5.1 错误码定义

```typescript
enum ApiErrorCode {
  // 通用错误 (1xxx)
  UNAUTHORIZED = "UNAUTHORIZED", // 401
  FORBIDDEN = "FORBIDDEN", // 403
  NOT_FOUND = "NOT_FOUND", // 404
  VALIDATION_ERROR = "VALIDATION_ERROR", // 400
  INTERNAL_ERROR = "INTERNAL_ERROR", // 500
  RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED", // 429

  // 业务错误 - 项目 (2xxx)
  PROJECT_NOT_FOUND = "PROJECT_NOT_FOUND",
  PROJECT_ACCESS_DENIED = "PROJECT_ACCESS_DENIED",
  PROJECT_NAME_DUPLICATE = "PROJECT_NAME_DUPLICATE",

  // 业务错误 - 分镜 (3xxx)
  STORYBOARD_NOT_FOUND = "STORYBOARD_NOT_FOUND",
  STORYBOARD_ORDER_INVALID = "STORYBOARD_ORDER_INVALID",
  STORYBOARD_TIME_OVERLAP = "STORYBOARD_TIME_OVERLAP",

  // 业务错误 - AI (4xxx)
  AI_GENERATION_FAILED = "AI_GENERATION_FAILED",
  AI_GENERATION_TIMEOUT = "AI_GENERATION_TIMEOUT",
  AI_CREDITS_INSUFFICIENT = "AI_CREDITS_INSUFFICIENT",
  AI_JOB_NOT_FOUND = "AI_JOB_NOT_FOUND",

  // 业务错误 - 导出 (5xxx)
  EXPORT_FAILED = "EXPORT_FAILED",
  EXPORT_JOB_NOT_FOUND = "EXPORT_JOB_NOT_FOUND",
  EXPORT_FORMAT_NOT_SUPPORTED = "EXPORT_FORMAT_NOT_SUPPORTED",
}
```

### 5.2 错误响应示例

#### 验证错误

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "请求参数验证失败",
    "details": {
      "errors": [
        {
          "field": "name",
          "message": "项目名称不能为空",
          "value": ""
        },
        {
          "field": "type",
          "message": "项目类型必须是 'mine' 或 'collab'",
          "value": "invalid"
        }
      ]
    }
  },
  "meta": {
    "timestamp": "2025-01-27T10:00:00Z",
    "requestId": "req_123456"
  }
}
```

#### 资源不存在

```json
{
  "success": false,
  "error": {
    "code": "PROJECT_NOT_FOUND",
    "message": "项目不存在",
    "details": {
      "projectId": 999
    }
  },
  "meta": {
    "timestamp": "2025-01-27T10:00:00Z",
    "requestId": "req_123457"
  }
}
```

#### 权限不足

```json
{
  "success": false,
  "error": {
    "code": "PROJECT_ACCESS_DENIED",
    "message": "您没有权限访问此项目",
    "details": {
      "projectId": 1,
      "requiredRole": "editor",
      "userRole": "viewer"
    }
  },
  "meta": {
    "timestamp": "2025-01-27T10:00:00Z",
    "requestId": "req_123458"
  }
}
```

---

## 6. 认证与授权

### 6.1 JWT Token 认证

- **Token 格式**：Bearer Token
- **Token 有效期**：1 小时
- **Refresh Token 有效期**：7 天
- **Token 刷新**：使用 Refresh Token 获取新 Token

### 6.2 权限模型

#### 项目角色

- **owner**：项目所有者，拥有所有权限
- **editor**：编辑者，可以编辑项目内容
- **viewer**：查看者，只能查看项目

#### 权限矩阵

| 操作     | owner | editor | viewer |
| -------- | ----- | ------ | ------ |
| 查看项目 | ✅    | ✅     | ✅     |
| 编辑项目 | ✅    | ✅     | ❌     |
| 删除项目 | ✅    | ❌     | ❌     |
| 管理成员 | ✅    | ❌     | ❌     |
| 创建分镜 | ✅    | ✅     | ❌     |
| 编辑分镜 | ✅    | ✅     | ❌     |
| 删除分镜 | ✅    | ✅     | ❌     |
| AI 生成  | ✅    | ✅     | ❌     |
| 导出项目 | ✅    | ✅     | ❌     |

---

## 7. 性能优化建议

### 7.1 分页优化

- 所有列表接口必须支持分页
- 默认每页 20 条，最大 100 条
- 使用数据库索引优化分页查询

### 7.2 缓存策略

- **项目列表**：缓存 5 分钟
- **项目详情**：缓存 1 分钟
- **资源列表**：缓存 10 分钟
- **AI 任务状态**：不缓存，实时查询

### 7.3 批量操作

- 支持批量创建/更新/删除资源
- 使用事务保证数据一致性

### 7.4 异步处理

- AI 生成任务：异步处理，返回任务 ID
- 导出任务：异步处理，支持进度查询
- 文件上传：支持分片上传

---

## 8. API 版本管理

### 8.1 版本策略

- **URL 版本化**：`/api/v1/`、`/api/v2/`
- **向后兼容**：新版本保持旧版本接口可用
- **废弃策略**：提前 3 个月通知，提供迁移指南

### 8.2 版本升级示例

```http
# v1 版本（已废弃，2025-06-01 停止支持）
GET /api/v1/projects

# v2 版本（当前版本）
GET /api/v2/projects
```

---

## 9. 接口清单

### 9.1 完整接口列表

| 模块           | 方法   | 端点                                 | 说明               |
| -------------- | ------ | ------------------------------------ | ------------------ |
| **认证**       | POST   | `/api/v1/auth/login`                 | 用户登录           |
| **认证**       | POST   | `/api/v1/auth/refresh`               | 刷新 Token         |
| **文件夹**     | GET    | `/api/v1/folders`                    | 获取文件夹列表     |
| **文件夹**     | GET    | `/api/v1/folders/tree`               | 获取文件夹树形结构 |
| **文件夹**     | GET    | `/api/v1/folders/{id}`               | 获取文件夹详情     |
| **文件夹**     | POST   | `/api/v1/folders`                    | 创建文件夹         |
| **文件夹**     | PATCH  | `/api/v1/folders/{id}`               | 更新文件夹         |
| **文件夹**     | POST   | `/api/v1/folders/{id}/move`          | 移动文件夹         |
| **文件夹**     | DELETE | `/api/v1/folders/{id}`               | 删除文件夹         |
| **文件夹**     | POST   | `/api/v1/folders/batch`              | 批量操作文件夹     |
| **文件夹成员** | GET    | `/api/v1/folders/{id}/members`       | 获取文件夹成员     |
| **文件夹成员** | POST   | `/api/v1/folders/{id}/members`       | 添加文件夹成员     |
| **文件夹成员** | PATCH  | `/api/v1/folders/{id}/members/{id}`  | 更新成员角色       |
| **文件夹成员** | DELETE | `/api/v1/folders/{id}/members/{id}`  | 移除文件夹成员     |
| **项目**       | GET    | `/api/v1/projects`                   | 获取项目列表       |
| **项目**       | GET    | `/api/v1/projects/{id}`              | 获取项目详情       |
| **项目**       | POST   | `/api/v1/projects`                   | 创建项目           |
| **项目**       | PATCH  | `/api/v1/projects/{id}`              | 更新项目           |
| **项目**       | DELETE | `/api/v1/projects/{id}`              | 删除项目           |
| **项目**       | POST   | `/api/v1/projects/{id}/move`         | 移动项目到文件夹   |
| **项目**       | POST   | `/api/v1/projects/batch/move`        | 批量移动项目       |
| **项目**       | POST   | `/api/v1/projects/{id}/exports`      | 导出项目           |
| **分镜**       | GET    | `/api/v1/projects/{id}/storyboards`  | 获取分镜列表       |
| **分镜**       | GET    | `/api/v1/storyboards/{id}`           | 获取分镜详情       |
| **分镜**       | POST   | `/api/v1/projects/{id}/storyboards`  | 创建分镜           |
| **分镜**       | PATCH  | `/api/v1/storyboards/{id}`           | 更新分镜           |
| **分镜**       | DELETE | `/api/v1/storyboards/{id}`           | 删除分镜           |
| **分镜**       | PUT    | `/api/v1/storyboards/{id}/resources` | 更新分镜资源       |
| **资源**       | GET    | `/api/v1/resources`                  | 获取资源列表       |
| **资源**       | POST   | `/api/v1/resources`                  | 上传资源           |
| **资源**       | DELETE | `/api/v1/resources/{id}`             | 删除资源           |
| **视频**       | GET    | `/api/v1/videos`                     | 获取视频列表       |
| **视频**       | POST   | `/api/v1/videos`                     | 创建视频           |
| **视频**       | PATCH  | `/api/v1/videos/{id}`                | 更新视频           |
| **视频**       | DELETE | `/api/v1/videos/{id}`                | 删除视频           |
| **音效**       | GET    | `/api/v1/sound-effects`              | 获取音效列表       |
| **音效**       | POST   | `/api/v1/sound-effects`              | 创建音效           |
| **音效**       | PATCH  | `/api/v1/sound-effects/{id}`         | 更新音效           |
| **音效**       | DELETE | `/api/v1/sound-effects/{id}`         | 删除音效           |
| **字幕**       | GET    | `/api/v1/subtitles`                  | 获取字幕列表       |
| **字幕**       | POST   | `/api/v1/subtitles`                  | 创建字幕           |
| **字幕**       | PATCH  | `/api/v1/subtitles/{id}`             | 更新字幕           |
| **字幕**       | DELETE | `/api/v1/subtitles/{id}`             | 删除字幕           |
| **配音**       | GET    | `/api/v1/voiceovers`                 | 获取配音列表       |
| **配音**       | POST   | `/api/v1/voiceovers`                 | 创建配音           |
| **配音**       | PATCH  | `/api/v1/voiceovers/{id}`            | 更新配音           |
| **配音**       | DELETE | `/api/v1/voiceovers/{id}`            | 删除配音           |
| **AI**         | POST   | `/api/v1/ai/generate-image`          | 生成图片           |
| **AI**         | POST   | `/api/v1/ai/transform-angle`         | 角度变换           |
| **AI**         | POST   | `/api/v1/ai/adjust-lens`             | 镜头调整           |
| **AI**         | POST   | `/api/v1/ai/generate-resource`       | 生成资源           |
| **AI**         | POST   | `/api/v1/ai/generate-video`          | 生成视频           |
| **AI**         | POST   | `/api/v1/ai/generate-sound`          | 生成音效           |
| **AI**         | POST   | `/api/v1/ai/generate-subtitle`       | 生成字幕           |
| **AI**         | POST   | `/api/v1/ai/generate-voiceover`      | 生成配音           |
| **AI**         | GET    | `/api/v1/ai/jobs/{id}`               | 查询 AI 任务状态   |
| **分镜看板**     | GET    | `/api/v1/projects/{id}/timeline`     | 获取分镜看板         |
| **分镜看板**     | PUT    | `/api/v1/projects/{id}/timeline`     | 更新分镜看板         |
| **成员**       | GET    | `/api/v1/projects/{id}/members`      | 获取项目成员       |
| **成员**       | POST   | `/api/v1/projects/{id}/members`      | 添加项目成员       |
| **成员**       | PATCH  | `/api/v1/projects/{id}/members/{id}` | 更新成员角色       |
| **成员**       | DELETE | `/api/v1/projects/{id}/members/{id}` | 移除项目成员       |
| **评论**       | GET    | `/api/v1/comments`                   | 获取评论列表       |
| **评论**       | POST   | `/api/v1/comments`                   | 创建评论           |
| **通知**       | GET    | `/api/v1/notifications`              | 获取通知列表       |
| **通知**       | PATCH  | `/api/v1/notifications/{id}/read`    | 标记通知已读       |

### 9.2 接口优先级

**P0（核心功能）**：

- 文件夹管理 CRUD
- 项目管理 CRUD
- 分镜管理 CRUD
- 资源管理
- 视频/音效/字幕/配音管理
- AI 生成基础功能

**P1（重要功能）**：

- 文件夹成员管理
- 文件夹权限继承
- 分镜看板管理
- 项目成员管理
- AI 任务状态查询
- 导出功能

**P2（增强功能）**：

- 文件夹批量操作
- 项目批量移动
- 评论功能
- 通知功能
- 高级 AI 功能

- 评论功能
- 通知功能
- 高级 AI 功能

---

## 10. 数据库字段映射参考

### 10.1 项目表映射

| 数据库字段      | API 字段       | 类型               | 说明                 |
| --------------- | -------------- | ------------------ | -------------------- |
| `project_id`    | `id`           | number             | 项目 ID              |
| `name`          | `name`         | string             | 项目名称             |
| `description`   | `description`  | string             | 项目描述             |
| `type`          | `type`         | 'mine' \| 'collab' | 项目类型             |
| `owner_id`      | `ownerId`      | number             | 所有者 ID            |
| `thumbnail_url` | `thumbnailUrl` | string             | 缩略图 URL           |
| `settings`      | `settings`     | object             | 项目设置（JSONB）    |
| `status`        | `status`       | string             | 项目状态             |
| `created_at`    | `createdAt`    | string             | 创建时间（ISO 8601） |
| `updated_at`    | `updatedAt`    | string             | 更新时间（ISO 8601） |

### 10.2 分镜表映射

| 数据库字段            | API 字段             | 类型   | 说明           |
| --------------------- | -------------------- | ------ | -------------- |
| `storyboard_id`       | `id`                 | number | 分镜 ID        |
| `project_id`          | `projectId`          | number | 项目 ID        |
| `title`               | `title`              | string | 分镜标题       |
| `description`         | `description`        | string | 分镜描述       |
| `thumbnail_url`       | `thumbnailUrl`       | string | 缩略图 URL     |
| `order_index`         | `orderIndex`         | number | 顺序索引       |
| `start_time`          | `startTime`          | number | 开始时间（秒） |
| `end_time`            | `endTime`            | number | 结束时间（秒） |
| `transition_type`     | `transitionType`     | string | 转场类型       |
| `transition_duration` | `transitionDuration` | number | 转场时长（秒） |

---

## 附录

### A. 参考文档

- [RESTful API 设计最佳实践](https://restfulapi.net/)
- [JSON API 规范](https://jsonapi.org/)
- [OpenAPI 规范](https://swagger.io/specification/)

### B. 变更记录

- **v1.0** (2025-01-27)：初始版本，基于产品需求、数据库设计和 API 设计原则创建

---

**文档结束**

> 本文档将作为前后端 API 对接的标准规范，所有接口实现必须遵循本文档定义。