• App Router 기반 라우팅
• SSR/ISR 활용으로 SEO 최적화
• React 19의 use() 훅 활용한 데이터 페칭

• 작은 번들 사이즈로 모바일 웹 최적화
• 서버 컴포넌트 호환성
• 직관적인 API로 빠른 개발 가능

• 유틸리티 퍼스트 접근으로 빠른 개발
• 커스텀 테마로 브랜드 디자인 시스템 구축

• Tailwind 기반 컴포넌트
• 필요한 컴포넌트만 가져와 번들 크기 최적화

• 서버 컴포넌트: use() 훅으로 SEO 최적화
• 클라이언트: TanStack Query로 복잡한 상태 관리

• 타입스크립트 연동
• 서버-클라이언트 스키마 공유

• 가벼운 번들 사이즈로 모바일 친화적
• Zod과 통합해 정교한 유효성 검사 가능
• Server Action과 병행 사용 가능 (필요 시 SSR + 빠른 UX 모두 확보)

• 국내 사용자 친화적 UI
• 커스텀 마커/클러스터링 지원

• Next.js 15 내장 빌드 도구 ( Turbopack : 개발 환경, Webpack : 프로덕션 환경 )
• 빠른 개발 환경과 HMR 지원

• 홈 또는 약관 동의 페이지로 리다이렉트만 진행하는데, SSR을 사용하면 화면 깜빡임 없이 바로 리다이렉트 가능
• query parameter code를 처리해야하기 때문에 SSG는 적절하지 않음.

• 검색엔진에 노출될 필요 없는 페이지
• 사용자 인터랙션이 주요 기능 (체크박스 선택, 폼 제출)

• 사용자 인터렉션이 주요 기능 (폼 제출, 실시간 유효성 검증, 프로필 이미지 업로드)

• SSR 할 정도의 SEO 이점이 없음. 개인 정보이기 때문에 정적 페이지로 캐싱하면 안됨.
• 사용자가 저장한 장소리스트를 무한 스크롤로 처리하기 때문에 CSR 사용

• 사용자 인터렉션이 주요 기능 (폼 제출, 실시간 유효성 검증, 프로필 이미지 업로드)

• 사용자 인터렉션이 주요 기능 (사용자 확인 및 동의)

oauth/kakao/callback : 카카오 OAuth 콜백 처리 페이지

• 주요기능 : 카카오 인증 코드로 로그인/호원가입 후 적절한 페이지로 라우팅
• 사용 컴포넌트 :
  • KakaoCallbackClient (클라이언트 사이드 로직 처리)
• 데이터 로딩 시점 : 페이지 진입 시 Query Parameter (code)를 사용하여 POST /api/v1/auth/tokens API 호출 (by KakaoCallbackClient).
• 라우팅 (API 응답에 따라 KakaoCallbackClient가 처리):
  • 신규 회원 → /auth/consent
  • 기존 회원 → /
  • 에러 발생 → /onboarding

/auth/consent: 약관 동의 페이지

• 주요 기능 : 서비스 이용약관(개인정보 처리방침, 위치기반 서비스) 동의.
• 사용 컴포넌트 :
  • ConsentPage (페이지 레이아웃 및 로직 컨테이너)
  • PrivacyConsent (@/features/user/components/consent/PrivacyConsent.tsx)
  • LocationConsent (@/features/user/components/consent/LocationConsent.tsx)
  • useConsent (@/features/user/hooks/useConsent.ts)
• 데이터 로딩 시점 :
  • 약관 내용은 각 PrivacyConsent, LocationConsent 컴포넌트 내에 직접 작성되어 있음.
• 라우팅 : useConsent 훅의 handleAgreement 함수 내에서 POST /api/v1/users/agreement API 호출 성공 시 → /auth/signup

/auth/signup: 추가 정보 입력 페이지

• 주요 기능 : 닉네임 설정, 소개글 설정, 프로필 이미지 업로드하여 회원가입 완료.
• 사용 컴포넌트 :
  • ProfileForm (@/features/user/components/profile-form/ProfileForm.tsx)
• 데이터 로딩 시점 : 없음 (새 정보 입력).
• 라우팅 : ProfileForm의 onSubmit 핸들러에서 POST /api/v1/users API 호출 성공 시 → / (또는 온보딩 완료/환영 페이지)

/mypage : 마이페이지 - 내 프로필

• 주요기능 : 사용자 프로필 정보 조회 및 표시, 회원정보 수정/로그아웃/탈퇴 기능 링크 제공.
• 사용 컴포넌트 :
  • Profile (@/features/user/components/profile/Profile.tsx)
  • useUser (@/features/user/hooks/useUser.ts)
  • Header (@/shared/components)
• 데이터 로딩 시점 : 페이지 진입 시 useUser 훅을 통해 GET /api/v1/users/me API 호출.
• 라우팅 :
  • "회원정보 수정" 버튼 클릭 시 → /mypage/edit
  • "로그아웃" 버튼 클릭 시 → logout API 호출 후 /onboarding
  • "회원 탈퇴하기" 버튼 클릭 시 → /mypage/delete

/mypage/places : 마이페이지 - 저장한 장소

• 주요기능 : 사용자 프로필 정보 조회 및 표시
• 사용 컴포넌트 : (현재 코드 분석 기준, 이 페이지의 구체적인 유저 관련 컴포넌트는 확인되지 않음. 장소 목록 관련 기능이 주가 될 것으로 예상)
  • Profile (@/features/user/components/profile/Profile.tsx)
  • SavedPlaceListCard (내가 저장한 장소 목록) , v2 예정
• 데이터 로딩 시점 : 페이지 진입 시 GET /api/v1/users/me API 호출

/mypage/edit: 마이페이지 - 유저 정보 수정

• 주요 기능 : 유저 정보 수정 (닉네임 설정, 소개글 설정, 프로필 이미지).
• 사용 컴포넌트 :
  • ProfileForm (@/features/user/components/profile-form/ProfileForm.tsx)
  • useUser (@/features/user/hooks/useUser.ts) (수정 전 초기 데이터 로딩용)
• 데이터 로딩 시점 : 페이지 진입 시 useUser 훅을 통해 GET /api/v1/users/me API를 호출하여 기존 프로필 정보를 ProfileForm의 defaultValues로 전달.
• 라우팅 : ProfileForm의 onSubmit 핸들러에서 PATCH /api/v1/users API 호출 성공 시 → /mypage

/mypage/delete: 마이페이지 - 탈퇴

• 주요 기능 : 유저 탈퇴 처리.
• 사용 컴포넌트 :
  • DeleteAccountForm (@/features/user/components/delete-account/DeleteAccountForm.tsx)
• 라우팅 : DeleteAccountForm 내부에서 DELETE /api/v1/users API 호출 성공 시 → /onboarding

개요

• 역할: src/app/(auth)/auth/consent/page.tsx 내에서 PrivacyConsent, LocationConsent 컴포넌트와 useConsent 훅을 조합하여 서비스 이용을 위한 약관 동의 기능을 제공합니다. 각 약관 내용은 해당 컴포넌트 내에 직접 작성되어 있습니다.

관련 컴포넌트 및 훅

• ConsentPage (src/app/(auth)/auth/consent/page.tsx): 약관 동의 UI 전체를 구성하는 페이지 컴포넌트입니다.
• PrivacyConsent (@/features/user/components/consent/PrivacyConsent.tsx): 개인정보 처리방침 동의 UI를 렌더링합니다. (내부적으로 ConsentCard 사용)
  • Props: checked: boolean, onCheckedChange: (checked: boolean) => void
• LocationConsent (@/features/user/components/consent/LocationConsent.tsx): 위치기반 서비스 이용약관 동의 UI를 렌더링합니다. (내부적으로 ConsentCard 사용)
  • Props: checked: boolean, onCheckedChange: (checked: boolean) => void
• ConsentCard (@/features/user/components/consent/ConsentCard.tsx): 개별 약관 내용을 표시하고 동의 체크박스를 제공하는 UI 컴포넌트입니다.
  • Props: title: string, label: string, checked: boolean, onCheckedChange: (checked: boolean) => void, children: ReactNode
• useConsent (@/features/user/hooks/useConsent.ts): 약관 동의 상태 및 관련 로직을 관리하는 커스텀 훅입니다.

  • 반환 값:

    {
      privacyConsent: boolean;
      setPrivacyConsent: (value: boolean) => void;
      locationConsent: boolean;
      setLocationConsent: (value: boolean) => void;
      handleAllConsent: () => void;
      handleAgreement: () => Promise<void>;
    }

주요 로직 ( useConsent 훅 내부 )

• privacyConsent, locationConsent: 각 약관의 동의 상태 (boolean)
• handleAllConsent: 전체 동의 상태를 토글합니다.
• handleAgreement:
  • postAgreement({ location_agreed: boolean, privacy_agreed: boolean }) API (POST /api/v1/users/agreement)를 호출하여 동의 결과를 서버에 전송합니다.
  • API 호출 성공 시 /auth/signup 페이지로 라우팅합니다.

에러 처리 / 엣지 케이스

• handleAgreement 함수 내 API 호출 실패 시 console.error를 통해 에러가 로깅됩니다.
• 필수 약관 (개인정보, 위치정보) 모두 동의해야 '다음' 버튼이 활성화됩니다.

스타일링

• ConsentCard 내부에서 약관 내용 스크롤 처리.
• 각 약관 라벨에 "[필수]" 텍스트 포함.

개요

• 역할: 사용자 프로필 정보 (닉네임, 소개글, 프로필 이미지) 입력 및 수정을 위한 폼 컴포넌트입니다. (src/features/user/components/profile-form/ProfileForm.tsx)

Props & Interface

interface ProfileFormProps {
  onSubmit: (data: ProfileFormValues) => Promise<void>;
  defaultValues?: Partial<ProfileFormValues>;
  buttonText?: string; // 기본값: '저장'
}

type ProfileFormValues = {
  profile_image?: string;
  username: string;
  introduction?: string;
};

• onSubmit (required): 폼 제출 시 호출될 함수. ProfileFormValues를 인자로 받습니다.
• defaultValues (optional): 폼 초기값을 설정합니다. (예: 프로필 수정 시 기존 데이터)
• buttonText (optional): 제출 버튼의 텍스트를 설정합니다. (기본값: "저장")

내부 상태 & 주요 기능

• 폼 관리: react-hook-form 라이브러리와 zod를 사용하여 폼 상태 관리 및 유효성 검증을 수행합니다.
• 프로필 이미지 처리:
  • useImageUpload 커스텀 훅을 사용하여 이미지 업로드 로직을 처리합니다.
  • 사용자가 이미지를 선택하면 미리보기를 제공합니다.
  • 파일 제한: 최대 5MB, 허용 확장자 (.jpg, .jpeg, .png, .webp).
  • 이미지 유효성 검사 실패 또는 업로드 실패 시 에러 메시지를 표시합니다.
  • 이미지 업로드 성공 시, onSubmit으로 전달되는 profile_image 필드에 업로드된 URL이 포함됩니다.
• 닉네임 (username):
  • 필수 입력 항목입니다.
  • 유효성 검증: 최소 2자, 최대 10자, 특수문자 사용 불가 (/^[가-힣a-zA-Z0-9\s]+$/).
  • 유효성 검증 실패 시 에러 메시지가 표시됩니다.
  • 참고: 닉네임 중복 실시간 체크 기능은 ProfileForm 컴포넌트 자체에는 포함되어 있지 않습니다. 중복 체크는 onSubmit 핸들러를 통해 서버 측에서 처리되거나, 별도의 로직으로 구현될 수 있습니다.
• 소개글 (introduction):
  • 선택 입력 항목입니다.
  • 유효성 검증: 최대 70자.
  • 유효성 검증 실패 시 에러 메시지가 표시됩니다.

사용 예시 (Usage)

import { ProfileForm } from '@/features/user/components/profile-form';

function SignupPage() {
  const handleSignup = async (data: ProfileFormValues) => {
    // 회원가입 API 호출 (data.profile_image는 URL임)
    // 예: await api.signup(data);
  };

  return <ProfileForm onSubmit={handleSignup} buttonText="가입하기" />;
}

function ProfileEditPage() {
  const userInitialData = await api.getUser(); // 유저 정보 조회 API 호출

  const handleProfileUpdate = async (data: ProfileFormValues) => {
    // 프로필 수정 API 호출
    // 예: await api.updateProfile(data);
  };

  return (
    <ProfileForm
      defaultValues={userInitialData}
      onSubmit={handleProfileUpdate}
      buttonText="수정완료"
    />
  );
}

에러처리 / 엣지 케이스

• 이미지 관련: 파일 크기 초과, 지원하지 않는 확장자 선택 시 폼 내 에러 메시지 표시.
• 폼 유효성: 각 필드(닉네임, 소개글)의 유효성 규칙 위반 시 해당 필드 아래 에러 메시지 표시.
• 필수 필드 (닉네임) 누락 시 에러 메시지.

스타일링

• 입력 필드 레이아웃 및 에러 메시지 스타일링.
• 이미지 미리보기 영역 (원형, 클릭하여 파일 선택).
• 폼 제출 중 버튼 비활성화 및 로딩 상태 시각적 피드백 (예: 이미지 영역에 "업로드중...").

Storybook

• Empty Form: defaultValues 없이 기본 상태 (회원가입 시나리오).
• With Values: defaultValues를 전달하여 초기값이 채워진 상태 (프로필 수정 시나리오).
• With Errors: 각 필드에 유효성 검증 에러가 발생한 상태.

개요

• 역할: 사용자의 프로필 이미지, 닉네임, 소개글을 종합적으로 표시합니다. (src/features/user/components/profile/Profile.tsx)
• 이 컴포넌트는 기존 문서의 ProfileSummaryCard와 ProfileDetailCard의 기능을 통합하여 제공합니다.

Props & Interface

interface ProfileProps {
  username: string;
  profile_image: string; // 이미지 URL
  introduction: string;
}

• username (required): 사용자의 닉네임.
• profile_image (required): 사용자의 프로필 이미지 URL. 이미지가 없을 경우 빈 문자열 전달 시 기본 아이콘이 표시됩니다.
• introduction (required): 사용자의 소개글. 줄바꿈은 whitespace-pre-line으로 처리됩니다.

사용 예시 (Usage)

<Profile
  username="멋진닉네임"
  profile_image="/path/to/image.jpg"
  introduction="안녕하세요.\n만나서 반갑습니다."
/>

에러처리 / 엣지 케이스

• profile_image가 제공되지 않거나 빈 문자열일 경우, 기본 사용자 아이콘을 표시합니다.

스타일링

• 프로필 이미지 원형 스타일링 및 기본 아이콘 스타일.
• 닉네임 (heading-2), 소개글 (body-text, text-gray-600) 스타일링.

Storybook

• Default: 모든 정보(이미지, 닉네임, 소개글)가 정상적으로 표시되는 상태.
• No Image: 프로필 이미지가 없는 상태 (기본 아이콘 표시).
• Long Introduction: 여러 줄의 긴 소개글이 있는 상태.

• 역할: 사용자가 저장한 장소 목록을 카드 형태로 표시합니다.

• 역할: 회원 탈퇴 관련 유의사항을 안내하고, 사용자의 동의를 받아 실제 탈퇴를 처리하는 폼 컴포넌트입니다. (src/features/user/components/delete-account/DeleteAccountForm.tsx)
• 이 컴포넌트는 기존 문서의 AccountDeletionNotice와 AccountDeletionButton의 기능을 통합하여 제공합니다.

• 유의사항 안내: 컴포넌트 내에 하드코딩된 탈퇴 관련 유의사항을 목록 형태로 표시합니다.
• 탈퇴 동의: 사용자는 "위 내용을 모두 확인하였으며, 탈퇴에 동의합니다." 체크박스를 선택해야 합니다.
• 상태 관리: isAgreed (boolean) 내부 상태를 통해 사용자의 동의 여부를 관리합니다.
• 탈퇴 실행 (handleDelete 함수):
  • isAgreed가 true일 때 활성화되는 "탈퇴하기" 버튼을 통해 실행됩니다.
  • deleteUser() API (DELETE /api/v1/users)를 호출하여 회원 탈퇴를 요청합니다.

• 유의사항 텍스트, 동의 체크박스, "탈퇴하기" 버튼 (활성/비활성 상태 포함)에 대한 스타일링이 적용됩니다.
• "탈퇴하기" 버튼은 동의 시 빨간색 계열로 강조됩니다.

• Default: 기본 회원 탈퇴 폼 (유의사항 및 동의 체크박스 표시).
• Agreed: 사용자가 탈퇴에 동의하여 버튼이 활성화된 상태.

Consent 관련 기능 (src/app/(auth)/auth/consent/page.tsx 중심으로):

• 역할: 약관 동의 페이지의 전체적인 UI와 사용자 인터랙션 및 데이터 흐름을 관리합니다.
• 구성 요소 및 관계:
  • ConsentPage (page.tsx):
    • useConsent 훅을 사용하여 약관 동의 상태 (privacyConsent, locationConsent) 및 제출 로직 (handleAgreement)을 관리합니다.
    • PrivacyConsent 및 LocationConsent 컴포넌트를 사용하여 각 약관 내용을 화면에 표시하고, 이들 컴포넌트에 useConsent 훅에서 받은 상태와 상태 변경 함수를 props로 전달합니다.
  • useConsent (@/features/user/hooks/useConsent.ts):
    • 약관 동의 여부 (privacyConsent, locationConsent)를 useState로 관리합니다.
    • setPrivacyConsent, setLocationConsent 함수를 통해 각 동의 상태를 업데이트합니다.
    • handleAllConsent 함수로 전체 동의/해제를 처리합니다.
    • handleAgreement 함수에서 postAgreement API를 호출하여 서버에 동의 데이터를 전송하고, 성공 시 다음 페이지로 라우팅합니다.
  • PrivacyConsent / LocationConsent (@/features/user/components/consent/):
    • 각각 개인정보 처리방침과 위치기반 서비스 이용약관의 UI를 담당합니다.
    • 내부적으로 ConsentCard 컴포넌트를 사용하여 약관 제목, 내용, 동의 체크박스를 일관된 형태로 렌더링합니다.
    • ConsentPage로부터 checked (동의 상태)와 onCheckedChange (상태 변경 함수)를 props로 받아 ConsentCard 및 내부 Checkbox와 연동합니다.
  • ConsentCard (@/features/user/components/consent/ConsentCard.tsx):
    • 약관 제목, 스크롤 가능한 약관 내용 영역, 그리고 하단의 동의 문구와 Checkbox를 포함하는 재사용 가능한 UI 카드입니다.
    • PrivacyConsent 및 LocationConsent 컴포넌트에게 UI 구조를 제공합니다.

회원가입 페이지 (src/app/(auth)/auth/signup/page.tsx) 관련:

• 역할: 사용자가 닉네임, 프로필 이미지, 소개글 등의 추가 정보를 입력하여 회원가입을 완료하는 페이지입니다.
• 구성 요소 및 관계:
  • SignupPage (page.tsx):
    • ProfileForm 컴포넌트를 사용하여 사용자 입력을 받습니다.
    • ProfileForm의 onSubmit 핸들러에서 signup API (POST /api/v1/users)를 호출하여 회원가입 처리를 수행하고, 성공 시 메인 페이지 등으로 라우팅합니다.
  • ProfileForm (@/features/user/components/profile-form/ProfileForm.tsx):
    • 회원가입에 필요한 필드(닉네임, 프로필 이미지, 소개글)를 제공하고 유효성 검증을 수행합니다.
    • 이미지 업로드, 입력 값 관리 등의 로직을 내부적으로 처리합니다.
    • 사용자가 입력한 데이터를 onSubmit prop을 통해 SignupPage로 전달합니다.

마이페이지 (src/app/(main)/mypage/page.tsx) 관련:

• 역할: 로그인한 사용자의 프로필 정보를 보여주고, 프로필 수정, 로그아웃, 회원 탈퇴 등의 기능을 제공하는 페이지입니다.
• 구성 요소 및 관계:
  • MyPage (page.tsx):
    • useUser 훅을 사용하여 현재 로그인된 사용자 정보를 조회합니다. (내부적으로 getUser API - GET /api/v1/users/me 호출)
    • 조회된 사용자 정보를 Profile 컴포넌트에 전달하여 화면에 프로필을 표시합니다.
    • "회원정보 수정", "로그아웃", "회원 탈퇴하기" 버튼을 제공하며, 각 버튼 클릭 시 해당 페이지로 라우팅하거나 관련 API (logout)를 호출합니다.
  • useUser (@/features/user/hooks/useUser.ts):
    • 사용자 정보를 가져오고 상태를 관리합니다.
  • Profile (@/features/user/components/profile/Profile.tsx):
    • MyPage로부터 받은 사용자 정보(닉네임, 프로필 이미지 URL, 소개글)를 UI에 표시합니다.

프로필 수정 페이지 (src/app/(main)/mypage/edit/page.tsx) 관련:

• 역할: 사용자가 기존 프로필 정보(닉네임, 프로필 이미지, 소개글)를 수정하는 페이지입니다.
• 구성 요소 및 관계:
  • ProfileEditPage (page.tsx):
    • useUser 훅을 사용하여 현재 사용자 정보를 조회하고, 이 정보를 ProfileForm의 defaultValues로 전달합니다.
    • ProfileForm 컴포넌트를 사용하여 사용자 입력을 받습니다.
    • ProfileForm의 onSubmit 핸들러에서 patchUser API (PATCH /api/v1/users)를 호출하여 프로필 수정을 요청하고, 성공 시 마이페이지 등으로 라우팅합니다.
  • useUser (@/features/user/hooks/useUser.ts): 현재 사용자 정보를 가져옵니다.
  • ProfileForm (@/features/user/components/profile-form/ProfileForm.tsx):
    • 프로필 수정에 필요한 필드를 제공하고, defaultValues로 기존 정보를 표시합니다.
    • 사용자가 수정한 데이터를 onSubmit prop을 통해 ProfileEditPage로 전달합니다.

회원 탈퇴 페이지 (src/app/(main)/mypage/delete/page.tsx) 관련:

• 역할: 사용자가 서비스에서 탈퇴하는 절차를 진행하는 페이지입니다.
• 구성 요소 및 관계:
  • DeleteAccountPage (page.tsx):
    • DeleteAccountForm 컴포넌트를 사용하여 탈퇴 유의사항 안내 및 동의를 받습니다.
  • DeleteAccountForm (@/features/user/components/delete-account/DeleteAccountForm.tsx):
    • 탈퇴 유의사항을 표시하고, 사용자로부터 탈퇴 동의를 받습니다.
    • 동의 시, 내부적으로 deleteUser API (DELETE /api/v1/users)를 호출하고, 성공 시 온보딩 페이지 등으로 라우팅합니다.

• 사용자 정보 (User | null)를 React useState를 통해 관리합니다.
• 컴포넌트 마운트 시 useEffect 내에서 getUser API (GET /api/v1/users/me)를 호출하여 사용자 정보를 가져와 상태를 업데이트합니다.
• Zustand와 같은 별도의 전역 상태 관리 라이브러리를 사용하지 않고, React의 기본 훅을 활용한 로컬 상태 관리 및 API 연동 방식을 따릅니다.
• 반환값: { user: User | null }

• ProfileForm: 폼 입력 값, 유효성 검증 상태, 이미지 미리보기 URL, 제출 중 상태 등을 useState 및 react-hook-form의 내부 상태로 관리합니다.
• useConsent: 약관 동의 여부 (privacyConsent, locationConsent)를 useState로 관리합니다.
• DeleteAccountForm: 탈퇴 동의 여부 (isAgreed)를 useState로 관리합니다.

• 현재는 useEffect 또는 일반 비동기 함수 내에서 커스텀 API 함수를 통해 호출하는 방식으로 구현되어있습니다.
• 프로필 이미지 업로드: useImageUpload 훅을 통해 이미지가 서버(예: S3)에 업로드된 후 반환되는 URL을 사용합니다.
• 저장된 장소 데이터: v2 예정

• GET /api/v1/auth/oauth : 로그인 요청
• POST /api/v1/auth/tokens : 로그인
• POST /api/v1/auth/token/refresh : 토큰 재발급
• POST /api/v1/auth/logout : 로그아웃
• POST /api/v1/users/agreement : 개인 정보 및 위치 정보 동의
• POST /api/v1/users : 회원가입
• GET /api/v1/users/me : 본인 프로필 조회
• PATCH /api/v1/users : 본인 프로필 수정
• DELETE /api/v1/users : 유저 탈퇴

• API 요청/응답 상태에 따른 로딩 문구 표시
• fetch 사용
• API 오류 발생 시 사용자에게 친화적인 메시지 표시 및 로깅.
• Tanstack Query를 활용하여 중복 호출 방지, 캐시 관리, 자동 재요청 등 처리 예정