[ Refactor] - AI 월간 리포트 PDF 시각화 개선

[bigwaveBigwave]

관련 이슈

Resolves: #217

배경

기존 이메일 첨부용 AI 월간 리포트 PDF는 텍스트와 표 중심으로 구성되어 있어 핵심 재무 상태와 소비·근무 성과를 한눈에 파악하기 어려웠습니다.

이번 PR에서는 기존 PDFBox 기반 생성 구조와 이메일 발송 계약을 유지하면서, 월간 재무 정보를 카드와 그래프 중심의 2페이지 PDF로 개선했습니다.

작업 사항

1페이지: 월간 재무 요약

• 대상 연월 및 리포트 생성 시각 표시
• 총소득·총소비·가용자금 요약 카드
• AI 맞춤 제안 카드
• 총소득 대비 소비율 도넛 그래프
• 주요 소비 카테고리 누적 막대그래프
• 소비 카테고리 최대 4개 표시
• AGGREGATED_OTHER를 기타로 표시
• 카테고리별 금액과 비율 표시

2페이지: 근무 성과 및 금융상품 추천

• 잡별 근무시간·소득 표시
• 잡별 소득 비교 막대그래프
• AI 잡별 소득 인사이트 카드
• 추천 금융상품 카드
• 금융기관명·상품명·상품 요약 표시
• 버튼 대신 맞춤 추천 배지 표시
• 추천 이유·예상 혜택·향후 소득 전망 표시
• 상품 상세 조건 표시

디자인 및 렌더링

• 별도 이미지 리소스 미사용
• 외부 차트 라이브러리 미사용
• 기존 PDFBox 도형·텍스트 렌더링 활용
• 녹색·민트 계열 카드 및 그래프 적용
• 긴 한글 문구 자동 줄바꿈
• 긴 인사이트는 페이지 분할 가능한 문단 형태로 자동 전환
• 페이지 번호 유지

예외 처리

• 총소득이 없거나 0인 경우 소비율을 안전하게 0으로 처리
• 음수 및 비정상 금액의 그래프 렌더링 방어
• 카테고리 또는 잡 목록이 없을 때 빈 상태 표시
• 추천 상품이 없을 때 안내 문구 표시
• 긴 카테고리명·잡 이름·상품명 말줄임 및 원문 보존
• 기존 동적 상품 상세 정보 출력 유지

표시 문구 정리

상품 상세 키를 PDF에서 한글로 표시하도록 변경했습니다.

• interestRate → 금리
• savingPeriod → 저축 기간
• maxMonthlyAmount → 월 최대 납입액
• minimumSpend → 최소 이용 금액
• benefits → 혜택
• rate → 비율

동적 잔여 필드로 중복 노출되던 Fixed Expense는 제거했습니다.

영향 범위

• AiReportPdfService의 PDF 레이아웃 및 시각화
• AiReportPdfServiceTest의 PDF 생성 회귀 테스트

다음 계약은 변경하지 않았습니다.

• AiReportDetailSummary
• FastAPI 요청·응답
• AI 리포트 DB 스키마
• BFF API
• 이메일 발송 흐름
• PDF 첨부 방식
• Scheduler
• 외부 이미지 및 로고 자산

테스트

PDF 전용 테스트

.\gradlew.bat :services:ai-service:test --tests "com.ntropy.ai.service.AiReportPdfServiceTest"
--no-daemon

결과:

BUILD SUCCESSFUL
5 tests passed

다음 항목을 검증했습니다.

• 기본 데이터의 A4 2페이지 PDF 생성
• 핵심 재무 정보 포함
• 소비율 및 카테고리 시각화 문구 포함
• 잡별 근무 성과 포함
• 추천 상품 카드 및 배지 포함
• 긴 한글 인사이트의 페이지 분할 및 원문 보존
• 긴 카테고리명·잡 이름·상품 상세 원문 보존
• 동시 PDF 생성 안정성

WAR 빌드

.\gradlew.bat :api:war -x :api:test --no-daemon

결과:

BUILD SUCCESSFUL

참고: 전체 API 테스트

전체 api:test에서는 기존 develop의 다음 테스트 1건이 실패했습니다.

DiagnosisDefenseWiringTest

DefenseModeService 생성에 필요한 DiagnosisCommandClient 빈이 테스트 설정에 등록되지 않은 기존 wiring 문제입니다. 이번 PR에서 수정한 PDF 파일과 관련이 없으며, 이슈 #217 범위에서는
변경하지 않았습니다.

확인 사항

• A4 2페이지 PDF 생성
• 총소득·총소비·가용자금 카드 표시
• 소비율 도넛 그래프 표시
• 주요 소비 카테고리 최대 4개 표시
• 잡별 근무 성과 및 비교 막대그래프 표시
• 추천 금융상품과 맞춤 추천 배지 표시
• null·빈 데이터 안전 처리
• 긴 한글 텍스트 페이지 분할
• PDF 전용 테스트 통과
• WAR 빌드 성공
• 이미지 및 외부 차트 라이브러리 미사용
• 이메일·FastAPI·DB·BFF 계약 변경 없음