xiaoxia-saas/docs/API-MAINLINE.md

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