mirror of
https://github.com/ktds-dg0501/kt-event-marketing.git
synced 2025-12-06 20:06:23 +00:00
387 lines
13 KiB
Markdown
387 lines
13 KiB
Markdown
# User Service 내부 시퀀스 설계서
|
|
|
|
## 문서 정보
|
|
- **작성일**: 2025-10-22
|
|
- **작성자**: System Architect
|
|
- **버전**: 1.0
|
|
- **관련 문서**:
|
|
- [유저스토리](../../../userstory.md)
|
|
- [외부 시퀀스](../outer/사용자인증플로우.puml)
|
|
- [논리 아키텍처](../../logical/logical-architecture.md)
|
|
|
|
---
|
|
|
|
## 개요
|
|
|
|
User Service의 4가지 주요 시나리오에 대한 내부 처리 흐름을 상세히 정의합니다.
|
|
|
|
### 시나리오 목록
|
|
|
|
| 번호 | 파일명 | 유저스토리 | 주요 처리 내용 |
|
|
|------|--------|-----------|---------------|
|
|
| 1 | user-회원가입.puml | UFR-USER-010 | 기본 정보 검증, 사업자번호 검증(국세청 API), 트랜잭션 처리, JWT 발급 |
|
|
| 2 | user-로그인.puml | UFR-USER-020 | 비밀번호 검증(bcrypt), JWT 발급, 세션 저장, 최종 로그인 시각 업데이트 |
|
|
| 3 | user-프로필수정.puml | UFR-USER-030 | 기본 정보 수정, 매장 정보 수정, 비밀번호 변경, 트랜잭션 처리 |
|
|
| 4 | user-로그아웃.puml | UFR-USER-040 | JWT 검증, 세션 삭제, Blacklist 추가 |
|
|
|
|
---
|
|
|
|
## 아키텍처 구조
|
|
|
|
### Layered Architecture
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ API Layer (Controller) │ - HTTP 요청/응답 처리
|
|
│ │ - DTO 변환 및 검증
|
|
└─────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────┐
|
|
│ Business Layer (Service) │ - 비즈니스 로직 처리
|
|
│ - UserService │ - 트랜잭션 관리
|
|
│ - AuthenticationService │ - 외부 API 연동
|
|
│ - BusinessValidator │
|
|
└─────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────┐
|
|
│ Data Layer (Repository) │ - 데이터베이스 접근
|
|
│ - UserRepository │ - JPA/MyBatis
|
|
│ - StoreRepository │
|
|
└─────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────┐
|
|
│ External Systems │ - 국세청 API
|
|
│ │ - Redis Cache
|
|
│ │ - PostgreSQL DB
|
|
└─────────────────────────────────────┘
|
|
```
|
|
|
|
### 주요 컴포넌트
|
|
|
|
#### API Layer
|
|
- **UserController**: 사용자 관련 REST API 엔드포인트
|
|
- `POST /api/users/register`: 회원가입
|
|
- `POST /api/users/login`: 로그인
|
|
- `PUT /api/users/profile`: 프로필 수정
|
|
- `POST /api/users/logout`: 로그아웃
|
|
|
|
#### Business Layer
|
|
- **UserService**: 사용자 정보 관리 비즈니스 로직
|
|
- **AuthenticationService**: 인증 및 세션 관리 로직
|
|
- **BusinessValidator**: 사업자번호 검증 로직 (Circuit Breaker 적용)
|
|
|
|
#### Data Layer
|
|
- **UserRepository**: users 테이블 CRUD
|
|
- **StoreRepository**: stores 테이블 CRUD
|
|
|
|
#### Utility
|
|
- **PasswordEncoder**: bcrypt 해싱 (Cost Factor 10)
|
|
- **JwtTokenProvider**: JWT 토큰 생성/검증 (만료 7일)
|
|
|
|
---
|
|
|
|
## 시나리오별 상세 설명
|
|
|
|
### 1. 회원가입 (user-회원가입.puml)
|
|
|
|
#### 처리 단계
|
|
1. **입력 검증**: `@Valid` 어노테이션으로 DTO 검증
|
|
2. **중복 사용자 확인**: 전화번호 기반 중복 체크
|
|
3. **사업자번호 검증**:
|
|
- Redis 캐시 확인 (TTL 7일)
|
|
- 캐시 MISS: 국세청 API 호출 (Circuit Breaker 적용)
|
|
- 캐시 HIT: 0.1초, MISS: 5초
|
|
4. **비밀번호 해싱**: bcrypt (Cost Factor 10)
|
|
5. **사업자번호 암호화**: AES-256
|
|
6. **데이터베이스 트랜잭션**:
|
|
- User INSERT
|
|
- Store INSERT
|
|
- COMMIT (실패 시 자동 Rollback)
|
|
7. **JWT 토큰 생성**: Claims(userId, role=OWNER, exp=7일)
|
|
8. **세션 저장**: Redis (TTL 7일)
|
|
|
|
#### Resilience 패턴
|
|
- **Circuit Breaker**: 국세청 API (실패율 50% 초과 시 Open)
|
|
- **Retry**: 최대 3회 (지수 백오프: 1초, 2초, 4초)
|
|
- **Timeout**: 5초
|
|
- **Fallback**: 사업자번호 검증 스킵 (수동 확인 안내)
|
|
|
|
#### 응답 시간
|
|
- 캐시 HIT: 1초 이내
|
|
- 캐시 MISS: 5초 이내
|
|
|
|
---
|
|
|
|
### 2. 로그인 (user-로그인.puml)
|
|
|
|
#### 처리 단계
|
|
1. **입력 검증**: 필수 필드 확인
|
|
2. **사용자 조회**: 전화번호로 사용자 검색
|
|
3. **비밀번호 검증**: bcrypt compare
|
|
4. **JWT 토큰 생성**: Claims(userId, role=OWNER, exp=7일)
|
|
5. **세션 저장**: Redis (TTL 7일)
|
|
6. **최종 로그인 시각 업데이트**: 비동기 처리 (`@Async`)
|
|
|
|
#### 보안 처리
|
|
- 에러 메시지: 전화번호/비밀번호 구분 없이 동일 메시지 반환
|
|
- 비밀번호: bcrypt compare (원본 노출 안 됨)
|
|
|
|
#### 성능 최적화
|
|
- 최종 로그인 시각 업데이트: 비동기 처리로 응답 시간 단축
|
|
- 응답 시간: 0.5초 목표
|
|
|
|
---
|
|
|
|
### 3. 프로필 수정 (user-프로필수정.puml)
|
|
|
|
#### 처리 단계
|
|
1. **JWT 인증**: `@AuthenticationPrincipal`로 userId 추출
|
|
2. **사용자 조회**: userId로 기존 정보 조회
|
|
3. **비밀번호 변경 처리** (선택적):
|
|
- 현재 비밀번호 검증 (bcrypt compare)
|
|
- 새 비밀번호 해싱 (bcrypt)
|
|
4. **기본 정보 업데이트**: 이름, 전화번호, 이메일
|
|
5. **매장 정보 업데이트**: 매장명, 업종, 주소, 영업시간
|
|
6. **데이터베이스 트랜잭션**:
|
|
- User UPDATE
|
|
- Store UPDATE
|
|
- COMMIT (실패 시 자동 Rollback)
|
|
7. **캐시 무효화**: 프로필 캐시 삭제 (선택적)
|
|
|
|
#### 보안 처리
|
|
- 비밀번호 변경: 현재 비밀번호 확인 필수
|
|
- 권한 검증: 본인만 수정 가능
|
|
|
|
#### 향후 개선사항
|
|
- 전화번호 변경: SMS/이메일 재인증 구현
|
|
- 이메일 변경: 이메일 인증 구현
|
|
|
|
---
|
|
|
|
### 4. 로그아웃 (user-로그아웃.puml)
|
|
|
|
#### 처리 단계
|
|
1. **JWT 인증**: `@AuthenticationPrincipal`로 userId 추출
|
|
2. **JWT 토큰 검증**: 서명 및 만료 시간 확인
|
|
3. **Redis 세션 삭제**: `DEL user:session:{token}`
|
|
4. **JWT Blacklist 추가** (선택적):
|
|
- 만료되지 않은 토큰 강제 무효화
|
|
- Redis에 Blacklist 추가 (TTL: 남은 만료 시간)
|
|
5. **로그아웃 로그 기록**: userId, timestamp
|
|
|
|
#### 보안 처리
|
|
- JWT Blacklist: 만료 전 토큰 강제 무효화
|
|
- 멱등성 보장: 중복 로그아웃 요청에 안전
|
|
|
|
#### 클라이언트 측 처리
|
|
- LocalStorage 또는 Cookie에서 JWT 토큰 삭제
|
|
- 로그인 화면으로 리다이렉트
|
|
|
|
#### 성능 최적화
|
|
- Redis 삭제 연산: O(1) 시간 복잡도
|
|
- 응답 시간: 0.1초 이내
|
|
|
|
---
|
|
|
|
## 데이터 모델
|
|
|
|
### User Entity
|
|
```java
|
|
@Entity
|
|
@Table(name = "users")
|
|
public class User {
|
|
@Id
|
|
@GeneratedValue(strategy = GenerationType.IDENTITY)
|
|
private Long userId;
|
|
|
|
@Column(nullable = false, length = 100)
|
|
private String name;
|
|
|
|
@Column(nullable = false, unique = true, length = 20)
|
|
private String phoneNumber;
|
|
|
|
@Column(nullable = false, unique = true, length = 255)
|
|
private String email;
|
|
|
|
@Column(nullable = false, length = 60)
|
|
private String passwordHash; // bcrypt hash
|
|
|
|
@Enumerated(EnumType.STRING)
|
|
@Column(nullable = false, length = 20)
|
|
private UserRole role; // OWNER, CUSTOMER
|
|
|
|
@Column(name = "last_login_at")
|
|
private LocalDateTime lastLoginAt;
|
|
|
|
@Column(name = "created_at", nullable = false)
|
|
private LocalDateTime createdAt;
|
|
|
|
@Column(name = "updated_at")
|
|
private LocalDateTime updatedAt;
|
|
}
|
|
```
|
|
|
|
### Store Entity
|
|
```java
|
|
@Entity
|
|
@Table(name = "stores")
|
|
public class Store {
|
|
@Id
|
|
@GeneratedValue(strategy = GenerationType.IDENTITY)
|
|
private Long storeId;
|
|
|
|
@Column(name = "user_id", nullable = false)
|
|
private Long userId;
|
|
|
|
@Column(nullable = false, length = 200)
|
|
private String storeName;
|
|
|
|
@Column(length = 100)
|
|
private String industry;
|
|
|
|
@Column(columnDefinition = "TEXT")
|
|
private String address;
|
|
|
|
@Column(name = "business_number_encrypted", length = 255)
|
|
private String businessNumberEncrypted; // AES-256 encrypted
|
|
|
|
@Column(name = "business_hours", length = 500)
|
|
private String businessHours;
|
|
|
|
@Column(name = "created_at", nullable = false)
|
|
private LocalDateTime createdAt;
|
|
|
|
@Column(name = "updated_at")
|
|
private LocalDateTime updatedAt;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 캐싱 전략
|
|
|
|
### Redis 캐시 키 구조
|
|
|
|
| 캐시 키 패턴 | 데이터 타입 | TTL | 용도 |
|
|
|------------|-----------|-----|------|
|
|
| `user:session:{token}` | String (JSON) | 7일 | JWT 세션 정보 (userId, role) |
|
|
| `user:business:{사업자번호}` | String (JSON) | 7일 | 사업자번호 검증 결과 (valid, status) |
|
|
| `jwt:blacklist:{token}` | String | 남은 만료 시간 | 로그아웃된 JWT 토큰 Blacklist |
|
|
| `user:profile:{userId}` | String (JSON) | 1시간 | 사용자 프로필 정보 (선택적) |
|
|
|
|
### Cache-Aside 패턴
|
|
1. Application → Redis 확인 (Cache HIT/MISS)
|
|
2. Cache MISS → Database/External API 조회
|
|
3. Database/External API → Redis 캐싱 (TTL 설정)
|
|
4. Redis → Application 반환
|
|
|
|
---
|
|
|
|
## 에러 처리
|
|
|
|
### 주요 예외 클래스
|
|
|
|
| 예외 클래스 | HTTP 상태 | 발생 시점 |
|
|
|-----------|---------|----------|
|
|
| `DuplicateUserException` | 400 | 이미 가입된 전화번호 |
|
|
| `BusinessNumberInvalidException` | 400 | 사업자번호 검증 실패 |
|
|
| `AuthenticationFailedException` | 401 | 로그인 실패 (전화번호/비밀번호 불일치) |
|
|
| `InvalidTokenException` | 401 | JWT 토큰 무효 |
|
|
| `UserNotFoundException` | 404 | 사용자 없음 |
|
|
| `InvalidPasswordException` | 400 | 현재 비밀번호 불일치 (프로필 수정) |
|
|
|
|
### 에러 응답 형식
|
|
```json
|
|
{
|
|
"error": "에러 메시지",
|
|
"code": "ERROR_CODE",
|
|
"timestamp": "2025-10-22T10:30:00Z"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 보안 고려사항
|
|
|
|
### 1. 비밀번호 보안
|
|
- **해싱 알고리즘**: bcrypt (Cost Factor 10)
|
|
- **원본 노출 방지**: 비밀번호는 해시로만 저장, 평문 로깅 금지
|
|
- **에러 메시지**: 전화번호/비밀번호 구분 없이 동일 메시지 반환 (보안 강화)
|
|
|
|
### 2. JWT 보안
|
|
- **만료 시간**: 7일 (Refresh Token 별도 구현 가능)
|
|
- **서명 알고리즘**: HS256 또는 RS256
|
|
- **Blacklist 관리**: 로그아웃 시 Redis Blacklist에 추가
|
|
|
|
### 3. 민감 정보 암호화
|
|
- **사업자번호**: AES-256 암호화 저장
|
|
- **전송 보안**: HTTPS 강제 적용
|
|
|
|
### 4. 세션 관리
|
|
- **세션 저장**: Redis (서버 재시작에도 유지)
|
|
- **세션 만료**: 7일 후 자동 삭제 (TTL)
|
|
- **동시 세션**: 동일 사용자 다중 세션 허용 (필요 시 제한 가능)
|
|
|
|
---
|
|
|
|
## 성능 최적화
|
|
|
|
### 1. 캐싱 효과
|
|
- **사업자번호 검증**: 5초 → 0.1초 (98% 개선)
|
|
- **세션 조회**: Redis 사용으로 DB 부하 감소
|
|
|
|
### 2. 비동기 처리
|
|
- **최종 로그인 시각 업데이트**: `@Async`로 비동기 처리
|
|
- **응답 시간 개선**: 0.5초 목표 달성
|
|
|
|
### 3. 데이터베이스 최적화
|
|
- **인덱스**: `phone_number`, `email` 컬럼에 Unique Index
|
|
- **Connection Pool**: HikariCP 사용 (최소 10개, 최대 50개)
|
|
|
|
---
|
|
|
|
## 테스트 전략
|
|
|
|
### Unit Test
|
|
- UserService, AuthenticationService 단위 테스트
|
|
- Mock 객체: UserRepository, Redis, 국세청 API
|
|
|
|
### Integration Test
|
|
- Controller → Service → Repository 통합 테스트
|
|
- 실제 Redis 및 PostgreSQL 사용 (Testcontainers)
|
|
|
|
### E2E Test
|
|
- Postman 또는 REST Assured로 전체 플로우 테스트
|
|
- 회원가입 → 로그인 → 프로필 수정 → 로그아웃
|
|
|
|
---
|
|
|
|
## 향후 개선사항
|
|
|
|
### Phase 2
|
|
1. **Refresh Token 구현**: Access Token 만료 시 갱신 메커니즘
|
|
2. **소셜 로그인**: 카카오, 네이버, 구글 OAuth 2.0 연동
|
|
3. **2FA (Two-Factor Authentication)**: SMS 또는 TOTP 기반 2단계 인증
|
|
4. **비밀번호 재설정**: 이메일/SMS를 통한 비밀번호 재설정 기능
|
|
|
|
### Phase 3
|
|
1. **계정 잠금 정책**: 로그인 5회 실패 시 계정 잠금
|
|
2. **세션 관리 고도화**: 동시 세션 수 제한, 세션 활성 기록
|
|
3. **감사 로그**: 민감 작업(로그인, 비밀번호 변경) 감사 로그 저장
|
|
4. **Rate Limiting**: 로그인 API에 Rate Limiting 적용 (사용자당 5회/분)
|
|
|
|
---
|
|
|
|
## 참고 문서
|
|
- [유저스토리](../../../userstory.md)
|
|
- [외부 시퀀스](../outer/사용자인증플로우.puml)
|
|
- [논리 아키텍처](../../logical/logical-architecture.md)
|
|
- [공통설계원칙](../../../common-principles.md)
|
|
- [내부시퀀스설계가이드](../../../../claude/sequence-inner-design.md)
|
|
|
|
---
|
|
|
|
**문서 버전**: 1.0
|
|
**최종 수정일**: 2025-10-22
|
|
**작성자**: System Architect
|
|
**변경 사항**: User Service 내부 시퀀스 4개 시나리오 초안 작성 완료
|