[Feat/#110] 스플래시·로그인·온보딩 화면 구현

[jjunh33]

#️⃣연관된 이슈

• Closes 스플래시·로그인·온보딩 화면 구현 #110

🎯 해결하려는 문제가 무엇인가요?

앱을 처음 열었을 때의 진입 흐름(스플래시, 로그인, 온보딩)이 없어서, 모든 화면이 로그인 없이 바로 열립니다. Figma의 스플래시 & 로그인(3658:112096)과 온보딩(3738:73115) 화면을 화면설계서(스플래시/로그인 3747:74283, 온보딩 3747:74298, 화면 ID FLW_HOM_001)에 맞춰 구현합니다.

❓ 왜 해결해야 하나요?

신규 사용자는 K-CONNECT 인증 후 연락처와 약관 동의를 받아야 서비스를 쓸 수 있습니다. 이 입구가 없으면 행사 신청 같은 기능에 필요한 연락처를 받을 방법이 없고, 앱을 처음 여는 사용자가 어디로 시작해야 하는지도 정해지지 않습니다.

⭐ 어떻게 해결했나요?

화면 (모두 Bottom Nav 없이 흰 배경)

경로	화면
/auth/splash	스플래시. 심볼이 0.45초 동안 페이드인하고, 0.5초 뒤 슬로건과 워드마크가 페이드인하며, 총 1.2초 뒤 이동합니다
/auth/login	로그인 소개 캐러셀 3장(자동 전환 없음, 스와이프·닷으로 이동) + K-CONNECT로 시작하기
/auth/onboarding/phone	1/2 연락처. 인삿말에 이름, 숫자 키패드, 자동 하이픈, 11자리일 때만 다음 활성화
/auth/onboarding/terms	2/2 약관 동의. 전체 동의와 개별 항목 연동, 필수 2개 동의 시 다음 활성화(선택 약관은 미동의여도 진행)
/auth/onboarding/terms/:termsId	약관 상세 3종. 확인했어요·뒤로가기로 복귀하고 동의 상태는 바뀌지 않음
/auth/onboarding/complete	가입 완료. 체크 로띠, stream 시작하기·닫기는 홈으로 이동

흐름

• 앱 첫 진입점 /에 AuthEntryGate를 두었습니다. 로그인 표시가 없으면 /auth/splash로 보내고(replace), 스플래시가 1.2초 뒤 로그인으로 넘깁니다. 있으면 홈을 그대로 보여 줍니다. 다른 화면 경로(/events 등)에는 가드를 걸지 않았습니다.
• 로그인(목): 신규 사용자는 온보딩으로, 기존 사용자는 홈으로 갑니다. 실패하면 "로그인에 실패했어요. 다시 시도해 주세요." 토스트가 뜹니다.
• "로그인 표시"는 sessionStorage에 stream:auth:logged-in = "1"만 저장합니다(이름 등 로그인 정보는 저장하지 않음). 같은 탭에서는 새로고침해도 홈이 유지되고, 탭·브라우저를 새로 열면 스플래시 → 로그인부터 시작합니다.
• 온보딩 단계 간 이름·연락처는 navigate state로 넘기고, 약관 동의 상태는 모듈 저장소(useSyncExternalStore)에 둡니다. 약관 상세가 별도 라우트라 돌아오면 목록이 다시 마운트되기 때문입니다.
• 데이터는 entities/auth(authApi, session)에 두었습니다.

QA용 쿼리 (목 전용): /auth/login?mockLogin=fail은 실패 토스트, ?mockLogin=existing은 기존 사용자(바로 홈), 쿼리 없이 누르면 신규 사용자(온보딩)입니다.

커밋 구성: 문서 → 목 로그인 API·로그인 표시 → 스플래시·로그인 화면 → 온보딩 화면 → 라우트와 첫 진입 가드

2026-10-09.4.12.59.mov

🧩 이 PR의 한계 & 트레이드오프

• K-CONNECT 인증은 목입니다. 인증 사이트 이동, 신규 사용자 판별, 세션 유지, 실패 처리의 API와 스펙이 없어서 loginWithKConnect()가 지연 후 결과만 돌려줍니다. 실 API가 붙으면 entities/auth만 교체합니다. 인증 취소·네트워크 오류도 지금은 실패 토스트 하나로 처리합니다.
• 로그인 유지는 탭 단위입니다. 로그인 정보를 저장하지 않으려고 sessionStorage에 표시만 남겼습니다. 실제 인증이 붙으면 서버 세션(쿠키·토큰)으로 바뀌어야 하고, 설계서의 "유효한 세션이 있으면 로그인 화면을 건너뛴다"는 그때 서버 기준으로 다시 맞춰야 합니다.
• 기존 사용자도 스플래시 없이 홈이 열립니다. 설계서는 스플래시를 먼저 보여 준 뒤 로그인만 건너뛰는 흐름인데, 지금은 세션이 있으면 /에서 홈이 바로 열립니다(개발 중 매번 1.2초를 기다리지 않도록).
• 약관 본문은 Figma 문구를 정적 상수로 넣었습니다. 실제 약관 게시 방식(서버·정적 문서)이 정해지면 교체해야 합니다.
• 용어: 로그인·온보딩이 용어 사전에 따로 없어서 공통 auth 아래에서 처리했습니다. 백엔드 엔드포인트 네이밍과 맞는지 확인이 필요합니다.
• 이미지 용량: 로그인 일러스트 3장이 960x720 PNG라 장당 약 500KB, 합쳐서 약 1.5MB입니다. 투명 배경이 필요해서 PNG로 두었고, WebP 변환 도구는 도입하지 않았습니다.
• 고정 px 일부 유지: 하단 안전 영역 여백 sm:h-[14px](4곳)은 행사 신청·사물함 등 저장소 전체가 같은 표기라 그대로 두었습니다.

⛓️ 기존 기능에 미치는 영향

• /(홈) 진입이 바뀝니다. 이 PR이 머지되면 브라우저에 로그인 표시가 없을 때 /가 스플래시 → 로그인으로 갑니다. 개발·QA에서 홈을 바로 보려면 한 번 로그인해야 합니다(/auth/login?mockLogin=existing이 가장 빠름).
• 다른 경로(/events, /notices 등)는 그대로 열립니다.
• 딥링크로 들어온 화면의 뒤로가기 폴백이 /로 가는 경우, 세션이 없으면 스플래시 → 로그인으로 한 번 더 넘어갑니다.
• index.css에 토큰 1개(--color-k-connect)와 스플래시 페이드인 애니메이션을 추가했고, 기존 화면 스타일은 바뀌지 않습니다.
• 공용 ResultScreen과 CompleteCheck는 수정 없이 재사용했습니다.

🔀 Edge Case & 실패 시나리오

• 로그인 실패(?mockLogin=fail)는 토스트가 뜨고 로그인 화면이 유지되며, 버튼은 다시 눌러집니다.
• 로그인 요청 중에는 버튼이 비활성화되어(aria-busy) 중복 요청을 막습니다.
• 연락처에 숫자 아닌 문자나 11자리를 넘는 입력을 넣어도 숫자 11자리까지만 남고 하이픈이 붙습니다.
• 온보딩 연락처·약관 화면에 로그인을 거치지 않고(딥링크·새로고침) 들어오면 처음 상태가 없어서 /auth/login으로 돌려보냅니다.
• 약관 상세에 잘못된 termsId로 들어오면 약관 동의 화면으로 보냅니다.
• 모션 줄이기를 켠 사용자는 스플래시 페이드인이 없고, 로그인 닷 이동도 즉시 이동합니다.
• sessionStorage 접근이 막힌 환경에서는 로그인 표시를 저장하지 못해 새로고침마다 로그인부터 시작합니다(경고만 남김).

📋 검토한 대안과 선택 이유

• WDS PaginationDots 사용: Figma 닷은 지름 6px이고 중심 간격이 12px인데, WDS는 small이 8px, 간격 16px이고 크기를 CSS 변수로만 바꿀 수 있어서 로컬 AuthPaginationDots로 만들었습니다.
• K-CONNECT 버튼에 WDS ActionAreaButton 사용: 브랜드색 #004F9F와 높이 57px이 WDS 버튼 스케일에 없어서 로컬 버튼으로 만들었습니다.
• 약관 체크박스 크기: 행사 신청 폼의 small(20px)이 아니라 Figma Control이 24px이라 medium을 썼습니다.
• 모든 화면 로그인 가드: 개발·QA 방식이 바뀌는 부담이 커서 / 하나에만 걸었습니다.
• 로그인 정보를 localStorage에 유지: 로그인 정보를 저장하지 않는 쪽으로 요청받아 sessionStorage의 표시 하나로 줄였습니다.
• 약관 동의 상태를 컨텍스트나 라우트 state로 관리: 새 라우트 구조가 필요하거나 변경 때마다 history를 갱신해야 해서, 모듈 단위 저장소를 택했습니다.

💬 리뷰 포인트

• [r] 앱 WebView와 웹 브라우저의 위치 처리가 다릅니다. 스플래시 심볼과 로그인 본문은 Figma 프레임에서 상태 표시줄(54px)을 뺀 앱 WebView 영역 기준 값입니다. 브라우저는 창 전체가 웹 영역이라 같은 값이면 위로 치우쳐 보여서, isInAppShell()(앱 연동에 이미 쓰는 window.ReactNativeWebView 판별)일 때와 아닐 때를 나눴습니다.
  • 스플래시 심볼: 앱은 세로 42%(Figma), 웹은 50%
  • 로그인 본문: 앱은 위에서 72px에 시작하고 버튼을 바닥에 붙임, 웹은 버튼 위 영역의 세로 가운데
  • 폰 브라우저도 앱이 아니므로 웹 기준(가운데)으로 보입니다. 앱 WebView에서 ReactNativeWebView가 주입되는지는 실기기에서 확인해 주세요. 로컬에서는 이 객체를 임시로 주입해 앱 위치(심볼 358px, 본문 72px)가 Figma와 같음을 확인했습니다.
• [r] 용어 auth 아래에서 로그인·온보딩을 처리하는 것이 백엔드 엔드포인트 네이밍과 맞는지 확인해 주세요.
• [c] /에서 세션이 없을 때 스플래시로 보내는 진입 가드와, 기존 사용자는 스플래시 없이 홈이 열리는 동작이 의도에 맞는지 봐주세요.
• [c] 약관 동의 상태 저장소(useOnboardingAgreements)와 navigate state로 온보딩 값을 넘기는 방식이 컨벤션에 없는 새 패턴입니다. 괜찮은지 의견 부탁드립니다.
• [c] [Feat/#96] 설정 화면과 알림 설정·전화번호 변경·회원 탈퇴 화면 구현 #97(설정·전화번호 변경·회원 탈퇴)과 전화번호 입력·포맷(formatPhoneNumber)이 겹칠 수 있습니다. 머지 순서에 따라 한쪽에서 공통화가 필요합니다.
• [a] 이 환경에서는 Pretendard가 로드되지 않아 대체 폰트 기준으로 줄바꿈을 확인했습니다. 실기기에서 로그인 문구와 약관 본문 줄바꿈이 Figma와 같은지 봐주세요.
• [a] Figma 대조는 측정 기준으로 했고, 🟢 수준의 차이가 남아 있습니다. 연락처 입력칸에 Figma의 약한 그림자가 없는 것(WDS TextField 기본값), 로그인 배경 빛의 가로 위치가 4.5px 다를 수 있는 것입니다.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 4d06225a-455e-4aa6-8d45-5ac3ed591325

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[tnals0924]

온보딩은 퍼널 구조를 적용하면 좋을 거 같고, 로그인 기능같은 경우에는 제가 개발해둔 k-connect 로그인을 위한 private npm 패키지를 사용하도록 수정하는 건 어떨까요?!

월요일이나 화요일 중 관련해서 자세한 설명드리도록 하겠습니다.

퍼널 구조 참고용 발표 영상
https://www.youtube.com/watch?v=NwLWX2RNVcw&t=289s