zhixing-system/.trellis/spec/frontend/hook-guidelines.md

Hook 与数据请求

API 适配三件套

服务端数据按 feature 放置为 API 函数、query hook 和类型文件：

1. features/system/api/system.types.ts 定义 SystemStatus。
2. features/system/api/system.api.ts:getSystemStatus 调用 shared transport，并把 AbortSignal 传给 fetch。
3. features/system/api/system.query.ts:useSystemStatus 暴露 React Query hook，并使用 systemStatusQueryKey。

页面只调用 useSystemStatus，不直接调用 fetch。新增 feature 应保持同样分层。

export const systemStatusQueryKey = ["system", "status"] as const

export function useSystemStatus() {
  return useQuery({
    queryFn: ({ signal }) => getSystemStatus(signal),
    queryKey: systemStatusQueryKey,
  })
}

React Query

• 服务器状态由 TanStack Query 管理；公共默认值在 app/query-client.ts（不跟随窗口刷新、失败重试 1 次、staleTime 30 秒）。
• query key 使用 as const 常量，避免页面散落字符串。
• 使用 query function 提供的 signal 支持取消请求；不要忽略它或在页面手写生命周期 fetch。
• 页面显式处理 isPending、isError 和 data，参照 SystemStatusPage。

Hook 命名与副作用

• 自定义 hook 以 use 开头并表达资源或行为，例如 useSystemStatus、useUiStore。
• 纯数据 hook 不执行额外副作用；需要同步 DOM 的副作用集中在 app/providers.tsx:ThemeEffect，由 Zustand 主题驱动 document.documentElement 的 class。
• 不要把一个 hook 同时用作服务器缓存和 UI 偏好存储；两者分别使用 React Query 与 Zustand。

反模式

• 不要在组件中直接 fetch、重复设置 query key 或把响应复制到本地 useState。
• 不要用 Zustand 保存 API 响应以“共享”数据，也不要用 React Query 保存主题等本地偏好。
• 不要为了复用一次性的 useEffect 创建泛化 hook；先确认是否已有跨页面重复模式。