fix: 添加skills

2026-01-29 15:13:27 +08:00
parent b716198d4b
commit 6279752f23
16 changed files with 5462 additions and 27 deletions
--- a/.claude/skills/repo-sdk/references/client-usage.md
+++ b/.claude/skills/repo-sdk/references/client-usage.md
@@ -0,0 +1,619 @@
+# 客户端使用指南
+
+本文档详细介绍 @repo/sdk 的客户端调用方式及其配置方法。
+
+## 目录
+
+1. [推荐方式：root.get (DI 风格)](#1-推荐方式rootget-di-风格)
+2. [复用 Schema 和类型](#2-复用-schema-和类型)
+3. [Better Auth 插件风格](#3-better-auth-插件风格)
+4. [API 函数风格](#4-api-函数风格)
+5. [服务端实现](#5-服务端实现)
+6. [错误处理](#6-错误处理)
+
+---
+
+## 1. 推荐方式：root.get (DI 风格)
+
+**强烈推荐使用此方式**，保证完整的类型安全和最佳开发体验。
+
+### 基本用法
+
+```typescript
+import { root } from '@repo/core'
+import {
+  ProjectController,
+  TemplateController,
+  TemplateSocialController,
+  AigcController,
+  FileController
+} from '@repo/sdk'
+import type { CreateProjectInput, Project, ListProjectsResult } from '@repo/sdk'
+
+// 获取控制器实例（完整类型推导）
+const projectCtrl = root.get(ProjectController)
+const templateCtrl = root.get(TemplateController)
+const socialCtrl = root.get(TemplateSocialController)
+const aigcCtrl = root.get(AigcController)
+const fileCtrl = root.get(FileController)
+
+// 调用方法（参数和返回值都有完整类型提示）
+const projects: ListProjectsResult = await projectCtrl.list({ page: 1, limit: 10 })
+const project: Project = await projectCtrl.create({ title: '新项目', content: {} })
+const template = await templateCtrl.get('template-id')
+await socialCtrl.like({ templateId: 'xxx' })
+```
+
+### 优势
+
+1. **完整类型安全**：参数和返回值都有精确的类型推导
+2. **IDE 支持**：自动补全、跳转定义、重构支持
+3. **可测试性**：可以轻松 mock Controller 进行单元测试
+4. **前后端一致**：服务端和客户端使用相同的接口定义
+5. **灵活性**：可以自定义代理实现（如添加缓存、日志等）
+
+### 前置条件
+
+需要先初始化客户端插件（注册 HTTP 代理）：
+
+```typescript
+import { createAuthClient } from 'better-auth/client'
+import { createSkerClientPlugin } from '@repo/sdk'
+
+// 初始化（会自动将 Controller 替换为 HTTP 代理）
+const auth = createAuthClient({
+  baseURL: 'http://localhost:3000',
+  plugins: [createSkerClientPlugin()]
+})
+```
+
+### 自定义代理（高级）
+
+```typescript
+import { root } from '@repo/core'
+import { ProjectController } from '@repo/sdk'
+import type { ListProjectsInput, ListProjectsResult } from '@repo/sdk'
+
+// 注册带缓存的自定义实现
+root.set([{
+  provide: ProjectController,
+  useFactory: () => ({
+    list: async (input: ListProjectsInput): Promise<ListProjectsResult> => {
+      const cacheKey = `projects-${JSON.stringify(input)}`
+      const cached = cache.get(cacheKey)
+      if (cached) return cached
+
+      const result = await originalProxy.list(input)
+      cache.set(cacheKey, result)
+      return result
+    },
+    // ... 其他方法
+  })
+}])
+```
+
+---
+
+## 2. 复用 Schema 和类型
+
+**强烈推荐复用 SDK 导出的 Zod Schema 和 TypeScript 类型**，确保前后端数据一致性。
+
+### 导入类型（推荐）
+
+```typescript
+// 始终从 @repo/sdk 导入类型，不要自己定义
+import type {
+  // 项目相关
+  Project,
+  CreateProjectInput,
+  ListProjectsInput,
+  ListProjectsResult,
+  UpdateProjectInput,
+  TransferProjectInput,
+
+  // 模板相关
+  TemplateDetail,
+  CreateTemplateInput,
+  RunTemplateInput,
+  ListTemplatesInput,
+  ListTemplatesResult,
+
+  // AI 生成
+  AigcModel,
+  SubmitTaskBody,
+  SubmitTaskResult,
+  GetTaskStatusResult,
+
+  // 社交
+  LikeTemplateInput,
+  CreateCommentInput,
+  TemplateComment,
+  GetCommentsResponse,
+
+  // 消息
+  Message,
+  ListMessagesInput,
+  UnreadCountResult,
+
+  // 文件
+  FileUploadResponse,
+  VideoCompressRequest,
+  ConvertToWebpRequest
+} from '@repo/sdk'
+```
+
+### 复用 Zod Schema 验证
+
+```typescript
+import {
+  CreateProjectSchema,
+  ListProjectsSchema,
+  RunTemplateSchema,
+  SubmitTaskBodySchema,
+  CreateCommentSchema
+} from '@repo/sdk'
+
+// 验证用户输入（抛出错误）
+function validateInput(data: unknown) {
+  return CreateProjectSchema.parse(data)
+}
+
+// 安全验证（不抛错，返回结果对象）
+function safeValidate(data: unknown) {
+  const result = CreateProjectSchema.safeParse(data)
+  if (!result.success) {
+    console.error('验证失败:', result.error.flatten())
+    return null
+  }
+  return result.data  // 类型安全的数据
+}
+
+// 部分验证（用于更新操作）
+const PartialProjectSchema = CreateProjectSchema.partial()
+function validatePartialUpdate(data: unknown) {
+  return PartialProjectSchema.parse(data)
+}
+```
+
+### 前端表单集成
+
+```typescript
+import { CreateProjectSchema } from '@repo/sdk'
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { z } from 'zod'
+import { root } from '@repo/core'
+import { ProjectController } from '@repo/sdk'
+
+// 从 Schema 推导表单类型
+type FormData = z.infer<typeof CreateProjectSchema>
+
+function CreateProjectForm() {
+  const { register, handleSubmit, formState: { errors } } = useForm<FormData>({
+    resolver: zodResolver(CreateProjectSchema)  // 复用 SDK Schema
+  })
+
+  const onSubmit = async (data: FormData) => {
+    const projectCtrl = root.get(ProjectController)
+    const project = await projectCtrl.create(data)  // 类型完全匹配
+    console.log('创建成功:', project.id)
+  }
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('title')} />
+      {errors.title && <span>{errors.title.message}</span>}
+      {/* ... */}
+    </form>
+  )
+}
+```
+
+### 服务端实现复用类型
+
+```typescript
+import { Injectable } from '@repo/core'
+import { ProjectController } from '@repo/sdk'
+// 直接复用 SDK 导出的类型
+import type {
+  Project,
+  CreateProjectInput,
+  ListProjectsInput,
+  ListProjectsResult,
+  UpdateProjectInput
+} from '@repo/sdk'
+
+@Injectable()
+export class ProjectControllerImpl implements ProjectController {
+  constructor(
+    private readonly db: DatabaseService,
+    private readonly auth: AuthService
+  ) {}
+
+  // 参数和返回值类型直接复用 SDK 类型
+  async create(data: CreateProjectInput): Promise<Project> {
+    const userId = this.auth.getCurrentUserId()
+    return this.db.project.create({
+      data: { ...data, userId }
+    })
+  }
+
+  async list(body: ListProjectsInput): Promise<ListProjectsResult> {
+    // 实现...
+  }
+
+  async update(body: UpdateProjectInput): Promise<Project> {
+    // 实现...
+  }
+}
+```
+
+---
+
+## 3. Better Auth 插件风格
+
+**适用场景**：已使用 Better Auth 进行身份认证的项目
+
+### 安装和配置
+
+```typescript
+import { createAuthClient } from 'better-auth/client'
+import { createSkerClientPlugin } from '@repo/sdk'
+
+// 创建带 Sker 插件的 Auth 客户端
+const auth = createAuthClient({
+  baseURL: 'http://localhost:3000',
+  plugins: [createSkerClientPlugin()]
+})
+
+export { auth }
+```
+
+### 调用方式
+
+```typescript
+// 项目管理
+const projects = await auth.sker.project.list({ page: 1, limit: 10 })
+const project = await auth.sker.project.create({ title: '新项目', content: {} })
+const detail = await auth.sker.project.get('project-id')
+
+// 模板管理
+const templates = await auth.sker.template.list({ page: 1 })
+const { generationId } = await auth.sker.template.run({ templateId: 'xxx', formData: {} })
+
+// 社交功能
+await auth.sker.templateSocial.like({ templateId: 'xxx' })
+const comments = await auth.sker.templateSocial.getComments({ templateId: 'xxx' })
+
+// AI 生成
+const models = await auth.sker.aigc.getModels('image')
+const { task_id } = await auth.sker.aigc.submitTask({ model_name: 'xxx', prompt: 'xxx' })
+
+// 文件上传
+const formData = new FormData()
+formData.append('file', file)
+const { data: fileUrl } = await auth.sker.file.uploadS3(formData)
+```
+
+### 插件工作原理
+
+`createSkerClientPlugin()` 做了以下事情：
+
+1. **注册 HTTP 代理**：将所有 Controller 替换为 HTTP 调用代理
+2. **提供 Better Auth 风格 API**：通过 `auth.sker.xxx` 访问
+3. **自动处理认证**：使用 Better Auth 的 session 进行认证
+4. **生成路径映射**：自动从 Controller 元数据生成路由
+
+```typescript
+// 插件内部实现简化版
+export function createSkerClientPlugin(): BetterAuthClientPlugin {
+  return {
+    id: 'sker',
+    getActions: ($fetch) => {
+      // 注册代理到 DI 容器
+      registerControllerProxies($fetch)
+      // 返回 Better Auth 风格的 actions
+      return buildBetterAuthActions(controllers, $fetch)
+    },
+    pathMethods: generatePathMethods(controllers)
+  }
+}
+```
+
+---
+
+## 4. API 函数风格
+
+**推荐场景**：不使用 Better Auth、需要独立的 API 客户端
+
+### 配置客户端
+
+```typescript
+import { client, generateApiFunctions } from '@repo/sdk'
+
+// 配置基础 URL 和认证
+client.setConfig({
+  baseUrl: 'http://localhost:3000',
+  auth: async () => {
+    // 返回认证 token
+    return localStorage.getItem('token') || ''
+  }
+})
+
+// 生成所有 API 函数
+const apis = generateApiFunctions()
+```
+
+### 调用方式
+
+函数名格式：`{httpMethod}{Path}`（驼峰命名）
+
+```typescript
+// POST /loomart/project/list -> postLoomartProjectList
+const projects = await apis.postLoomartProjectList({ page: 1, limit: 10 })
+
+// GET /loomart/template/get -> getLoomartTemplateGet
+const template = await apis.getLoomartTemplateGet({ id: 'template-id' })
+
+// POST /loomart/template/run -> postLoomartTemplateRun
+const { generationId } = await apis.postLoomartTemplateRun({
+  templateId: 'xxx',
+  formData: {}
+})
+
+// GET /loomart/aigc/models -> getLoomartAigcModels
+const models = await apis.getLoomartAigcModels({ category: 'image' })
+
+// POST /loomart/file/upload-s3 -> postLoomartFileUploadS3
+const formData = new FormData()
+formData.append('file', file)
+const result = await apis.postLoomartFileUploadS3(formData)
+```
+
+### 函数名映射规则
+
+| 路由 | HTTP 方法 | 函数名 |
+|------|-----------|--------|
+| /loomart/project/create | POST | postLoomartProjectCreate |
+| /loomart/project/list | POST | postLoomartProjectList |
+| /loomart/project/get | GET | getLoomartProjectGet |
+| /loomart/template/run | POST | postLoomartTemplateRun |
+| /loomart/aigc/task/submit | POST | postLoomartAigcTaskSubmit |
+| /loomart/aigc/task/status | GET | getLoomartAigcTaskStatus |
+| /loomart/file/upload-s3 | POST | postLoomartFileUploadS3 |
+
+### 动态认证
+
+```typescript
+client.setConfig({
+  baseUrl: 'http://localhost:3000',
+  auth: async (authContext) => {
+    // 可以根据上下文动态获取 token
+    if (authContext?.refreshToken) {
+      // 刷新 token
+      const newToken = await refreshAccessToken(authContext.refreshToken)
+      return newToken
+    }
+    return localStorage.getItem('token') || ''
+  }
+})
+```
+
+---
+
+## 5. 服务端实现
+
+**场景**：在 Hono/Express 等后端框架中实现 Controller
+
+### 注册控制器实现
+
+```typescript
+import { root } from '@repo/core'
+import { ProjectController } from '@repo/sdk'
+import { ProjectControllerImpl } from './impl/project.controller.impl'
+
+// 注册实现类
+root.set([
+  {
+    provide: ProjectController,
+    useClass: ProjectControllerImpl
+  }
+])
+```
+
+### 实现类示例
+
+```typescript
+import { Injectable } from '@repo/core'
+import { ProjectController } from '@repo/sdk'
+import type {
+  Project,
+  CreateProjectInput,
+  ListProjectsInput,
+  ListProjectsResult
+} from '@repo/sdk'
+
+@Injectable()
+export class ProjectControllerImpl implements ProjectController {
+  constructor(
+    private readonly db: DatabaseService,
+    private readonly auth: AuthService
+  ) {}
+
+  async create(data: CreateProjectInput): Promise<Project> {
+    const userId = this.auth.getCurrentUserId()
+
+    const project = await this.db.project.create({
+      data: {
+        ...data,
+        userId
+      }
+    })
+
+    return project
+  }
+
+  async list(body: ListProjectsInput): Promise<ListProjectsResult> {
+    const userId = this.auth.getCurrentUserId()
+
+    const [projects, total] = await Promise.all([
+      this.db.project.findMany({
+        where: { userId, isDeleted: false },
+        skip: ((body.page || 1) - 1) * (body.limit || 20),
+        take: body.limit || 20,
+        orderBy: { [body.sortBy || 'createdAt']: body.sortOrder || 'desc' }
+      }),
+      this.db.project.count({ where: { userId, isDeleted: false } })
+    ])
+
+    return {
+      projects,
+      total,
+      page: body.page || 1,
+      limit: body.limit || 20
+    }
+  }
+
+  async get(id: string): Promise<Project> {
+    const project = await this.db.project.findUnique({ where: { id } })
+    if (!project) throw new Error('Project not found')
+    return project
+  }
+
+  async update(body: UpdateProjectInput): Promise<Project> {
+    return this.db.project.update({
+      where: { id: body.id },
+      data: body
+    })
+  }
+
+  async delete(body: { id: string }): Promise<{ message: string }> {
+    await this.db.project.update({
+      where: { id: body.id },
+      data: { isDeleted: true }
+    })
+    return { message: 'Project deleted' }
+  }
+
+  async transfer(body: TransferProjectInput): Promise<TransferProjectResult> {
+    // 实现转移逻辑...
+  }
+}
+```
+
+### 与 Hono 集成
+
+```typescript
+import { Hono } from 'hono'
+import { root, CONTROLLES } from '@repo/core'
+
+const app = new Hono()
+
+// 自动注册所有控制器路由
+const controllers = root.get(CONTROLLES, [])
+for (const controller of controllers) {
+  // 使用 @repo/core 的路由注册逻辑
+  registerControllerRoutes(app, controller)
+}
+
+export default app
+```
+
+---
+
+## 6. 错误处理
+
+### 客户端错误处理
+
+```typescript
+import { ProjectController } from '@repo/sdk'
+import { root } from '@repo/core'
+
+const projectCtrl = root.get(ProjectController)
+
+try {
+  const project = await projectCtrl.get('non-existent-id')
+} catch (error) {
+  if (error.message.includes('API error')) {
+    // API 返回的错误
+    console.error('API 错误:', error.message)
+  } else {
+    // 网络或其他错误
+    console.error('请求失败:', error)
+  }
+}
+```
+
+### 统一错误处理
+
+```typescript
+// 创建带错误处理的包装器
+function withErrorHandling<T extends (...args: any[]) => Promise<any>>(fn: T): T {
+  return (async (...args: Parameters<T>) => {
+    try {
+      return await fn(...args)
+    } catch (error: any) {
+      // 统一错误处理
+      if (error.message.includes('401')) {
+        // 未认证，跳转登录
+        window.location.href = '/login'
+        return
+      }
+      if (error.message.includes('403')) {
+        // 无权限
+        throw new Error('您没有权限执行此操作')
+      }
+      if (error.message.includes('404')) {
+        throw new Error('资源不存在')
+      }
+      throw error
+    }
+  }) as T
+}
+
+// 使用
+const safeList = withErrorHandling(projectCtrl.list.bind(projectCtrl))
+const projects = await safeList({ page: 1 })
+```
+
+---
+
+## 最佳实践总结
+
+### 推荐做法
+
+| 场景 | 推荐方式 |
+|------|----------|
+| 调用 API | `root.get(Controller)` - 完整类型安全 |
+| 定义类型 | 从 `@repo/sdk` 导入，不要自己定义 |
+| 验证数据 | 复用 SDK 导出的 Zod Schema |
+| 表单验证 | 使用 `zodResolver(Schema)` |
+| 服务端实现 | `implements Controller` + 复用类型 |
+
+### 避免做法
+
+```typescript
+// ❌ 不要自己定义类型
+interface MyProject {
+  id: string;
+  title: string;
+}
+
+// ✅ 从 SDK 导入类型
+import type { Project } from '@repo/sdk'
+
+// ❌ 不要自己写验证逻辑
+if (!data.title || data.title.length < 1) {
+  throw new Error('标题不能为空')
+}
+
+// ✅ 复用 SDK Schema
+import { CreateProjectSchema } from '@repo/sdk'
+CreateProjectSchema.parse(data)
+
+// ❌ 不要使用 any 类型
+const projectCtrl: any = root.get(ProjectController)
+
+// ✅ 让 TypeScript 自动推导
+const projectCtrl = root.get(ProjectController)  // 类型自动推导
+```