expo-popcore-app/.claude/skills/repo-sdk/references/controllers.md

控制器 API 参考

目录

1. 项目管理
2. 模板管理
3. 模板生成记录
4. 社交互动
5. 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

类型定义

// 创建项目
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	根据生成记录重新运行	-

类型定义

// 模板详情
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

类型定义

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

类型定义

// 点赞/收藏
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

类型定义

// 模型信息
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

类型定义

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

类型定义

// 文件上传响应
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

类型定义

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

类型定义

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	设置项目标签	-

类型定义

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

类型定义

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

类型定义

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

类型定义

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	查询用户当前余额