# 控制器 API 参考

## 目录

1. [项目管理](#项目管理)
2. [模板管理](#模板管理)
3. [模板生成记录](#模板生成记录)
4. [社交互动](#社交互动)
5. [AI 生成](#ai-生成)
6. [聊天](#聊天)
7. [文件处理](#文件处理)
8. [分类管理](#分类管理)
9. [标签管理](#标签管理)
10. [项目标签](#项目标签)
11. [消息系统](#消息系统)
12. [公告系统](#公告系统)
13. [权限管理](#权限管理)
14. [角色管理](#角色管理)
15. [支付相关](#支付相关)

---

## 项目管理

**控制器**: `ProjectController`
**路由前缀**: `/loomart`

| 方法 | 路由 | 功能 | 权限 |
|------|------|------|------|
| POST | /project/create | 创建新项目 | project:create |
| POST | /project/list | 获取用户项目列表 | project:list |
| GET | /project/get | 获取单个项目 | project:read |
| POST | /project/update | 更新项目信息 | project:update |
| POST | /project/delete | 删除项目 | project:delete |
| POST | /project/transfer | 转移/复制项目所有权 | project:update OR project:create |

### 类型定义

```typescript
// 创建项目
interface CreateProjectInput {
  title: string;
  titleEn?: string;
  description?: string;
  descriptionEn?: string;
  content: any;
  sourceTemplateId?: string;
}

// 列表查询
interface ListProjectsInput {
  page?: number;
  limit?: number;
  tagId?: string;
  search?: string;
  sortBy?: 'createdAt' | 'updatedAt' | 'title';
  sortOrder?: 'asc' | 'desc';
}

// 项目响应
interface Project {
  id: string;
  userId: string;
  title: string;
  titleEn: string;
  description?: string;
  descriptionEn?: string;
  resultUrl?: string;
  content: any;
  sourceTemplateId?: string;
  isDeleted: boolean;
  createdAt: Date;
  updatedAt: Date;
  tags?: UserTagBasic[];
}

// 转移项目
interface TransferProjectInput {
  projectId: string;
  targetUserId: string;
  mode: 'transfer' | 'copy';
}
```

---

## 模板管理

**控制器**: `TemplateController`
**路由前缀**: `/loomart`

| 方法 | 路由 | 功能 | 权限 |
|------|------|------|------|
| POST | /template/create | 创建新模板 | - |
| POST | /template/list | 获取模板列表 | - |
| GET | /template/get | 获取单个模板 | - |
| POST | /template/update | 更新模板 | - |
| POST | /template/delete | 删除模板 | - |
| POST | /template/run | 运行模板工作流 | - |
| POST | /template/rerun | 根据生成记录重新运行 | - |

### 类型定义

```typescript
// 模板详情
interface TemplateDetail {
  id: string;
  userId: string;
  title: string;
  titleEn: string;
  description: string;
  descriptionEn: string;
  coverImageUrl: string;
  previewUrl: string;
  watermarkedPreviewUrl?: string;
  webpPreviewUrl?: string;
  webpHighPreviewUrl?: string;
  content: any;
  formSchema?: any;
  sortOrder: number;
  viewCount: number;
  useCount: number;
  likeCount: number;
  favoriteCount: number;
  shareCount: number;
  commentCount: number;
  costPrice?: number;
  price?: number;
  aspectRatio: string;
  status: string;
  isDeleted: boolean;
  createdAt: Date;
  updatedAt: Date;
  isLiked?: boolean;
  isFavorited?: boolean;
}

// 运行模板
interface RunTemplateInput {
  templateId: string;
  formData?: Record<string, any>;
  projectId?: string;
}

// 列表查询
interface ListTemplatesInput {
  page?: number;
  limit?: number;
  categoryId?: string;
  tagId?: string;
  status?: string;
  search?: string;
  sortBy?: 'sortOrder' | 'likeCount' | 'useCount' | 'viewCount' | 'createdAt';
  sortOrder?: 'asc' | 'desc';
}
```

---

## 模板生成记录

**控制器**: `TemplateGenerationController`
**路由前缀**: `/loomart`

| 方法 | 路由 | 功能 | 权限 |
|------|------|------|------|
| POST | /template-generation/list | 获取生成记录列表 | template:run |
| GET | /template-generation/get | 获取单个记录 | template:run |
| POST | /template-generation/update | 更新记录 | template:run |
| POST | /template-generation/delete | 删除记录 | template:run |
| POST | /template-generation/batch-delete | 批量删除 | template:run |

### 类型定义

```typescript
interface TemplateGeneration {
  id: string;
  userId: string;
  templateId: string;
  projectId?: string;
  status: 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED';
  formData?: any;
  resultUrl?: string;
  errorMessage?: string;
  createdAt: Date;
  updatedAt: Date;
}

interface ListTemplateGenerationsInput {
  page?: number;
  limit?: number;
  templateId?: string;
  projectId?: string;
  status?: string;
}
```

---

## 社交互动

**控制器**: `TemplateSocialController`
**路由前缀**: `/loomart/template`

| 方法 | 路由 | 功能 | 权限 |
|------|------|------|------|
| POST | /like | 点赞模板 | template:run |
| POST | /unlike | 取消点赞 | template:run |
| GET | /check-liked | 检查是否已点赞 | template:run |
| POST | /check-liked-batch | 批量检查点赞状态 | template:run |
| POST | /favorite | 收藏模板 | template:run |
| POST | /unfavorite | 取消收藏 | template:run |
| GET | /check-favorited | 检查是否已收藏 | template:run |
| POST | /check-favorited-batch | 批量检查收藏状态 | template:run |
| POST | /favorites | 获取用户收藏列表 | template:run |
| POST | /likes | 获取用户喜欢列表 | template:run |
| POST | /share | 转发模板 | template:run |
| POST | /comment/create | 创建评论 | template:run |
| POST | /comment/delete | 删除评论 | template:run |
| GET | /comments | 获取评论列表 | template:run |
| GET | /comment/replies | 获取评论回复 | template:run |

### 类型定义

```typescript
// 点赞/收藏
interface LikeTemplateInput { templateId: string; }
interface FavoriteTemplateInput { templateId: string; }

// 批量检查
interface CheckLikedBatchInput { templateIds: string[]; }
interface CheckLikedBatchResponse {
  results: Record<string, boolean>;
}

// 评论
interface CreateCommentInput {
  templateId: string;
  content: string;
  parentId?: string;  // 回复评论时使用
}

interface TemplateComment {
  id: string;
  userId: string;
  templateId: string;
  content: string;
  parentId?: string;
  isDeleted: boolean;
  createdAt: Date;
  user?: { id: string; name: string; image?: string; };
  replies?: TemplateComment[];
  replyCount?: number;
}

// 获取评论
interface GetCommentsInput {
  templateId: string;
  page?: number;
  limit?: number;
}
```

---

## AI 生成

**控制器**: `AigcController`
**路由前缀**: `/loomart/aigc`

| 方法 | 路由 | 功能 | 权限 |
|------|------|------|------|
| GET | /models | 获取支持的模型列表 | project:run OR template:run |
| POST | /task/submit | 提交图像/视频生成任务 | project:run OR template:run |
| GET | /task/status | 获取任务状态 | project:run OR template:run |

### 类型定义

```typescript
// 模型信息
interface AigcModel {
  model_name: string;
  description: string;
  description_en: string;
  supported_ar: string[];        // 支持的宽高比
  supported_count: string[];     // 支持的生成数量
  supported_duration: string[];  // 支持的时长（视频）
  supported_resolution: string[];
  mode: string;                  // 'image' | 'video'
  model_provider: string;
  tags: string[];
  tags_en: string[];
  provider: string;
  display_name: string;
}

// 提交任务
interface SubmitTaskBody {
  mode?: string;
  model_name: string;
  prompt: string;
  aspect_ratio?: string;
  webhook_flag?: boolean;
  watermark?: boolean;
  extra?: string;
  img_url?: string;
  img_list?: any[];
  duration?: string;
  resolution?: string;
}

// 任务状态
interface GetTaskStatusResult {
  task_id: string;
  status: 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED';
  progress?: number;
  result_url?: string;
  error_message?: string;
}
```

---

## 聊天

**控制器**: `ChatController`
**路由前缀**: `/loomart`

| 方法 | 路由 | 功能 | 权限 |
|------|------|------|------|
| POST | /chat | 发送聊天消息 | project:run OR template:run |
| GET | /chat/models | 获取模型列表 | project:run OR template:run |

### 类型定义

```typescript
interface ChatRequest {
  prompt: string;
  model_name: string;
  img_list?: string[];
  video_url?: string[];
  stream?: boolean;
  tools?: string;
  tool_choice?: string;
}

interface ChatResponse {
  data: string;
  status: boolean;
  msg: string;
  usage?: any;
}
```

---

## 文件处理

**控制器**: `FileController`
**路由前缀**: `/loomart`

| 方法 | 路由 | 功能 | 权限 | 内容类型 |
|------|------|------|------|---------|
| POST | /file/upload-s3 | 上传文件到S3 | RequireSession | multipart/form-data |
| POST | /file/compress-video | 压缩视频 | project:run OR template:run | - |
| POST | /file/convert-to-ani | 转换为ANI格式 | project:run OR template:run | - |
| POST | /file/convert-to-webp | 转换为WebP格式 | project:run OR template:run | - |
| POST | /file/convert-to-watermark | 添加水印 | project:run OR template:run | - |
| POST | /file/upload-and-convert-ani | 上传并转换ANI | project:run OR template:run | multipart/form-data |

### 类型定义

```typescript
// 文件上传响应
interface FileUploadResponse {
  status: boolean;
  msg: string;
  data: string;  // 文件URL
}

// 视频压缩
interface VideoCompressRequest {
  videoUrl: string;
  quality: 'low' | 'medium' | 'high';
}

// 转换为 WebP
interface ConvertToWebpRequest {
  videoUrl: string;
  compressionLevel: number;  // 0-6
  quality: number;           // 0-100
  loop: boolean;
  resolution: string;
  fps: number;
  mode?: string;
}

// 添加水印
interface ConvertToWatermarkRequest {
  videoUrl: string;
  watermarkUrl: string;
  position?: 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight' | 'center';
}
```

---

## 分类管理

**控制器**: `CategoryController`
**路由前缀**: `/loomart`

| 方法 | 路由 | 功能 | 权限 |
|------|------|------|------|
| POST | /category/create | 创建分类 | category:create |
| POST | /category/list | 获取分类列表 | - |
| GET | /category/get | 获取单个分类 | - |
| GET | /category/get-by-name | 按名称获取分类 | - |
| GET | /category/get-by-id | 按ID获取分类及模板 | - |
| POST | /category/list-with-tags | 获取分类及标签列表 | - |
| POST | /category/update | 更新分类 | category:update |
| POST | /category/delete | 删除分类 | category:delete |
| POST | /category/batch-update-sort-order | 批量更新排序 | category:update |
| POST | /category/batch-update-tag-sort-order | 批量更新标签排序 | category:update |
| GET | /category/stats | 获取分类统计 | category:read |

### 类型定义

```typescript
interface Category {
  id: string;
  name: string;
  nameEn: string;
  description?: string;
  descriptionEn?: string;
  coverImageUrl?: string;
  sortOrder: number;
  isDeleted: boolean;
  createdAt: Date;
  updatedAt: Date;
  tags?: Tag[];
  templates?: TemplateDetail[];
}

interface CreateCategoryInput {
  name: string;
  nameEn?: string;
  description?: string;
  descriptionEn?: string;
  coverImageUrl?: string;
  sortOrder?: number;
}
```

---

## 标签管理

**控制器**: `TagController`
**路由前缀**: `/loomart`

| 方法 | 路由 | 功能 | 权限 |
|------|------|------|------|
| POST | /tags/create | 创建标签 | tag:create |
| POST | /tags/list | 获取标签列表 | tag:list |
| GET | /tags/get | 获取单个标签 | tag:read |
| GET | /tags/get-by-name | 按名称获取标签 | tag:read |
| GET | /tags/get-by-category-tag-id | 按CategoryTag ID获取 | - |
| POST | /tags/update | 更新标签 | tag:update |
| POST | /tags/delete | 删除标签 | tag:delete |
| POST | /tags/update-category-tag | 更新分类标签关联 | tag:update |
| POST | /tags/batch-update-sort-order | 批量更新排序 | tag:update |

### 类型定义

```typescript
interface Tag {
  id: string;
  name: string;
  nameEn: string;
  description?: string;
  sortOrder: number;
  isDeleted: boolean;
  createdAt: Date;
  updatedAt: Date;
}

interface CreateTagInput {
  name: string;
  nameEn?: string;
  description?: string;
  sortOrder?: number;
}
```

---

## 项目标签

**控制器**: `ProjectTagController`
**路由前缀**: `/loomart`

| 方法 | 路由 | 功能 | 权限 |
|------|------|------|------|
| POST | /project-tags/create | 创建用户标签 | - |
| GET | /project-tags/list | 获取标签列表 | - |
| POST | /project-tags/update | 更新标签 | - |
| POST | /project-tags/delete | 删除标签 | - |
| POST | /project-tags/add-to-project | 添加标签到项目 | - |
| POST | /project-tags/remove-from-project | 从项目移除标签 | - |
| POST | /project-tags/set-project-tags | 设置项目标签 | - |

### 类型定义

```typescript
interface UserTag {
  id: string;
  userId: string;
  name: string;
  color?: string;
  sortOrder: number;
  createdAt: Date;
  updatedAt: Date;
}

interface CreateUserTagInput {
  name: string;
  color?: string;
}

interface SetProjectTagsInput {
  projectId: string;
  tagIds: string[];
}
```

---

## 消息系统

**控制器**: `MessageController`
**路由前缀**: `/loomart`

| 方法 | 路由 | 功能 | 权限 |
|------|------|------|------|
| POST | /messages/list | 获取消息列表 | RequireSession |
| GET | /messages/get | 获取单条消息 | RequireSession |
| POST | /messages/mark-read | 标记消息已读 | RequireSession |
| POST | /messages/batch-mark-read | 批量标记已读 | RequireSession |
| POST | /messages/delete | 删除消息 | RequireSession |
| GET | /messages/unread-count | 获取未读数量 | RequireSession |

### 类型定义

```typescript
interface Message {
  id: string;
  userId: string;
  type: 'SYSTEM' | 'ACTIVITY' | 'BILLING' | 'MARKETING';
  title: string;
  content: string;
  data?: any;
  link?: string;
  priority: 'URGENT' | 'HIGH' | 'NORMAL' | 'LOW';
  expiresAt?: Date;
  isRead: boolean;
  readAt?: Date;
  isDeleted: boolean;
  deletedAt?: Date;
  createdAt: Date;
  updatedAt: Date;
}

interface ListMessagesInput {
  page?: number;
  limit?: number;
  type?: 'SYSTEM' | 'ACTIVITY' | 'BILLING' | 'MARKETING';
  isRead?: boolean;
}

interface UnreadCountResult {
  total: number;
  byType: {
    SYSTEM: number;
    ACTIVITY: number;
    BILLING: number;
    MARKETING: number;
  };
}
```

---

## 公告系统

**控制器**: `AnnouncementController`
**路由前缀**: `/loomart`

| 方法 | 路由 | 功能 | 权限 |
|------|------|------|------|
| POST | /announcements/create | 创建公告 | announcement:create |
| POST | /announcements/list | 获取公告列表 | - |
| GET | /announcements/get | 获取单条公告 | - |
| POST | /announcements/update | 更新公告 | announcement:update |
| POST | /announcements/delete | 删除公告 | announcement:delete |
| POST | /announcements/mark-read | 标记已读 | RequireSession |
| GET | /announcements/unread-count | 获取未读数量 | RequireSession |

---

## 权限管理

**控制器**: `PermissionController`
**路由前缀**: `/loomart/admin/permissions`

| 方法 | 路由 | 功能 | 权限 |
|------|------|------|------|
| GET | /permissions/list | 获取权限列表 | user:permissions |
| POST | /permissions/create | 创建权限 | user:permissions |
| PATCH | /permissions/get | 更新权限 | user:permissions |
| DELETE | /permissions/delete | 删除权限 | user:permissions |

### 类型定义

```typescript
interface Permission {
  id: string;
  resource: string;
  action: string;
  description?: string;
  createdAt: Date;
  updatedAt: Date;
}
```

---

## 角色管理

**控制器**: `RoleController`
**路由前缀**: `/loomart/admin`

| 方法 | 路由 | 功能 | 权限 |
|------|------|------|------|
| GET | /roles/list | 获取角色列表 | role:list |
| POST | /roles/create | 创建角色 | role:create |
| PATCH | /roles/update | 更新角色基本信息 | role:update |
| PUT | /roles/update/permissions | 更新角色权限 | role:update |
| DELETE | /roles/delete | 删除角色 | role:delete |

### 类型定义

```typescript
interface RoleWithPermissions {
  id: string;
  name: string;
  displayName: string;
  description?: string;
  isSystem: boolean;
  scope: string;
  organizationId?: string;
  createdAt: Date;
  updatedAt: Date;
  permissions: Permission[];
}
```

---

## 支付相关

### AlipayController

**路由前缀**: `/loomart`

| 方法 | 路由 | 功能 |
|------|------|------|
| POST | /alipay/app-pay | 支付宝APP支付下单 |
| POST | /alipay/auth-info | 获取支付宝授权字符串 |
| POST | /alipay/webhook | 支付宝异步通知回调 |
| POST | /credits/pre-recharge | 积分预充值 |

### AdminBalanceController

**路由前缀**: `/loomart/admin-balance`

| 方法 | 路由 | 功能 |
|------|------|------|
| POST | /add-user-balance | 管理员给用户充值 |
| POST | /deduct-user-balance | 管理员扣除用户余额 |
| POST | /get-user-balance | 查询用户当前余额 |