src/
├── api/                    # API 相關
│   ├── client.ts           # axios/fetch 設定
│   └── products.ts         # 商品 API 函式
│
├── hooks/                  # TanStack Query hooks
│   ├── useProducts.ts      # 商品查詢 hook
│   └── useCart.ts          # 購物車相關 query hook
│
├── stores/                 # Zustand stores
│   ├── cartStore.ts        # 購物車狀態
│   └── filterStore.ts      # 篩選條件狀態
│
├── components/             # React 元件
└── App.tsx
Code language: PHP (php)

這個資料從哪來？
│
├─ 來自 API/伺服器 → 用 TanStack Query
│   例如：商品列表、用戶資料、訂單記錄
│
└─ 來自使用者操作，只存在前端 → 用 Zustand
    │
    ├─ 只在單一元件內使用 → 考慮用 useState
    │   例如：modal 開關、表單輸入中的值
    │
    └─ 需要跨元件共享 → 用 Zustand
        例如：購物車、篩選條件、用戶偏好設定

// stores/cartStore.ts
import { create } from 'zustand'

interface CartItem {
  productId: string
  quantity: number
}

interface CartStore {
  items: CartItem[]
  addItem: (productId: string) => void
  removeItem: (productId: string) => void
  clearCart: () => void
}

export const useCartStore = create<CartStore>((set) => ({
  items: [],

  addItem: (productId) => set((state) => {
    const existing = state.items.find(item => item.productId === productId)
    if (existing) {
      return {
        items: state.items.map(item =>
          item.productId === productId
            ? { ...item, quantity: item.quantity + 1 }
            : item
        )
      }
    }
    return { items: [...state.items, { productId, quantity: 1 }] }
  }),

  removeItem: (productId) => set((state) => ({
    items: state.items.filter(item => item.productId !== productId)
  })),

  clearCart: () => set({ items: [] })
}))
Code language: JavaScript (javascript)

// stores/filterStore.ts
import { create } from 'zustand'

interface FilterStore {
  category: string | null
  minPrice: number | null
  maxPrice: number | null
  setCategory: (category: string | null) => void
  setPriceRange: (min: number | null, max: number | null) => void
}

export const useFilterStore = create<FilterStore>((set) => ({
  category: null,
  minPrice: null,
  maxPrice: null,

  setCategory: (category) => set({ category }),
  setPriceRange: (min, max) => set({ minPrice: min, maxPrice: max })
}))
Code language: JavaScript (javascript)

// hooks/useProducts.ts
import { useQuery } from '@tanstack/react-query'
import { useFilterStore } from '../stores/filterStore'

interface Product {
  id: string
  name: string
  price: number
  category: string
}

// API 函式
async function fetchProducts(filters: {
  category?: string | null
  minPrice?: number | null
  maxPrice?: number | null
}): Promise<Product[]> {
  const params = new URLSearchParams()
  if (filters.category) params.set('category', filters.category)
  if (filters.minPrice) params.set('minPrice', String(filters.minPrice))
  if (filters.maxPrice) params.set('maxPrice', String(filters.maxPrice))

  const response = await fetch(`/api/products?${params}`)
  return response.json()
}

// 整合 Zustand 狀態的 Query Hook
export function useProducts() {
  // 從 Zustand 取得篩選條件
  const { category, minPrice, maxPrice } = useFilterStore()

  return useQuery({
    // 關鍵：將篩選條件納入 queryKey
    queryKey: ['products', { category, minPrice, maxPrice }],
    queryFn: () => fetchProducts({ category, minPrice, maxPrice })
  })
}
Code language: HTML, XML (xml)

// components/ProductList.tsx
import { useProducts } from '../hooks/useProducts'
import { useCartStore } from '../stores/cartStore'
import { useFilterStore } from '../stores/filterStore'

function ProductList() {
  // TanStack Query：取得商品資料
  const { data: products, isLoading, error } = useProducts()

  // Zustand：購物車操作
  const addItem = useCartStore(state => state.addItem)

  if (isLoading) return <div>載入中...</div>
  if (error) return <div>載入失敗</div>

  return (
    <div className="product-grid">
      {products?.map(product => (
        <div key={product.id} className="product-card">
          <h3>{product.name}</h3>
          <p>${product.price}</p>
          <button onClick={() => addItem(product.id)}>
            加入購物車
          </button>
        </div>
      ))}
    </div>
  )
}
Code language: JavaScript (javascript)

// components/FilterPanel.tsx
import { useFilterStore } from '../stores/filterStore'

function FilterPanel() {
  const { category, setCategory, setPriceRange } = useFilterStore()

  return (
    <div className="filter-panel">
      <select
        value={category || ''}
        onChange={(e) => setCategory(e.target.value || null)}
      >
        <option value="">全部分類</option>
        <option value="electronics">電子產品</option>
        <option value="clothing">服飾</option>
      </select>

      <button onClick={() => setPriceRange(0, 1000)}>
        $1000 以下
      </button>
      <button onClick={() => setPriceRange(1000, 5000)}>
        $1000 - $5000
      </button>
    </div>
  )
}
Code language: JavaScript (javascript)

// components/Cart.tsx
import { useCartStore } from '../stores/cartStore'

function Cart() {
  const { items, removeItem, clearCart } = useCartStore()

  return (
    <div className="cart">
      <h2>購物車 ({items.length} 件)</h2>
      {items.map(item => (
        <div key={item.productId}>
          商品 {item.productId} x {item.quantity}
          <button onClick={() => removeItem(item.productId)}>移除</button>
        </div>
      ))}
      <button onClick={clearCart}>清空購物車</button>
    </div>
  )
}
Code language: JavaScript (javascript)

// hooks/useCategories.ts
import { useQuery } from '@tanstack/react-query'
import { useEffect } from 'react'
import { useFilterStore } from '../stores/filterStore'

export function useCategories() {
  const setCategory = useFilterStore(state => state.setCategory)
  const currentCategory = useFilterStore(state => state.category)

  const query = useQuery({
    queryKey: ['categories'],
    queryFn: () => fetch('/api/categories').then(res => res.json())
  })

  // 當分類載入完成且尚未選擇時，預設選中第一個
  useEffect(() => {
    if (query.data && query.data.length > 0 && !currentCategory) {
      setCategory(query.data[0].id)
    }
  }, [query.data, currentCategory, setCategory])

  return query
}
Code language: JavaScript (javascript)

// hooks/useCheckout.ts
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { useCartStore } from '../stores/cartStore'

export function useCheckout() {
  const queryClient = useQueryClient()
  const clearCart = useCartStore(state => state.clearCart)
  const cartItems = useCartStore(state => state.items)

  return useMutation({
    mutationFn: () => fetch('/api/checkout', {
      method: 'POST',
      body: JSON.stringify({ items: cartItems })
    }),
    onSuccess: () => {
      // 清空 Zustand 購物車
      clearCart()
      // 讓訂單列表重新查詢
      queryClient.invalidateQueries({ queryKey: ['orders'] })
    }
  })
}
Code language: JavaScript (javascript)

// 錯誤做法
const useProductStore = create((set) => ({
  products: [],
  fetchProducts: async () => {
    const data = await fetch('/api/products').then(res => res.json())
    set({ products: data })  // 不要這樣做！
  }
}))

// 正確做法：用 TanStack Query
const { data: products } = useQuery({
  queryKey: ['products'],
  queryFn: () => fetch('/api/products').then(res => res.json())
})
Code language: JavaScript (javascript)

// 錯誤做法
useQuery({
  queryKey: ['products'],
  queryFn: async () => {
    const data = await fetchProducts()
    useFilterStore.getState().setCategory(data[0].category)  // 不要這樣！
    return data
  }
})

// 正確做法：用 useEffect 處理副作用
const query = useQuery({ queryKey: ['products'], queryFn: fetchProducts })

useEffect(() => {
  if (query.data) {
    useFilterStore.getState().setCategory(query.data[0].category)
  }
}, [query.data])
Code language: JavaScript (javascript)

// 錯誤做法
const category = useFilterStore(state => state.category)

useQuery({
  queryKey: ['products'],  // 沒有包含 category！
  queryFn: () => fetchProducts({ category })
})

// 正確做法
useQuery({
  queryKey: ['products', { category }],  // category 改變時會重新查詢
  queryFn: () => fetchProducts({ category })
})
Code language: JavaScript (javascript)

┌─────────────────────────────────────────────────────────┐
│                      React 元件                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   ┌─────────────────┐       ┌─────────────────┐        │
│   │  useProducts()  │       │  useCartStore() │        │
│   │  TanStack Query │       │     Zustand     │        │
│   └────────┬────────┘       └────────┬────────┘        │
│            │                         │                  │
│            │    queryKey 包含        │                  │
│            │◄───篩選條件──────────────┤                  │
│            │                         │                  │
│   ┌────────▼────────┐       ┌────────▼────────┐        │
│   │   伺服器狀態     │       │   客戶端狀態     │        │
│   │  - 商品列表      │       │  - 購物車       │        │
│   │  - 訂單記錄      │       │  - 篩選條件      │        │
│   │  - 用戶資料      │       │  - UI 狀態      │        │
│   └────────┬────────┘       └─────────────────┘        │
│            │                                            │
└────────────┼────────────────────────────────────────────┘
             │
             ▼
      ┌─────────────┐
      │   API 伺服器 │
      └─────────────┘