[ Refactor ] - 미분석 거래 일간 소비 분류 배치 구현

[bigwaveBigwave]

관련 이슈

• Resolves: [ Refactor ] - 미분석 거래 일간 소비 분류 배치 구현 #140

작업 사항

미분석 거래 일간 소비 분류 배치 구현

• 매일 새벽 2시에 실행되는 DailyTransactionClassificationScheduler 추가
• TXN_ANALYSIS가 없는 미분석 거래를 최대 500건씩 반복 조회
• 과거 거래를 포함하여 아직 분석 결과가 없는 거래 처리
• 미분석 거래가 더 이상 없을 때까지 페이지 단위로 반복 처리
• 일간 소비 분류와 월간 AI 리포트 생성 책임 분리
• 월간 AI 리포트 실행 시간을 매월 1일 새벽 3시로 변경

매일 02:00
→ 미분석 거래 소비 분류
→ TXN_ANALYSIS 저장

매월 1일 03:00
→ 전월 TXN_ANALYSIS 소비 데이터 집계
→ 월간 AI 리포트 생성

거래 유형별 분석 대상 조회

• ORDINARY
  • out_amount > 0
• INSTALLMENT
  • in_amount > 0
• LOAN
  • out_amount > 0
• 이미 TXN_ANALYSIS가 존재하는 거래는 조회 대상에서 제외
• 비활성 계좌의 과거 미분석 거래도 누락되지 않도록 계좌 상태 조건 없이 조회

Spring 결정적 사전 분류 구현

FastAPI를 호출하기 전에 거래 유형과 명확한 키워드로 결과를 확정하도록 TransactionPreClassificationService를 추가했습니다.

거래 유형	소비 여부	카테고리	지출 유형
LOAN 정상 상환	TRUE	FINANCE	FIXED
LOAN 신규·실행·증액	FALSE	NULL	NULL
INSTALLMENT 납입	TRUE	FINANCE	FIXED
금융상품 계좌 이체	FALSE	NULL	NULL
카드대금	TRUE	ETC	VARIABLE
현금 인출	TRUE	ETC	VARIABLE
보험료	TRUE	INSURANCE	FIXED

금융 목적이 명확한 다음 키워드는 비소비 거래 판정에 사용합니다.

정기예금
정기적금
자유적금
적금납입
예금납입
대출상환
원금상환
대출계좌
수시입출금계좌
본인계좌
내계좌

다음 표현은 거래 방식이므로 해당 키워드만으로 비소비 처리하지 않습니다.

자동이체
CMS
FBS
전자금융
인터넷뱅킹
타행이체

FastAPI 소비 분류 연동

• Spring 결정적 규칙으로 분류하지 못한 ORDINARY 출금만 FastAPI에 전달
• AI 이슈 #33에서 확정한 구조화된 요청 DTO 적용
• FastAPI 요청 제한에 맞춰 최대 100건씩 분할 호출
• desc3 → desc1 → desc2 → desc4 순서로 활용할 수 있도록 원본 필드 전달

FastAPI 요청 예시:

{
  "transactions": [
    {
      "transactionId": 101,
      "amount": 65000,
      "transactionCategory": "ORDINARY",
      "organizationCode": "0004",
      "desc1": null,
      "desc2": "FBS출금",
      "desc3": "KT통신요금",
      "desc4": "강남지점"
    }
  ]
}

FastAPI 응답 검증 및 fallback

• 요청에 포함되지 않은 transactionId 응답 제외
• 동일한 transactionId가 중복 반환되면 해당 결과를 신뢰하지 않고 fallback
• 소비 결과에는 category, expenseType이 모두 존재하는지 검증
• 비소비 결과에는 category, expenseType이 모두 NULL인지 검증
• 허용되지 않은 카테고리 또는 지출 유형 응답 제외
• FastAPI 호출 실패, 응답 누락 또는 잘못된 응답은 다음 값으로 최종 저장

isConsumption = TRUE
category = ETC
expenseType = VARIABLE

TXN_ANALYSIS 저장 계약 확장

• 소비 거래뿐 아니라 분석이 완료된 비소비 거래도 저장
• account_transaction_id 기준 일괄 upsert
• 비소비 거래는 다음 값으로 저장

is_consumption = FALSE
category = NULL
expense_type = NULL

• 비소비 결과도 저장하여 다음 일간 배치에서 동일 거래가 반복 조회되는 문제 방지
• DB 저장 실패로 TXN_ANALYSIS가 생성되지 않은 거래는 다음 배치에서 다시 조회
• 빈 저장 요청은 처리하지 않고 종료
• 동일 요청 내 중복 transactionId 검증
• 소비 여부에 따른 카테고리 및 지출 유형 정합성 검증
• 일간 조회 크기를 1~500으로 제한

참고 사항

• ETC는 미분석 상태가 아니라 세부 카테고리를 특정하지 못한 최종 소비 분류 결과입니다.

TXN_ANALYSIS 없음
→ 아직 분석하지 않은 거래

TXN_ANALYSIS 존재 + category = ETC
→ 분석은 완료했지만 세부 소비 카테고리를 특정하지 못한 거래

• 일간 배치는 전날 거래만 조회하지 않고 과거 거래를 포함하여 TXN_ANALYSIS가 없는 모든 분석 대상 거래를 처리합니다.
• FastAPI에는 Spring에서 결정적으로 분류하지 못한 일반 출금 거래만 전달합니다.
• 적금 납입과 대출 정상 상환 금액의 월간 집계 기준 변경은 별도 월간 소비 집계 정합성 작업에서 처리합니다.
• .idea 등 IntelliJ 개인 설정 파일은 커밋 대상에서 제외했습니다.

테스트

다음 테스트를 추가하거나 수정했습니다.

• Spring 결정적 사전 분류 규칙 테스트
• Spring 분류 결과와 FastAPI 결과 통합 저장 테스트
• FastAPI 최대 100건 분할 요청 테스트
• FastAPI 응답 누락 및 잘못된 Enum fallback 테스트
• 미분석 거래 반복 조회 테스트
• 소비·비소비 결과 저장 정합성 테스트
• 일간 조회 크기 검증 테스트
• 미분석 거래 조회 SQL 계약 테스트
• TXN_ANALYSIS 일괄 upsert SQL 계약 테스트
• 일간 및 월간 Scheduler 실행 시간 계약 테스트

검증 명령:

./gradlew :services:account-service:test :services:ai-service:test
./gradlew :services:account-service:build :services:ai-service:build
./gradlew :services:account-service:clean :services:ai-service:clean \
  :services:account-service:build :services:ai-service:build

검증 결과:

BUILD SUCCESSFUL

추가로 로컬에서 애플리케이션을 실행하여 다음 항목을 확인했습니다.

• Spring 애플리케이션 컨텍스트 정상 생성
• MyBatis Mapper 및 XML 정상 로딩
• 일간 소비 분류 Scheduler 빈 등록
• account-service와 AI-service Client 연결
• 내장 Tomcat 정상 기동