phonebill/design/backend/database/bill-inquiry.md

Bill-Inquiry 서비스 데이터 설계서

1. 개요

1.1 설계 목적

Bill-Inquiry 서비스의 요금 조회 기능을 위한 독립적인 데이터베이스 설계

1.2 설계 원칙

• 서비스 독립성: Bill-Inquiry 서비스 전용 데이터베이스 구성
• 데이터 격리: 타 서비스와 데이터 공유 금지, 캐시를 통한 성능 최적화
• 외래키 제한: 서비스 내부에서만 FK 관계 설정
• 이력 관리: 모든 요청/처리 이력의 완전한 추적

1.3 주요 기능

• UFR-BILL-010: 요금조회 메뉴 접근
• UFR-BILL-020: 요금조회 신청
• UFR-BILL-030: KOS 요금조회 서비스 연동
• UFR-BILL-040: 요금조회 결과 전송

2. 데이터베이스 구성

2.1 데이터베이스 정보

• 데이터베이스명: bill_inquiry_db
• DBMS: PostgreSQL 14
• 문자셋: UTF8
• 타임존: Asia/Seoul

2.2 스키마 구성

• public: 기본 스키마 (비즈니스 테이블)
• cache: 캐시 데이터 스키마 (Redis 보조용)
• audit: 감사 및 이력 스키마

3. 테이블 설계

3.1 고객정보 테이블 (customer_info)

목적: 캐시에서 가져온 고객 기본 정보 임시 저장

컬럼명	타입	제약조건	설명
customer_id	VARCHAR(50)	PRIMARY KEY	고객 식별자
line_number	VARCHAR(20)	NOT NULL	회선번호
customer_name	VARCHAR(100)		고객명
status	VARCHAR(10)	NOT NULL DEFAULT 'ACTIVE'	고객상태 (ACTIVE, INACTIVE)
operator_code	VARCHAR(10)	NOT NULL	사업자 코드
cached_at	TIMESTAMP	NOT NULL DEFAULT CURRENT_TIMESTAMP	캐시 저장 시각
expires_at	TIMESTAMP	NOT NULL	캐시 만료 시각
created_at	TIMESTAMP	NOT NULL DEFAULT CURRENT_TIMESTAMP	생성일시
updated_at	TIMESTAMP	NOT NULL DEFAULT CURRENT_TIMESTAMP	수정일시

3.2 요금조회 요청 이력 테이블 (bill_inquiry_history)

목적: MVNO에서 MP로의 요금조회 요청 이력 관리

컬럼명	타입	제약조건	설명
id	BIGSERIAL	PRIMARY KEY	이력 ID
request_id	VARCHAR(50)	NOT NULL UNIQUE	요청 식별자
user_id	VARCHAR(50)	NOT NULL	요청 사용자 ID
line_number	VARCHAR(20)	NOT NULL	회선번호
inquiry_month	VARCHAR(7)		조회월 (YYYY-MM, null이면 당월)
request_time	TIMESTAMP	NOT NULL DEFAULT CURRENT_TIMESTAMP	요청일시
process_time	TIMESTAMP		처리완료일시
status	VARCHAR(20)	NOT NULL DEFAULT 'PROCESSING'	처리상태
result_summary	TEXT		결과 요약
bill_info_json	JSONB		요금정보 JSON
error_message	TEXT		오류 메시지
created_at	TIMESTAMP	NOT NULL DEFAULT CURRENT_TIMESTAMP	생성일시
updated_at	TIMESTAMP	NOT NULL DEFAULT CURRENT_TIMESTAMP	수정일시

인덱스:

• idx_bill_history_user_line: (user_id, line_number)
• idx_bill_history_request_time: (request_time DESC)
• idx_bill_history_status: (status)
• idx_bill_history_inquiry_month: (inquiry_month)

상태값 (status):

• PROCESSING: 처리중
• COMPLETED: 완료
• FAILED: 실패
• TIMEOUT: 타임아웃

3.3 KOS 연동 이력 테이블 (kos_inquiry_history)

목적: MP에서 KOS로의 요금조회 연동 이력 관리

컬럼명	타입	제약조건	설명
id	BIGSERIAL	PRIMARY KEY	이력 ID
bill_request_id	VARCHAR(50)		요금조회 요청 ID (FK)
line_number	VARCHAR(20)	NOT NULL	회선번호
inquiry_month	VARCHAR(7)		조회월
request_time	TIMESTAMP	NOT NULL DEFAULT CURRENT_TIMESTAMP	KOS 요청일시
response_time	TIMESTAMP		KOS 응답일시
result_code	VARCHAR(10)		KOS 응답코드
result_message	TEXT		KOS 응답메시지
kos_data_json	JSONB		KOS 응답 데이터 JSON
error_detail	TEXT		오류 상세 정보
retry_count	INTEGER	NOT NULL DEFAULT 0	재시도 횟수
circuit_breaker_state	VARCHAR(20)		Circuit Breaker 상태
created_at	TIMESTAMP	NOT NULL DEFAULT CURRENT_TIMESTAMP	생성일시
updated_at	TIMESTAMP	NOT NULL DEFAULT CURRENT_TIMESTAMP	수정일시

인덱스:

• idx_kos_history_line_month: (line_number, inquiry_month)
• idx_kos_history_request_time: (request_time DESC)
• idx_kos_history_result_code: (result_code)
• idx_kos_history_bill_request: (bill_request_id)

3.4 요금정보 캐시 테이블 (bill_info_cache)

목적: KOS에서 조회한 요금정보의 임시 캐시 (Redis 보조용)

컬럼명	타입	제약조건	설명
cache_key	VARCHAR(100)	PRIMARY KEY	캐시 키 (line_number:inquiry_month)
line_number	VARCHAR(20)	NOT NULL	회선번호
inquiry_month	VARCHAR(7)	NOT NULL	조회월
bill_info_json	JSONB	NOT NULL	요금정보 JSON
cached_at	TIMESTAMP	NOT NULL DEFAULT CURRENT_TIMESTAMP	캐시 저장 시각
expires_at	TIMESTAMP	NOT NULL	캐시 만료 시각
access_count	INTEGER	NOT NULL DEFAULT 1	접근 횟수
last_accessed_at	TIMESTAMP	NOT NULL DEFAULT CURRENT_TIMESTAMP	최종 접근 시각

인덱스:

• idx_cache_line_month: (line_number, inquiry_month)
• idx_cache_expires: (expires_at)

3.5 시스템 설정 테이블 (system_config)

목적: Bill-Inquiry 서비스 관련 시스템 설정 관리

컬럼명	타입	제약조건	설명
config_key	VARCHAR(100)	PRIMARY KEY	설정 키
config_value	TEXT	NOT NULL	설정 값
description	VARCHAR(500)		설정 설명
config_type	VARCHAR(20)	NOT NULL DEFAULT 'STRING'	설정 타입
is_active	BOOLEAN	NOT NULL DEFAULT true	활성화 여부
created_at	TIMESTAMP	NOT NULL DEFAULT CURRENT_TIMESTAMP	생성일시
updated_at	TIMESTAMP	NOT NULL DEFAULT CURRENT_TIMESTAMP	수정일시

설정 예시:

• bill.cache.ttl.hours: 요금정보 캐시 TTL (기본 4시간)
• kos.connection.timeout.ms: KOS 연결 타임아웃
• kos.retry.max.attempts: KOS 최대 재시도 횟수
• bill.inquiry.available.months: 조회 가능한 개월 수

4. 외래키 관계

4.1 서비스 내부 관계

• kos_inquiry_history.bill_request_id → bill_inquiry_history.request_id
  • KOS 연동 이력과 요금조회 요청 이력 연결
  • ON DELETE CASCADE로 요금조회 이력 삭제 시 KOS 이력도 삭제

4.2 외부 서비스와의 관계

• Auth 서비스: user_id는 참조만 하고 FK 관계 설정하지 않음
• 캐시 데이터: Redis를 통한 데이터 공유, DB 직접 참조 없음

5. 캐시 전략

5.1 Redis 캐시 키 전략

• 고객정보: customer:info:{user_id} (TTL: 1시간)
• 요금정보: bill:info:{line_number}:{inquiry_month} (TTL: 4시간)
• 가용조회월: bill:available:months (TTL: 24시간)

5.2 캐시 무효화 정책

• 요금조회 완료 시: 해당 회선/월 캐시 갱신
• 고객정보 변경 시: 고객정보 캐시 삭제
• 시스템 설정 변경 시: 관련 캐시 전체 삭제

6. 데이터 보안

6.1 개인정보 보호

• 암호화 컬럼: customer_name, bill_info_json
• 접근 제어: 사용자별 회선번호 권한 확인
• 로그 마스킹: 개인정보 포함 로그는 마스킹 처리

6.2 데이터 보관 정책

• 요금조회 이력: 2년 보관 후 아카이브
• KOS 연동 이력: 1년 보관 후 삭제
• 캐시 데이터: TTL 만료 후 자동 삭제
• 오류 로그: 6개월 보관

7. 성능 최적화

7.1 인덱스 전략

• 복합 인덱스: 자주 함께 조회되는 컬럼들
• 부분 인덱스: 활성 데이터만 대상으로 하는 인덱스
• JSONB 인덱스: 요금정보 JSON 검색용 GIN 인덱스

7.2 파티셔닝 전략

• bill_inquiry_history: 월별 파티셔닝 (request_time 기준)
• kos_inquiry_history: 월별 파티셔닝 (request_time 기준)

7.3 통계 정보 관리

• 자동 통계 수집: 주요 테이블 자동 분석
• 쿼리 플랜 모니터링: 성능 저하 쿼리 식별

8. 모니터링 및 알람

8.1 성능 모니터링

• 테이블별 용량 및 성장률 추적
• 슬로우 쿼리 모니터링
• 캐시 히트율 모니터링

8.2 비즈니스 모니터링

• 요금조회 성공률
• KOS 연동 응답시간
• Circuit Breaker 상태

9. 데이터 백업 및 복구

9.1 백업 전략

• 전체 백업: 주 1회 (일요일 새벽)
• 증분 백업: 일 1회 (매일 새벽)
• 트랜잭션 로그 백업: 15분마다

9.2 복구 전략

• Point-in-Time 복구: 특정 시점 데이터 복구
• 테이블 단위 복구: 개별 테이블 복구
• 응급 복구: 1시간 내 서비스 복구

10. 관련 산출물

• ERD 설계서: bill-inquiry-erd.puml
• 스키마 스크립트: bill-inquiry-schema.psql
• API 설계서: ../api/bill-inquiry-service-api.yaml
• 클래스 설계서: ../class/bill-inquiry.puml