본문으로 건너뛰기

게스트 계정 연동 가이드 (웹 프런트엔드)

본 문서는 SleepZ 웹 프런트엔드가 도메인 계층에 도입되는 게스트 계정 기능을 지원하기 위해 필요한 통합 방식을 정의한다. Auth/User/Group/Plan/IAM 도메인 구현 계획(docs/domains/common/core-domains/guest-account/implementation-plan.md)을 전제로 하며, identityLevel이 GUEST인 세션을 안전하게 처리하고 Step-up 인증으로 전환시키는 것을 목표로 한다.

1. 적용 범위 및 전제​

  • 대상 애플리케이션: apps/dha-sleep-web (Next.js 15 App Router)
  • 게스트 세션은 Auth 도메인이 발급하는 게스트 Access·Refresh 토큰을 사용하며, 기존 sleepz_access_token/sleepz_refresh_token 쿠키 키를 재활용한다.
  • 게스트 계정의 상태 값은 사용자 프로필(GET /users/{id}) 응답의 accountType, identityLevel, upgradedAt 필드로 확인한다. 게스트 모드는 만료 시나리오 없이 유지된다.

2. 주요 사용자 흐름​

2.0 초기 사용자 선택 및 약관 동의​

  1. apps/dha-sleep-web 최초 진입 시 사용자 유형 선택 화면을 노출한다.
  2. 기존 사용자 CTA 선택 시 즉시 Kakao 로그인 페이지(/auth/oauth/kakao)로 이동한다.
  3. 신규 사용자 CTA 선택 시 약관 동의 페이지로 전환되며, 필수 약관 동의 후 게스트 온보딩이 시작된다.
  4. 약관 동의 화면에서는 Universal 약관과 SleepZ 서비스 약관을 구분 표시하며, 뒤로 가기 아이콘을 통해 사용자 선택 화면으로 복귀할 수 있어야 한다.

2.1 게스트 온보딩​

  1. 약관 동의 페이지에서 "동의하고 계속"을 선택하면 POST /auth/guest/register 호출.
    • 프런트엔드는 /api/auth/guest/register 프록시를 통해 App Token(sleepz_app_token)을 헤더에 실어 백엔드와 통신한다.
    • User-Agent 헤더 필수: 브라우저가 자동으로 전송하는 User-Agent를 통해 region, platform, appVersion 등이 서버에서 자동 추출된다.
    • 요청 본문에는 agreements[] (약관 버전 ID와 동의 여부), deviceUuid (문자열), profile (language + timezone)이 포함된다.
    • ⚠️ 변경사항:
      • 기존 acceptedTerms, marketingConsent, deviceFingerprint, region 필드는 제거되었습니다. agreements 배열과 deviceUuid 문자열로 통일되었습니다.
      • profile 필드가 필수로 추가되었습니다. 정식 회원가입과 동일하게 language와 timezone 정보를 포함해야 합니다.
  2. 요청 헤더에는 App Token과 디바이스 식별자(쿠키 또는 X-Device-Id)를 포함한다.
  3. 성공 응답 시 Body에는 { success: true }만 포함된다. 토큰 발급은 별도의 게스트 로그인 API(POST /auth/guest/login)를 통해 수행한다.
  4. 게스트 로그인 후 GET /users/me를 호출하여 groupIds에 patients.guest.* 패턴이 포함되어 있음을 확인하고, 게스트 대시보드로 라우팅한다. (v1.2.0부터 IAM Group 기반 식별 권장)
  5. 대시보드 초기 렌더 시 GuestExperienceContext를 생성하여 identityLevel과 Step-up 관련 안내 문구를 공유한다.

2.2 Step-up 인증​

  1. 사용자가 이메일·카카오 등 자격 연동을 시도하면 POST /auth/guest/link/init 호출.
  2. Auth에서 반환한 링크 토큰/상태 값을 이용해 소셜 인증 또는 이메일 인증 UI를 표시한다.
  3. 인증이 성공하면 POST /auth/guest/link/complete 요청을 전송한다.
  4. 성공 시 기존 게스트 Refresh 토큰은 폐기되고 새로운 정규 세션이 내려온다. 응답의 nextAction이 "RELOAD_SESSION"일 경우, 프런트는 쿠키 갱신 완료 후 router.refresh() 또는 전면 리로드를 수행해야 한다.
  5. 이후 GET /users/me 재호출 시 groupIds에서 patients.guest.*가 제거되고 서비스 정책에 따른 대상 그룹이 포함되어야 하며, upgradedAt가 설정되어 있어야 한다. Step-up 전용 안내 배너는 groupIds 변화를 감지해 자동으로 숨긴다. (v1.2.0부터 IAM Group 기반 식별)

2.3 게스트 지속 사용​

  1. 게스트 사용자는 명시적 Step-up을 완료하기 전까지 동일한 게스트 세션으로 서비스를 이용할 수 있다.
  2. 프런트는 주요 기능(보고서 다운로드 등) 접근 시마다 groupIds에 patients.guest.*가 포함되어 있는지 확인해 제한 기능 가드를 노출하되, 세션을 강제 종료하지 않는다.
  3. 장기간 게스트 상태가 유지되는 경우 마케팅/UX 정책에 따라 비차단형 Step-up 안내 배너 또는 모달을 노출할 수 있으며, 닫은 후에도 정상 사용이 가능해야 한다.

3. API 정리​

기능HTTP엔드포인트인증/헤더응답 요약프런트 요구사항
게스트 등록POST/auth/guest/registerX-App-Token, X-Device-Id{ success: true }등록 후 게스트 로그인 API 호출
게스트 로그인POST/auth/guest/loginX-App-Token, X-Device-Idtokens, user, userCycle, profile, roles, permissions쿠키 저장 후 /guest 대시보드로 이동
Step-up 초기화POST/auth/guest/link/init게스트 Access JWTlinkSessionId, expiresAt, verificationUrl외부 인증 화면 또는 모달로 이동
Step-up 완료POST/auth/guest/link/complete게스트 Access JWT, linkSessionId정규 Access/Refresh 쿠키, identityLevel=REGISTERED쿠키 재적재, GET /users/me 재호출
Step-up 취소POST/auth/guest/link/cancel게스트 Access JWT, linkSessionId204 No ContentUI 상태 롤백, CTA 재활성화
게스트 세션 검증POST/auth/token/validateAccess JWTidentityLevel, expiresAtidentityLevel이 GUEST이면 게스트 UI 유지
  • 모든 요청은 credentials: "include" 설정으로 쿠키를 주고받아야 한다.
  • 게스트 온보딩 직후 /api/users/me 프록시를 호출해 groupIds에 patients.guest.* 패턴이 포함되어 있음을 확인하고, 해당 응답을 기반으로 게스트 배너와 제한 기능 가드를 초기화한다. (v1.2.0부터 IAM Group 기반 식별)
  • Step-up 완료 시 반환되는 정규 세션과 이전 세션 간 Race condition을 피하기 위해, guest/link/complete 호출 직후에는 API 병렬 호출을 잠시 중단한다.

4. UI 컴포넌트 가이드​

  • 사용자 유형 선택 화면: 신규 사용자/기존 사용자 CTA를 동일한 레이아웃에서 제공하며, 신규 선택 시 약관 페이지로, 기존 선택 시 Kakao 로그인으로 이동한다.
  • 게스트 헤더 배너: 현재 세션이 게스트임을 명시하고, Step-up CTA 버튼을 포함한다. identityLevel 확인 후 렌더링한다.
  • 제한 기능 가드: 보고서 다운로드, 플랜 커스터마이징, 커뮤니티 등 정규 사용자 기능은 groupIds에 patients.guest.*가 포함된 경우 게이트 UI를 노출하고 Step-up을 유도한다.
  • Step-up 리마인더 모달: 장기 게스트 사용자를 대상으로 비차단형 Step-up 안내 모달을 노출한다. 사용자가 닫은 뒤에도 게스트 기능 이용이 계속 가능해야 한다.
  • 오류 처리: AUTH_GUEST_LINK_CONFLICT, AUTH_GUEST_LINK_INVALID_STATE 등의 도메인 오류 코드를 사용자 친화적 메시지로 매핑한다.

5. 상태 관리 및 도메인 동기화​

  • 세션 쿠키 외 추가적인 게스트 플래그를 로컬 스토리지에 저장하지 않는다. 모든 상태는 GET /users/me 응답과 서버 액션을 통해 검증한다.
  • React Server Component에서 cookies().get()를 사용할 때 게스트 세션 여부를 식별하여 SSR에서 게스트 UI를 선반영한다.
  • Step-up 완료 후에는 React Query/RTK Query 캐시를 비우고, accountType이 반영된 최신 데이터를 다시 가져와야 한다.
  • 게스트 세션 전용 Analytics 이벤트(guest_onboarded, guest_step_up_click, guest_step_up_view)를 발행하여 도메인 지표와 일치하도록 Tagging 한다.

6. 테스트 체크리스트 (프런트 관점)​

  1. 게스트 온보딩 성공 후 게스트 대시보드가 즉시 렌더링되고 제한 기능 가드가 작동하는지 확인.
  2. Step-up 진행 중 취소/재시도 시 linkSessionId 상태가 적절히 정리되는지 확인.
  3. Step-up 완료 후 기존 게스트 쿠키가 제거되고 정규 사용자 기능이 활성화되는지 검증.
  4. 장기간 게스트 사용 시 비차단형 Step-up 리마인더가 노출되고, 닫은 뒤에도 기능 이용이 유지되는지 확인.
  5. 다중 탭 동시 사용 시 한 탭에서 Step-up 완료 후 다른 탭이 자동으로 리프레시되는지 확인(storage 이벤트 활용).

본 가이드는 게스트 계정 기능이 프로덕션에 배포되기 전까지 지속적으로 업데이트되며, 도메인 문서 변경사항이 있을 경우 동기화를 필수로 수행한다.