🛠️ API-Football 동기화 장애 대응 및 상태 표시 개선

[son0307]

변경 내용

동기화 상태 추적 확장

• api_football_sync_status에 다음 정보를 저장하도록 확장
  • 마지막 시도 시각
  • 마지막 성공 시각
  • 마지막 실패 시각
  • 연속 실패 횟수
  • 마지막 오류 메시지
  • 동기화 상태
• 동기화 상태를 정상, 지연, 실패, 재시도 대기 중, 기록 없음으로 구분
• Teams, Standings, Fixtures, Fixture Details, Players, Injuries 동기화의 시도 및 성공 기록 연동
• 실패 재시도 스케줄러 상태를 동기화 상태에 반영
• 관리자 Manual Sync 패널에서 작업별 성공·시도·실패 시각과 오류 원인 표시

사용자 화면 데이터 기준 시각 표시

• 순위 및 경기 화면에 최근 업데이트 시간 표시
• 마지막 성공 시각이 24시간 이상 지난 경우 지연 상태로 처리
• 관리자 수동 갱신은 기존 /api/v1/admin/sync/** 흐름을 재사용
• 관리자 권한 검증, 감사 로그, 프론트·백엔드 쿨다운 적용

API-Football 전체 장애 대응

• 모든 API-Football 요청에 공통으로 적용되는 전역 서킷 브레이커 추가
• 연속 실패 임계치 도달 시 일정 시간 외부 API 호출 차단
• 정상 응답 수신 시 실패 상태와 차단 상태 초기화
• 기존 지수 백오프 재시도와 스케줄러 재시도 로직 유지
• 전체 API 장애 상태를 관리자 화면에서 확인 가능하도록 표시

관리자 감사 로그 개선

• Recent Admin Logs에 요청 식별 파라미터 표시
• leagueId, season, teamId, playerId, fixtureId, eventSequence 등을 안전하게 노출
• 수정 전후 값이나 외부 API 오류 본문 전체는 계속 숨김

검증

• 프론트엔드 TypeScript 및 Vite 빌드 통과
• AdminService 관련 테스트 통과
• 관리자 수동 동기화 USER 권한 403 테스트 통과
• 모바일 순위·경기 화면에서 업데이트 시각과 레이아웃 확인

[github-actions]

Codex PR Review

PR 요약

요약

API-Football 동기화의 실패·지연 상태를 더 세밀하게 추적하고, 관리자와 사용자 화면에서 최신 데이터 시점과 장애 상태를 더 잘 보이도록 개선했습니다. 또한 전역 서킷 브레이커와 공용 수동 동기화 엔드포인트를 추가해 장애 시 대응성과 재시도 흐름을 강화했습니다.

주요 변경사항

• 동기화 상태에 마지막 시도/성공/실패 시각, 연속 실패 횟수, 오류 메시지, 상태값을 저장하도록 확장
• 관리자 페이지에서 동기화 작업별 상태 배지, 성공/시도/실패 시각, 실패 사유를 표시하도록 개선
• 순위/경기 화면에 최근 업데이트 시각과 데이터 신선도 표시를 추가하고, 지연 시 수동 갱신 버튼 제공
• API-Football 요청 전역 서킷 브레이커를 추가해 연속 실패 시 외부 API 호출을 일시 차단
• Teams, Standings, Fixtures, Players, Injuries, Fixture Details 동기화 시도/성공/실패 기록을 연동
• 수동 동기화용 /api/v1/sync/** POST 엔드포인트를 추가하고 인증 및 쿨다운을 적용
• 관리자 감사 로그에 leagueId, season, teamId, playerId, fixtureId 등 요청 식별자만 안전하게 노출하도록 개선
• 상태 표시용 UI 스타일과 관련 타입/API를 정리

영향 범위

• 라이브 경기/순위 화면의 데이터 신선도 표시
• Fixture / Standings 공개 수동 동기화
• 관리자 동기화 패널 및 감사 로그
• API-Football 동기화 상태 관리
• 인증/권한 설정
• 애플리케이션 설정 및 CI/빌드 관련 코드

검증

• 프론트엔드 TypeScript 및 Vite 빌드 통과
• AdminService 관련 테스트 통과
• 관리자 수동 동기화 USER 권한 403 테스트 통과

시니어 개발자 리뷰

• [P1] src/main/java/com/son/soccerStreaming/apifootball/service/ApiFootballSyncStatusController.java:29-94 - 공용 동기화 API가 관리자 권한 없이 노출됨

  • 문제: /api/v1/sync/statuses는 인증만 필요하고, /api/v1/sync/standings, /api/v1/sync/fixtures는 authenticated()만 걸려 있습니다. 프론트에서는 currentUser가 있으면 버튼을 노출하지만, 서버 측에서 관리자 권한 검증이 없어 일반 로그인 사용자가 외부 데이터 동기화를 직접 트리거할 수 있습니다. @AuthenticationPrincipal userDetails도 실제로 사용되지 않습니다.
  • 영향: 비관리자 사용자가 수동 동기화를 반복 호출해 외부 API 호출량/레이트리밋을 소모하거나, 운영 의도와 다르게 데이터 갱신을 유발할 수 있습니다.
  • 수정 방향: /api/v1/sync/** POST 엔드포인트를 hasRole("ADMIN")로 제한하고, 컨트롤러에서도 AuthUserDetails 역할 검증을 추가하세요. 최소한 현재 userDetails를 사용해 ADMIN인지 확인해야 합니다.

• [P1] src/main/java/com/son/soccerStreaming/apifootball/service/ApiFootballSyncStatusController.java:40-57,75-92 - 공용 수동 동기화 쿨다운이 서버 인스턴스 로컬 메모리라 우회 가능

  • 문제: publicSyncCooldowns가 ConcurrentHashMap의 인메모리 상태라서, 서버가 여러 대이거나 재시작되면 쿨다운이 사라집니다. 같은 키라도 인스턴스별로 각각 호출 가능하고, 장애 시 반복 요청을 막지 못합니다.
  • 영향: 운영 환경에서 “30초 쿨다운”이 사실상 무력화되어 외부 API 보호 목적을 달성하지 못할 수 있습니다.
  • 수정 방향: 최소한 관리자 전용으로 제한하고, 필요하면 기존 AdminSyncJob/락 메커니즘처럼 저장소 기반 또는 분산 가능한 제한으로 바꾸세요. 현재 범위에서는 인스턴스 로컬 제한이라는 점을 전제로 사용자 노출을 줄이는 것이 안전합니다.

• [P1] frontend/src/pages/LeagueStandingsPage.tsx:67-112, frontend/src/pages/LeagueFixturesPage.tsx:233-278, src/main/java/com/son/soccerStreaming/apifootball/service/ApiFootballSyncStatusController.java:58-93 - 재요청 직후 상태 갱신이 누락되어 버튼이 계속 “지연”으로 남을 수 있음

  • 문제: 두 페이지 모두 refresh*Sync() 성공 시 loadStandings/loadFixtures와 loadSyncStatus()를 호출하지만, 서버의 requestPublicSync()는 동기화 수행 후에도 실패 시 상태를 갱신할 수 있고, 성공 시에도 loadSyncStatus()가 즉시 호출되더라도 아직 반영 전 상태를 읽을 수 있습니다. 또한 실패 시에는 상태만 다시 읽고 UI 메시지는 유지되므로 사용자는 실제 재시도 결과를 즉시 구분하기 어렵습니다.
  • 영향: 사용자는 새로고침을 눌렀는데도 여전히 stale/failed 상태가 남아 있어서, 동기화가 실패했는지 아직 처리 중인지 헷갈릴 수 있습니다. 모바일에서는 특히 혼란이 커집니다.
  • 수정 방향: 공개 동기화 API가 비동기라면 “요청됨”과 “완료됨”을 명확히 분리하고, 프론트는 성공 응답 후 일정 지연 뒤 상태를 재조회하거나 polling 하세요. 최소한 요청 성공 시에는 상태 메시지를 “요청됨/처리 중”으로 표시해 오해를 줄이세요.

• [P2] src/main/java/com/son/soccerStreaming/apifootball/client/ApiFootballCircuitBreaker.java:18-21,42-43 - 서킷 브레이커 상태가 인스턴스 로컬이라 배포 환경에서 보호가 불완전함

  • 문제: consecutiveFailures와 openUntilEpochMs가 메모리 내 Atomic 값이라 서버 인스턴스마다 별도입니다. 한 인스턴스에서 연속 실패가 쌓여도 다른 인스턴스는 그대로 외부 API를 계속 호출할 수 있습니다.
  • 영향: 멀티 인스턴스 환경에서 API-Football 장애 시 호출 차단 효과가 절반 이하로 떨어질 수 있습니다.
  • 수정 방향: 현재 구조에서 완전한 분산 서킷 브레이커까지는 범위가 크니, 최소한 운영 문서/설정으로 단일 인스턴스 가정이 아니면 기대 효과가 제한적임을 명시하거나, 공통 상태 저장소를 쓰는 방향을 고려하세요.

• [P2] src/main/java/com/son/soccerStreaming/apifootball/service/ApiFootballSyncStatusService.java:25-62 및 src/main/java/com/son/soccerStreaming/apifootball/entity/ApiFootballSyncStatus.java:33-55 - 실패 시 이전 성공 시각이 보존되지 않아 “지연” 판정이 부정확할 수 있음

  • 문제: recordFailure()가 lastSuccessAt를 유지하긴 하지만 recordAttempt()는 최초 1회만 lastSyncedAt을 채우고, recordRetryPending()/recordFailure()가 상태 전환 중 lastSyncedAt 의미를 일관되게 유지하지 않습니다. 특히 toSyncStatusItem()과 프론트의 lastSuccessfulSyncTime()가 lastSuccessAt → lastSyncedAt 순으로 fallback 하는데, 실패/재시도 패턴에 따라 “최근 성공 시각”과 “마지막 시도 시각”이 섞여 보일 수 있습니다.
  • 영향: 관리자 화면과 사용자 화면의 “최근 업데이트” 표기가 실제 최신 성공 시점과 다르게 해석될 수 있습니다.
  • 수정 방향: lastSyncedAt는 성공 시각으로만 쓰고, 실패/시도는 별도 필드만 사용하도록 의미를 명확히 맞추세요. 프론트 fallback도 lastSuccessAt만 기준으로 통일하는 편이 안전합니다.

• [P2] frontend/src/pages/LeagueFixturesPage.tsx:368-376, frontend/src/pages/LeagueStandingsPage.tsx:129-137 - 업데이트 시각 배지가 작은 화면에서 쉽게 줄바꿈/클리핑될 수 있음

  • 문제: data-freshness가 display:flex + justify-content: space-between인데 버튼/문구를 한 줄에 고정하는 추가 처리 없이 긴 한국어/날짜 텍스트가 들어갑니다. 특히 모바일에서 날짜 문구와 버튼이 한 줄에 들어가면 폭이 부족해져 잘리거나 두 줄로 깨질 수 있습니다.
  • 영향: 사용자가 최신성 정보를 빠르게 스캔하기 어려워지고, 버튼 영역이 눌리기 힘들어질 수 있습니다.
  • 수정 방향: 모바일 폭에서는 세로 배치로 전환하거나 flex-wrap: wrap을 추가하세요. 최소한 텍스트와 버튼이 자연스럽게 내려가도록 처리하는 게 좋습니다.

보안 리뷰

• [Medium] src/main/java/com/son/soccerStreaming/apifootball/service/ApiFootballSyncStatusController.java:20-80 - 공개 동기화 엔드포인트에 인증만 있고 관리자 권한 제한이 없음

  • 문제:
    • /api/v1/sync/standings, /api/v1/sync/fixtures POST가 authenticated()만 요구합니다. 즉, 일반 로그인 사용자가 외부 API-Football 동기화를 트리거할 수 있습니다.
    • PR 설명상 “관리자 수동 갱신” 용도인데, 실제 라우팅은 사용자 화면에서 currentUser만 있으면 버튼이 표시되고 요청도 시도됩니다.
  • 공격/노출 시나리오:
    • 임의의 일반 사용자가 반복적으로 동기화 요청을 보내 외부 API 쿼터 소진, 동기화 큐 적체, 관리자 운영 방해를 유발할 수 있습니다.
    • 과도한 요청으로 서킷 브레이커/쿨다운이 개별 키 기준으로만 작동하면, 여러 계정 또는 여러 세션을 통해 우회 시도가 가능할 수 있습니다.
  • 수정 방향:
    • 해당 공개 동기화 POST는 ROLE_ADMIN 전용으로 제한하거나, 최소한 서버 측에서 관리자 권한을 명시적으로 검증하세요.
    • 프론트엔드의 버튼 표시도 관리자에게만 노출되도록 맞추는 것이 좋습니다.

• [Medium] frontend/src/pages/LeagueStandingsPage.tsx:67-110, frontend/src/pages/LeagueFixturesPage.tsx:233-270 - 일반 사용자 화면에서 동기화 요청 UI와 호출이 노출됨

  • 문제:
    • 페이지 컴포넌트가 currentUser만 있으면 stale 상태에서 refresh 버튼을 보여주고 /api/v1/sync/**로 POST를 보냅니다.
    • 현재 백엔드 인증 정책상 일반 사용자도 접근 가능하므로, 프론트는 사실상 비관리자 사용자에게 동기화 기능을 노출합니다.
  • 공격/노출 시나리오:
    • 로그인한 일반 사용자가 경기/순위 페이지에서 데이터 갱신 요청을 반복해 서비스 리소스와 외부 API를 소모할 수 있습니다.
  • 수정 방향:
    • 사용자 화면에서 버튼을 관리자 권한 보유 시에만 표시하세요.
    • 백엔드 권한 체크도 반드시 함께 강화해야 합니다.

• [Low] src/main/java/com/son/soccerStreaming/admin/service/AdminService.java:1299-1368 - 감사 로그 상세 노출 범위가 부분적으로 확장됨

  • 문제:
    • publicAuditDetails()가 targetId, leagueId, teamId, playerId, fixtureId, eventSequence 등을 조합해 외부에 노출합니다.
    • 본문에서 민감 데이터 전체는 숨긴다고 했지만, AdminAuditType.SYNC의 details를 파싱해 노출하므로 향후 details 포맷이 바뀌면 예상치 못한 값이 드러날 수 있습니다.
  • 공격/노출 시나리오:
    • 감사 로그 조회 권한이 있는 사용자에게 내부 식별자와 작업 파라미터가 더 많이 노출됩니다.
  • 수정 방향:
    • 허용 파라미터 화이트리스트를 더 엄격히 유지하고, 포맷 변경 시 누출되지 않도록 테스트를 추가하세요.
    • 특히 details 문자열 전체를 파싱하는 로직은 입력 형식이 바뀌면 과노출 위험이 있으니 구조화된 필드 사용을 고려하세요.
      Model: gpt-5.4-mini