🛠️ 외부 API 호출 안정성 및 관리자 모니터링 개선

[son0307]

변경 사항

외부 API 공통 호출 안정성 개선

• API-Football, SerpAPI, OpenAI 호출에 공통 실행기를 적용했습니다.
• provider별 connect/read timeout을 설정하고 HTTP 상태 및 예외 유형에 따라 오류를 분류합니다.
• 408, API-Football 499, rate limit 429, 500/502/503/504, timeout 및 일시적인 네트워크 오류만 최대 3회 재시도합니다.
• 지수 백오프, jitter, Retry-After를 적용하고 인증·권한·잘못된 요청·quota 소진·응답 변환 오류는 재시도하지 않습니다.
• API-Football의 기존 서킷 브레이커를 공통 실행기와 연동하고, scheduler/startup 재실행은 최종 오류가 재시도 가능한 경우에만 예약합니다.

provider 상태 및 관리자 감사 로그 확장

• 별도 상태 테이블을 추가하지 않고 기존 api_football_sync_status를 API-Football, SerpAPI, OpenAI의 최신 상태 저장소로 확장했습니다.
• provider별 마지막 시도·성공·실패 시각, 연속 실패 횟수, operation, HTTP 상태, 오류 category, attempt 수를 최종 호출 결과 기준으로 저장합니다.
• 상태 저장을 별도 트랜잭션으로 처리하여 상위 작업이 rollback되더라도 최종 장애 기록이 남도록 했습니다.
• 관리자가 시작한 SerpAPI/OpenAI 호출만 EXTERNAL_API_CALL 감사 로그로 기록하고, scheduler 호출과 retry 중간 실패는 기록하지 않습니다.
• API 키, 요청 query, Authorization, prompt, 원문·번역 결과와 응답 본문은 감사 로그에서 제외했습니다.

관리자 및 뉴스 화면 개선

• 관리자 화면에 API-Football, SerpAPI, OpenAI의 최신 통신 상태 카드를 표시합니다.
• Recent Admin Logs에 외부 API 호출 유형, provider, 성공·실패 badge와 안전한 호출 메타데이터를 표시합니다.
• 뉴스 수집 상태가 Team 내부 DB ID와 API-Football teamId를 혼용해 마지막 수집 시각을 찾지 못하던 문제를 수정했습니다.
• 관리자 수동 수집과 scheduler 수집 모두 뉴스 탭의 마지막 수집 시각에 반영됩니다.

변경 이유

외부 API별로 timeout과 오류 처리 방식이 달라 일시 장애와 영구 오류를 일관되게 구분하기 어려웠고, retry 이후의 최종 상태와 관리자 호출 이력을 확인할 수 없었습니다. 공통 실행기와 기존 상태 테이블을 이용해 호출 안정성과 운영 가시성을 함께 개선했습니다.

또한 뉴스 수집 상태 행은 Team 내부 ID를 기본키로 사용하지만 API teamId로 조회하고 있어, 두 값이 다른 팀에서는 수집이 완료되어도 수집 기록 없음으로 표시되는 문제가 있었습니다.

API 및 설정 변경

• api_football_sync_status에 provider 공통 상태 필드를 추가합니다.
• admin_audit_log에 nullable provider 필드를 추가하고 EXTERNAL_API_CALL 유형을 추가합니다.
• API-Football, SerpAPI, OpenAI timeout과 공통 retry 설정을 환경 변수로 조정할 수 있습니다.
• 기존 관리자 응답 코드와 뉴스 조회·새로고침 API 형식은 유지합니다.

검증

• 외부 API 오류 분류, 재시도, quota/rate limit 구분, timeout 및 interrupt 테스트 통과
• provider 상태 생성, 실패 누적, 성공 복구 및 기존 API-Football 행 호환 테스트 통과
• 관리자 호출과 scheduler 호출의 감사 로그 분리 테스트 통과
• 뉴스 수집 시각 저장·조회 및 관리자 새로고침 관련 테스트 통과
• ./gradlew.bat compileJava 통과
• npm run build 통과
• 전체 백엔드 테스트 190개 중 189개 통과
  • contextLoads() 1개는 로컬 환경에서 Docker/Testcontainers를 사용할 수 없어 실패했습니다.

동일한 Docker 제약으로 로그인된 관리자 화면의 브라우저 직접 검증은 수행하지 못했습니다.

[github-actions]

Codex PR Review

PR 요약

요약

외부 API(API-Football, SerpAPI, OpenAI) 호출에 공통 재시도·타임아웃·오류 분류를 적용해 안정성을 높이고, 관리자 화면과 감사 로그에서 최신 통신 상태를 더 잘 보이도록 개선했습니다. 또한 뉴스 수집 상태 조회 기준을 정리해 마지막 수집 시각이 누락되던 문제를 수정했습니다.

주요 변경사항

• API-Football, SerpAPI, OpenAI에 공통 실행기와 provider별 timeout/retry 정책을 적용했습니다.
• 재시도 대상 오류만 최대 3회 재시도하고, Retry-After, 지수 백오프, jitter를 반영하도록 했습니다.
• 외부 API 호출 결과를 기존 상태 테이블에 provider별 최신 상태로 저장하도록 확장했습니다.
• 관리자 시작 외부 API 호출만 EXTERNAL_API_CALL 감사 로그로 남기고, 민감한 요청/응답 내용은 제외했습니다.
• 관리자 화면에 SerpAPI/OpenAI 상태 카드와 외부 API 호출 메타데이터를 추가했습니다.
• 뉴스 수집 상태 조회를 team 내부 ID/외부 teamId 혼용 문제 없이 동작하도록 수정했습니다.
• 관리자 수동 수집/번역 요청 시 사용자 정보를 외부 API 호출 컨텍스트에 반영하도록 변경했습니다.

영향 범위

• 외부 API 호출 안정성
• 관리자 모니터링/감사 로그
• 뉴스 수집 및 번역
• API-Football 스케줄러/스타트업 재시도
• 프론트엔드 관리자 UI
• 설정 및 DB 스키마

검증

• ./gradlew.bat compileJava 통과
• npm run build 통과
• 백엔드 테스트 190개 중 189개 통과
• 자동 생성 요약 기준으로 확인된 테스트 정보 없음

시니어 개발자 리뷰

• [P1] src/main/java/com/son/soccerStreaming/global/externalapi/ExternalApiExecutor.java:91-132 - 429/4xx 오류 분류가 잘못되어 재시도 정책과 상태 기록이 틀어질 수 있음

  • 문제: classify()에서 400은 BAD_REQUEST로 비재시도 처리하지만, 401/403/404 외의 다른 4xx는 전부 BAD_REQUEST로 떨어집니다. 그런데 PR 설명상 “인증·권한·잘못된 요청·quota 소진·응답 변환 오류는 재시도하지 않는다”는 의도인데, 실제로는 예를 들어 422 같은 외부 API의 의미 있는 클라이언트 오류도 모두 동일 처리됩니다. 더 큰 문제는 429의 quota 판별이 OpenAI/SerpAPI 본문 문자열에 강하게 의존해서, 응답 형태가 조금만 바뀌어도 잘못 RATE_LIMITED로 분류되어 재시도됩니다.
  • 영향: 외부 API가 비정형/변형된 오류 바디를 반환하면 불필요한 재시도로 호출량과 지연이 늘고, 관리자 상태에도 잘못된 카테고리가 저장됩니다. 특히 뉴스 수집/번역 경로에서 rate limit과 quota exhausted를 잘못 구분하면 반복 실패가 길어질 수 있습니다.
  • 수정 방향: 4xx는 기본적으로 비재시도로 두되, 429는 provider별로 Retry-After/본문 파싱에 실패해도 안전하게 RATE_LIMITED 또는 QUOTA_EXHAUSTED로 보수적으로 처리하세요. BAD_REQUEST로 묶는 범위를 명확히 하고, provider 응답 형태가 바뀌어도 재시도 여부가 흔들리지 않게 분기 우선순위를 정리하는 것이 좋습니다.

• [P1] src/main/java/com/son/soccerStreaming/global/externalapi/ExternalApiExecutor.java:202-214 - Retry-After를 그대로 sleep해서 장시간 스레드 점유 가능

  • 문제: retryDelay()가 Retry-After 헤더를 그대로 반환하고, sleep()이 이를 그대로 Thread.sleep() 합니다. 상단에는 max-retry-after 설정이 있지만 실제로는 retryAfterExceedsLimit()일 때만 “최종 실패”로 끝내고, 그 이하라도 매우 긴 값을 그대로 기다립니다. 또한 retryAfter가 초 단위든 날짜든 결국 길게 잡히면 요청 스레드가 블로킹됩니다.
  • 영향: 외부 API가 Retry-After: 300 같은 값을 주면 요청 처리 스레드가 5분씩 묶일 수 있어, 관리자 수동 호출이나 배치 실행 중 스레드 고갈/응답 지연으로 이어질 수 있습니다.
  • 수정 방향: Retry-After는 maxRetryAfter로 상한을 두거나, 상한 초과 시 즉시 재시도 중단 대신 “지연 재시도 스케줄링”으로 넘겨야 합니다. 최소한 현재 동기 실행 흐름에서는 min(retryAfter, maxRetryAfter)로 잘라서 sleep 하세요.

• [P1] src/main/java/com/son/soccerStreaming/global/externalapi/ExternalApiExecutor.java:43-81 - 성공 후 감사 이벤트/상태 기록이 요청 스레드 예외로 유실될 수 있음

  • 문제: recordSuccess()와 publish()가 요청 성공 직후 동기적으로 호출되는데, recordSuccess() 실패 시 예외를 삼키고, publish()도 실패를 삼킵니다. 이 자체는 호출 성공에 영향을 주지 않지만, 실제로는 성공 이벤트/상태가 저장되지 않아 관리자 화면과 감사 로그가 누락될 수 있습니다. 반대로 실패 기록도 동일한 방식이라 상태 저장 실패 시 관측성이 크게 떨어집니다.
  • 영향: 외부 API는 성공했는데 관리자 상태가 계속 RUNNING/이전 실패로 남는 식의 운영 혼란이 생길 수 있습니다.
  • 수정 방향: 상태 저장 실패를 최소한 별도 경고 지표로 남기고, 가능한 경우 이벤트 발행/상태 저장을 애플리케이션 이벤트 리스너처럼 분리하되 실패 시에도 어떤 provider/operation에서 실패했는지 남겨야 합니다. 현재 구조를 유지한다면 recordSuccess/recordFailure/publish의 실패가 어디서 얼마나 발생하는지 계측을 강화하세요.

• [P2] frontend/src/pages/AdminPage.tsx:1172,1450-1480 - 외부 API 상태 카드를 모바일에서 한 섹션에 과도하게 몰아넣어 스캔성이 떨어질 수 있음

  • 문제: External APIs 섹션이 API-Football + SerpAPI + OpenAI 상태를 모두 한 패널 안에 나열합니다. 이미 관리자 페이지가 정보 밀도가 높은데, 카드 수가 늘어나면 모바일에서 긴 상태/오류 메시지와 버튼이 한 화면에 섞여 읽기 어려워집니다.
  • 영향: 사용자가 “어떤 provider가 문제인지” 빠르게 파악하기 어려워지고, 특히 긴 오류 메시지가 있으면 수동 새로고침 버튼이 아래로 밀려 UX가 나빠질 수 있습니다.
  • 수정 방향: 최소한 provider별 카드를 접을 수 있게 하거나, 상태 요약과 상세를 분리하세요. 지금 범위 내에서는 카드 간 간격/오류 메시지 길이 제한을 두는 정도가 안전합니다.

• [P2] src/main/java/com/son/soccerStreaming/news/controller/AdminTeamNewsController.java:19-30 - 관리자 인증 주입이 없으면 NPE 가능성

  • 문제: @AuthenticationPrincipal AuthUserDetails userDetails를 새로 받도록 바뀌었지만, 메서드 내부에서 userDetails.getId()를 바로 사용합니다. 이 엔드포인트는 관리자 전용으로 보이지만, 인증 필터 누락/만료/비정상 접근 시 userDetails가 null일 수 있습니다.
  • 영향: 인증 컨텍스트가 없는 요청에서 500이 발생해, 원래라면 401/403으로 처리되어야 할 케이스가 서버 오류로 보일 수 있습니다.
  • 수정 방향: userDetails == null이면 명시적으로 인증 오류를 반환하도록 방어 코드를 넣는 것이 안전합니다. 최소한 서비스 호출 전에 null 체크가 필요합니다.

보안 리뷰

중대한 보안 문제 없음
Model: gpt-5.4-mini
Diff was truncated to 90000 characters; review may be incomplete.