expo-duooomi-app/.claude/skills/hooks-api/SKILL.md

name	description
hooks-api	Duooomi 应用 Hooks API 层使用指南。当需要数据获取、API 调用、AIGC 任务提交、模板操作、文件上传、用户认证、余额查询时触发。Hooks 分三层：core（基础能力）、data（数据查询）、actions（写操作）。所有 hooks 基于 @repo/sdk Controller 通过 IoC 容器 root.get() 获取实例，使用 handleError 统一错误处理。

Hooks API 层

架构

hooks/
├── core/          # 基础能力：useAuth, useLoomartApi, useUserBalance
├── data/          # 数据查询：useTemplates, useTemplateDetail, useTemplateGenerations,
│                  #   useRecommendedTemplates, usePublicTemplates, useLikesTemplates,
│                  #   useCategories, useTags, useActivities, useSearchHistory, useError
├── actions/       # 写操作：useAigcTask, useTemplateActions, useFileUpload, useTemplateInteraction
└── 独立hooks      # useIOSPurchase, useUpdateChecker, useColorScheme, useThemeColor

核心模式

handleError 统一错误处理

import { handleError } from '@/hooks/data/use-error'
const { data, error } = await handleError(async () => await controller.method(params))

IoC 容器获取 Controller

import { root } from '@repo/core'
import { TemplateController } from '@repo/sdk'
const controller = root.get(TemplateController)

通用返回值

// 简单列表: { data, loading, error, load }
// 分页列表: { data, loading, loadingMore, error, execute/load, refetch, loadMore, hasMore }
// 详情:     { data, loading, error, execute/load, refetch }

使用示例

模板列表（分页）

const { data, loading, loadingMore, execute, loadMore, hasMore } = useTemplates()
useEffect(() => { execute({ page: 1, limit: 20, categoryId: 'xxx' }) }, [])
const handleLoadMore = () => { if (hasMore && !loadingMore) loadMore({ categoryId: 'xxx' }) }

AIGC 任务提交 + 轮询

const { submitTask, startPolling, stopPolling, isPolling } = useAigcTask()
const { taskId } = await submitTask({ templateId: 'xxx', params: {...} })
if (taskId) {
  startPolling(taskId,
    (result) => { /* 完成 */ },
    (error) => { /* 失败 */ }
  )
}
useEffect(() => () => stopPolling(), [])

文件上传

const { uploadFile, loading, progress, uploadedUrl } = useFileUpload()
const { url, error } = await uploadFile(file, 'avatars')

模板点赞/收藏

const { likeTemplate, unlikeTemplate, checkLiked, favoriteTemplate } = useTemplateInteraction()
const { liked } = await checkLiked(templateId)

认证

const { user, isLogin, signIn, signOut } = useAuth()

编写新 Hook 规范

1. 放在正确的分层目录 (core/data/actions)
2. 用 handleError 包裹所有 SDK 调用
3. 通过 root.get(XxxController) 获取 controller
4. 返回 { data, loading, error, ...methods }
5. 操作方法用 useCallback 包裹
6. 在对应 index.ts 中导出
7. ownerId 从 process.env.EXPO_PUBLIC_OWNER_ID 获取