54 KiB

Raw Blame History

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.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 统一响应结构

成功响应

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

错误响应

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

分页响应

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 请求头规范

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

2.5 分页参数

所有列表接口支持分页：

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

2.6 过滤参数

支持通用过滤参数：

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 用户登录

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

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 获取文件夹列表

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 获取文件夹树形结构

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 获取文件夹详情

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 创建文件夹

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 更新文件夹

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 移动文件夹

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 删除文件夹

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 批量操作文件夹

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 获取文件夹成员

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 添加文件夹成员

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 更新成员角色

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 移除文件夹成员

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 获取项目列表

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 获取项目详情

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 创建项目

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 移动项目到文件夹

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 批量移动项目

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 更新项目

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 删除项目

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

Response 204 No Content

4.14.8 导出项目

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 获取项目分镜列表

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 获取分镜详情

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 创建分镜

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 更新分镜

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 删除分镜

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

Response 204 No Content

4.15.6 更新分镜资源

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 获取资源列表

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 上传资源

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 删除资源

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

Response 204 No Content

4.14 视频管理

4.14.1 获取视频列表

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 创建视频

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 更新视频

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 删除视频

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

Response 204 No Content

4.15 音效管理

4.15.1 获取音效列表

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 创建音效

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 更新音效

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 删除音效

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

Response 204 No Content

4.16 字幕管理

4.16.1 获取字幕列表

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 创建字幕

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 更新字幕

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 删除字幕

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

Response 204 No Content

4.14 配音管理

4.14.1 获取配音列表

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 创建配音

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 更新配音

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 删除配音

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

Response 204 No Content

4.15 AI 生成 API

4.15.1 生成图片

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 角度变换

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 镜头调整

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 生成资源素材

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 生成视频

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 生成音效

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 生成字幕

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 生成配音

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 任务状态

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 获取项目分镜看板

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 更新分镜看板

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 获取项目成员

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 添加项目成员

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 更新成员角色

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 移除项目成员

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

Response 204 No Content

4.15 评论管理

4.15.1 获取评论列表

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 创建评论

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 获取通知列表

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 标记通知为已读

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 错误码定义

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 错误响应示例

验证错误

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

资源不存在

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

权限不足

{
  "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 版本升级示例

# 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. 参考文档

B. 变更记录

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

文档结束

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

54 KiB Raw Blame History

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

目录

1. API 设计原则

1.1 RESTful 设计原则

1.2 命名规范

1.3 HTTP 方法语义

2. 基础规范

2.1 协议与格式

2.2 统一响应结构

成功响应

错误响应

分页响应

2.3 HTTP 状态码

2.4 请求头规范

2.5 分页参数

2.6 过滤参数

3. 数据模型映射

3.1 数据库表与 API 资源映射

3.2 字段映射规则

4. API 接口详细定义

4.1 认证相关

4.1.1 用户登录

4.1.2 刷新 Token

4.3 文件夹管理

4.15.1 获取文件夹列表

4.15.2 获取文件夹树形结构

4.15.3 获取文件夹详情

4.15.4 创建文件夹

4.15.5 更新文件夹

4.15.6 移动文件夹

4.15.7 删除文件夹

4.15.8 批量操作文件夹

4.16 文件夹成员管理

4.16.1 获取文件夹成员

4.16.2 添加文件夹成员

4.16.3 更新成员角色

4.16.4 移除文件夹成员

4.14 项目管理（更新）

4.14.1 获取项目列表

4.14.2 获取项目详情

4.14.3 创建项目

4.14.4 移动项目到文件夹

4.14.5 批量移动项目

4.14.6 更新项目

4.14.7 删除项目

4.14.8 导出项目

4.15 分镜管理

4.15.1 获取项目分镜列表

4.15.2 获取分镜详情

4.15.3 创建分镜

4.15.4 更新分镜

4.15.5 删除分镜

4.15.6 更新分镜资源

4.16 资源管理

4.16.1 获取资源列表

4.16.2 上传资源

4.16.3 删除资源

4.14 视频管理

4.14.1 获取视频列表

4.14.2 创建视频

4.14.3 更新视频

4.14.4 删除视频

4.15 音效管理

4.15.1 获取音效列表

4.15.2 创建音效

4.15.3 更新音效

4.15.4 删除音效

4.16 字幕管理

4.16.1 获取字幕列表

4.16.2 创建字幕

4.16.3 更新字幕

4.16.4 删除字幕

4.14 配音管理

4.14.1 获取配音列表

4.14.2 创建配音

4.14.3 更新配音

4.14.4 删除配音

4.15 AI 生成 API

4.15.1 生成图片

54 KiB

Raw Blame History