// データフェッチングで対処すべき共通課題
 
// 1. ローディング状態の管理
// Bad: boolean フラグの手動管理
const [loading, setLoading] = useState(false);
const [error, setError] = useState<Error | null>(null);
const [data, setData] = useState<User[] | null>(null);
 
useEffect(() => {
  setLoading(true);
  setError(null);
  fetchUsers()
    .then(setData)
    .catch(setError)
    .finally(() => setLoading(false));
}, []);
 
// Good: 専用ライブラリで宣言的に管理
const { data, isLoading, error } = useQuery({
  queryKey: ['users'],
  queryFn: fetchUsers,
});
 
// 2. キャッシュの一貫性
// 同じデータを複数コンポーネントで使用する場合、
// キャッシュが一元管理されていないと不整合が生じる
 
// 3. 競合状態（Race Condition）
// Bad: useEffect でのフェッチは競合状態を引き起こす
useEffect(() => {
  // ユーザーが素早く切り替えると、古いレスポンスが
  // 新しいレスポンスを上書きする可能性がある
  fetchUser(userId).then(setUser);
}, [userId]);
 
// Good: AbortController でキャンセル
useEffect(() => {
  const controller = new AbortController();
 
  fetchUser(userId, { signal: controller.signal })
    .then(setUser)
    .catch(err => {
      if (err.name !== 'AbortError') setError(err);
    });
 
  return () => controller.abort();
}, [userId]);
 
// 4. エラーハンドリングとリトライ
// ネットワークエラー、タイムアウト、認証エラーなど
// 各種エラーに対する適切な処理が必要
 
// 5. メモリリーク防止
// アンマウントされたコンポーネントへの状態更新を防ぐ

// lib/query-client.ts
import { QueryClient } from '@tanstack/react-query';
 
// QueryClient のシングルトンインスタンスを作成
// サーバーサイドではリクエストごとに新しいインスタンスを作成する必要がある
function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        // === キャッシュ制御 ===
        staleTime: 60 * 1000,           // 60秒間はキャッシュを新鮮とみなす
        gcTime: 5 * 60 * 1000,          // 5分間キャッシュをメモリに保持（旧 cacheTime）
        refetchInterval: false,          // 自動ポーリング無効（必要な箇所で有効に）
 
        // === リトライ制御 ===
        retry: 3,                        // 失敗時に3回リトライ
        retryDelay: (attemptIndex) =>     // 指数バックオフ
          Math.min(1000 * 2 ** attemptIndex, 30000),
 
        // === 再取得トリガー ===
        refetchOnWindowFocus: true,      // ウィンドウフォーカス時に再取得
        refetchOnReconnect: true,        // ネットワーク再接続時に再取得
        refetchOnMount: true,            // コンポーネントマウント時に再取得
 
        // === 構造的共有 ===
        structuralSharing: true,         // データの参照的同一性を保持
 
        // === ネットワーク状態 ===
        networkMode: 'online',           // オフライン時はリクエストを一時停止
      },
      mutations: {
        retry: 1,                        // ミューテーションは1回だけリトライ
        networkMode: 'online',
      },
    },
  });
}
 
// ブラウザではシングルトン、サーバーでは毎回新規作成
let browserQueryClient: QueryClient | undefined;
 
export function getQueryClient() {
  if (typeof window === 'undefined') {
    // サーバー: 常に新しいインスタンスを作成
    return makeQueryClient();
  }
  // ブラウザ: シングルトンを使用
  if (!browserQueryClient) {
    browserQueryClient = makeQueryClient();
  }
  return browserQueryClient;
}

// app/providers.tsx
'use client';
 
import { QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { getQueryClient } from '@/lib/query-client';
 
export function Providers({ children }: { children: React.ReactNode }) {
  // NOTE: useState を使わないことで、Suspense 境界での再作成を防ぐ
  const queryClient = getQueryClient();
 
  return (
    <QueryClientProvider client={queryClient}>
      {children}
      {process.env.NODE_ENV === 'development' && (
        <ReactQueryDevtools initialIsOpen={false} />
      )}
    </QueryClientProvider>
  );
}

// lib/query-keys.ts
// Query Key Factory パターン — 大規模アプリで推奨
 
export const queryKeys = {
  // === Users ===
  users: {
    all: ['users'] as const,
    lists: () => [...queryKeys.users.all, 'list'] as const,
    list: (filters: UserFilters) =>
      [...queryKeys.users.lists(), filters] as const,
    details: () => [...queryKeys.users.all, 'detail'] as const,
    detail: (id: string) =>
      [...queryKeys.users.details(), id] as const,
    profile: (id: string) =>
      [...queryKeys.users.detail(id), 'profile'] as const,
    posts: (id: string) =>
      [...queryKeys.users.detail(id), 'posts'] as const,
  },
 
  // === Products ===
  products: {
    all: ['products'] as const,
    lists: () => [...queryKeys.products.all, 'list'] as const,
    list: (filters: ProductFilters) =>
      [...queryKeys.products.lists(), filters] as const,
    details: () => [...queryKeys.products.all, 'detail'] as const,
    detail: (id: string) =>
      [...queryKeys.products.details(), id] as const,
    reviews: (id: string) =>
      [...queryKeys.products.detail(id), 'reviews'] as const,
    inventory: (id: string) =>
      [...queryKeys.products.detail(id), 'inventory'] as const,
  },
 
  // === Orders ===
  orders: {
    all: ['orders'] as const,
    lists: () => [...queryKeys.orders.all, 'list'] as const,
    list: (filters: OrderFilters) =>
      [...queryKeys.orders.lists(), filters] as const,
    detail: (id: string) =>
      [...queryKeys.orders.all, 'detail', id] as const,
  },
} as const;
 
// 型定義
interface UserFilters {
  role?: 'admin' | 'user' | 'moderator';
  status?: 'active' | 'inactive';
  search?: string;
  page?: number;
  limit?: number;
}
 
interface ProductFilters {
  category?: string;
  minPrice?: number;
  maxPrice?: number;
  sortBy?: 'price' | 'rating' | 'newest';
  page?: number;
}
 
interface OrderFilters {
  status?: 'pending' | 'processing' | 'shipped' | 'delivered';
  dateRange?: { start: Date; end: Date };
  page?: number;
}

// Query Key Factory の使用例
 
// 全ユーザーキャッシュの無効化
queryClient.invalidateQueries({ queryKey: queryKeys.users.all });
 
// フィルタ付きリストの無効化
queryClient.invalidateQueries({
  queryKey: queryKeys.users.list({ role: 'admin' }),
});
 
// 特定ユーザーの詳細キャッシュのみ無効化
queryClient.invalidateQueries({
  queryKey: queryKeys.users.detail('user-123'),
});
 
// 全リスト系キャッシュの無効化（フィルタに関係なく）
queryClient.invalidateQueries({
  queryKey: queryKeys.users.lists(),
});
 
// 特定ユーザーに関連する全キャッシュの無効化
// （詳細 + プロフィール + 投稿）
queryClient.invalidateQueries({
  queryKey: queryKeys.users.detail('user-123'),
});

// hooks/use-users.ts
import { useQuery, useMutation, useQueryClient, useInfiniteQuery } from '@tanstack/react-query';
import { queryKeys } from '@/lib/query-keys';
import { api } from '@/lib/api-client';
import type { User, CreateUserInput, UpdateUserInput, UserFilters } from '@/types';
 
/**
 * ユーザー一覧を取得するカスタムフック
 *
 * @example
 * ```tsx
 * const { data, isLoading, error } = useUsers({ role: 'admin', page: 1 });
 * ```
 */
export function useUsers(filters?: UserFilters) {
  return useQuery({
    queryKey: queryKeys.users.list(filters ?? {}),
    queryFn: () => api.users.list(filters),
    staleTime: 30 * 1000, // 30秒間キャッシュ
    placeholderData: (previousData) => previousData, // ページ切替時に前のデータを表示
  });
}
 
/**
 * ユーザー詳細を取得するカスタムフック
 * 一覧データからの初期データ設定により、即座に表示可能
 */
export function useUser(userId: string) {
  const queryClient = useQueryClient();
 
  return useQuery({
    queryKey: queryKeys.users.detail(userId),
    queryFn: () => api.users.get(userId),
    staleTime: 5 * 60 * 1000, // 5分間キャッシュ
    // 一覧データのキャッシュから初期データを設定
    initialData: () => {
      const listsCache = queryClient.getQueriesData<{ users: User[] }>({
        queryKey: queryKeys.users.lists(),
      });
      for (const [, data] of listsCache) {
        const user = data?.users.find(u => u.id === userId);
        if (user) return user;
      }
      return undefined;
    },
    initialDataUpdatedAt: () => {
      // 初期データのタイムスタンプを取得（staleTime の計算に使用）
      return queryClient.getQueryState(queryKeys.users.lists())
        ?.dataUpdatedAt;
    },
  });
}
 
/**
 * ユーザー検索フック（デバウンス付き）
 */
export function useUserSearch(searchTerm: string) {
  return useQuery({
    queryKey: queryKeys.users.list({ search: searchTerm }),
    queryFn: () => api.users.search(searchTerm),
    enabled: searchTerm.length >= 2, // 2文字以上で検索開始
    staleTime: 10 * 1000,
    placeholderData: (previousData) => previousData,
  });
}
 
/**
 * ユーザー作成ミューテーション
 * 成功時にリストキャッシュを自動無効化
 */
export function useCreateUser() {
  const queryClient = useQueryClient();
 
  return useMutation({
    mutationFn: (data: CreateUserInput) => api.users.create(data),
    onSuccess: (newUser) => {
      // リストキャッシュを無効化して再取得
      queryClient.invalidateQueries({
        queryKey: queryKeys.users.lists(),
      });
      // 新しいユーザーの詳細キャッシュを設定
      queryClient.setQueryData(
        queryKeys.users.detail(newUser.id),
        newUser,
      );
    },
    onError: (error) => {
      console.error('Failed to create user:', error);
    },
  });
}
 
/**
 * ユーザー更新ミューテーション（楽観的更新付き）
 */
export function useUpdateUser() {
  const queryClient = useQueryClient();
 
  return useMutation({
    mutationFn: ({ id, data }: { id: string; data: UpdateUserInput }) =>
      api.users.update(id, data),
 
    onMutate: async ({ id, data }) => {
      // 進行中のクエリをキャンセル
      await queryClient.cancelQueries({
        queryKey: queryKeys.users.detail(id),
      });
 
      // スナップショットを保存
      const previousUser = queryClient.getQueryData<User>(
        queryKeys.users.detail(id),
      );
 
      // 楽観的にキャッシュを更新
      if (previousUser) {
        queryClient.setQueryData(
          queryKeys.users.detail(id),
          { ...previousUser, ...data },
        );
      }
 
      return { previousUser };
    },
 
    onError: (error, { id }, context) => {
      // エラー時にロールバック
      if (context?.previousUser) {
        queryClient.setQueryData(
          queryKeys.users.detail(id),
          context.previousUser,
        );
      }
    },
 
    onSettled: (data, error, { id }) => {
      // 最新データで再検証
      queryClient.invalidateQueries({
        queryKey: queryKeys.users.detail(id),
      });
      queryClient.invalidateQueries({
        queryKey: queryKeys.users.lists(),
      });
    },
  });
}
 
/**
 * ユーザー削除ミューテーション
 */
export function useDeleteUser() {
  const queryClient = useQueryClient();
 
  return useMutation({
    mutationFn: (userId: string) => api.users.delete(userId),
 
    onMutate: async (userId) => {
      await queryClient.cancelQueries({
        queryKey: queryKeys.users.lists(),
      });
 
      // 全リストキャッシュから楽観的に削除
      const previousLists = queryClient.getQueriesData<{ users: User[] }>({
        queryKey: queryKeys.users.lists(),
      });
 
      queryClient.setQueriesData<{ users: User[] }>(
        { queryKey: queryKeys.users.lists() },
        (old) => old ? {
          ...old,
          users: old.users.filter(u => u.id !== userId),
        } : old,
      );
 
      return { previousLists };
    },
 
    onError: (error, userId, context) => {
      // ロールバック
      context?.previousLists.forEach(([queryKey, data]) => {
        queryClient.setQueryData(queryKey, data);
      });
    },
 
    onSettled: () => {
      queryClient.invalidateQueries({
        queryKey: queryKeys.users.lists(),
      });
    },
  });
}

// hooks/use-infinite-products.ts
import { useInfiniteQuery } from '@tanstack/react-query';
import { queryKeys } from '@/lib/query-keys';
import { api } from '@/lib/api-client';
 
interface ProductsResponse {
  products: Product[];
  nextCursor: string | null;
  totalCount: number;
}
 
export function useInfiniteProducts(filters?: ProductFilters) {
  return useInfiniteQuery({
    queryKey: queryKeys.products.list(filters ?? {}),
    queryFn: ({ pageParam }) => api.products.list({
      ...filters,
      cursor: pageParam,
      limit: 20,
    }),
    initialPageParam: undefined as string | undefined,
    getNextPageParam: (lastPage: ProductsResponse) => lastPage.nextCursor,
    // 前のページパラメータ（双方向スクロール時）
    getPreviousPageParam: undefined,
    staleTime: 60 * 1000,
    // 最大ページ数を制限（メモリ節約）
    maxPages: 10,
  });
}
 
// コンポーネントでの使用
function InfiniteProductList() {
  const {
    data,
    fetchNextPage,
    hasNextPage,
    isFetchingNextPage,
    isLoading,
    error,
  } = useInfiniteProducts({ category: 'electronics' });
 
  // Intersection Observer で自動読み込み
  const loadMoreRef = useRef<HTMLDivElement>(null);
 
  useEffect(() => {
    const observer = new IntersectionObserver(
      (entries) => {
        if (entries[0].isIntersecting && hasNextPage && !isFetchingNextPage) {
          fetchNextPage();
        }
      },
      { threshold: 0.1 },
    );
 
    if (loadMoreRef.current) {
      observer.observe(loadMoreRef.current);
    }
 
    return () => observer.disconnect();
  }, [hasNextPage, isFetchingNextPage, fetchNextPage]);
 
  if (isLoading) return <ProductGridSkeleton />;
  if (error) return <ErrorMessage error={error} />;
 
  const allProducts = data?.pages.flatMap(page => page.products) ?? [];
 
  return (
    <div>
      <div className="grid grid-cols-3 gap-4">
        {allProducts.map(product => (
          <ProductCard key={product.id} product={product} />
        ))}
      </div>
 
      <div ref={loadMoreRef} className="h-20 flex items-center justify-center">
        {isFetchingNextPage && <Spinner />}
        {!hasNextPage && allProducts.length > 0 && (
          <p className="text-gray-500">全ての商品を表示しました</p>
        )}
      </div>
    </div>
  );
}

// TanStack Query と Server Components の統合（Next.js App Router）
 
// app/users/page.tsx — Server Component
import { dehydrate, HydrationBoundary } from '@tanstack/react-query';
import { getQueryClient } from '@/lib/query-client';
import { queryKeys } from '@/lib/query-keys';
import { api } from '@/lib/api-client';
import { UserListClient } from './user-list-client';
 
export default async function UsersPage() {
  const queryClient = getQueryClient();
 
  // サーバーサイドでデータを事前取得
  await queryClient.prefetchQuery({
    queryKey: queryKeys.users.list({}),
    queryFn: () => api.users.list(),
  });
 
  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <UserListClient />
    </HydrationBoundary>
  );
}
 
// app/users/user-list-client.tsx — Client Component
'use client';
 
import { useUsers } from '@/hooks/use-users';
 
export function UserListClient() {
  // サーバーで prefetch したデータが即座に利用可能
  // isLoading は false でスタート
  const { data, isLoading, error } = useUsers();
 
  if (isLoading) return <Skeleton />;
  if (error) return <ErrorMessage error={error} />;
 
  return (
    <ul>
      {data.users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

// Router レベルの Prefetch（ナビゲーション前にデータを取得）
 
// リンクホバー時にプリフェッチ
function UserLink({ userId, children }: { userId: string; children: React.ReactNode }) {
  const queryClient = useQueryClient();
 
  const prefetchUser = () => {
    queryClient.prefetchQuery({
      queryKey: queryKeys.users.detail(userId),
      queryFn: () => api.users.get(userId),
      staleTime: 5 * 60 * 1000,
    });
  };
 
  return (
    <Link
      href={`/users/${userId}`}
      onMouseEnter={prefetchUser}
      onFocus={prefetchUser}
    >
      {children}
    </Link>
  );
}

// ポーリングによるリアルタイム更新
 
// 通知カウントの定期取得
export function useNotificationCount() {
  return useQuery({
    queryKey: ['notifications', 'count'],
    queryFn: () => api.notifications.getUnreadCount(),
    refetchInterval: 30 * 1000,          // 30秒ごとにポーリング
    refetchIntervalInBackground: false,   // バックグラウンドではポーリングしない
    staleTime: 10 * 1000,
  });
}
 
// ジョブの進捗状態をポーリング（完了したらポーリング停止）
export function useJobStatus(jobId: string) {
  return useQuery({
    queryKey: ['jobs', jobId],
    queryFn: () => api.jobs.getStatus(jobId),
    refetchInterval: (query) => {
      // ジョブ完了時はポーリングを停止
      const status = query.state.data?.status;
      if (status === 'completed' || status === 'failed') {
        return false;
      }
      return 2000; // 2秒ごとにポーリング
    },
    enabled: !!jobId,
  });
}
 
// WebSocket との統合
export function useRealtimeOrders() {
  const queryClient = useQueryClient();
 
  useEffect(() => {
    const ws = new WebSocket('wss://api.example.com/ws/orders');
 
    ws.onmessage = (event) => {
      const update = JSON.parse(event.data);
 
      switch (update.type) {
        case 'ORDER_CREATED':
          // リストキャッシュを無効化
          queryClient.invalidateQueries({
            queryKey: queryKeys.orders.lists(),
          });
          break;
 
        case 'ORDER_UPDATED':
          // 特定の注文キャッシュを直接更新
          queryClient.setQueryData(
            queryKeys.orders.detail(update.orderId),
            (old: Order | undefined) =>
              old ? { ...old, ...update.changes } : old,
          );
          break;
 
        case 'ORDER_DELETED':
          // キャッシュから削除
          queryClient.removeQueries({
            queryKey: queryKeys.orders.detail(update.orderId),
          });
          queryClient.invalidateQueries({
            queryKey: queryKeys.orders.lists(),
          });
          break;
      }
    };
 
    ws.onerror = () => {
      // WebSocket エラー時はポーリングにフォールバック
      console.warn('WebSocket error, falling back to polling');
    };
 
    return () => ws.close();
  }, [queryClient]);
 
  return useQuery({
    queryKey: queryKeys.orders.lists(),
    queryFn: () => api.orders.list(),
    staleTime: 60 * 1000,
  });
}

// lib/swr-config.tsx
import { SWRConfig } from 'swr';
 
// グローバルフェッチャー関数
const fetcher = async (url: string) => {
  const res = await fetch(url);
 
  if (!res.ok) {
    const error = new Error('An error occurred while fetching the data.');
    (error as any).info = await res.json();
    (error as any).status = res.status;
    throw error;
  }
 
  return res.json();
};
 
export function SWRProvider({ children }: { children: React.ReactNode }) {
  return (
    <SWRConfig
      value={{
        fetcher,
        // === キャッシュ制御 ===
        dedupingInterval: 2000,         // 2秒以内の同一リクエストを重複排除
        revalidateOnFocus: true,        // フォーカス時に再検証
        revalidateOnReconnect: true,    // ネットワーク復帰時に再検証
        revalidateIfStale: true,        // マウント時にstaleデータを再検証
 
        // === エラーハンドリング ===
        shouldRetryOnError: true,
        errorRetryCount: 3,
        errorRetryInterval: 5000,
 
        // === ローディング ===
        loadingTimeout: 3000,           // 3秒でslow判定
        focusThrottleInterval: 5000,    // フォーカス再検証のスロットル
 
        // === カスタムキャッシュプロバイダー ===
        provider: () => new Map(),
 
        onError: (error, key) => {
          if (error.status === 403 || error.status === 401) {
            // 認証エラーのグローバルハンドリング
            console.error(`Auth error for ${key}:`, error);
          }
        },
 
        onLoadingSlow: (key) => {
          console.warn(`Slow loading detected for: ${key}`);
        },
      }}
    >
      {children}
    </SWRConfig>
  );
}

// hooks/use-swr-users.ts
import useSWR from 'swr';
import useSWRMutation from 'swr/mutation';
import useSWRInfinite from 'swr/infinite';
 
// 基本的なデータ取得
export function useUser(userId: string | undefined) {
  return useSWR(
    userId ? `/api/users/${userId}` : null, // null でフェッチを無効化
  );
}
 
// 条件付きフェッチ
export function useUserProfile(userId: string | undefined, enabled: boolean) {
  return useSWR(
    enabled && userId ? `/api/users/${userId}/profile` : null,
  );
}
 
// 依存フェッチ（前のデータに依存）
export function useUserProjects(userId: string | undefined) {
  const { data: user } = useUser(userId);
  // user データが取得されるまでフェッチしない
  return useSWR(
    user ? `/api/users/${user.id}/projects` : null,
  );
}
 
// Mutation with SWR
export function useCreateUser() {
  return useSWRMutation(
    '/api/users',
    async (url: string, { arg }: { arg: CreateUserInput }) => {
      const res = await fetch(url, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(arg),
      });
      if (!res.ok) throw new Error('Failed to create user');
      return res.json();
    },
  );
}
 
// 無限スクロール with SWR
export function useInfiniteUsers() {
  const getKey = (pageIndex: number, previousPageData: any) => {
    // 最後のページに到達
    if (previousPageData && !previousPageData.nextCursor) return null;
 
    // 最初のページ
    if (pageIndex === 0) return '/api/users?limit=20';
 
    // 次のページ
    return `/api/users?cursor=${previousPageData.nextCursor}&limit=20`;
  };
 
  return useSWRInfinite(getKey);
}
 
// 楽観的更新 with SWR
export function useToggleLike(postId: string) {
  const { data, mutate } = useSWR(`/api/posts/${postId}`);
 
  const toggleLike = async () => {
    // 楽観的更新
    const optimisticData = {
      ...data,
      isLiked: !data.isLiked,
      likeCount: data.isLiked ? data.likeCount - 1 : data.likeCount + 1,
    };
 
    try {
      await mutate(
        fetch(`/api/posts/${postId}/like`, { method: 'POST' }).then(r => r.json()),
        {
          optimisticData,
          rollbackOnError: true,  // エラー時に自動ロールバック
          populateCache: true,    // レスポンスでキャッシュを更新
          revalidate: false,      // 再検証しない（レスポンスを信頼）
        },
      );
    } catch (error) {
      // ロールバックは自動で行われる
      console.error('Failed to toggle like:', error);
    }
  };
 
  return { data, toggleLike };
}

// パターン1: リスト項目の追加（楽観的）
function useAddTodo() {
  const queryClient = useQueryClient();
 
  return useMutation({
    mutationFn: (newTodo: CreateTodoInput) => api.todos.create(newTodo),
 
    onMutate: async (newTodo) => {
      await queryClient.cancelQueries({ queryKey: ['todos'] });
      const previousTodos = queryClient.getQueryData<Todo[]>(['todos']);
 
      // 仮のIDとタイムスタンプでリストに追加
      const optimisticTodo: Todo = {
        id: `temp-${Date.now()}`,
        ...newTodo,
        completed: false,
        createdAt: new Date().toISOString(),
        _optimistic: true, // UIで「保存中...」表示に使える
      };
 
      queryClient.setQueryData<Todo[]>(['todos'], (old) =>
        old ? [optimisticTodo, ...old] : [optimisticTodo],
      );
 
      return { previousTodos };
    },
 
    onSuccess: (serverTodo) => {
      // サーバーから返った本物のデータで仮データを置換
      queryClient.setQueryData<Todo[]>(['todos'], (old) =>
        old?.map(todo =>
          todo._optimistic ? serverTodo : todo,
        ),
      );
    },
 
    onError: (error, newTodo, context) => {
      queryClient.setQueryData(['todos'], context?.previousTodos);
      toast.error(`Todoの作成に失敗しました: ${error.message}`);
    },
 
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['todos'] });
    },
  });
}
 
// パターン2: お気に入りトグル（楽観的）
function useToggleFavorite() {
  const queryClient = useQueryClient();
 
  return useMutation({
    mutationFn: (productId: string) => api.favorites.toggle(productId),
 
    onMutate: async (productId) => {
      await queryClient.cancelQueries({ queryKey: ['products'] });
      const previous = queryClient.getQueryData(['products']);
 
      queryClient.setQueryData(['products'], (old: Product[]) =>
        old.map(p =>
          p.id === productId
            ? { ...p, isFavorite: !p.isFavorite }
            : p,
        ),
      );
 
      return { previous };
    },
 
    onError: (error, productId, context) => {
      queryClient.setQueryData(['products'], context?.previous);
      toast.error('お気に入りの更新に失敗しました');
    },
 
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['products'] });
    },
  });
}
 
// パターン3: 並び替え（楽観的 — ドラッグ&ドロップ）
function useReorderItems() {
  const queryClient = useQueryClient();
 
  return useMutation({
    mutationFn: (reorder: { id: string; newIndex: number }) =>
      api.items.reorder(reorder),
 
    onMutate: async ({ id, newIndex }) => {
      await queryClient.cancelQueries({ queryKey: ['items'] });
      const previousItems = queryClient.getQueryData<Item[]>(['items']);
 
      queryClient.setQueryData<Item[]>(['items'], (old) => {
        if (!old) return old;
        const items = [...old];
        const currentIndex = items.findIndex(item => item.id === id);
        if (currentIndex === -1) return old;
 
        const [removed] = items.splice(currentIndex, 1);
        items.splice(newIndex, 0, removed);
 
        return items.map((item, index) => ({
          ...item,
          order: index,
        }));
      });
 
      return { previousItems };
    },
 
    onError: (error, variables, context) => {
      queryClient.setQueryData(['items'], context?.previousItems);
      toast.error('並び替えに失敗しました');
    },
 
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['items'] });
    },
  });
}
 
// パターン4: 複数キャッシュにまたがる楽観的更新
function useCompleteOrder() {
  const queryClient = useQueryClient();
 
  return useMutation({
    mutationFn: (orderId: string) => api.orders.complete(orderId),
 
    onMutate: async (orderId) => {
      await Promise.all([
        queryClient.cancelQueries({ queryKey: queryKeys.orders.detail(orderId) }),
        queryClient.cancelQueries({ queryKey: queryKeys.orders.lists() }),
        queryClient.cancelQueries({ queryKey: ['dashboard', 'stats'] }),
      ]);
 
      const previousOrder = queryClient.getQueryData(
        queryKeys.orders.detail(orderId),
      );
      const previousOrders = queryClient.getQueriesData({
        queryKey: queryKeys.orders.lists(),
      });
      const previousStats = queryClient.getQueryData(['dashboard', 'stats']);
 
      queryClient.setQueryData(
        queryKeys.orders.detail(orderId),
        (old: Order | undefined) =>
          old ? { ...old, status: 'completed', completedAt: new Date().toISOString() } : old,
      );
 
      queryClient.setQueriesData(
        { queryKey: queryKeys.orders.lists() },
        (old: { orders: Order[] } | undefined) =>
          old ? {
            ...old,
            orders: old.orders.map(o =>
              o.id === orderId ? { ...o, status: 'completed' } : o,
            ),
          } : old,
      );
 
      queryClient.setQueryData(
        ['dashboard', 'stats'],
        (old: DashboardStats | undefined) =>
          old ? {
            ...old,
            completedOrders: old.completedOrders + 1,
            pendingOrders: old.pendingOrders - 1,
          } : old,
      );
 
      return { previousOrder, previousOrders, previousStats };
    },
 
    onError: (error, orderId, context) => {
      if (context?.previousOrder) {
        queryClient.setQueryData(
          queryKeys.orders.detail(orderId),
          context.previousOrder,
        );
      }
      if (context?.previousOrders) {
        context.previousOrders.forEach(([key, data]) => {
          queryClient.setQueryData(key, data);
        });
      }
      if (context?.previousStats) {
        queryClient.setQueryData(['dashboard', 'stats'], context.previousStats);
      }
    },
 
    onSettled: (data, error, orderId) => {
      queryClient.invalidateQueries({ queryKey: queryKeys.orders.detail(orderId) });
      queryClient.invalidateQueries({ queryKey: queryKeys.orders.lists() });
      queryClient.invalidateQueries({ queryKey: ['dashboard', 'stats'] });
    },
  });
}

// ❌ アンチパターン1: onMutate で cancelQueries を忘れる
// → 進行中の再取得が楽観的データを上書きしてしまう
useMutation({
  mutationFn: updateTodo,
  onMutate: async (newTodo) => {
    // ❌ cancelQueries がない！
    const previous = queryClient.getQueryData(['todos']);
    queryClient.setQueryData(['todos'], /* ... */);
    return { previous };
  },
});
 
// ✅ 正しいパターン
useMutation({
  mutationFn: updateTodo,
  onMutate: async (newTodo) => {
    await queryClient.cancelQueries({ queryKey: ['todos'] }); // ✅
    const previous = queryClient.getQueryData(['todos']);
    queryClient.setQueryData(['todos'], /* ... */);
    return { previous };
  },
});
 
// ❌ アンチパターン2: onSettled で invalidateQueries を忘れる
// → サーバーとの不整合が残る可能性がある
useMutation({
  mutationFn: updateTodo,
  onMutate: async (newTodo) => { /* 楽観的更新 */ },
  onError: (error, vars, context) => { /* ロールバック */ },
  // ❌ onSettled がない！
});
 
// ❌ アンチパターン3: 重要なデータに楽観的更新を使う
// 決済処理、在庫管理など、整合性が絶対に必要な操作には不適切
useMutation({
  mutationFn: processPayment,
  onMutate: async () => {
    // ❌ 決済処理に楽観的更新は危険！
    queryClient.setQueryData(['balance'], (old) => old - amount);
  },
});

// ===========================
// パターン1: 基本的なデータ取得
// ===========================
 
// app/users/page.tsx — Server Component
import { prisma } from '@/lib/prisma';
import { UserList } from './user-list';
 
export default async function UsersPage() {
  // Server Component で直接データベースにアクセス
  const users = await prisma.user.findMany({
    orderBy: { createdAt: 'desc' },
    take: 20,
    select: {
      id: true,
      name: true,
      email: true,
      avatar: true,
      createdAt: true,
    },
  });
 
  return (
    <div className="container mx-auto py-8">
      <h1 className="text-3xl font-bold mb-6">ユーザー一覧</h1>
      <UserList users={users} />
    </div>
  );
}
 
// ===========================
// パターン2: 並列データ取得（ウォーターフォール防止）
// ===========================
 
// app/dashboard/page.tsx
async function DashboardPage() {
  // ❌ ウォーターフォール（逐次実行）
  // const users = await getRecentUsers();    // 200ms
  // const orders = await getRecentOrders();  // 300ms
  // const stats = await getDashboardStats(); // 150ms
  // 合計: 650ms
 
  // ✅ 並列実行
  const [users, orders, stats] = await Promise.all([
    getRecentUsers(),     // 200ms
    getRecentOrders(),    // 300ms
    getDashboardStats(),  // 150ms
  ]);
  // 合計: 300ms（最も遅いリクエストの時間）
 
  return (
    <Dashboard>
      <UserSection users={users} />
      <OrderSection orders={orders} />
      <StatsSection stats={stats} />
    </Dashboard>
  );
}
 
// ===========================
// パターン3: Suspense による段階的レンダリング
// ===========================
 
// app/products/[id]/page.tsx
import { Suspense } from 'react';
 
async function ProductPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const product = await getProduct(id);
 
  return (
    <div>
      {/* 即座に表示（プロダクト情報は既に取得済み） */}
      <ProductHeader product={product} />
 
      {/* レビューは独立して取得・表示 */}
      <Suspense fallback={<ReviewsSkeleton />}>
        <ProductReviews productId={id} />
      </Suspense>
 
      {/* おすすめも独立して取得・表示 */}
      <Suspense fallback={<RecommendationsSkeleton />}>
        <Recommendations productId={id} />
      </Suspense>
    </div>
  );
}
 
// 各セクションは独立した async Server Component
async function ProductReviews({ productId }: { productId: string }) {
  const reviews = await prisma.review.findMany({
    where: { productId },
    orderBy: { createdAt: 'desc' },
    take: 10,
    include: { user: { select: { name: true, avatar: true } } },
  });
 
  return (
    <section>
      <h2>レビュー ({reviews.length})</h2>
      {reviews.map(review => (
        <ReviewCard key={review.id} review={review} />
      ))}
    </section>
  );
}
 
async function Recommendations({ productId }: { productId: string }) {
  const recommendations = await getRecommendations(productId);
 
  return (
    <section>
      <h2>おすすめ商品</h2>
      <div className="grid grid-cols-4 gap-4">
        {recommendations.map(product => (
          <ProductCard key={product.id} product={product} />
        ))}
      </div>
    </section>
  );
}

// Next.js fetch() キャッシュオプション
 
// ===========================
// 静的データ（ビルド時に取得、再検証なし）— SSG相当
// ===========================
async function getStaticContent() {
  const res = await fetch('https://api.example.com/content', {
    cache: 'force-cache', // デフォルト値（Next.js 14以降は 'no-store' がデフォルト）
  });
  return res.json();
}
 
// ===========================
// 動的データ（リクエストごとに取得）— SSR相当
// ===========================
async function getDynamicData() {
  const res = await fetch('https://api.example.com/data', {
    cache: 'no-store', // キャッシュしない
  });
  return res.json();
}
 
// ===========================
// 時間ベースの再検証 — ISR相当
// ===========================
async function getRevalidatedData() {
  const res = await fetch('https://api.example.com/data', {
    next: { revalidate: 3600 }, // 1時間ごとに再検証
  });
  return res.json();
}
 
// ===========================
// タグベースの再検証（オンデマンド）
// ===========================
async function getTaggedData() {
  const res = await fetch('https://api.example.com/products', {
    next: { tags: ['products'] }, // タグを付与
  });
  return res.json();
}
 
// Server Action やAPI Route から再検証をトリガー
import { revalidateTag, revalidatePath } from 'next/cache';
 
export async function updateProduct(formData: FormData) {
  'use server';
  await db.products.update(/* ... */);
 
  // タグベースの再検証
  revalidateTag('products');
 
  // パスベースの再検証
  revalidatePath('/products');
  revalidatePath('/products/[id]', 'page');
}

// キャッシュ戦略の比較表
//
// | 方式 | キャッシュ | 再検証 | ユースケース |
// |------|----------|--------|-------------|
// | force-cache | あり | なし | 静的コンテンツ |
// | no-store | なし | 毎回 | ユーザー固有データ |
// | revalidate: N | あり | N秒後 | ニュース、ブログ |
// | tags + revalidateTag | あり | オンデマンド | EC商品、CMS |
 
// データ取得関数のパターン（推奨）
// lib/data.ts
 
import { cache } from 'react';
 
// React cache() でリクエスト内の重複排除
// 同一リクエスト内で複数回呼んでも1回のDBアクセスに
export const getUser = cache(async (userId: string) => {
  const user = await prisma.user.findUnique({
    where: { id: userId },
  });
  if (!user) throw new Error('User not found');
  return user;
});
 
// unstable_cache でクロスリクエストキャッシュ
import { unstable_cache } from 'next/cache';
 
export const getCachedUser = unstable_cache(
  async (userId: string) => {
    return prisma.user.findUnique({
      where: { id: userId },
    });
  },
  ['user'], // キャッシュキー
  {
    revalidate: 3600, // 1時間
    tags: ['users'],  // 再検証タグ
  },
);

// app/actions/user-actions.ts
'use server';
 
import { revalidatePath } from 'next/cache';
import { redirect } from 'next/navigation';
import { z } from 'zod';
import { prisma } from '@/lib/prisma';
import { auth } from '@/lib/auth';
 
// バリデーションスキーマ
const CreateUserSchema = z.object({
  name: z.string().min(1, '名前は必須です').max(100, '名前は100文字以内です'),
  email: z.string().email('有効なメールアドレスを入力してください'),
  role: z.enum(['admin', 'user', 'moderator']).default('user'),
});
 
const UpdateUserSchema = CreateUserSchema.partial().extend({
  id: z.string().uuid(),
});
 
// 型安全なアクション結果
type ActionResult<T = void> =
  | { success: true; data?: T }
  | { success: false; errors: Record<string, string[]> };
 
// ===========================
// ユーザー作成アクション
// ===========================
export async function createUser(
  prevState: ActionResult | null,
  formData: FormData,
): Promise<ActionResult> {
  // 認証チェック
  const session = await auth();
  if (!session?.user || session.user.role !== 'admin') {
    return {
      success: false,
      errors: { _form: ['権限がありません'] },
    };
  }
 
  // バリデーション
  const parsed = CreateUserSchema.safeParse({
    name: formData.get('name'),
    email: formData.get('email'),
    role: formData.get('role'),
  });
 
  if (!parsed.success) {
    return {
      success: false,
      errors: parsed.error.flatten().fieldErrors,
    };
  }
 
  // 重複チェック
  const existing = await prisma.user.findUnique({
    where: { email: parsed.data.email },
  });
 
  if (existing) {
    return {
      success: false,
      errors: { email: ['このメールアドレスは既に使用されています'] },
    };
  }
 
  // データ作成
  try {
    await prisma.user.create({ data: parsed.data });
  } catch (error) {
    return {
      success: false,
      errors: { _form: ['ユーザーの作成に失敗しました'] },
    };
  }
 
  // キャッシュ無効化
  revalidatePath('/users');
 
  // リダイレクト
  redirect('/users');
}
 
// ===========================
// ユーザー更新アクション
// ===========================
export async function updateUser(
  prevState: ActionResult | null,
  formData: FormData,
): Promise<ActionResult> {
  const parsed = UpdateUserSchema.safeParse({
    id: formData.get('id'),
    name: formData.get('name'),
    email: formData.get('email'),
    role: formData.get('role'),
  });
 
  if (!parsed.success) {
    return {
      success: false,
      errors: parsed.error.flatten().fieldErrors,
    };
  }
 
  const { id, ...data } = parsed.data;
 
  try {
    await prisma.user.update({
      where: { id },
      data,
    });
  } catch (error) {
    return {
      success: false,
      errors: { _form: ['ユーザーの更新に失敗しました'] },
    };
  }
 
  revalidatePath('/users');
  revalidatePath(`/users/${id}`);
 
  return { success: true };
}
 
// ===========================
// ユーザー削除アクション
// ===========================
export async function deleteUser(userId: string): Promise<ActionResult> {
  const session = await auth();
  if (!session?.user || session.user.role !== 'admin') {
    return {
      success: false,
      errors: { _form: ['権限がありません'] },
    };
  }
 
  try {
    await prisma.user.delete({ where: { id: userId } });
  } catch (error) {
    return {
      success: false,
      errors: { _form: ['ユーザーの削除に失敗しました'] },
    };
  }
 
  revalidatePath('/users');
  return { success: true };
}

// app/users/create/page.tsx
'use client';
 
import { useActionState } from 'react';
import { createUser } from '@/app/actions/user-actions';
 
export default function CreateUserPage() {
  const [state, action, isPending] = useActionState(createUser, null);
 
  return (
    <div className="max-w-md mx-auto py-8">
      <h1 className="text-2xl font-bold mb-6">ユーザー作成</h1>
 
      <form action={action} className="space-y-4">
        {/* グローバルエラー */}
        {state?.errors?._form && (
          <div className="bg-red-50 text-red-600 p-3 rounded">
            {state.errors._form.map((error, i) => (
              <p key={i}>{error}</p>
            ))}
          </div>
        )}
 
        {/* 名前フィールド */}
        <div>
          <label htmlFor="name" className="block text-sm font-medium">
            名前
          </label>
          <input
            id="name"
            name="name"
            type="text"
            required
            className="mt-1 block w-full rounded border-gray-300"
            aria-describedby="name-error"
          />
          {state?.errors?.name && (
            <p id="name-error" className="mt-1 text-sm text-red-500">
              {state.errors.name[0]}
            </p>
          )}
        </div>
 
        {/* メールフィールド */}
        <div>
          <label htmlFor="email" className="block text-sm font-medium">
            メールアドレス
          </label>
          <input
            id="email"
            name="email"
            type="email"
            required
            className="mt-1 block w-full rounded border-gray-300"
            aria-describedby="email-error"
          />
          {state?.errors?.email && (
            <p id="email-error" className="mt-1 text-sm text-red-500">
              {state.errors.email[0]}
            </p>
          )}
        </div>
 
        {/* ロール選択 */}
        <div>
          <label htmlFor="role" className="block text-sm font-medium">
            ロール
          </label>
          <select
            id="role"
            name="role"
            className="mt-1 block w-full rounded border-gray-300"
          >
            <option value="user">ユーザー</option>
            <option value="admin">管理者</option>
            <option value="moderator">モデレーター</option>
          </select>
        </div>
 
        {/* 送信ボタン */}
        <button
          type="submit"
          disabled={isPending}
          className="w-full bg-blue-600 text-white py-2 px-4 rounded
                     hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed"
        >
          {isPending ? '作成中...' : 'ユーザーを作成'}
        </button>
      </form>
    </div>
  );
}

// Server Actions と楽観的更新の組み合わせ
'use client';
 
import { useOptimistic, useTransition } from 'react';
import { toggleTodoComplete } from '@/app/actions/todo-actions';
 
interface Todo {
  id: string;
  title: string;
  completed: boolean;
}
 
export function TodoList({ initialTodos }: { initialTodos: Todo[] }) {
  const [isPending, startTransition] = useTransition();
  const [optimisticTodos, setOptimisticTodo] = useOptimistic(
    initialTodos,
    (state: Todo[], updatedTodo: Todo) =>
      state.map(todo =>
        todo.id === updatedTodo.id ? updatedTodo : todo,
      ),
  );
 
  const handleToggle = (todo: Todo) => {
    startTransition(async () => {
      // 楽観的にUIを更新
      setOptimisticTodo({ ...todo, completed: !todo.completed });
      // Server Action を実行
      await toggleTodoComplete(todo.id);
    });
  };
 
  return (
    <ul className="space-y-2">
      {optimisticTodos.map(todo => (
        <li
          key={todo.id}
          className="flex items-center gap-3 p-3 bg-white rounded shadow"
        >
          <input
            type="checkbox"
            checked={todo.completed}
            onChange={() => handleToggle(todo)}
            disabled={isPending}
          />
          <span className={todo.completed ? 'line-through text-gray-400' : ''}>
            {todo.title}
          </span>
        </li>
      ))}
    </ul>
  );
}