zhixing-system/.trellis/spec/frontend/state-management.md

# 状态管理

## 三类状态

| 状态 | 当前方案 | 示例 |
| --- | --- | --- |
| 服务器状态 | TanStack Query | `useSystemStatus` 和 `queryClient` |
| 跨页面 UI 偏好 | Zustand + `persist` | `useUiStore.theme` |
| 组件瞬时状态 | React 自带状态/事件 | 当前页面暂无复杂局部状态 |

URL/路由状态由 TanStack Router 承担；当前路由树只有静态 `/`，不要为了静态页面额外引入全局 store。

## Zustand 使用边界

`shared/config/ui-store.ts` 只保存主题这一类跨页面 UI 偏好，并以 `zhixing-ui` 持久化到浏览器存储。组件读取最小 selector：

```tsx
const theme = useUiStore((state) => state.theme)
const toggleTheme = useUiStore((state) => state.toggleTheme)
```

新增全局字段前，确认它需要跨多个页面共享且不属于服务端缓存；否则优先放在组件局部或 URL。

## 服务器状态

所有 API 数据都通过 `queryClient` 和 feature query hook 管理，利用缓存、重试和失效机制。页面不应把 `data` 再写入 Zustand 或重复维护 `loading` 标志。

## 副作用

主题 class 的 DOM 同步集中在 `AppProviders` 内的 `ThemeEffect`，并依赖 store selector。不要在每个页面分别切换 `document.documentElement`，也不要在渲染阶段直接修改 DOM。

## 常见错误

- 把后端响应、错误对象或加载状态复制进 Zustand。
- 通过 `useUiStore((state) => state)` 订阅整个 store，造成无关更新。
- 为一个页面才能使用的开关添加持久化全局状态。