mirror of https://github.com/cna-bootcamp/phonebill.git synced 2025-12-06 08:06:24 +00:00

- 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>

2025-09-08 10:27:39 +09:00

7.6 KiB

Raw Blame History

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

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

개요

설계 원칙

마이크로서비스 아키텍처: 서비스별 독립성 보장, 독립적 배포/확장
클라우드 네이티브 패턴 적용: API Gateway, Cache-Aside, Circuit Breaker 패턴 적용
캐시 우선 전략: 성능 최적화를 위한 Redis 기반 캐싱
외부 시스템 안정성: Circuit Breaker를 통한 장애 격리

핵심 컴포넌트 정의

API Gateway: 단일 진입점, 인증/인가, 라우팅
마이크로서비스: Auth, Bill-Inquiry, Product-Change 서비스
캐시 레이어: Redis 기반 캐시-어사이드 패턴
외부 연동: 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. 결과 처리 및 전송]

데이터 흐름 및 캐싱 전략

데이터 흐름

클라이언트 요청 → API Gateway (인증/라우팅)
서비스 처리 → 캐시 확인 → 외부/DB 조회 (필요시)
응답 처리 → 캐시 업데이트 → 클라이언트 응답
이력 저장 → 비동기 처리

캐싱 전략 (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 파일을 참조하세요.

검토 결과

유저스토리 매칭 검토 ✅

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매니저), 박화면(프론트)

7.6 KiB Raw Blame History