DevNogi Front

마비노기 정보 커뮤니티를 위한 Next.js 15 기반 프론트엔드 애플리케이션입니다. MSA(Microservices Architecture)와 BFF(Backend for Frontend) 패턴을 적용하여 효율적인 서비스 간 통신을 구현합니다.

로컬 설치·Docker 실행·표준 검증은 개발 환경 안내를 먼저 확인하세요. 표준 명령은 npm ci 다음 npm run verify입니다. PR은 별도로 검증하며, main push는 검증 후 운영 배포를 실행합니다. 복구 시 main에서 workflow_dispatch로 수동 실행할 수 있습니다.

기술 스택

런타임: Node.js v20 (.nvmrc, Docker, CI 기준)
프레임워크: Next.js v15.3.3 (App Router)
언어: TypeScript v5
UI 라이브러리: React v19
스타일링:
- Tailwind CSS v4
- Shadcn/UI
- Pretendard 폰트 (Primary)
상태 관리 & 데이터 페칭: TanStack Query v5
HTTP 클라이언트: Axios v1.10
폼 관리: React Hook Form + Zod
아이콘: Lucide React
API 모킹: MSW (Mock Service Worker) v2
테스팅:
- Jest v30
- React Testing Library v16
- jest-fixed-jsdom (Next.js 15 호환)
코드 품질:
- ESLint v9 + Prettier v3.5
- Husky v9 + lint-staged v16

프로젝트 구조

devnogi-front/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── (auth)/             # 인증 페이지 그룹
│   │   │   ├── sign-in/          # 로그인 페이지
│   │   │   ├── sign-up/          # 회원가입 페이지
│   │   │   └── social-callback/  # 소셜 로그인 콜백
│   │   ├── (main)/             # 메인 애플리케이션 (NavBar 포함)
│   │   │   ├── auction/          # 경매장 페이지
│   │   │   ├── auction-history/  # 거래 내역 페이지
│   │   │   ├── community/        # 커뮤니티 페이지
│   │   │   │   ├── [id]/           # 상세 페이지
│   │   │   │   └── write/          # 글쓰기 페이지
│   │   │   └── mypage/           # 마이페이지
│   │   ├── api/                # BFF API 라우트
│   │   │   ├── auth/             # 인증 API
│   │   │   ├── posts/            # 게시글 API
│   │   │   ├── comments/         # 댓글 API
│   │   │   ├── boards/           # 게시판 API
│   │   │   ├── auction-history/  # 경매 내역 API
│   │   │   └── item-categories/  # 아이템 카테고리 API
│   │   └── fonts/              # 폰트 파일
│   ├── components/
│   │   ├── page/               # 페이지별 컴포넌트
│   │   │   ├── auction/          # 경매장 관련
│   │   │   ├── auction-history/  # 거래 내역 관련
│   │   │   ├── community/        # 커뮤니티 관련
│   │   │   └── auth/             # 인증 관련
│   │   ├── commons/            # 공용 컴포넌트
│   │   ├── navigation/         # 네비게이션 컴포넌트
│   │   ├── errors/             # 에러 페이지 컴포넌트
│   │   └── ui/                 # Shadcn UI 컴포넌트
│   ├── hooks/                  # 커스텀 React Hooks
│   ├── types/                  # TypeScript 타입 정의
│   ├── contexts/               # React Context
│   ├── lib/
│   │   ├── api/                # API 클라이언트 & 서버 설정
│   │   │   ├── clients.ts        # clientAxios, TanStack Query 설정
│   │   │   ├── server.ts         # createServerAxios, MSW 초기화
│   │   │   └── gateway-selector.ts # 게이트웨이 URL 선택
│   │   └── auth/               # 인증 관련 유틸
│   ├── mocks/                  # MSW 모킹 설정
│   │   ├── data/                 # Mock JSON 데이터
│   │   ├── server.ts             # MSW 핸들러
│   │   └── initServer.ts         # MSW 서버 초기화
│   └── utils/                  # 공통 유틸리티 함수
├── public/                     # 정적 파일
├── Dockerfile                  # Docker 멀티 스테이지 빌드
└── docker-compose-*.yml        # Docker Compose 설정

주요 기능

인증 시스템

소셜 전용 로그인·회원가입: 구글, 카카오, 네이버 OAuth 연동
신규 소셜 회원 안내: 미회원 확인 후 소셜 가입 화면으로 연결
호환 API 유지: 기존 이메일 인증 BFF는 서버 호환을 위해 유지하지만 공개 UI에서는 노출하지 않음
세션 관리: 쿠키 기반 인증 상태 유지

커뮤니티

게시글 목록: 카드 형태 UI, 무한 스크롤
카테고리 필터: 게시판별 분류
정렬 옵션: 최신순, 인기순, 댓글순, 조회순
게시글 상세: 댓글 작성 및 조회
글쓰기: 모달 기반 게시글 작성

경매 내역

무한 스크롤: TanStack Query 기반 페이지네이션
검색 기능: 아이템 이름 검색
필터링: 카테고리, 가격 범위, 날짜 범위, 아이템 옵션
정렬: 거래 최신순, 가격순 등
반응형 UI: 데스크톱 사이드바 / 모바일 모달 필터

마이페이지

사용자 정보 조회 및 프로필 편집

아키텍처

BFF (Backend for Frontend) 패턴

이 프로젝트는 Next.js API Routes를 활용한 BFF 패턴을 구현합니다:

요청 흐름:

Client Component
  ↓ (clientAxios)
Next.js API Route (/api/*)
  ↓ (createServerAxios)
Gateway Server (http://168.107.43.221:8080)
  ↓ (prefix 기반 라우팅)
Backend Services
  ├─ OPEN API BATCH (/oab/*) - 경매장, 거래 내역
  └─ 커뮤니티 서버 (/dcs/api/*) - 게시판, 댓글

Route Groups

(auth)/ - 인증 페이지 (NavBar 없음)
(main)/ - 메인 애플리케이션 (NavBar 포함)

API 레이어

Client-side (src/lib/api/clients.ts):

clientAxios: 클라이언트 컴포넌트에서 사용
Base URL: /api (Next.js API Routes)
Timeout: 5000ms

Server-side (src/lib/api/server.ts):

createServerAxios(): API 라우트 핸들러에서 사용
Base URL: process.env.GATEWAY_URL
Authorization 및 Cookie 헤더 전달
MSW 서버 자동 초기화

TanStack Query 설정:

staleTime: 200ms
윈도우 포커스, 재연결, 마운트 시 자동 refetch 비활성화

커스텀 Hooks

Hook	용도
`useInfiniteAuctionHistory`	경매 내역 무한 스크롤
`useAuctionHistory`	경매 내역 단일 페이지 조회
`useInfinitePosts`	게시글 무한 스크롤
`usePostDetail`	게시글 상세 조회
`useItemCategories`	아이템 카테고리 트리 조회
`useSearchOptions`	검색 옵션 조회
`useItemInfos`	아이템 정보 조회

API 모킹 (MSW)

활성화 조건:

VERCEL_ENV=development|preview AND
API_MOCKING=enabled

구성:

Mock 핸들러: src/mocks/server.ts
Mock 데이터: src/mocks/data/*.json
테스트 환경에서 자동 활성화 (jest.setup.ts)

API 문서

백엔드 서비스

모든 API는 게이트웨이 서버를 통해 라우팅됩니다.

게이트웨이 서버:

http://168.107.43.221:8080/

백엔드 서비스:

서비스	Prefix	Swagger	담당 기능
OPEN API BATCH	`/oab`	Swagger UI	경매장, 거래 내역
커뮤니티 서버	`/dcs/api`	Swagger UI	게시판, 게시글, 댓글
Auth 서버	`/das/api`	-	인증, 회원가입, 소셜 로그인

커뮤니티 API 응답 구조:

{
  success: boolean,
  code: string,
  message: string,
  data: T,
  timestamp: string
}

API 라우트 목록

인증 API (/api/auth/*)

POST   /api/auth/login              # 로그인
POST   /api/auth/signup             # 회원가입
POST   /api/auth/signup/social      # 소셜 회원가입
POST   /api/auth/logout             # 로그아웃
GET    /api/auth/me                 # 현재 사용자 정보
POST   /api/auth/check-email        # 이메일 중복 체크
POST   /api/auth/check-nickname     # 닉네임 중복 체크

커뮤니티 API (/api/posts/*, /api/comments/*)

GET    /api/posts                   # 전체 게시글 조회
GET    /api/posts/[id]              # 게시판별 게시글 조회
GET    /api/posts/details/[id]      # 게시글 상세 조회
GET    /api/comments/[postId]       # 댓글 조회
POST   /api/comments/[postId]       # 댓글 작성
GET    /api/boards                  # 게시판 목록 조회

경매 API (/api/auction-history/*)

GET    /api/auction-history         # 경매 내역 조회
POST   /api/auction-history/search  # 상세 검색
GET    /api/item-categories         # 아이템 카테고리 조회
GET    /api/item-infos              # 아이템 정보 조회
GET    /api/search-option           # 검색 옵션 조회

Slash Commands

프로젝트에서 사용 가능한 커스텀 명령어:

/api-spec - 전체 API 스펙 조회
/api-endpoint - 특정 엔드포인트 상세 조회

개발 환경 설정

원본 저장소에서 프로젝트 포크 원본 저장소 링크
저장소 클론

git clone [your-repository-url]
cd devnogi-front

의존성 설치

npm ci

환경 변수 설정

# .sample_env를 참조하여 .env 파일 생성
cp .sample_env .env

환경 변수 설명:

NODE_ENV - 런타임 환경 (development/production)
VERCEL_ENV - Vercel 환경 (development/preview/production)
API_MOCKING - MSW 활성화 여부 (enabled/disabled)
GATEWAY_URL - 백엔드 게이트웨이 URL

개발 서버 실행

npm run dev

브라우저에서 http://localhost:3000을 열어 애플리케이션을 확인할 수 있습니다.

Path Aliases

프로젝트는 @/ alias를 사용하여 절대 경로로 import합니다:

import { Button } from "@/components/ui/button";
import { clientAxios } from "@/lib/api/clients";
import { formatDate } from "@/utils/date";

TypeScript 및 Jest 설정에서 모두 지원됩니다.

개발 프로세스

GitHub Flow 브랜치 전략

이 프로젝트는 실제 배포 전까지는 단순하고 지속적인 배포를 지향하는 GitHub Flow를 따릅니다:

main: 항상 배포 가능한 상태를 유지하는 기본 브랜치

브랜치 작업 플로우

작업 전 원본 저장소와 싱크 확인
새로운 작업 시작

git switch main
git pull origin main
git switch -c 브랜치명
# 개발 작업 수행
git add .
git commit -m "작업 설명"
git push origin 브랜치명
# PR 생성: 브랜치명 -> main

PR(Pull Request) 프로세스
- PR 생성 시 작업 내용 상세히 설명
- 코드 리뷰 진행
- 승인 후 main 브랜치에 머지
머지 완료 후 포크 저장소 최신화

커밋 메시지 컨벤션

<type>: <subject>

<body> (선택사항)

<footer> (선택사항)

Type:

feat: 새로운 기능 추가
fix: 버그 수정
docs: 문서 수정
style: 코드 포맷팅 (기능 변경 없음)
refactor: 코드 리팩토링 (기능 변경 없음)
test: 테스트 코드 추가/수정
chore: 빌드 프로세스, 도구 변경
perf: 성능 개선
design: UI/UX 디자인 변경
security: 보안 관련 변경

Subject 규칙:

최대 50자
소문자로 시작
마침표 없음
명령형 현재 시제 (add, fix, update, remove)

예시:

feat: add user login functionality
fix: improve error handling on login
docs: update README with API documentation

Footer (선택사항):

Closes: #123
Fixes: #456
BREAKING CHANGE: API response format changed

품질 관리

Pre-commit Hooks (Husky + lint-staged)

커밋 시 Staged 파일에 대해 자동으로 다음 작업이 수행됩니다:

npm ci가 Husky hook을 설치합니다. 커밋 전에 staged 변경의 whitespace와 conflict marker를 검사하고, staged 코드에 Prettier와 ESLint 자동 수정 및 import 정렬을 적용합니다. 다른 unstaged 변경은 stage하지 않습니다. push 전에는 npm run verify로 lint, 타입, 미사용 코드, 테스트와 빌드를 검사합니다. hook을 우회하더라도 PR CI에서 같은 검사가 실행됩니다.

ESLint

Next.js 권장 설정 사용 (eslint.config.mjs)
빌드 시 ESLint 에러가 있어도 빌드 성공 (next.config.ts)

테스팅

Jest 환경: jest-fixed-jsdom (Next.js 15 호환)
테스트 파일: *.test.tsx (소스 파일과 동일 위치)
MSW: 모든 테스트에서 자동으로 사용 가능

실행 명령어:

npm test                    # 전체 테스트
npm test -- --watch        # Watch 모드
npm test -- <file-path>    # 특정 파일 테스트

개발 명령어

# 개발 서버 실행
npm run dev

# 프로덕션 빌드
npm run build

# 프로덕션 서버 실행
npm start

# 린트 검사
npm run lint

# 테스트 실행
npm test

Docker 배포

로컬 개발

# 개발 환경 실행
docker-compose -f docker-compose-dev.yml up

# 로컬 환경 실행
docker-compose -f docker-compose-local.yml up

프로덕션 배포

# 프로덕션 빌드 및 실행
docker-compose -f docker-compose-prod.yaml up -d

Docker 설정:

멀티 스테이지 빌드 (node:20-alpine)
Next.js standalone 출력 모드
기본 포트: 3010
보안 사용자(nextjs)로 실행

디자인 시스템

공통 액션색, 커뮤니티 구성, 화면별 반응형·접근성 기준은 DESIGN.md를 따릅니다. 기본 액션은 라이트 테마의 검정/흰색, 다크 테마의 흰색/검정 조합이며, 의미가 있는 상태색과 소셜 로그인 브랜드색은 유지합니다.

개발 원칙

TypeScript 원칙

타입 안정성 우선: 모든 변수, 함수, 컴포넌트에 명시적 타입 정의
any 지양: 대신 unknown 사용
제네릭 활용: 재사용 가능한 타입 정의
타입 추론 활용: 불필요한 타입 어노테이션 지양

React 원칙

단일 책임: 각 컴포넌트는 하나의 명확한 책임
컴포넌트 크기: 200줄 이하 유지
불변성: 상태 업데이트 시 항상 새 객체/배열 생성
순수 함수 컴포넌트: 부수효과 없는 순수 함수로 작성
Hook 규칙: 최상위 레벨에서만 호출, 조건문/반복문 내 사용 금지

Next.js 원칙

Server Components 우선: 기본적으로 서버 컴포넌트 사용
'use client': 필요한 경우에만 사용
메타데이터 관리: 각 페이지에 적절한 메타데이터 설정
동적 메타데이터: generateMetadata 함수 활용

상태 관리

로컬 상태 우선: Props drilling이 3단계 이하일 때 컴포넌트 상태 사용
전역 상태: Props drilling이 3단계 초과 시에만 고려
상태 정규화: 중첩된 객체 대신 평탄한 구조 사용
ID 기반 관계: 중복 데이터 제거

성능 최적화

코드 스플리팅: 라우트 기반 자동 스플리팅 활용
동적 import: 큰 컴포넌트는 동적 import로 분할
메모이제이션: useMemo, useCallback 적절히 활용
Image 최적화: Next.js Image 컴포넌트 사용

접근성

시맨틱 HTML: 적절한 HTML 태그 사용
ARIA 속성: 필요시 ARIA 속성 활용
키보드 내비게이션: 키보드로 모든 기능 접근 가능
색상 대비: WCAG 2.1 AA 기준 준수

보안

입력 검증: 모든 사용자 입력 검증
XSS 방지: 적절한 이스케이핑 및 새니타이징
환경 변수: 민감 정보는 환경 변수로 관리
클라이언트 노출 금지: 서버 전용 정보 클라이언트에 노출 금지

라이선스

이 프로젝트는 오픈 소스이며, 학습 및 포트폴리오 목적으로 자유롭게 사용할 수 있습니다.

폰트 라이선스:

Pretendard: SIL Open Font License 1.1 (상업적 사용 가능)

Name		Name	Last commit message	Last commit date
.claude		.claude
.codex/skills		.codex/skills
.github/workflows		.github/workflows
.husky		.husky
.idea		.idea
.taste-skill		.taste-skill
dev_rules		dev_rules
docs		docs
public		public
qa-evidence		qa-evidence
reference		reference
scripts		scripts
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.nvmrc		.nvmrc
.sample_env		.sample_env
.sample_env.prod		.sample_env.prod
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
DESIGN.md		DESIGN.md
Dockerfile		Dockerfile
README.md		README.md
components.json		components.json
design-qa.md		design-qa.md
docker-compose-dev.yml		docker-compose-dev.yml
docker-compose-local.yml		docker-compose-local.yml
docker-compose-prod.yml		docker-compose-prod.yml
eslint.config.mjs		eslint.config.mjs
jest.config.ts		jest.config.ts
jest.setup.ts		jest.setup.ts
knip.json		knip.json
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
popover-sample.png		popover-sample.png
postcss.config.mjs		postcss.config.mjs
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation