게스트 계정 아키텍처 설계 (v1.2.0)
1. 개요
이 문서는 게스트 계정의 전체 아키텍처를 정의합니다. 게스트 계정은 약관 동의만으로 가입하여 앱의 기본 기능을 체험할 수 있는 사용자 유형입니다.
1.1 핵심 설계 원칙
중요: 게스트 계정도 정식 사용자와 동일하게
User+UserCycle레코드를 생성합니다. 게스트와 정식 사용자의 구분은accountType필드가 아닌 IAM Group과 Plan으로 관리됩니다.
| 구분 | 기존 설계 (v1.1.x) | 신규 설계 (v1.2.0) |
|---|---|---|
| 게스트 등록 시 생성되는 데이터 | GuestAccountLifecycle만 생성 | User + UserCycle + GuestAccountLifecycle 모두 생성 |
| 게스트/정식 사용자 구분 | accountType 필드 | IAM Group (guests.* vs patients.*) |
| 기능 제어 | accountType 기반 조건문 | Plan (plan.guest vs plan.therapeutic) |
| Step-up 시 userId | 새 UUID 발급 (데이터 마이그레이션 필요) | 동일 UUID 유지 (데이터 자동 연결) |
1.2 설계 장점
- 데이터 일관성: 게스트 기간 동안 생성된 모든 데이터(수면 기록, 설문 등)가 Step-up 후에도 자연스럽게 연결됩니다.
- 단순한 코드: IAM Group과 Plan 기반 권한 체계를 사용하여 조건문 분기가 줄어듭니다.
- 유연한 확장: 새로운 게스트 유형이나 기능 제한을 Group/Plan 조합으로 쉽게 추가할 수 있습니다.
2. 도메인 역할 분담
2.1 Auth 도메인
- 게스트 등록 API (
POST /auth/guest/register) - Step-up 인증 API (
POST /auth/guest/link/*) - 토큰 발급 (
identityLevel=guest클레임 포함) - 인증 수단 연결 및 관리
2.2 User 도메인
User레코드 생성/관리UserCycle레코드 생성/관리GuestAccountLifecycle이벤트 기록- 게스트 만료 처리
2.3 Group 도메인
- 게스트 그룹 (
guests,guests.kr,guests.de등) 관리 - 정식 사용자 그룹 (
patients.general,patients.kr등) 관리 - Step-up 시 그룹 전환
2.4 Plan 도메인
- 게스트 플랜 (
plan.guest) 관리 - 치료 플랜 (
plan.therapeutic) 관리 - Step-up 시 플랜 전환
- 기능 제한/허용 정책
3. 그룹 및 플랜 체계
3.1 게스트 그룹 (Guest Groups)
| 그룹 ID | 설명 |
|---|---|
guests | 기본 게스트 그룹 (모든 게스트 사용자) |
guests.kr | 한국 지역 게스트 그룹 |
guests.de | 독일 지역 게스트 그룹 |
guests.us | 미국 지역 게스트 그룹 |
guests.jp | 일본 지역 게스트 그룹 |
3.2 게스트 플랜 (Guest Plan)
ID: plan.guest
기능 범위: 서비스 정책에 따라 제공/제한 기능이 정의됩니다.
특이사항:
- 서비스 설정에 따른 이용 기간
- TimeMachine/Cloud Scheduler로 자동 만료 관리
4. 사용자 여정 (User Journey)
4.1 게스트 등록
4.2 Step-up 인증 (정식 사용자 전환)
4.3 자발적 탈퇴
4.4 게스트 만료
5. 토큰 구조
5.1 게스트 Access Token
게스트 로그인 시 발급되는 Access Token의 JWT 클레임:
{
"sub": "550e8400-e29b-41d4-a716-446655440000",
"identityLevel": "guest",
"userCycleId": "d2f8e5c1-9b3a-4f8c-8e2f-1b9a3c5e2d7c",
"exp": 1692698400,
"iat": 1692697500,
"aud": ["dta-wide-api"]
}
참고: 게스트 관련 추가 정보(guestAccountId, 만료일 등)는 데이터베이스에 저장되며 토큰에는 포함되지 않습니다.
5.2 정식 사용자 Access Token (Step-up 후)
{
"sub": "550e8400-e29b-41d4-a716-446655440000",
"identityLevel": "registered",
"userCycleId": "d2f8e5c1-9b3a-4f8c-8e2f-1b9a3c5e2d7c",
"exp": 1692698400,
"iat": 1692697500,
"aud": ["dta-wide-api"]
}
참고:
sub필드(userId)가 동일합니다. Step-up 전후로 userId는 변경되지 않습니다. Group/Plan 정보는 별도 조회를 통해 확인됩니다.
6. 이벤트 체계
6.1 GuestAccountLifecycle 이벤트 타입
| 이벤트 타입 | 설명 | 발생 시점 |
|---|---|---|
ONBOARDED | 게스트 등록 완료 | 게스트 등록 API 호출 시 |
UPGRADE_INITIATED | Step-up 인증 시작 | /auth/guest/link/init 호출 시 |
UPGRADED | 정식 사용자로 업그레이드 | /auth/guest/link/complete 성공 시 |
EXPIRY_SCHEDULED | 만료 타이머 예약 | 게스트 등록 완료 시 |
EXPIRY_CANCELLED | 만료 타이머 취소 | 업그레이드 또는 자발적 탈퇴 시 |
EXPIRED | 게스트 계정 만료 | 설정된 기간 경과 시 |
CLEANED | 만료 후 정리 완료 | 만료 후 정리 작업 완료 시 |
VOLUNTARILY_WITHDRAWN | 자발적 탈퇴 | DELETE /users/me 호출 시 |
6.2 크로스 도메인 이벤트
| 이벤트 | 발행자 | 수신자 | 목적 |
|---|---|---|---|
auth.guest.registered | Auth | User, IAM | 게스트 등록 알림 |
user.identity-level-upgrade.requested | Auth | User | Group/Plan 전환 요청 |
user.identity-level-upgrade.confirmed | User | Auth, IAM | 전환 완료 알림 |
auth.identity-level.changed | Auth | IAM | 캐시 동기화 |
7. 데이터 모델
7.1 게스트 등록 시 생성되는 데이터
┌──────────────────────────────────────────────────────────────┐
│ User 레코드 │
│ - id: "550e8400-..." (UUID) │
│ - status: ACTIVE │
│ - groupIds: ["guests.kr"] (IAM Group으로 게스트 식별) │
│ - guestExpiresAt: "2025-01-17T..." (서비스 설정에 따른 만료일)│
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ UserCycle 레코드 │
│ - id: "cycle-..." │
│ - userId: "550e8400-..." │
│ - planId: "plan.guest" │
│ - status: ACTIVE │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ GuestAccountLifecycle 레코드 │
│ - guestAccountId: "guest-4f52c7fa" │
│ - userId: "550e8400-..." │
│ - eventType: ONBOARDED │
│ - occurredAt: "2024-12-17T00:00:00Z" │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ IAM Group 할당 │
│ - userId: "550e8400-..." │
│ - groupId: "guests.kr" │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ IAM Plan 할당 │
│ - userId: "550e8400-..." │
│ - planId: "plan.guest" │
└──────────────────────────────────────────────────────────────┘
7.2 Step-up 후 변경되는 데이터
┌──────────────────────────────────────────────────────────────┐
│ User 레코드 (변경) │
│ - id: "550e8400-..." (동일!) │
│ - groupIds: ["patients.kr", ...] (IAM Group 변경) │
│ - upgradedAt: "2024-12-20T00:00:00Z" │
│ - guestExpiresAt: null (제거) │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ UserCycle 레코드 (변경) │
│ - planId: (서비스 정책에 따른 대상 플랜) │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ GuestAccountLifecycle 레코드 (추가) │
│ - eventType: UPGRADED │
│ - metadata: { previousPlan: "plan.guest", ... } │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ IAM Group 할당 (변경) │
│ - groupId: (서비스 정책에 따른 대상 그룹) │
│ (guests.* 그룹 제거됨) │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ IAM Plan 할당 (변경) │
│ - planId: (서비스 정책에 따른 대상 플랜) │
└──────────────────────────────────────────────────────────────┘
8. 관련 문서
- Group 도메인 - 게스트 그룹 정의
- Plan 도메인 - 게스트 플랜 정의
- Auth 도메인 - 게스트 Step-up 인증
- User 도메인 - GuestAccountLifecycle 모델
9. 변경 이력
| 버전 | 날짜 | 작성자 | 변경 내용 |
|---|---|---|---|
| 1.0.0 | 2025-12-17 | bok@weltcorp.com | 최초 문서 생성: 게스트 아키텍처 통합 설계 문서화 |