commit d96fc9578239a4842bbabe057cc8b5e2cf301613 Author: NYD Date: Fri Jan 30 09:01:27 2026 +0900 first commit diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..85b58c2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,68 @@ +# Dependencies +node_modules/ +.pnp +.pnp.js + +# Testing +coverage/ +.nyc_output/ + +# Production +dist/ +dist-ssr/ +*.local + +# Environment variables +.env +.env.local +.env.*.local +.env.development.local +.env.test.local +.env.production.local + +# Editor directories and files +.vscode/* +!.vscode/extensions.json +.idea +.DS_Store +*.suo +*.ntvs* +*.njsproj +*.sln +*.sw? + +# Logs +logs/ +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* +lerna-debug.log* + +# OS files +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +ehthumbs.db +Thumbs.db +desktop.ini + +# Temporary files +*.tmp +*.temp +*.swp +*.swo +*~ +.cache/ + +# Build files +*.tsbuildinfo + +# 아키텍처 문서 디렉터리 (참고용, 커밋 제외) +base_arcitectures_md/ + +# Vite +.vite/ diff --git a/ENV_SETUP.md b/ENV_SETUP.md new file mode 100644 index 0000000..369cd88 --- /dev/null +++ b/ENV_SETUP.md @@ -0,0 +1,37 @@ +# 환경 변수 파일 설정 + +다음 파일들을 프로젝트 루트에 생성해주세요: + +## .env.development +``` +# 개발 환경 변수 +VITE_API_BASE_URL=http://localhost:8080 +VITE_API_PREFIX=/api +VITE_HTTP_TIMEOUT_MS=20000 +VITE_HTTP_LOGGING=true + +# TanStack Query 사용 여부 (옵션) +# true: TanStack Query 활성화 (서버 상태 관리) +# false 또는 미설정: TanStack Query 비활성화 (직접 fetch 사용) +VITE_USE_REACT_QUERY=false +``` + +## .env.production +``` +# 운영 환경 변수 +VITE_API_BASE_URL=https://api.example.com +VITE_API_PREFIX=/api +VITE_HTTP_TIMEOUT_MS=20000 +VITE_HTTP_LOGGING=false + +# TanStack Query 사용 여부 (옵션) +VITE_USE_REACT_QUERY=false +``` + +## 환경 변수 설명 + +- `VITE_API_BASE_URL`: API 서버 기본 URL +- `VITE_API_PREFIX`: API 경로 prefix (기본값: /api) +- `VITE_HTTP_TIMEOUT_MS`: HTTP 요청 타임아웃 (밀리초, 기본값: 20000) +- `VITE_HTTP_LOGGING`: HTTP 로깅 활성화 여부 (개발: true, 운영: false) +- `VITE_USE_REACT_QUERY`: TanStack Query 사용 여부 (옵션, 기본값: false) diff --git a/README.md b/README.md new file mode 100644 index 0000000..5f5db23 --- /dev/null +++ b/README.md @@ -0,0 +1,1176 @@ +# Frontend 프로젝트 가이드 + +Vite + React + TypeScript 기반 프론트엔드 프로젝트 개발 가이드입니다. + +--- + +## 목차 + +1. [개발 규칙](#1-개발-규칙) +2. [개발 환경 및 옵션 리스팅](#2-개발-환경-및-옵션-리스팅) +3. [설치 및 동작 방법](#3-설치-및-동작-방법) +4. [아키텍처 & 책임 분리 규칙](#4-아키텍처--책임-분리-규칙) +5. [네이밍 & 패키지 규칙](#5-네이밍--패키지-규칙) +6. [예외 처리 & 에러 응답 규칙](#6-예외-처리--에러-응답-규칙) +7. [로그 & 감사(Audit) 규칙](#7-로그--감사audit-규칙) +8. [설정 관리 규칙](#8-설정-관리-규칙) +9. [보안 관련 추가 규칙](#9-보안-관련-추가-규칙) +10. [테스트 & 검증 규칙](#10-테스트--검증-규칙) +11. [금지 패턴 / 안티 패턴 목록](#11-금지-패턴--안티-패턴-목록) +12. [성능 최적화 가이드](#12-성능-최적화-가이드) +13. [의존성 관리](#13-의존성-관리) +14. [트러블슈팅 가이드](#14-트러블슈팅-가이드) + +--- + +## 1. 개발 규칙 + +### 1.1 시큐어 코딩 규칙 준수 + +- **OWASP Top 10 기반 보안 규칙 준수 필수** +- XSS 방지: `dangerouslySetInnerHTML` 금지, 필요 시 DOMPurify 사용 +- 인증 정보 저장 금지: `localStorage`/`sessionStorage`에 토큰 저장 금지 +- URL 인코딩: `encodeURIComponent` 사용 필수 +- `eval` / `new Function` 사용 금지 +- 환경 변수에 비밀키 저장 금지 + +**상세 규칙은 `base_arcitectures_md/SECURE_RULE.md` 참조** + +### 1.2 공통 소스 기능 및 활용 방법 + +#### 공통 API (`common/api/`) + +- **`http.ts`**: Axios 인스턴스 + - `baseURL`, `timeout`, `withCredentials` 설정 + - 전역 헤더 설정 + +- **`endpoints.ts`**: API 엔드포인트 상수 + ```typescript + import { API } from "@/common/api/endpoints"; + const response = await http.get(API.AUTH.ME); + ``` + +- **`interceptors.ts`**: 전역 인터셉터 + - 요청: 전역 로딩 시작 + - 응답: 전역 로딩 종료, 401/403 처리 + +#### 공통 인증 (`common/auth/`) + +- **`AuthContext`**: 인증 상태 Context +- **`AuthProvider`**: 인증 상태 제공자 +- **`useAuth`**: 인증 훅 + ```typescript + const { user, login, logout, refreshMe } = useAuth(); + ``` + +- **`ProtectedRoute`**: 인증 필요 라우트 보호 + ```typescript + } /> + ``` + +- **`authService`**: 인증 API 호출 + - `login()`, `logout()`, `me()` + +#### 공통 컴포넌트 (`common/components/`) + +**디렉터리 구조:** +``` +common/components/ +├── form/ # 폼 입력 컴포넌트 (Input, Select, Textarea, Checkbox, Radio) +├── action/ # 액션 컴포넌트 (Button) +├── display/ # 표시 컴포넌트 (Table) +├── system/ # 시스템 컴포넌트 (LoadingOverlay, LoadingProvider, Toast, CommonModal) +└── index.ts # 통합 export +``` + +**공통 원칙:** +- 모든 공통 컴포넌트는 `id`, `name`, `className` 전달 옵션 지원 +- 스타일 관련 세부 구현은 CSS로 처리 가능한 영역은 최대한 CSS에 위임 +- 컴포넌트는 범용성 위주로 설계하되, 과도한 추상화는 지양 +- 동작이 필요한 부분은 props 옵션으로만 제어 + +**입력 / 액션 계열 컴포넌트:** + +- **`Button.tsx`**: 버튼 컴포넌트 + ```typescript + import { Button } from "@/common/components"; + + + ``` + - `disabled`: 비활성화 + - `loading`: 로딩 상태 (중복 클릭 방지) + - `size`: 버튼 크기 (`sm`, `md`, `lg`) + - `variant`: 버튼 스타일 변형 + +- **`Input.tsx`**: 입력 컴포넌트 (검색 기능 포함) + ```typescript + import { Input } from "@/common/components"; + + // 기본 텍스트 입력 + {} + }} + /> + + // 비밀번호 입력 + + + // 숫자 입력 (숫자 이외 문자 자동 제거) + + ``` + - 지원 타입: `text`, `password`, `number` + - `format`: 이메일/전화번호 자동 포맷, 정규식 검증 + - `search`: debounce, commitOnEnter, clearOnEscape 옵션 + +- **`Select.tsx`**: 선택 컴포넌트 + ```typescript + import { Select } from "@/common/components"; + +