refactor: 계좌 연동과 소비 분류 비동기 분리

[bigwaveBigwave]

관련 이슈

• Closes [ Refactor ] - 계좌 연동과 소비 분류 작업 비동기 분리 #234

배경

기존 계좌 연동 API는 계좌와 거래내역을 저장한 뒤 소비 분류가 완료될 때까지 기다리고 응답했습니다.

소비 분류 시간이 길어지면 사용자가 계좌 연동 화면에서 장시간 로딩을 기다려야 했습니다.

계좌·거래 저장이 끝나면 계좌 연동 응답을 반환하고, 소비 분류는 백그라운드에서 계속 처리하도록 두 작업을 분리했습니다.

기존 구조

계좌 연동 요청
→ 계좌 및 거래 저장
→ 소비 분류 완료 대기
→ 계좌 연동 API 응답

변경 구조

계좌 연동 요청
→ 계좌 및 거래 저장
→ 소비 분류 이벤트 등록
→ 계좌 연동 API 응답
↓
전용 executor에서 소비 분류
↓
TXN_ANALYSIS 저장

변경 내용

1. 계좌 연동과 소비 분류 분리

• 계좌 연동 경로의 동기 소비 분류 호출을 제거했습니다.
• 계좌와 거래 저장 후 소비 분류 이벤트를 발행하도록 변경했습니다.
• 활성 트랜잭션이 있으면 커밋 이후 이벤트를 발행합니다.
• 현재 계좌 조합 경로처럼 하위 저장 메서드가 이미 커밋된 경우 즉시 이벤트를 발행합니다.
• 실제 소비 분류는 별도 executor에서 실행됩니다.

2. 전용 executor 구성

소비 분류 작업이 웹 요청 스레드 및 기존 FastAPI 배치 executor를 점유하지 않도록 전용 executor를 추가했습니다.

기본 설정:

account.classification.async.core-pool-size=1
account.classification.async.max-pool-size=2
account.classification.async.queue-capacity=100

설정 파일이 없어도 위 기본값으로 동작합니다.

선택적으로 다음 외부 설정 파일에서 조정할 수 있습니다.

${NTROPY_CONFIG_DIR}/account-classification.properties

3. 중복 실행 방지

• 같은 사용자에 대한 소비 분류 작업이 이미 실행 또는 대기 중이면 중복 등록을 건너뜁니다.
• 작업 완료·실패 및 executor 등록 실패 시 중복 방지 상태를 해제합니다.
• 중복 방지는 단일 애플리케이션 인스턴스 내에서 적용됩니다.
• 실제 분류는 기존처럼 미분류 거래만 조회해 처리합니다.

4. 실패 격리

• 소비 분류 실패가 이미 성공한 계좌 연동 응답에 영향을 주지 않습니다.
• executor 포화로 작업 등록이 거부되더라도 계좌 연동 응답에는 예외를 전파하지 않습니다.
• 미분류 거래는 기존 일간 소비 분류 스케줄러에서 다시 처리할 수 있습니다.

5. 로그 추가

[비동기 소비 분류] 작업 시작.
scope=userId=...

[비동기 소비 분류] 작업 완료.
scope=userId=..., totalProcessed=..., elapsedMs=...

[비동기 소비 분류] 작업 실패.
scope=userId=..., elapsedMs=..., errorKind=...

[비동기 소비 분류] 작업 등록 실패.
scope=userId=..., errorKind=...

거래 원문, 인증정보 및 API 키는 기록하지 않습니다.

테스트

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

• 계좌 연동 경로에서 직접 소비 분류를 실행하지 않고 이벤트를 등록하는지
• 트랜잭션 커밋 이후에만 이벤트가 발행되는지
• 트랜잭션 rollback 시 이벤트가 발행되지 않는지
• 실제 소비 분류가 요청 스레드가 아닌 executor 작업으로 등록되는지
• 동일 사용자의 중복 작업을 건너뛰는지
• 작업 완료 후 같은 사용자의 재실행이 가능한지
• 분류 실패가 이벤트 처리 및 계좌 연동 결과에 전파되지 않는지
• executor 등록 실패 후 중복 방지 상태가 해제되는지
• executor 설정값 및 안전 범위 보정

실행 결과:

.\gradlew.bat :services:account-service:test :services:ai-service:test --no-daemon
BUILD SUCCESSFUL

.\gradlew.bat :api:war --no-daemon
BUILD SUCCESSFUL

로컬 Tomcat 실행 및 Swagger 접근도 확인했습니다.

DB 변경

• 새로운 테이블이나 컬럼을 추가하지 않았습니다.
• DB 마이그레이션이 필요하지 않습니다.
• 기존 거래 및 TXN_ANALYSIS 데이터를 그대로 사용합니다.

배포 설정

필수로 추가해야 하는 환경변수나 외부 설정은 없습니다. 설정이 없으면 기본 executor 설정으로 실행됩니다.

배포 후 확인

• POST /api/accounts가 소비 분류 완료 전에 응답하는지 확인
• API 응답 이후 비동기 소비 분류 시작·완료 로그 확인
• 작업 실패 또는 작업 등록 실패 로그 확인
• 소비 분류 완료 후 기존과 동일하게 TXN_ANALYSIS가 저장되는지 확인

범위 외

• 별도 작업 상태 테이블 추가
• 정확한 PENDING / PROCESSING / FAILED 상태 관리
• Kafka 또는 SQS 도입
• 서버 재시작 시 실행 중이던 작업의 즉시 복구
• 프론트엔드 소비 분류 진행 UI
• FastAPI LLM chunking 및 timeout 조정