FE 공통사항 도메인 테크스펙 - 100-hours-a-week/9-team-Devths-WIKI GitHub Wiki

1. 공통 도메인

1️⃣ 배경 (Background)

프로젝트 목표 (Objective): 여러 도메인에서 반복되는 구현(요청/캐싱/에러처리/폼/모달)을 공통 규칙으로 통일하여 UX 일관성, 버그 감소, 개발 생산성을 확보함
- 핵심 결과 (Key Result) 1: API 호출/에러 처리 방식 통일로 중복 구현 감소
- 핵심 결과 (Key Result) 2: 폼 검증/에러 메시지 표준화로 입력 단계 이탈 및 오류 리포트 감소
- 핵심 결과 (Key Result) 3: 모달/토스트 정책 통일로 UI/상태 꼬임(닫힘 누락, 배경 스크롤 등) 0건 목표
문제 정의 (Problem):
- 도메인별로 API 호출 방식이 달라지면(axios/fetch 혼용, 에러 처리 제각각) 유지보수 비용 커짐
- 폼 검증 방식이 통일되지 않으면 같은 입력 오류도 페이지마다 메시지/UX가 달라짐
- 모달이 각자 구현되면 포커스 트랩/스크롤 락/중첩 모달 같은 문제로 버그가 늘어남
가설 (Hypothesis): 공통 규칙(API 레이어/React Query 패턴/Zustand 원칙/폼 표준/모달 정책)을 정리하고 재사용 가능한 유틸, 컴포넌트를 제공하면, 도메인별 구현이 빠르고 안전해지며 UX도 일관됨
관련 자료: 프론트 기술 스택 선정 문서, 백엔드 API 명세

2️⃣ 목표가 아닌 것 (Non-goals) (Optional)

이번 프로젝트에서 다루지 않는 내용:

다크모드

2️⃣ 설계 및 기술 자료 (Architecture and Technical Documentation)

아키텍처 개요 (Architecture Overview)

프레임워크/라이브러리
- React + Next.js
  - App Router 기반으로 라우팅/레이아웃을 표준화할 수 있어 화면 수가 많은 Devths에서 구조를 일관되게 유지
  - 페이지 성격에 맞게 SSG/CSR을 선택해 초기 로딩 UX(랜딩)와 인터랙션 중심 화면(채팅/캘린더)을 균형 있게 구성할 수 있음
상태 관리
- Zustand
  - 전역 UI 상태가 많아서 Zustand가 store로 관리 가능해 props drilling을 줄임
  - 필요한 상태만 구독하는 방식으로 불필요한 리렌더링 줄이기 좋음
UI 컴포넌트
- shadcn/ui
  - 기본 UI를 빠르게 구성하면서도 Tailwind 기반으로 프로젝트 디자인을 일관되게 유지 가능
  - 공통 UI를 표준화하기에 적합함
스타일링
- Tailwind CSS
  - 화면이 많은 프로젝트에서 스타일을 컴포넌트 단위로 빠르게 적용 가능
폼 관리
- React Hook Form + Zod
  - 폼이 많은 서비스이기에 입력 상태/검증/에러 표시 표준화 필요성
  - RHF는 불필요한 리렌더링을 줄이면서 폼을 다루기 쉬움
  - Zod 스키마로 검증 규칙을 한 곳에 모아 타입과 검증의 불일치를 줄일 수 있음
데이터 페칭
- TanStack Query
  - 서버 데이터가 많은 화면에서 캐시 기반으로 중복 요청을 줄이고, 로딩/에러/성공 상태를 일관되게 관리 가능
API 통신
- Axios
  - baseURL, 헤더, 인터셉터를 한 곳에서 표준화해 API 호출 방식이 화면마다 달라지는 것을 방지함
실시간
- STMOP + WebSocket
  - 1:1/그룹 채팅, 읽음 처리처럼 이벤트가 많은 기능에서 Pub/Sub 구조로 확장하기 좋음
  - Spring과 궁합이 좋음
CSR/SSG 적용 범위
- / (랜딩) : SSG
  - 서비스 소개/기능 설명 등 정적 콘텐츠 중심이며, 빌드 시 HTML을 미리 생성해 빠른 초기 로딩과 안정적인 서빙에 유리함
- /auth/* (OAuth 콜백) : CSR
  - 사용자마다 매번 다른 인가 코드/쿼리를 받아 처리해야 하므로 정적 생성 불가
  - 브라우저에서 쿼리 파싱 → 서버 토큰 교환 API 호출 → 로그인 상태 설정 → 리다이렉트 흐름이 자연스러움
- /signup : CSR
  - 닉네임 입력/프로필 이미지 업로드 등 사용자 입력이 핵심
  - 가입 여부 판별도 보통 클라이언트에서 /me 조회로 분기 처리 가능(미가입이면 가입 폼 노출)
- /calendar, /board, /chat, /profile 등 메인 기능 페이지 : CSR
  - 로그인 이후 사용자 개인화 데이터(일정/글/채팅/알림)를 TanStack Query로 가져와 그리는 인터랙션 중심 화면
  - 필터/무한스크롤/실시간 업데이트 등 클라이언트 상태 변화가 많음

주요 페이지 / 컴포넌트 구조

페이지 (Pages):
1. / : 랜딩 페이지
  - 주요 기능: 서비스 소개, 기능 요약, ‘구글 로그인 시작하기’ 버튼
  - 사용 컴포넌트:
    - AppShell(공개 레이아웃), Toast, FullScreenLoader
  - 데이터 로딩 시점: 없음 (정적 콘텐츠 중심)
  - 라우팅
    - / → (로그인 버튼 클릭) → 구글 OAuth 인증 페이지로 이동
    - 인증 성공 후 → /auth/google/callback 로 리다이렉트(구글이 code를 쿼리에 붙여서 반환)
주요 컴포넌트 (Components):
1. 주요 컴포넌트 (Components):
  - 주요 컴포넌트 이름
    - 개요 (Overview)
      - 역할:
    - Props & Interface
    - 내부 상태 & 이벤트
    - 사용 예시 (Usage)
    - 에러 처리 / 엣지 케이스
    - 스타일링
    - Storybook
컴포넌트 간 관계

상태 관리 전략 (State Management Strategy)

Global State (Zustand Stores):
Local State (React useState, useReducer):
Server Cache State (React Query):

API 연동 (API Integration)

호출할 백엔드 API 목록: (백엔드 Tech Spec 참조)
API 호출 처리:

라우팅 (Routing)

폼 처리 및 유효성 검증 (Forms & Validation)

유효성 검증 로직
- 클라이언트 측:
- 서버 측(백엔드)에서도 별도 검증 로직 존재:

4️⃣ 이외 고려사항들 (Other Considerations) (Optional)

테스트 전략:
로깅 및 분석 (Logging & Analytics):

5️⃣ 함께 논의하고 싶은 내용 (Open Questions) (Optional)

6️⃣ 용어 정의 (Glossary) (Optional)

1. 유저 도메인

1️⃣ 배경 (Background)

프로젝트 목표 (Objective): 사용자가 랜딩 → 구글 로그인 → 회원가입(신규일때만) → 메인 화면(캘린더) 진입까지 끊김 없이 진행하도록 UX를 단순화하고, 인증 상태 관리/보안/개발 생산성을 함께 확보한다.
- 핵심 결과 (Key Result) 1: 로그인/회원가입 플로우에서 무한 리다이렉트 발생률 0%
- 핵심 결과 (Key Result) 2: 인증 관련 오류(401/토큰 만료/ 세션 만료)로 인한 강제 로그아웃/진입 실패율 감소 (Sentry/로그 기준)
- 핵심 결과 (Key Result) 3: Auth 관련 UI 컴포넌트(버튼/가드/폼/업로더) 재사용 50% 이상 확보 (Storybook 스토리 수/공유 컴포넌트 기준)
문제 정의 (Problem):
- 복잡한 흐름으로 UX 끊김: 로그인 직후 ‘어디로 가야 하는지’가 불명확하거나, 신규/기존 분기 처리의 일관성이 없으면 사용자가 혼란을 느낌
- 인증 버그 빈발: 새로고침 시 전역 상태 초기화로 로그인 풀림처럼 보임, 401 처리 정책 부재로 무한 리다이렉트, 만료 처리 미흡으로 토큰 만료 에러 발생
- 낮은 개발 생산성: 인증 로직이 페이지마다 흩어지면 수정 시 영향 범위가 커지고(리다이렉트 조건/에러 처리), 테스트가 어려움
- 로딩 UX 미정: 인증 상태가 unknown인 구간에서 로딩 UI가 없으면 화면 깜빡임/데이터 401이 자주 발생함
가설 (Hypothesis): 인증을 (1) 인증상태 전역관리(Zustand)와 (2) 유저데이터 서버캐시(React Query)로 역할을 분리하고, 보호 라우트는 AuthGuard에서 단일 정책으로 처리하면, 인증 버그(로그인 풀림/무한 리다이렉트/만료 에러)가 크게 줄고 개발 생산성도 개선될 것임
관련 자료: 요구사항 정의서, 화면 설계서, 백엔드 API 명세

2️⃣ 목표가 아닌 것 (Non-goals)

이번 프로젝트에서 다루지 않는 내용:

아이디/비밀번호 기반 자체 로그인
소셜 로그인 다중 제공자(카카오/네이버 등) 추가
계정 탈퇴/복구 정책의 세부 운영(보관 기간 등)

3️⃣ 설계 및 기술 자료 (Architecture and Technical Documentation)

아키텍처 개요 (Architecture Overview)

프레임워크/라이브러리: React + Next.js
- 라우팅/레이아웃을 표준으로 제공해 인증 플로우(공개/보호 라우트)를 구조적으로 분리하기 쉽고, 콜백처럼 클라이언트에서 리다이렉트가 필요한 페이지도 명확히 분리 가능
인증 상태 관리: Zustand
- 인증 UI 상태(로그인 됨/안 됨/확인 중)를 전역에서 일관되게 다루고, AuthGuard에서 단일 정책으로 제어하기 위함
유저 데이터 관리: TanStack Query
- me 같은 서버 데이터는 캐시/재시도/무효화 전략으로 관리해 새로고침/페이지 이동 시에도 일관된 사용자 정보를 제공하기 위함
API 통신: Axios
- 인증 API에서 공통 에러 포맷/401 처리/로깅을 표준화하여 페이지마다 다른 에러 처리를 방지하기 위함
UI 피드백: Toast + FullScreenLoader
- 인증 처리 중 로딩/실패 안내를 통일해 UX 끊김을 줄이기 위함

주요 페이지 / 컴포넌트 구조

페이지 (Pages)
- 페이지 이름:
  - 주요 기능:
  - 사용 컴포넌트:
  - 데이터 로딩 시점:
  - 라우팅:
주요 컴포넌트 (Components):
- 주요 컴포넌트 이름
  - 개요 (Overview)
    - 역할:
    - 디자인 시안:
  - Props & Interface
  - 내부 상태 & 이벤트
  - 사용 예시 (Usage)
  - 에러 처리 / 엣지 케이스
  - 스타일링
  - Storybook
컴포넌트 간 관계

상태 관리 전략 (State Management Strategy)

Global State (Zustand Stores):
Local State (React useState, useReducer):
Server Cache State (React Query):

API 연동 (API Integration)

호출할 백엔드 API 목록: (백엔드 Tech Spec 참조)
API 호출 처리:

라우팅 (Routing)

폼 처리 및 유효성 검증 (Forms & Validation)

유효성 검증 로직
- 클라이언트 측:
- 서버 측(백엔드)에서도 별도 검증 로직 존재:

4️⃣ 이외 고려사항들 (Other Considerations) (Optional)

테스트 전략:
로깅 및 분석 (Logging & Analytics):