친구하자 Frontend

🛠 기술 스택

Frontend

• React 18 - 모던 React 기능 활용
• TypeScript - 타입 안전성 보장
• Vite - 빠른 개발 서버 및 빌드
• TailwindCSS 3 - 유틸리티 퍼스트 CSS 프레임워크
• React Router 6 - SPA 라우팅
• React Query - 서버 상태 관리 및 API 캐싱
• shadcn/ui - 고품질 UI 컴포넌트 라이브러리

Backend (별도 프로젝트)

• Spring Boot 3.x + WebFlux
• MySQL 8.0 (Aiven/AWS RDS)
• Redis 7.0 (캐시/큐)
• JWT + OAuth2 (Kakao, Google 인증)
• Java 17+

📁 프로젝트 구조

client/                   # React SPA 프론트엔드
├── pages/                # 페이지 컴포넌트
│   ├── Index.tsx         # 홈 페이지
│   └── NotFound.tsx      # 404 페이지
├── components/ui/        # shadcn/ui 컴포넌트 라이브러리
├── hooks/                # 커스텀 React 훅
├── lib/                  # 유틸리티 함수
├── App.tsx               # 앱 진입점 및 라우팅 설정
└── global.css            # TailwindCSS 테마 및 글로벌 스타일

shared/                   # 클라이언트-서버 공유 타입
└── api.ts                # API 인터페이스 정의

🚀 시작하기

필수 요구사항

• Node.js 18+
• pnpm (권장) 또는 npm

설치 및 실행

1. 의존성 설치

   pnpm install

2. 개발 서버 실행

   pnpm dev

3. 브라우저에서 확인

   • 메인 애플리케이션: http://localhost:8080

기타 명령어

# 타입 체크
pnpm typecheck

# 테스트 실행
pnpm test

# 프로덕션 빌드
pnpm build

# 프로덕션 서버 실행 (정적 파일 서빙)
pnpm start

📱 iOS 빌드

필수 요구사항

• macOS (Xcode는 macOS에서만 실행 가능)
• Xcode 15.0 이상
• CocoaPods (sudo gem install cocoapods)
• Apple Developer 계정 (실제 기기에 배포하려면)

iOS 빌드 단계

1. 의존성 설치 및 빌드

   # 프로젝트 의존성 설치
   pnpm install
   
   # 웹 앱 빌드
   pnpm build

2. Capacitor 동기화

   # iOS 프로젝트에 웹 빌드 결과 동기화
   pnpm ios:sync

3. Xcode에서 열기

   # Xcode에서 iOS 프로젝트 열기
   pnpm ios:open

   또는 직접 열기:

   open ios/App/App.xcworkspace

4. Xcode에서 설정 및 빌드

   • Xcode에서 프로젝트를 열면 App.xcworkspace 파일을 열어야 합니다 (.xcodeproj가 아님)
   • Signing & Capabilities 탭에서:
     • Team: Apple Developer 계정 선택
     • Bundle Identifier: com.chingoohaja.app (필요시 변경)
   • 시뮬레이터 또는 실제 기기 선택
   • Product > Run (⌘R) 또는 빌드 버튼 클릭

iOS 빌드 스크립트

# 개발 모드 (라이브 리로드)
pnpm ios:dev

# 프로덕션 빌드 후 실행
pnpm ios:build

# Capacitor 동기화만 (빌드 후 변경사항 반영)
pnpm ios:sync

# Xcode에서 열기
pnpm ios:open

주의사항

• CocoaPods 설치: iOS 의존성 관리를 위해 CocoaPods가 필요합니다

  sudo gem install cocoapods
  cd ios/App
  pod install

• Info.plist 설정: 필요한 권한(카메라, 마이크 등)이 있다면 ios/App/App/Info.plist에서 설정

• Capacitor 플러그인: 새 플러그인을 추가한 후에는 pnpm ios:sync를 실행해야 합니다

문제 해결

• Pod 설치 오류: ios/App 디렉토리에서 pod install 실행
• 빌드 오류: Xcode에서 Clean Build Folder (⌘⇧K) 후 다시 빌드
• 동기화 문제: rm -rf ios/App/App/public 후 pnpm ios:sync 재실행

🔧 환경 설정

환경 변수

.env 파일에서 다음 변수들을 설정할 수 있습니다:

# Spring Boot API 서버 URL (예시)
VITE_API_BASE_URL=http://localhost:8080/api

# 기타 공개 변수들
VITE_APP_NAME=로그인 앱

📱 주요 기능

OAuth 소셜 로그인

• 카카오 로그인: 카카오 계정으로 간편 로그인
• 구글 로그인: 구글 계정으로 간편 로그인
• PKCE 보안: OAuth 2.0 PKCE 방식으로 안전한 인증
• 자동 리다이렉트: 로그인 상태에 따른 자동 페이지 이동
• 프로필 설정: 신규 사용자 프로필 완성 플로우

UI/UX 특징

• 모바일 상태바 시뮬레이션 (모바일 뷰)
• 한국 서비스에 최적화된 디자인
• 접근성을 고려한 컴포넌트 설계
• OAuth 콜백 처리 및 로딩 상태 표시

🔌 Spring Boot 연동

API 연동 설정

Spring Boot 서버와 연동하려면:

1. CORS 설정 (Spring Boot에서)

   @CrossOrigin(origins = "http://localhost:8080")

2. API 호출 설정 (React에서)

   const API_BASE_URL =
     import.meta.env.VITE_API_BASE_URL || "http://localhost:8080/api";

OAuth 소셜 로그인 플로우

1. OAuth 설정 조회: GET /api/v1/auth/oauth/{provider}/config
2. 소셜 로그인 시작: 사용자가 소셜 로그인 버튼 클릭
3. 인증 페이지 리다이렉트: 카카오/구글 인증 페이지로 이동
4. 콜백 처리: POST /api/v1/auth/oauth/{provider}로 인가 코드 전송
5. 토큰 저장:
   • Access Token은 메모리에만 저장 (XSS 공격 방어)
   • Refresh Token은 HttpOnly 쿠키로 서버에서 관리
6. 페이지 이동: 사용자 상태에 따라 프로필 설정 또는 대시보드로 이동

보안 특징

• 메모리 기반 토큰 관리: Access Token을 메모리에만 저장하여 XSS 공격 방어
• 자동 토큰 재발급: 앱 부팅 시 refresh token으로 access token 자동 재발급
• API 인터셉터: 401 에러 시 자동으로 토큰 갱신 후 재시도
• PKCE (Proof Key for Code Exchange): OAuth 2.0 보안 강화
• State 검증: CSRF 공격 방지
• SessionStorage 활용: 임시 OAuth 데이터 보안 저장
• HttpOnly 쿠키: Refresh Token을 XSS/CSRF로부터 안전하게 보호
• 환경별 로깅 정책:
  • 개발 환경: 상세 디버깅 로그 출력
  • 프로덕션: 민감한 정보(토큰, App ID, 채널명 등) 로그 제거

🚀 배포

프론트엔드 배포

• Netlify/Vercel: 자동 배포 지원
• 정적 호스팅: 빌드된 SPA 파일 배포

백엔드 연동

• Spring Boot 서버를 별도로 배포
• 환경 변수로 API 서버 URL 설정

📝 개발 가이드

새 페이지 추가

1. client/pages/에 컴포넌트 생성
2. client/App.tsx에 라우트 추가

API 호출 예시

// React Query 사용
const { data, isLoading } = useQuery({
  queryKey: ["user"],
  queryFn: () => fetch("/api/user").then((res) => res.json()),
});

컴포넌트 사용

import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";