# 통신요금 관리 서비스 - 논리아키텍처 설계서

**최적안**: 이개발(백엔더)

---

## 개요

### 설계 원칙
- **마이크로서비스 아키텍처**: 서비스별 독립성 보장, 독립적 배포/확장
- **클라우드 네이티브 패턴 적용**: 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매니저), 박화면(프론트)