[ Refactor ] - 계좌 연동 후 소비 카테고리 분류 시간 단축

[bigwaveBigwave]

배경

회원가입 후 계좌를 연동하면 해당 사용자의 미분류 거래내역에 대해 소비 여부, 소비 카테고리, 지출 유형 분류를 실행한다.

현재 계좌 연동 API가 소비 분류 완료까지 동기적으로 기다리기 때문에, 최초 계좌 연동 완료까지 약 4분이 소요되고 있다. 이로 인해 사용자가 계좌 연동 화면에서 장시간 대기해야 한다.

현재 처리 흐름

1. POST /api/accounts 호출
2. 가상계좌 생성 또는 CODEF 계좌 및 최근 90일 거래 수집
3. 사용자의 미분류 거래를 DB에서 최대 500건씩 조회
4. Java 규칙으로 분류 가능한 거래를 사전 분류
5. 남은 거래를 최대 100건 단위로 분할
6. FastAPI /api/v1/classify-transactions를 배치별로 순차 호출
7. 분류 결과를 TXN_ANALYSIS에 저장
8. 모든 분류가 끝난 후 계좌 연동 API 응답 반환

문제점

• FastAPI 100건 단위 요청이 순차적으로 실행된다.
• FastAPI 배치별 처리 시간이 전체 응답 시간에 누적된다.
• 계좌 연동, DB 조회, 규칙 분류, FastAPI 호출, DB 저장 시간이 분리 계측되지 않는다.
• FastAPI 클라이언트에 명시적인 connect/read timeout이 없다.
• 현재 로그만으로는 정확한 병목과 개선 전후 차이를 판단하기 어렵다.
• 계좌 연동 API가 소비 분류 완료까지 기다려 사용자 체감 지연이 크다.

예상 병목

예를 들어 FastAPI 대상 거래가 400건이고 100건 요청 하나가 50초 걸리는 경우, 현재 구조에서는 다음과 같이 누적될 수 있다.

50초 × 4회 = 약 200초

여기에 계좌·거래 수집과 DB 처리 시간이 더해지면 전체 응답 시간이 약 4분까지 증가할 수 있다.

목표

• 동일한 거래 수를 기준으로 소비 분류 처리 시간을 단축한다.
• FastAPI 호출을 제한된 동시성으로 병렬 처리한다.
• 개선 전후를 비교할 수 있도록 단계별 성능 지표를 기록한다.
• FastAPI 지연 또는 장애가 계좌 연동 요청을 무기한 대기시키지 않도록 timeout을 설정한다.
• 기존 분류 결과 검증 및 fallback 정책을 유지한다.

측정 지표

개선 전후 동일한 테스트 데이터로 다음 지표를 비교한다.

주요 지표

• 계좌 연동 API 전체 응답 시간

• 소비 분류 전체 처리 시간

• 전체 분류 대상 거래 수

• 초당 처리 건수

  • 전체 처리 건수 / 소비 분류 시간

• FastAPI 호출 횟수

• FastAPI 호출별 및 누적 처리 시간

• p50, p95 처리 시간

안정성 지표

• 정상 분류 완료율
• FastAPI fallback 건수 및 비율
• 응답 누락·중복·유효하지 않은 결과 건수
• 분류 전후 카테고리 분포
• DB 저장 성공 건수
• 미분류 잔여 거래 수

세부 구간 지표

• 미분류 거래 DB 조회 시간
• Java 규칙 분류 건수 및 처리 시간
• FastAPI 전달 거래 수
• FastAPI 배치별 요청 건수 및 처리 시간
• TXN_ANALYSIS 저장 시간

구현 범위

• FastAPI 분류 요청을 전용 실행기에서 제한적으로 병렬 실행
• 병렬 처리 동시성 설정 추가
• FastAPI connect/read timeout 설정
• 전체 소비 분류 시작·종료 시간 로그 추가
• DB 조회 및 저장 시간 로그 추가
• Java 규칙 분류 건수 로그 추가
• FastAPI 대상 건수와 배치 수 로그 추가
• FastAPI 배치별 처리 시간과 fallback 건수 로그 추가
• 기존 결과 순서 및 fallback 정책 유지
• 단위 테스트 보강
• 동일 데이터 기준 개선 전후 성능 측정

병렬 처리 정책

• FastAPI의 요청 최대 크기인 100건은 유지한다.
• 여러 100건 배치를 제한된 스레드 풀에서 병렬 실행한다.
• 기본 동시성은 4로 설정하고 환경 설정으로 변경할 수 있도록 한다.
• 서버 및 FastAPI 부하를 고려해 최대 동시성 상한을 설정한다.
• 처리 결과는 기존 요청 순서대로 합쳐 저장한다.

설정 예시:

fastapi.classification.parallelism=4
fastapi.connect-timeout-ms=5000
fastapi.read-timeout-ms=120000

완료 조건

• 동일한 거래 데이터에서 기존보다 소비 분류 전체 시간이 감소한다.
• FastAPI 배치가 설정된 동시성 범위 안에서 병렬 실행된다.
• 계좌 연동, DB 조회, 분류, FastAPI, DB 저장 시간을 로그로 구분할 수 있다.
• FastAPI 호출이 설정된 timeout을 초과하면 기존 fallback 정책으로 처리된다.
• 소비·비소비 및 카테고리 결과 계약이 기존과 동일하게 유지된다.
• FastAPI 응답 누락·중복·오류 시 기존과 동일하게 ETC / VARIABLE fallback이 적용된다.
• 처리 후 대상 사용자의 미분류 거래가 남지 않는다.
• 관련 단위 테스트와 모듈 테스트가 통과한다.

검증 방법

1. 동일한 가상 사용자를 준비한다.
2. 동일한 은행과 기준일로 가상계좌를 생성한다.
3. 분류 전 대상 거래 수를 기록한다.
4. 계좌 연동 또는 소비 분류 API의 전체 시간을 측정한다.
5. 서버 로그에서 구간별 처리 시간을 수집한다.
6. 분류 후 TXN_ANALYSIS 저장 건수와 미분류 잔여 건수를 확인한다.
7. 개선 전후 결과를 다음 형식으로 비교한다.

항목 개선 전 개선 후
━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━ ━━━━━━━━━
분류 대상 거래 수
───────────────────── ───────── ─────────
계좌 연동 전체 시간
───────────────────── ───────── ─────────
소비 분류 전체 시간
───────────────────── ───────── ─────────
처리량(건/초)
───────────────────── ───────── ─────────
FastAPI 호출 횟수
───────────────────── ───────── ─────────
FastAPI 누적 시간
───────────────────── ───────── ─────────
fallback 건수
───────────────────── ───────── ─────────
미분류 잔여 건수

후속 검토

제한된 병렬 처리 이후에도 사용자 체감 시간이 충분히 개선되지 않으면 다음 작업을 별도 이슈로 검토한다.

• 계좌 연동과 소비 분류의 비동기 분리
• 소비 분류 진행 상태 조회 API
• 프론트엔드 분류 진행/완료 UI
• FastAPI 내부 추론 및 모델 호출 최적화