bitforum-frontend/CLAUDE.md

CLAUDE.md

Project Overview

bitForum - Next.js 15 App Router 기반 커뮤니티 프론트엔드 (https://bitforum.io)

• Framework: Next.js 15.3+ (App Router, Server Components)
• React: 19.1+
• Language: TypeScript 5
• Backend API: https://localhost:4000 (ASP.NET Core Minimal API)

Project Structure

app/                → Next.js App Router (페이지, 레이아웃, API 라우트)
  ├── (account)/    → 계정 관리 (프로필, 비밀번호 변경 등)
  ├── (auth)/       → 인증 (로그인, 회원가입, 비밀번호 찾기)
  ├── (forum)/      → 게시판 (게시글, 댓글, 글쓰기)
  ├── api/          → Route Handler (백엔드 API 프록시)
  ├── component/    → 공통 레이아웃 컴포넌트 (Layout, PopupModal 등)
  ├── support/      → 고객지원 (FAQ, 공지, 이용안내, 제휴문의)
  ├── news/         → 뉴스
  └── docs/         → 문서 페이지
components/ui/      → shadcn/ui 컴포넌트 (dialog, accordion 등)
contexts/           → React Context Provider (Auth, Member, Config, SignalR)
hooks/              → 커스텀 훅 (useAuth, useDragScroll 등)
lib/
  ├── api/          → 서버 사이드 API 호출 함수 (Server Actions)
  └── utils/
      ├── client.ts → 클라이언트 유틸 (fetchApi, cn, formatDate, throwError)
      └── server.ts → 서버 유틸 (fetchJson, getAccessToken, checkPermission)
types/              → TypeScript 타입 정의 (response/, request/, forum/, account/)
constants/          → 상수 정의
middleware.ts       → 인증 미들웨어 (토큰 검증, 리다이렉트)

Code Style Rules

• 인덴트: 탭 사용
• PK/ID 변수명: memberID, postID (camelCase + 대문자 ID)
• 클라이언트 컴포넌트: 파일 최상단에 'use client' 선언
• 서버 전용 함수: 'use server' 선언 (Server Actions, lib/utils/server.ts)
• 컴포넌트 파일명: PascalCase (PopupModal.tsx, Layout.tsx)
• 페이지/라우트: 소문자 kebab-case 디렉토리 (support/faq/)
• 스타일: 각 페이지 디렉토리에 style.scss 파일
• 파일 내용의 마지막 줄 제거 (빈 줄 없이 끝남)

Architecture Rules

• 서버 컴포넌트가 기본 — 'use client' 없으면 RSC
• 클라이언트 상태: React Context (AuthProvider, MemberProvider, ConfigProvider)
• API 프록시 패턴: 클라이언트 → app/api/[도메인]/[...path]/route.ts → 백엔드
  • 클라이언트에서 직접 백엔드 호출 안 함 (CORS, 쿠키 처리)
• 서버 데이터 흐름: Server Component → fetchJson() → 백엔드 직접 호출
• 인증: JWT Bearer 토큰 (accessToken/refreshToken, httpOnly 쿠키)
• 실시간: SignalR WebSocket (암호화폐 시세, 채팅)

Code Conventions

사용하는 패턴

• fetchApi<T>() — 클라이언트에서 Route Handler 호출 (lib/utils/client.ts)
• fetchJson<T>() — 서버에서 백엔드 직접 호출 (lib/utils/server.ts)
• ResultDto<T> — 모든 API 응답 래퍼 ({ success, status, message, data, errors })
• throwError(res) — 에러 응답 시 예외 발생
• cn() — Tailwind 클래스 병합 (clsx + tailwind-merge)
• dangerouslySetInnerHTML — 서버에서 받은 HTML 콘텐츠 렌더링
• Route Group — (auth), (account), (forum) 으로 관련 페이지 그룹화
• notFound() — 데이터 없을 때 404 처리

사용하지 않는 패턴 (제안 금지)

• Redux, Zustand (Context + 로컬 상태 사용)
• GraphQL (REST API만 사용)
• 클라이언트에서 백엔드 직접 호출 (반드시 Route Handler 프록시 경유)
• CSS-in-JS (Tailwind + SCSS 사용)
• React Query / SWR (직접 fetch 사용)

Styling

• Tailwind CSS — 기본 스타일링
• SCSS — 컴포넌트별 style.scss, 글로벌 globals.scss
• CSS Modules — common.module.scss (레이아웃 그리드)
• shadcn/ui — new-york 스타일, Radix UI 기반 (components/ui/)
• CSS Variables — HSL 형식 테마 변수 (--background, --foreground 등)
• Font Awesome — 아이콘 (@fortawesome 패키지)
• Lucide React — shadcn/ui 아이콘

Provider 구조 (Root Layout)

SignalRProvider → AuthProvider → MemberProvider → ConfigProvider → {children}

• ConfigProvider: initialConfig prop으로 서버에서 설정 전달 (React.cache)
• AuthProvider: 로그인 상태 관리, 토큰 갱신
• MemberProvider: 현재 사용자 정보
• SignalRProvider: WebSocket 연결 (암호화폐, 채팅)

API Route Handler 패턴

// app/api/{도메인}/[...path]/route.ts
export async function POST(request: NextRequest, { params }: { params: Promise<{ path: string[] }> }) {
    const { path } = await params;
    const endpoint = `/api/${path.join('/')}`;
    const res: ResultDto = await fetchJson(endpoint, {
        method: 'POST',
        body: await request.arrayBuffer(),
        headers: { 'Content-Type': request.headers.get('content-type') || '' }
    });
    return NextResponse.json(res);
}

Build & Run

# 개발 서버 (HTTPS, 포트 3000)
npm run dev

# 프로덕션 빌드
npm run build

# 프로덕션 실행
npm run start

# 린트
npm run lint

사용 Domain

• https://bitforum.io → 사용자 프론트엔드
• https://api.bitforum.io → 백엔드 API
• https://admin.bitforum.io → 관리자 패널