# 설계서: 프론트 - 로그인 메뉴 (#283) > **상태**: Approved > **작성**: [AI] Architect · **최종수정**: 2026-06-15 > **추적성** — Redmine: #283 · 관련 ADR: 없음 > · 구현 파일: `frontend/src/components/LoginMenu.tsx` · 테스트: TBD (현재 없음) ## 1. 목적 (Why) 헤더에서 비로그인 사용자가 한 번의 클릭으로 Google 소셜 로그인 모달을 띄워 가입/로그인을 완료할 수 있도록, 다른 UI(지도·바텀시트)와 겹치지 않는 **z-index 안전한 모달** 진입점을 제공한다. ## 2. 범위 (Scope) - **포함**: - "로그인" 버튼 (헤더용) - 클릭 시 ``에 Portal로 마운트되는 모달 (백드롭 + 카드) - Google 로그인 위젯(`@react-oauth/google`)의 콜백을 부모에 전달 - 백드롭 클릭 / "✕" 버튼으로 닫기 - 다크모드 색상 토큰 대응 - **제외 (out of scope)**: - 토큰 저장(`localStorage`), 백엔드 검증, 세션 갱신 — 부모(`onGoogleSuccess`)의 책임 - 카카오/네이버/이메일 로그인 등 추가 프로바이더 - 로그아웃 UI (별도 컴포넌트) - GoogleOAuthProvider 설정 (`_app`/`layout.tsx`에서 처리) ## 3. 인수조건 (이미 구현된 동작 기준) - [x] "로그인" 버튼이 헤더 스타일(보더+호버 brand 색)로 노출된다. - [x] 클릭 시 모달이 열리고, 화면 전체를 덮는 백드롭(`bg-black/40 backdrop-blur-sm`)이 깔린다. - [x] 모달은 `createPortal`로 `document.body`에 마운트되어 부모의 stacking context 영향을 받지 않는다. - [x] 모달 z-index는 `99999`로 다른 모든 오버레이(지도, 바텀시트)보다 위에 위치한다. - [x] 모달 안에 "소셜 계정으로 간편 로그인" 안내와 Google 로그인 버튼(`size=large, width=260`)이 표시된다. - [x] Google 로그인 성공 시 `credential`을 부모 `onGoogleSuccess(credential)`로 전달하고 모달을 닫는다. - [x] Google 로그인 실패 시 `console.error("Google login failed")` 로깅(UX는 위젯이 처리). - [x] 백드롭 영역(자식이 아닌 본인 클릭)에서만 모달이 닫힌다 (`e.target === e.currentTarget`). - [x] 우상단 "✕" 버튼으로 모달을 닫을 수 있다. - [x] 다크모드 토큰(`dark:text-gray-300`, `dark:border-gray-600`, `dark:hover:border-brand-500`)으로 색이 적응한다. ## 4. 컨텍스트 & 제약 - **프레임워크**: Next.js 16 App Router, Client Component (`"use client"`) - **라이브러리**: - `@react-oauth/google` — `` 위젯 사용, 상위 어딘가에 `` 마운트 필요 - `react-dom`의 `createPortal` - **스타일**: Tailwind, Saffron 디자인 토큰 — `bg-surface`, `text-brand-600`, `border-brand-400` - **z-index 제약**: 지도/바텀시트/Drawer 등 기존 오버레이가 다수 존재 → Portal + inline style `z-index: 99999` 사용 (Tailwind 클래스가 아닌 인라인으로 적용해 명시적 우선순위 보장) - **SSR 안전성**: `createPortal`이 `document.body`를 참조하므로 `"use client"` 필수. SSR 단계에서는 `open=false` 초기 상태로 모달 미렌더 → 안전. - **가정**: - 부모는 `onGoogleSuccess`에서 백엔드 `/api/auth/google` 호출 및 토큰 저장을 책임진다. - GoogleOAuthProvider clientId는 환경 변수(`NEXT_PUBLIC_GOOGLE_CLIENT_ID`)로 주입된다. ## 5. 아키텍처 개요 - 파일: - `LoginMenu.tsx` — 단일 컴포넌트 - 외부: - 부모: 헤더 (예: `Header.tsx`, `page.tsx`) — `onGoogleSuccess` 콜백 제공 - 상위: `` 마운트 (layout) ``` [Header] └─ │ │ state: open: boolean │ ├─ setOpen(true)}> │ └─ open && createPortal(

<안내 텍스트> { if (res.credential) { onGoogleSuccess(res.credential) setOpen(false) } }} onError={console.error}> , document.body ) 흐름: user → click 로그인 → open=true → Portal 모달 마운트 → Google 위젯 → OAuth popup/iframe → onSuccess(credential) → 부모 핸들러 (백엔드 검증/토큰 저장) → setOpen(false) → Portal 언마운트 ``` - **I/O ↔ 순수 로직 경계**: - I/O: Google OAuth (위젯 내부), `document.body` 접근, 부모 콜백 - 순수: `open` 상태기계(open/close), 백드롭 영역 판정 (`e.target === e.currentTarget`) ## 6. 데이터 모델 타입: ```ts interface LoginMenuProps { onGoogleSuccess: (credential: string) => void; } // @react-oauth/google interface CredentialResponse { credential?: string; // Google ID Token (JWT) select_by?: string; clientId?: string; } // 내부 상태 type LocalState = { open: boolean }; ``` - **경계 검증**: - `res.credential`이 falsy(undefined/empty)면 부모 콜백을 호출하지 않음 — 빈 토큰 전파 방지. - `credential`은 Google ID Token(JWT) 문자열. 검증은 백엔드(서명·aud·exp) 책임. - 모달 백드롭 클릭 판정: `e.target === e.currentTarget` — 자식(카드) 클릭은 닫지 않음. ## 7. 함수 명세 (Function Specs) | 함수 | 책임(1줄) | 시그니처(잠정) | 입력 | 출력 | 에러/실패 | 복잡? | |------|-----------|----------------|------|------|-----------|-------| | `LoginMenu` | 로그인 트리거 + 모달 렌더 | `({ onGoogleSuccess }) => JSX` | `LoginMenuProps` | JSX (button + portal) | onError → console.error | 단순 | | `setOpen(true)` (onClick) | 모달 오픈 | inline | MouseEvent | void | - | 단순 | | `closeIfBackdrop` | 백드롭 클릭 시 닫기 | inline `(e) => void` | MouseEvent | void | 자식 클릭이면 no-op | 단순 | | `setOpen(false)` (✕ onClick) | 모달 강제 닫기 | inline | MouseEvent | void | - | 단순 | | `GoogleLogin.onSuccess` | 토큰 추출 → 부모 콜백 → 닫기 | inline `(res) => void` | `CredentialResponse` | void | credential 없으면 무시 | 단순 | | `GoogleLogin.onError` | 실패 로깅 | inline `() => void` | - | void | console.error | 단순 | > 모든 함수가 단순. 외부 I/O(Google OAuth)는 위젯이 캡슐화하므로 추가 fn-*.md 불필요. ## 8. 흐름 / 알고리즘 **① 모달 오픈** 1. 사용자가 "로그인" 버튼 클릭 → `setOpen(true)` 2. 리렌더에서 `open === true` → `createPortal(...)` 실행 → `` 마지막 자식으로 모달 마운트 **② Google 로그인 성공** 1. `` 위젯 내부에서 Google OAuth 진행 2. 위젯이 `onSuccess({ credential })` 호출 3. `if (res.credential)` 가드 4. `onGoogleSuccess(credential)` — 부모가 백엔드 `/api/auth/google` 호출 등 처리 5. `setOpen(false)` → Portal 언마운트 **③ 모달 닫기 경로** - "✕" 버튼: `onClick={() => setOpen(false)}` - 백드롭 클릭: `onClick={(e) => { if (e.target === e.currentTarget) setOpen(false); }}` - 카드 내부 클릭: 이벤트가 백드롭까지 버블링되더라도 `e.target !== currentTarget`이므로 닫히지 않음 ✅ **④ 실패** - `onError`: 위젯이 호출 → `console.error("Google login failed")` 만 수행. 모달은 그대로 열려 있어 재시도 가능. ## 9. 엣지케이스 & 에러 처리 - **`res.credential` 없음**: 사용자가 OAuth 동의를 거부하거나 Google이 credential 없이 응답하는 경우 — 콜백/닫기 모두 skip하여 모달 유지. - **GoogleOAuthProvider 미설정**: 위젯이 렌더되지 않거나 콘솔 에러. 사용자에게는 빈 영역으로 보일 수 있음 → 상위 layout 설정 필수 (배포 체크리스트 항목). - **`document.body` 미존재 (SSR)**: `open` 초기값 `false` → 초기 렌더에서 `createPortal` 호출 안 함. 클라이언트 hydration 후에만 모달 가능. - **모달 열린 상태에서 라우트 이동**: 컴포넌트 언마운트 → Portal도 자동 제거. - **다중 모달 z-index 충돌**: 다른 모달들이 99999 이하라면 항상 위. 동일/상위 z-index 사용 모달이 있으면 디자인 가이드로 합의 필요. - **백드롭 위에서 텍스트 드래그**: `e.target === e.currentTarget` 판정으로 의도치 않은 닫힘 방지. - **백드롭 클릭으로 닫지 않게 하려면**: 향후 옵션화 필요 (현재는 항상 닫힘). - **ESC 키로 닫기**: 미구현 (개선 여지 — 미해결 질문 참조). - **Focus trap**: 미구현. 접근성 측면 약점. - **연속 클릭으로 다중 OAuth 팝업**: 위젯 자체 가드에 의존. LoginMenu 차원에서는 별도 디바운스 없음. ## 10. 테스트 계획 현재 자동화 테스트 없음 (TBD). 권장: - **단위 (Vitest + RTL)**: 1. 초기 렌더에서 모달 비노출 (`queryByText("소셜 계정으로 간편 로그인")` → null) 2. "로그인" 클릭 → 모달 노출 3. "✕" 클릭 → 모달 닫힘 4. 카드 내부 클릭 → 모달 유지 (백드롭 가드 검증) 5. 백드롭 클릭 → 모달 닫힘 6. `GoogleLogin.onSuccess` mock 호출 시 `onGoogleSuccess(credential)` 전달 + 모달 닫힘 7. `credential = undefined`인 응답 → 콜백 미호출 + 모달 유지 - **통합**: - `@react-oauth/google` 모듈 모킹 → 위젯 자리에 더미 버튼 렌더, 클릭 시 onSuccess 트리거 - Portal target(`document.body`) 검증 - **E2E (Playwright)**: - 실제 Google OAuth는 외부 의존이라 staging만 — 통상 모킹/스킵 - **드라이런 전략**: clientId를 테스트 환경 변수로 분리, `GoogleOAuthProvider`를 테스트 wrapper로 대체. ## 11. 리스크 & 대안 검토 - **Google 단일 프로바이더 의존**: 카카오/네이버 확장 시 다중 위젯 배치 필요 → 컴포넌트 분리(``)가 자연스러움. 현 단계는 단순성 우선. - **인라인 `z-index: 99999`**: 디자인 시스템 z-index 토큰 부재. 대안: `--z-modal: 99999` CSS 변수 + 클래스. 현재 인라인 사용은 의도된 안전장치. - **`@react-oauth/google` 의존**: 라이브러리 미유지 시 직접 Google Identity Services 스크립트 로드 필요. 폴백 계획은 미정. - **접근성**: focus trap, ESC 종료, ARIA(`role="dialog"`, `aria-modal`) 미적용 → 단기 개선 후보. - **다국어**: "로그인", "소셜 계정으로 간편 로그인" 하드코딩 한국어. i18n 도입 시 추출 필요. - **백드롭 닫기 비활성 옵션 부재**: 일부 화면(중단 위험 작업 중)에서 강제로 열어둘 수 없음. props로 옵션화 권장. - **부모 콜백의 비동기 실패 처리 누락**: `onGoogleSuccess`가 throw해도 `setOpen(false)`가 먼저 실행되어 사용자 피드백 사라짐. 대안: `await onGoogleSuccess()` 후 분기. ## 12. 미해결 질문 (Open Questions) - ESC 키 / focus trap / ARIA 속성을 도입할 일정·우선순위는? - 추가 OAuth 프로바이더(카카오/네이버/Apple) 도입 계획이 있는가? 있다면 위젯 통합 패턴은? - 로그인 후 어떤 화면으로 리다이렉트할지 (현재는 모달만 닫고 위치 유지) — 명시적 라우팅이 필요한 화면이 있는가? - 이미 로그인된 상태에서 ``가 헤더에 노출되는 경우는? (현재 상위에서 조건부 렌더 가정) - 모바일에서 모달 카드 위치/사이즈가 적절한가? (현재 `max-w-xs`) - 로그인 실패 사용자에게 인라인 에러 메시지를 보여줘야 하는가? (현재 console.error만) - Google ID Token을 부모로 직접 넘기는 대신, `LoginMenu` 안에서 백엔드 호출까지 묶는 것이 더 응집도가 높을까?