xiaoxia/xiaoxia-saas
1
0
Fork 0
Code Issues 8 Pull Requests 1 Actions 2 Packages Projects Releases 7 Wiki Activity
Files
1e483b7bf9a2de27bbce2ffe1d3ba8e2f7791e1f
xiaoxia-saas/docs/API-MAINLINE.md
T
Xiaoxia AI bc92400eff docs(deploy): document generated file retention
2026-06-21 11:29:33 +08:00

298 lines
8.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
Reference in New Issue View Git Blame Copy Permalink