# API 主线清单（2026-06-19）

> 本文档列出当前 SaaS 项目所有 active API endpoints。  
> 状态：✅ ACTIVE | 🧪 EXPERIMENTAL | ⚠️ DEPRECATED

---

## 一、认证相关（Auth）

**路由前缀**: `/api/v1/auth`  
**文件**: `apps/api/app/api/routes/auth.py`

| Method | Path | 功能 | 状态 |
|--------|------|------|------|
| POST | `/register` | 用户注册 | ✅ ACTIVE |
| POST | `/login` | 用户登录 | ✅ ACTIVE |
| POST | `/logout` | 用户登出 | ✅ ACTIVE |
| GET | `/verify-email` | 邮箱验证 | ✅ ACTIVE |
| POST | `/password/forgot` | 忘记密码 | ✅ ACTIVE |
| POST | `/password/reset` | 重置密码 | ✅ ACTIVE |

**Use Cases**:
- `RegisterUserUseCase`
- `LoginUseCase`
- `LogoutUseCase`
- `VerifyEmailUseCase`
- `RequestPasswordResetUseCase`
- `ResetPasswordUseCase`

---

## 二、工作空间（Workspaces）

**路由前缀**: `/api/v1/workspaces`  
**文件**: `apps/api/app/api/routes/workspaces.py`

| Method | Path | 功能 | 状态 |
|--------|------|------|------|
| POST | `/` | 创建工作空间 | ✅ ACTIVE |
| GET | `/` | 列出用户的工作空间 | ✅ ACTIVE |
| GET | `/{workspace_id}` | 获取工作空间详情 | ✅ ACTIVE |
| POST | `/{workspace_id}/members/invite` | 邀请成员 | ✅ ACTIVE |
| GET | `/{workspace_id}/members` | 列出成员 | ✅ ACTIVE |
| DELETE | `/{workspace_id}/members/{user_id}` | 移除成员 | ✅ ACTIVE |
| POST | `/{workspace_id}/leave` | 离开工作空间 | ✅ ACTIVE |
| PATCH | `/{workspace_id}/members/{user_id}/role` | 更新成员角色 | ✅ ACTIVE |
| POST | `/{workspace_id}/subscription/upgrade` | 升级订阅 | ✅ ACTIVE |
| POST | `/{workspace_id}/subscription/cancel` | 取消订阅 | ✅ ACTIVE |
| GET | `/{workspace_id}/quota` | 查询配额 | ✅ ACTIVE |
| POST | `/invitations/{token}/accept` | 接受邀请 | ✅ ACTIVE |
| POST | `/invitations/{token}/decline` | 拒绝邀请 | ✅ ACTIVE |

**Use Cases**:
- `CreateWorkspaceUseCase`
- `ListWorkspacesUseCase`
- `InviteMemberUseCase`
- `ListMembersUseCase`
- `RemoveMemberUseCase`
- `UpdateMemberRoleUseCase`
- `SubscriptionUseCase`
- `AcceptInvitationUseCase`

---

## 三、项目管理（Projects）

**路由前缀**: `/api/v1/projects`  
**文件**: `apps/api/app/api/routes/projects.py`

| Method | Path | 功能 | 状态 |
|--------|------|------|------|
| GET | `/` | 列出项目 | ✅ ACTIVE |
| POST | `/` | 创建项目 | ✅ ACTIVE |

**Use Cases**:
- `CreateProjectUseCase`
- `ListProjectsUseCase`

---

## 四、素材管理（Assets）

### 4.1 素材库（Asset Libraries）

**路由前缀**: `/api/v1/asset-libraries`  
**文件**: `apps/api/app/api/routes/asset_libraries.py`

| Method | Path | 功能 | 状态 |
|--------|------|------|------|
| GET | `/` | 列出素材库 | ✅ ACTIVE |
| POST | `/` | 创建素材库 | ✅ ACTIVE |

**Use Cases**:
- `CreateAssetLibraryUseCase`
- `ListAssetLibrariesUseCase`

### 4.2 素材（Assets）

**路由前缀**: `/api/v1/assets`  
**文件**: `apps/api/app/api/routes/assets.py`

| Method | Path | 功能 | 状态 |
|--------|------|------|------|
| GET | `/` | 列出素材 | ✅ ACTIVE |
| POST | `/` | 创建素材 | ✅ ACTIVE |

**Use Cases**:
- `CreateAssetUseCase`
- `ListAssetsUseCase`

### 4.3 上传（Upload）

**路由前缀**: `/api/v1/upload`  
**文件**: `apps/api/app/api/routes/upload.py`

| Method | Path | 功能 | 状态 |
|--------|------|------|------|
| POST | `/` | 上传文件 | ✅ ACTIVE |

**Use Cases / Services**:
- `SubmitIngestJobUseCase`
- `OSSStorageService`（经 `get_storage_service` 注入）

---

## 五、素材处理（Asset Processing）

### 5.1 Ingest Jobs

**路由前缀**: `/api/v1/ingest-jobs`  
**文件**: `apps/api/app/api/routes/ingest_jobs.py`

| Method | Path | 功能 | 状态 |
|--------|------|------|------|
| GET | `/{job_id}` | 获取任务状态 | ✅ ACTIVE |
| POST | `/` | 创建任务 | ✅ ACTIVE |

**Use Cases**:
- `CreateIngestJobUseCase`
- `GetIngestJobUseCase`

### 5.2 Classification Jobs

**路由前缀**: `/api/v1/classification-jobs`  
**文件**: `apps/api/app/api/routes/classification_jobs.py`

| Method | Path | 功能 | 状态 |
|--------|------|------|------|
| GET | `/{job_id}` | 获取分类任务状态 | ✅ ACTIVE |
| POST | `/` | 创建分类任务 | ✅ ACTIVE |

**Use Cases**:
- `CreateClassificationJobUseCase`
- `GetClassificationJobUseCase`

---

## 六、视频生成（Video Generation）

### 6.1 生成任务（Generation Tasks）

**路由前缀**: `/api/v1/generation`  
**文件**: `apps/api/app/api/routes/generation_tasks.py`

| Method | Path | 功能 | 状态 |
|--------|------|------|------|
| POST | `/tasks` | 创建生成任务 | ✅ ACTIVE |
| GET | `/tasks/{task_id}` | 获取任务状态 | ✅ ACTIVE |
| GET | `/tasks/{task_id}/results` | 获取生成结果列表 | ✅ ACTIVE |

**Use Cases**:
- `CreateGenerationTaskUseCase`
- `GetGenerationTaskUseCase`
- `ListGenerationTaskResultsUseCase`

### 6.2 生成结果（Generated Videos）

**路由前缀**: `/api/v1/generated-videos`  
**文件**: `apps/api/app/api/routes/generated_videos.py`

| Method | Path | 功能 | 状态 |
|--------|------|------|------|
| GET | `/` | 列出生成结果 | ✅ ACTIVE |
| GET | `/{video_id}` | 获取单个结果 | ✅ ACTIVE |
| GET | `/{video_id}/download-url` | 获取下载链接 | ✅ ACTIVE |

**Use Cases**:
- `ListGeneratedVideosUseCase`
- `GetGeneratedVideoUseCase`
- `GetGeneratedVideoDownloadUrlUseCase`

---

## 七、项目管理高级功能（Project Management）

**路由前缀**: `/api/v1/project-management`  
**文件**: `apps/api/app/api/routes/project_management.py`

| Method | Path | 功能 | 状态 |
|--------|------|------|------|
| POST | `/tasks` | 创建任务 | ✅ ACTIVE |
| GET | `/tasks` | 列出任务 | ✅ ACTIVE |
| GET | `/tasks/{task_id}` | 获取任务详情 | ✅ ACTIVE |
| PATCH | `/tasks/{task_id}` | 更新任务 | ✅ ACTIVE |
| PATCH | `/tasks/{task_id}/status` | 更新任务状态 | ✅ ACTIVE |
| PATCH | `/tasks/{task_id}/progress` | 更新任务进度 | ✅ ACTIVE |
| POST | `/milestones` | 创建里程碑 | ✅ ACTIVE |
| GET | `/milestones` | 列出里程碑 | ✅ ACTIVE |
| POST | `/issues` | 创建问题 | ✅ ACTIVE |
| GET | `/issues` | 列出问题 | ✅ ACTIVE |
| PATCH | `/issues/{issue_id}/resolve` | 解决问题 | ✅ ACTIVE |

**Use Cases**:
- `CreateTaskUseCase`
- `ListTasksUseCase`
- `GetTaskUseCase`
- `UpdateTaskUseCase`
- `UpdateTaskStatusUseCase`
- `UpdateTaskProgressUseCase`
- `CreateMilestoneUseCase`
- `ListMilestonesUseCase`
- `CreateTaskIssueUseCase`
- `ListTaskIssuesUseCase`
- `ResolveTaskIssueUseCase`

---

## 八、健康检查（Health）

**路由前缀**: `/api/v1`  
**文件**: `apps/api/app/api/routes/health.py`

| Method | Path | 功能 | 状态 |
|--------|------|------|------|
| GET | `/health` | 健康检查 | ✅ ACTIVE |
| GET | `/ready` | 就绪检查 | ✅ ACTIVE |
| GET | `/startup` | 启动检查 | ✅ ACTIVE |

---

## 九、主线路径总结

### Phase 7 核心路径（视频剪辑主链）

```
上传素材
  ↓
POST /api/v1/upload

创建 Asset
  ↓
POST /api/v1/assets

发起分类
  ↓
POST /api/v1/classification-jobs

创建生成任务
  ↓
POST /api/v1/generation/tasks

查询生成结果
  ↓
GET /api/v1/generation/tasks/{task_id}/results

获取下载链接
  ↓
GET /api/v1/generated-videos/{video_id}/download-url
```

### 当前主线技术栈

- **领域层**: `packages/domain/entities.py`
- **应用层**: `packages/application/*.py`
- **持久化**: `packages/adapters/sqlalchemy_impl/*.py`
- **API**: `apps/api/app/api/routes/*.py`
- **Worker**: `apps/worker/tasks.py`

---

## 十、兼容层标注

以下文件为兼容层，保留但不再是主线：

- `packages/domain/asset.py` - `[COMPAT]` 兼容旧素材模型
- `packages/domain/asset_library.py` - `[COMPAT]` 兼容旧素材库模型
- `packages/ports/asset_repository.py` - `[COMPAT]` 兼容旧仓储接口
- `packages/ports/asset_library_repository.py` - `[COMPAT]` 兼容旧仓储接口

已删除的历史兼容层：

- `packages/adapters/postgres/*` - 旧 psycopg adapter 已删除，持久化主线统一为 `packages/adapters/sqlalchemy_impl/*`

---

**维护人**: 小虾 🦐  
**最后更新**: 2026-06-19 10:05 GMT+8