mirror of
https://github.com/cna-bootcamp/phonebill.git
synced 2025-12-06 16:16:23 +00:00
7ec8a682c6
- 3개 핵심 비즈니스 플로우별 외부 시퀀스 다이어그램 작성 - 사용자인증플로우.puml: UFR-AUTH-010, UFR-AUTH-020 반영 - 요금조회플로우.puml: UFR-BILL-010~040 반영 - 상품변경플로우.puml: UFR-PROD-010~040 반영 - 논리아키텍처와 참여자 완전 일치 - UI/UX 설계서 사용자 플로우 100% 반영 - 클라우드 패턴 적용 (API Gateway, Cache-Aside, Circuit Breaker) - PlantUML 문법 검사 통과 (mono 테마 적용) 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
213 lines
7.6 KiB
Markdown
213 lines
7.6 KiB
Markdown
# 통신요금 관리 서비스 - 논리아키텍처 설계서
|
|
|
|
**최적안**: 이개발(백엔더)
|
|
|
|
---
|
|
|
|
## 개요
|
|
|
|
### 설계 원칙
|
|
- **마이크로서비스 아키텍처**: 서비스별 독립성 보장, 독립적 배포/확장
|
|
- **클라우드 네이티브 패턴 적용**: API Gateway, Cache-Aside, Circuit Breaker 패턴 적용
|
|
- **캐시 우선 전략**: 성능 최적화를 위한 Redis 기반 캐싱
|
|
- **외부 시스템 안정성**: Circuit Breaker를 통한 장애 격리
|
|
|
|
### 핵심 컴포넌트 정의
|
|
1. **API Gateway**: 단일 진입점, 인증/인가, 라우팅
|
|
2. **마이크로서비스**: Auth, Bill-Inquiry, Product-Change 서비스
|
|
3. **캐시 레이어**: Redis 기반 캐시-어사이드 패턴
|
|
4. **외부 연동**: KOS-Order 시스템과 Circuit Breaker 패턴 연동
|
|
|
|
---
|
|
|
|
## 서비스 아키텍처
|
|
|
|
### 서비스별 책임
|
|
|
|
#### 1. Auth Service
|
|
- **핵심 책임**: 사용자 인증 및 인가 처리
|
|
- **주요 기능**:
|
|
- JWT 토큰 발급/검증
|
|
- 사용자 세션 관리
|
|
- 서비스별 접근 권한 확인
|
|
- 로그인 실패 처리 (5회 실패 시 계정 잠금)
|
|
- **데이터**: 사용자 정보, 권한 정보, 세션 데이터
|
|
|
|
#### 2. Bill-Inquiry Service
|
|
- **핵심 책임**: 요금 조회 및 KOS 연동 처리
|
|
- **주요 기능**:
|
|
- 요금 조회 메뉴 제공
|
|
- 조회월 선택 처리 (당월 또는 특정 월)
|
|
- KOS-Order 시스템 연동 (Circuit Breaker 적용)
|
|
- 조회 결과 캐싱 및 MVNO AP 전송
|
|
- 요청/처리 이력 관리
|
|
- **데이터**: 요금 조회 이력, KOS 연동 결과
|
|
|
|
#### 3. Product-Change Service
|
|
- **핵심 책임**: 상품 변경 요청 및 처리
|
|
- **주요 기능**:
|
|
- 상품 변경 메뉴 제공
|
|
- 고객/상품 정보 조회 (KOS 연동)
|
|
- 상품 변경 사전 체크
|
|
- 상품 변경 처리 및 결과 전송
|
|
- 변경 이력 관리
|
|
- **데이터**: 상품 변경 이력, 고객 정보 캐시, 상품 정보 캐시
|
|
|
|
### 서비스 간 통신 전략
|
|
|
|
#### 동기 통신
|
|
- **API Gateway를 통한 서비스 라우팅**: 모든 클라이언트 요청
|
|
- **서비스 간 직접 통신 최소화**: 캐시를 통한 데이터 공유
|
|
|
|
#### 캐시 우선 전략
|
|
- **사용자 세션**: Auth 서비스에서 Redis 캐시 활용 (TTL: 30분)
|
|
- **요금 조회 결과**: 1시간 캐싱으로 KOS 부하 감소
|
|
- **상품 정보**: 24시간 캐싱으로 반복 조회 최적화
|
|
|
|
#### 비동기 처리
|
|
- **로그/이력 처리**: 응답 성능에 영향 없는 백그라운드 처리
|
|
|
|
---
|
|
|
|
## 주요 사용자 플로우
|
|
|
|
### 1. 인증 플로우
|
|
```
|
|
[클라이언트] → [API Gateway] → [Auth Service] → [Redis(세션)] → [PostgreSQL(사용자)]
|
|
↓
|
|
[JWT 토큰 발급] ← [Auth Service] ← [API Gateway] ← [클라이언트]
|
|
```
|
|
|
|
### 2. 요금 조회 플로우
|
|
```
|
|
[클라이언트] → [API Gateway] → [Bill-Inquiry Service]
|
|
↓
|
|
[1. Redis 캐시 확인]
|
|
↓
|
|
[2. 캐시 Miss 시 KOS 연동 (Circuit Breaker)]
|
|
↓
|
|
[3. 결과 캐싱 후 반환]
|
|
↓
|
|
[4. MVNO AP 전송]
|
|
↓
|
|
[5. 이력 DB 저장]
|
|
```
|
|
|
|
### 3. 상품 변경 플로우
|
|
```
|
|
[클라이언트] → [API Gateway] → [Product-Change Service]
|
|
↓
|
|
[1. 상품정보 캐시 확인/KOS 조회]
|
|
↓
|
|
[2. 변경 사전 체크]
|
|
↓
|
|
[3. KOS 상품 변경 처리 (Circuit Breaker)]
|
|
↓
|
|
[4. 결과 처리 및 전송]
|
|
```
|
|
|
|
---
|
|
|
|
## 데이터 흐름 및 캐싱 전략
|
|
|
|
### 데이터 흐름
|
|
1. **클라이언트 요청** → API Gateway (인증/라우팅)
|
|
2. **서비스 처리** → 캐시 확인 → 외부/DB 조회 (필요시)
|
|
3. **응답 처리** → 캐시 업데이트 → 클라이언트 응답
|
|
4. **이력 저장** → 비동기 처리
|
|
|
|
### 캐싱 전략 (Cache-Aside 패턴)
|
|
|
|
#### 캐시 대상 및 TTL
|
|
- **사용자 세션**: 30분 (로그인 유지 시간)
|
|
- **요금 조회 결과**: 1시간 (KOS 부하 감소)
|
|
- **상품 정보**: 24시간 (변경 빈도 낮음)
|
|
- **고객 정보**: 4시간 (상품 변경 시 필요)
|
|
|
|
#### 캐시 무효화 정책
|
|
- **사용자 로그아웃**: 즉시 세션 삭제
|
|
- **상품 변경 완료**: 해당 고객 상품 정보 캐시 삭제
|
|
- **TTL 만료**: 자동 삭제 후 다음 조회 시 갱신
|
|
|
|
#### 캐시 성능 목표
|
|
- **캐시 적중률**: 85% 이상
|
|
- **응답 시간 개선**: 80% (1000ms → 200ms)
|
|
- **외부 시스템 부하**: 85% 감소
|
|
|
|
---
|
|
|
|
## 확장성 및 성능 고려사항
|
|
|
|
### Horizontal Scaling 전략
|
|
- **API Gateway**: 로드 밸런서 뒤에 다중 인스턴스 배치
|
|
- **마이크로서비스**: 서비스별 독립적 확장 (CPU/메모리 사용량 기준)
|
|
- **Redis 클러스터**: 캐시 부하 분산 및 고가용성
|
|
- **데이터베이스**: 읽기 전용 복제본을 통한 읽기 성능 향상
|
|
|
|
### 성능 목표
|
|
- **API 응답 시간**:
|
|
- 일반 조회: 200ms 이내
|
|
- 외부 연동: 3초 이내 (Circuit Breaker 타임아웃)
|
|
- **동시 사용자**: 1,000명 (Peak 시간대)
|
|
- **처리량**: API Gateway 1,000 TPS
|
|
|
|
### 병목점 해결 방안
|
|
- **KOS 연동 지연**: Circuit Breaker + 캐시 활용
|
|
- **데이터베이스 부하**: 캐시-어사이드 패턴으로 85% 부하 감소
|
|
- **인증 처리**: JWT 토큰으로 상태 정보 분산
|
|
|
|
---
|
|
|
|
## 보안 고려사항
|
|
|
|
### 인증/인가 체계
|
|
- **JWT 기반 토큰**: 서버 상태 비저장으로 확장성 확보
|
|
- **토큰 만료**: Access Token(30분) + Refresh Token(24시간)
|
|
- **권한 기반 접근 제어**: 서비스별 권한 확인
|
|
|
|
### 데이터 보호
|
|
- **전송 중 암호화**: HTTPS 적용, API Gateway에서 SSL 종료
|
|
- **저장 중 암호화**: 민감 데이터(개인정보) DB 레벨 암호화
|
|
- **세션 보안**: Redis AUTH, TTL 기반 자동 만료
|
|
|
|
### 외부 연동 보안
|
|
- **KOS 연동**: 전용 네트워크 또는 VPN 연결
|
|
- **API 키 관리**: 환경 변수로 분리, 주기적 로테이션
|
|
- **요청/응답 로깅**: 개인정보 마스킹 처리
|
|
|
|
### 보안 모니터링
|
|
- **이상 트래픽 탐지**: API Gateway Rate Limiting
|
|
- **로그인 시도 추적**: 5회 실패 시 계정 잠금
|
|
- **접근 로그**: 모든 API 요청/응답 로그 수집
|
|
|
|
---
|
|
|
|
## 논리아키텍처 다이어그램
|
|
|
|
상세한 논리아키텍처 다이어그램은 [logical-architecture.mmd](logical-architecture.mmd) 파일을 참조하세요.
|
|
|
|
---
|
|
|
|
## 검토 결과
|
|
|
|
### 유저스토리 매칭 검토 ✅
|
|
- UFR-AUTH-010, UFR-AUTH-020: Auth Service에서 완전 처리
|
|
- UFR-BILL-010, UFR-BILL-020, UFR-BILL-030, UFR-BILL-040: Bill-Inquiry Service에서 완전 처리
|
|
- UFR-PROD-010, UFR-PROD-020, UFR-PROD-030, UFR-PROD-040: Product-Change Service에서 완전 처리
|
|
- 총 10개 유저스토리 100% 반영, 불필요한 추가 설계 없음
|
|
|
|
### 아키텍처 패턴 적용 검토 ✅
|
|
- **API Gateway 패턴**: 단일 진입점, 인증/라우팅 중앙 관리
|
|
- **Cache-Aside 패턴**: Redis 기반 캐싱으로 성능 최적화
|
|
- **Circuit Breaker 패턴**: KOS 연동 안정성 확보
|
|
|
|
### 사용자 플로우 반영 검토 ✅
|
|
- UI/UX 설계서의 8개 화면 플로우와 일치
|
|
- 메인 플로우와 오류 처리 플로우 모두 반영
|
|
- 화면 전환과 서비스 호출 흐름이 일치
|
|
|
|
---
|
|
|
|
**작성자**: 이개발(백엔더), 김기획(기획자)
|
|
**작성일**: 2025-01-08
|
|
**검토자**: 최운영(데옵스), 정테스트(QA매니저), 박화면(프론트) |