docs(project-b): complete mainline clarity project - API catalog and code status

2026-06-19 10:02:12 +08:00
parent c22f5e9c70
commit dce28d5bb8
5 changed files with 1082 additions and 235 deletions
@@ -0,0 +1,293 @@
+# 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**:
+- 直接调用 `MinIOService`
+
+---
+
+## 五、素材处理（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/asset_repository.py` - `[COMPAT]` 兼容旧 Postgres 实现
+
+---
+
+**维护人**: 小虾 🦐  
+**最后更新**: 2026-06-19 10:05 GMT+8