Next.js에서 FSD를 실용적으로 적용하기: ViewModel Hook, Repository DI, Storybook 테스트 전략

📂 project-root
├── 📂 app                     # Next.js 라우팅 진입점 (얇은 껍데기)
│   └── 📂 cart
│       └── page.tsx           # views/cart 를 re-export 하는 서버 컴포넌트
│
└── 📂 src
    ├── 📂 shared
    │   └── 📂 lib
    │       └── 📂 http
    │           ├── api-client.ts             # Axios 인스턴스 (인터셉터, 헤더)
    │           └── refresh-access-token.ts   # 토큰 갱신 (도메인 없는 HTTP 인프라)
    │
    ├── 📂 entities
    │   └── 📂 product
    │       └── 📂 model
    │           └── types.ts             # ProductEntity 데이터 명세
    │
    ├── 📂 features
    │   └── 📂 cart
    │       ├── 📂 repositories
    │       │   ├── inventory-repository.ts            # env 기반 real/mock 선택
    │       │   ├── inventory-repository.interface.ts  # 레포지토리 인터페이스
    │       │   ├── inventory-repository.mock.ts
    │       │   ├── inventory-repository.real.ts
    │       │   └── inventory-repository.context.tsx   # 기본값 내장 Context
    │       ├── 📂 lib
    │       │   └── 📂 constants
    │       │       └── cart.ts                   # CART_MAX_QUANTITY = 10
    │       ├── 📂 model
    │       │   ├── errors.ts                     # 도메인 에러 (OutOfStockError)
    │       │   └── store.ts                      # Zustand (동기 규칙 전담)
    │       ├── 📂 ui
    │       │   └── 📂 cart-view
    │       │       ├── cart-view.container.tsx   # 뷰모델 호출 + 바인딩
    │       │       ├── cart-view.stories.tsx
    │       │       ├── cart-view.view-model.ts
    │       │       └── cart-view.tsx             # props만 받는 순수 View
    │       ├── index.ts                          # Public API
    │       └── testing.ts                        # 테스트 전용 Public API
    │
    └── 📂 views                                  # FSD pages의 리네이밍
        └── 📂 cart
            ├── cart-page.stories.tsx
            ├── cart-page.ui.tsx
            └── index.ts

// app/cart/page.tsx — 라우팅 껍데기는 이게 전부입니다.
import { CartPage } from "@/views/cart";

export default CartPage;

// src/entities/product/model/types.ts
export interface ProductEntity {
  id: string;
  name: string;
  price: number;
  imageUrl: string;
}

// src/features/cart/model/errors.ts
// 뷰모델이 instanceof로 분기할 수 있는 도메인 에러.
// 전송 계층(HTTP)의 사정은 이 타입들 뒤로 숨습니다.
export class OutOfStockError extends Error {
  readonly code = "OUT_OF_STOCK" as const;

  constructor() {
    super("상품 재고가 부족합니다.");
    this.name = "OutOfStockError";
  }
}

// 재고 조회 요청 과정에서 발생한 전송 실패(네트워크 단절·타임아웃·HTTP 오류)를
// 정규화한 타입. 원인은 cause로 보존합니다.
export class StockCheckFailedError extends Error {
  readonly code = "STOCK_CHECK_FAILED" as const;

  constructor(options?: ErrorOptions) {
    super("재고를 확인하지 못했습니다.", options);
    this.name = "StockCheckFailedError";
  }
}

// src/features/cart/repositories/inventory-repository.interface.ts
export interface IInventoryRepository {
  // 검증 전용 메서드이므로 반환값이 없습니다.
  // 재고 없음 → OutOfStockError, 재고 조회 요청 실패 → StockCheckFailedError.
  assertAvailable: (productId: string) => Promise<void>;
}

// src/features/cart/repositories/inventory-repository.real.ts
import { apiClient } from "@/shared/lib/http";
import { OutOfStockError, StockCheckFailedError } from "../model/errors";
import { IInventoryRepository } from "./inventory-repository.interface";

// 서버 응답 DTO — 이 형태는 repository 바깥으로 새어나가지 않습니다.
interface StockResponseDto {
  stock: number;
}

export const realInventoryRepository: IInventoryRepository = {
  assertAvailable: async (productId) => {
    let response: { data: StockResponseDto };

    // catch 범위를 HTTP 호출로 제한해 프로그래밍 오류까지 감싸지 않습니다.
    try {
      response = await apiClient.get<StockResponseDto>(
        `/products/${productId}/stock`,
      );
    } catch (error) {
      // 전송 실패(네트워크 단절·타임아웃·HTTP 오류)의 정규화
      throw new StockCheckFailedError({ cause: error });
    }

    // DTO 해석: 재고 부족은 전송 실패가 아닌 기능 도메인 실패입니다.
    if (response.data.stock <= 0) {
      throw new OutOfStockError();
    }
  },
};

// src/features/cart/repositories/inventory-repository.ts
import { mockInventoryRepository } from "./inventory-repository.mock";
import { realInventoryRepository } from "./inventory-repository.real";

// process가 없는 브라우저 번들(Vite Storybook 등) 대비 가드
const useMock =
  typeof process !== "undefined" &&
  process.env.NEXT_PUBLIC_USE_MOCK === "true";

export const inventoryRepository = useMock
  ? mockInventoryRepository
  : realInventoryRepository;

// src/features/cart/repositories/inventory-repository.context.tsx
"use client";

import { createContext, useContext } from "react";
import { IInventoryRepository } from "./inventory-repository.interface";
import { inventoryRepository } from "./inventory-repository"; // barrel이 아닌 구체 경로

const InventoryRepositoryContext = createContext<IInventoryRepository>(inventoryRepository);

export const InventoryRepositoryProvider = InventoryRepositoryContext.Provider;
export const useInventoryRepository = () => useContext(InventoryRepositoryContext);

features/cart/
├── index.ts          # client-safe exports
├── index.server.ts   # server-only exports
└── testing.ts        # 테스트 전용 exports

// src/features/cart/testing.ts — 테스트/스토리북 전용 Public API
export { InventoryRepositoryProvider } from "./repositories/inventory-repository.context";
export { resetCartStore } from "./model/store";
export { OutOfStockError, StockCheckFailedError } from "./model/errors";
export type { IInventoryRepository } from "./repositories/inventory-repository.interface";

// src/features/cart/lib/constants/cart.ts
export const CART_MAX_QUANTITY = 10;

// src/features/cart/model/store.ts
import { create } from "zustand";
import { ProductEntity } from "@/entities/product";
import { CART_MAX_QUANTITY } from "../lib/constants/cart";

export interface CartItemModel extends ProductEntity {
  quantity: number; // 상품 Entity에 장바구니 도메인 상태(수량)를 결합
}

type AddItemResult =
  | { success: true }
  | { success: false; reason: "MAX_LIMIT_EXCEEDED" };

interface CartState {
  items: CartItemModel[];
  addItemSync: (product: ProductEntity) => AddItemResult;
}

const addOrIncreaseItem = (
  items: CartItemModel[],
  product: ProductEntity,
): CartItemModel[] => {
  const exists = items.some((item) => item.id === product.id);

  return exists
    ? items.map((item) =>
        item.id === product.id
          ? { ...item, quantity: item.quantity + 1 }
          : item,
      )
    : [...items, { ...product, quantity: 1 }];
};

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

  addItemSync: (product) => {
    // get()으로 규칙을 먼저 검증하고, 통과한 경우에만 set()을 수행합니다.
    const existingItem = get().items.find((item) => item.id === product.id);

    if (existingItem && existingItem.quantity >= CART_MAX_QUANTITY) {
      return { success: false, reason: "MAX_LIMIT_EXCEEDED" };
    }

    set((state) => ({ items: addOrIncreaseItem(state.items, product) }));

    return { success: true };
  },
}));

// 테스트/스토리북용 리셋 유틸 (testing.ts를 통해 노출)
export const resetCartStore = () =>
  useCartStore.setState(useCartStore.getInitialState(), true);

// src/features/cart/ui/cart-view/cart-view.view-model.ts
import { useMutation } from "@tanstack/react-query";
import { ProductEntity } from "@/entities/product";
import { useToast } from "@/shared/lib/toast";
import { useBottomSheet } from "@/shared/lib/bottom-sheet";
import { CART_MAX_QUANTITY } from "../../lib/constants/cart";

import { useInventoryRepository } from "../../repositories/inventory-repository.context";
import { OutOfStockError, StockCheckFailedError } from "../../model/errors";
import { useCartStore } from "../../model/store";

export const useCartViewModel = () => {
  // 정적 import 대신 Context에서 획득: 뷰모델은 인터페이스만 압니다.
  const inventoryRepository = useInventoryRepository();

  // 셀렉터 구독: 필요한 조각 외의 상태 변경에는 반응하지 않습니다.
  const items = useCartStore((state) => state.items);
  const addItemSync = useCartStore((state) => state.addItemSync);

  const { openToast } = useToast();
  const { openBottomSheet } = useBottomSheet();

  const { mutate: addToCart, isPending } = useMutation({
    // 1단계: 서버 재고 확인 — 실패는 repository가 도메인 에러로 던집니다
    mutationFn: async (product: ProductEntity) => {
      await inventoryRepository.assertAvailable(product.id);
      return product;
    },

    // 2단계: 통과 시 Zustand 동기 업데이트
    onSuccess: (product) => {
      const result = addItemSync(product);

      // 3단계: 동기 리턴값으로 즉시 UI 피드백 분기 (useEffect 감시 없음)
      if (!result.success && result.reason === "MAX_LIMIT_EXCEEDED") {
        openToast({
          type: "error",
          message: `최대 ${CART_MAX_QUANTITY}개까지만 담을 수 있습니다.`,
        });
        return;
      }

      openToast({ type: "success", message: "장바구니에 담겼습니다." });
    },

    onError: (error: Error) => {
      // 문자열이나 Axios 타입이 아닌, 기능에서 정의한 도메인 에러로 분기합니다.
      if (error instanceof OutOfStockError) {
        openBottomSheet({
          title: "품절 안내",
          content: "현재 상품의 서버 재고가 부족합니다.",
        });
        return;
      }

      if (error instanceof StockCheckFailedError) {
        openToast({
          type: "error",
          message: "재고를 확인하지 못했습니다. 잠시 후 다시 시도해 주세요.",
        });
        return;
      }

      // 예상하지 못한 오류는 재고 조회 실패로 위장하지 않습니다.
      // 프로젝트 정책에 따라 Sentry 등으로 보고합니다.
      console.error(error);
      openToast({ type: "error", message: "예상하지 못한 오류가 발생했습니다." });
    },
  });

  // 메모이제이션은 View에 전달되는 최종 경계인 Container에서만 합니다.
  return {
    cartItems: items,
    isSubmitting: isPending,
    onAddItemClick: addToCart,
  };
};

// src/features/cart/ui/cart-view/cart-view.tsx
import { memo } from "react";
import { CartItemModel } from "../../model/store";

interface CartViewProps {
  cartItems: CartItemModel[];
  isSubmitting: boolean;
  onAddItemClick: () => void;
}

// 훅 호출이 하나도 없는 순수 프리젠테이션 컴포넌트
export const CartView = memo(
  ({ cartItems, isSubmitting, onAddItemClick }: CartViewProps) => {
    return (
      <div className="cart-view-container">
        <h2>장바구니 목록 ({cartItems.length}개)</h2>

        <button onClick={onAddItemClick} disabled={isSubmitting}>
          {isSubmitting ? "서버 재고 판별 중..." : "장바구니 담기"}
        </button>
      </div>
    );
  },
);

// src/features/cart/ui/cart-view/cart-view.container.tsx
"use client";

import { useCallback } from "react";
import { ProductEntity } from "@/entities/product";
import { useCartViewModel } from "./cart-view.view-model";
import { CartView } from "./cart-view";

interface CartViewContainerProps {
  product: ProductEntity;
}

export const CartViewContainer = ({ product }: CartViewContainerProps) => {
  const vm = useCartViewModel();

  // View에 전달되는 콜백 참조를 Container에서 안정화합니다.
  const handleAddItemClick = useCallback(() => {
    vm.onAddItemClick(product);
  }, [vm.onAddItemClick, product]);

  return (
    <CartView
      cartItems={vm.cartItems}
      isSubmitting={vm.isSubmitting}
      onAddItemClick={handleAddItemClick}
    />
  );
};

// src/features/cart/ui/cart-view/cart-view.stories.tsx (외부 의존성 모킹 제로)
import type { Meta, StoryObj } from "@storybook/nextjs-vite";
import { fn } from "storybook/test";
import { CartView } from "./cart-view";

const meta: Meta<typeof CartView> = {
  component: CartView,
  title: "Features/Cart/CartView",
  args: {
    cartItems: [],
    isSubmitting: false,
    onAddItemClick: fn(),
  },
};

export default meta;

type Story = StoryObj<typeof CartView>;

export const Empty: Story = {};

export const Submitting: Story = {
  args: { isSubmitting: true },
};

// .storybook/preview.tsx
// 이 글의 스토리북 예시는 Storybook 9 + Vite 기반 @storybook/nextjs-vite 기준입니다.
// Webpack 커스텀이 필요한 프로젝트라면 import를 @storybook/nextjs로 교체하세요.
import { useState, type PropsWithChildren } from "react";
import type { Preview } from "@storybook/nextjs-vite";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { ToastProvider } from "@/shared/lib/toast";
import { BottomSheetProvider } from "@/shared/lib/bottom-sheet";

const StoryQueryProvider = ({ children }: PropsWithChildren) => {
  // 스토리 렌더 생명주기 동안 하나의 QueryClient를 유지합니다.
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: {
          queries: { retry: false },
          mutations: { retry: false },
        },
      }),
  );

  return (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  );
};

const preview: Preview = {
  decorators: [
    // 스토리가 교체되면 key로 Provider를 새로 마운트해 캐시를 격리합니다.
    // 뷰모델이 실제로 호출하는 토스트·바텀시트의 공통 UI Provider도 함께 등록합니다.
    (Story, context) => (
      <StoryQueryProvider key={context.id}>
        <ToastProvider>
          <BottomSheetProvider>
            <Story />
          </BottomSheetProvider>
        </ToastProvider>
      </StoryQueryProvider>
    ),
  ],
};

export default preview;

// src/views/cart/cart-page.stories.tsx
// Storybook 9 + @storybook/nextjs-vite 기준. Webpack 기반이면 @storybook/nextjs.
import type { Decorator, Meta, StoryObj } from "@storybook/nextjs-vite";
import { expect, screen } from "storybook/test";
// 테스트 전용 요소는 테스트 전용 Public API(testing.ts)로 가져옵니다.
import {
  InventoryRepositoryProvider,
  OutOfStockError,
  resetCartStore,
  type IInventoryRepository,
} from "@/features/cart/testing";
import { CartPageUI } from "./cart-page.ui";

// mock은 렌더마다 새 참조가 생기지 않도록 컴포넌트 밖 상수로 선언합니다.
const outOfStockRepository: IInventoryRepository = {
  assertAvailable: async () => {
    throw new OutOfStockError();
  },
};

// pending 검증용 deferred mock 팩토리
const createDeferredStockRepository = () => {
  let resolve!: () => void;

  const repository: IInventoryRepository = {
    assertAvailable: () =>
      new Promise((nextResolve) => {
        resolve = nextResolve;
      }),
  };

  return {
    repository,
    resolveStock: () => resolve(),
  };
};

type DeferredStockRepository = ReturnType<typeof createDeferredStockRepository>;

let successDeferred: DeferredStockRepository;

const withRepository =
  (repository: IInventoryRepository): Decorator =>
  (Story) => (
    <InventoryRepositoryProvider value={repository}>
      <Story />
    </InventoryRepositoryProvider>
  );

const meta = {
  component: CartPageUI,
  title: "Views/CartPage",
  parameters: {
    nextjs: { appDirectory: true },
  },

  // 스토어와 deferred(resolver 공유 방지)를 각 스토리 실행 전에 초기화합니다.
  async beforeEach() {
    resetCartStore();
    successDeferred = createDeferredStockRepository();
  },
} satisfies Meta<typeof CartPageUI>;

export default meta;

type Story = StoryObj<typeof meta>;

// 시나리오 1: pending → 담기 성공 (resolve 시점을 테스트가 제어)
export const AddToCartSuccessFlow: Story = {
  // beforeEach에서 만든 deferred를 렌더 시점에 읽습니다.
  decorators: [
    (Story) => (
      <InventoryRepositoryProvider value={successDeferred.repository}>
        <Story />
      </InventoryRepositoryProvider>
    ),
  ],
  play: async ({ canvas, userEvent }) => {
    await userEvent.click(canvas.getByRole("button", { name: "장바구니 담기" }));

    // resolve 전이므로 pending이 확정적으로 관찰됩니다 (findByText로 상태 반영 대기)
    await expect(
      await canvas.findByText("서버 재고 판별 중..."),
    ).toBeInTheDocument();

    // 테스트가 원하는 시점에 검증 통과를 흘려보냅니다
    successDeferred.resolveStock();

    await expect(
      await screen.findByText("장바구니에 담겼습니다."),
    ).toBeInTheDocument();
  },
};

// 시나리오 2: 품절 → 바텀시트 노출
export const OutOfStockFlow: Story = {
  decorators: [withRepository(outOfStockRepository)],
  play: async ({ canvas, userEvent }) => {
    await userEvent.click(canvas.getByRole("button", { name: "장바구니 담기" }));

    await expect(await screen.findByText("품절 안내")).toBeInTheDocument();
  },
};

{
  "$schema": "https://biomejs.dev/schemas/2.2.0/schema.json",
  "linter": {
    "enabled": true,
    "domains": {
      "project": "all"
    },
    "rules": {
      "recommended": true,
      "style": {
        "useFilenamingConvention": {
          "level": "error",
          "options": {
            "strictCase": true,
            "requireAscii": true,
            "filenameCases": ["kebab-case"]
          }
        },
        "noRestrictedImports": {
          "level": "error",
          "options": {
            "patterns": [
              {
                "group": [
                  "@/features/*/**",
                  "@/entities/*/**",
                  "@/views/*/**",
                  "!@/features/*/testing",
                  "!@/features/*/index.server"
                ],
                "message": "FSD 위반: 슬라이스 내부 파일에 직접 접근하지 마세요. Public API(index.ts / index.server.ts / testing.ts) 경로만 사용해야 합니다."
              }
            ]
          }
        }
      },
      "suspicious": {
        "noImportCycles": "error"
      }
    }
  }
}