User
docs/domain/user.md
User
개요
사용자 계정, 인증, 프로필, 환경설정을 관리하는 도메인. MAKITT 플랫폼의 모든 사용자(Seller)가 이 도메인으로 관리됩니다.
서버 패키지: com.makitt.core.domain.user
DynamoDB Entity
User
Single Table Design 기반의 메인 사용자 엔티티.
키 구조:
| 키 | 패턴 | 예시 |
|---|---|---|
| PK | USER#{userId} | USER#abc123 |
| SK | PROFILE | PROFILE |
필드:
| 필드 | DynamoDB Attribute | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| pk | PK | String | O | Partition Key |
| sk | SK | String | O | Sort Key |
| entityType | entity_type | String | O | "USER" 고정 |
| userId | user_id | String | O | 사용자 고유 ID |
email | String | O | 로그인 이메일 | |
| status | status | UserStatus | O | 계정 상태 |
| signUpStatus | sign_up_status | SignUpStatus | O | 가입 진행 상태 |
| role | role | String | O | "SELLER" |
| profile | profile | UserProfile | X | 프로필 정보 (nested) |
| preferences | preferences | UserPreferences | X | 환경설정 (nested) |
| auth | auth | UserAuth | X | 인증 정보 (nested) |
| createdAt | created_at | Instant | O | 생성 시각 |
| updatedAt | updated_at | Instant | O | 수정 시각 |
| ttl | ttl | Long | X | TTL (휴면 계정용) |
Factory Methods:
User.createEmailUser(userId, email, passwordHash)— 이메일 기반 사용자 생성User.createOAuthUser(userId, email, provider, oauthId, oauthProvider)— OAuth 사용자 생성
Nested Objects
UserProfile
| 필드 | DynamoDB Attribute | 타입 | 설명 |
|---|---|---|---|
| firstName | first_name | String | 이름 |
| lastName | last_name | String | 성 |
| name | name | String | 전체 이름 (firstName + lastName) |
| phone | phone | String | 연락처 |
| imageUrl | image_url | String | 프로필 이미지 URL |
UserPreferences
| 필드 | DynamoDB Attribute | 타입 | 기본값 | 설명 |
|---|---|---|---|---|
| language | language | String | ko | 언어 코드 |
| timezone | timezone | String | Asia/Seoul | 시간대 |
| dateFormat | date_format | String | YYYY-MM-DD | 날짜 포맷 |
| numberFormat | number_format | String | comma_dot | 숫자 포맷 (1,000.00) |
| theme | theme | String | system | 테마 (system/light/dark) |
UserAuth
| 필드 | DynamoDB Attribute | 타입 | 설명 |
|---|---|---|---|
| provider | provider | AuthProvider | 인증 제공자 |
| oauthId | oauth_id | String | OAuth ID (OAuth 사용자만) |
| oauthProvider | oauth_provider | String | OAuth 제공자 이름 |
| emailVerified | email_verified | Boolean | 이메일 인증 여부 |
| passwordHash | password_hash | String | BCrypt 해시 (이메일 사용자만) |
Enums
AuthProvider
| 값 | 설명 |
|---|---|
EMAIL | 이메일 인증 |
GOOGLE | Google OAuth |
APPLE | Apple Sign In |
UserStatus
| 값 | 설명 |
|---|---|
DRAFT | 가입 진행 중 |
ACTIVE | 활성 상태 |
INACTIVE | 비활성 상태 |
SUSPENDED | 정책 위반으로 정지 |
SignUpStatus
| 값 | 설명 |
|---|---|
INIT | 초기 가입 완료 |
EMAIL_VERIFIED | 이메일 인증 완료 |
READY | 서비스 사용 가능 |
GSI (Global Secondary Index)
| GSI | PK 패턴 | SK 패턴 | 용도 |
|---|---|---|---|
| EntityLookupIndex | USER#{userId} | PROFILE | 엔티티 타입별 조회 |
| UniqueLookupIndex | {email} | USER#{userId} | 이메일로 사용자 조회 |
| SecondaryIdIndex | OAUTH#{provider}#{oauthId} | USER#{userId} | OAuth ID로 사용자 조회 |
OpenSearch Document
UserDocument
Index: users
Document ID: userId
| 필드 | JSON Field | 타입 | 설명 |
|---|---|---|---|
| userId | user_id | String | 사용자 ID |
email | String | 이메일 | |
| firstName | first_name | String | 이름 |
| lastName | last_name | String | 성 |
| name | name | String | 전체 이름 |
| phone | phone | String | 연락처 |
| profileImageUrl | profile_image_url | String | 프로필 이미지 |
| language | language | String | 언어 코드 |
| timezone | timezone | String | 시간대 |
| authProvider | auth_provider | String | 인증 제공자 (enum name) |
| oauthId | oauth_id | String | OAuth ID |
| oauthProvider | oauth_provider | String | OAuth 제공자 이름 |
| status | status | String | 계정 상태 (enum name) |
| signUpStatus | sign_up_status | String | 가입 상태 (enum name) |
| role | role | String | 역할 |
| emailVerified | email_verified | Boolean | 이메일 인증 여부 |
| createdAt | created_at | Long | 생성 시각 (epoch ms) |
| updatedAt | updated_at | Long | 수정 시각 (epoch ms) |
변환: UserDocument.fromEntity(User user) — DynamoDB Entity → OpenSearch Document
검색 기능:
searchByEmail(email)— 이메일 정확히 일치searchByName(name)— 이름 부분 일치
Key Builder
클래스: com.makitt.core.common.dynamodb.key.UserKey
// Primary Keys
UserKey.pk(userId) → "USER#{userId}"
UserKey.sk() → "PROFILE"
// GSI1: EntityLookupIndex
UserKey.gsi1Pk(userId) → "USER#{userId}"
UserKey.gsi1Sk() → "PROFILE"
// GSI2: UniqueLookupIndex (Email)
UserKey.gsi2Pk(email) → "{email}"
UserKey.gsi2Sk(userId) → "USER#{userId}"
// GSI3: SecondaryIdIndex (OAuth)
UserKey.gsi3Pk(provider, oauthId) → "OAUTH#{provider}#{oauthId}"
UserKey.gsi3Sk(userId) → "USER#{userId}"
// Helper
UserKey.extractUserId(pk) → userId (PK에서 추출)
관련 엔티티
| 엔티티 | PK | SK | 설명 |
|---|---|---|---|
| RefreshToken | - | - | JWT 리프레시 토큰 |
| EmailVerificationToken | - | - | 이메일 인증 토큰 |
| EmailLock | - | - | 이메일 중복 방지 잠금 |