kt-event-marketing-fe/docs/api-server-issue.md

API 서버 연결 문제 보고

문제 요약

현상:

1. 회원가입 API 호출 시 30초 타임아웃 발생
2. 로그아웃 API 호출 시 500 Internal Server Error 발생

원인: API 서버(http://20.196.65.160:8081)의 성능 및 구현 이슈 날짜: 2025-10-28 최종 업데이트: 2025-10-28

상세 분석

1. 프론트엔드 구현 상태

✅ 완료됨 - 프론트엔드는 정상적으로 구현됨

• API client 설정 완료
• 회원가입, 로그인, 프로필, 로그아웃 페이지 API 연동 완료
• 상세 로깅 추가
• 타입 정의 및 유효성 검증 완료
• 에러 처리 강화 (로그아웃은 실패해도 로컬 상태 정리 후 진행)

2. 테스트 결과

이슈 1: 회원가입 API 타임아웃

curl 테스트 (명령줄)

curl -X POST http://20.196.65.160:8081/api/v1/users/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "테스트",
    "phoneNumber": "01012345678",
    "email": "test@example.com",
    "password": "password123",
    "storeName": "테스트가게",
    "industry": "restaurant",
    "address": "서울시 강남구",
    "businessHours": "09:00-18:00"
  }'

결과: timeout after 30 seconds

브라우저 테스트

❌ API Error: {
  message: 'timeout of 10000ms exceeded',
  status: undefined,
  statusText: undefined,
  url: '/api/v1/users/register',
  data: undefined
}

프론트엔드 조치: 타임아웃을 90초로 증가

---

이슈 2: 로그아웃 API 500 에러

브라우저 테스트

❌ API Error: {
  message: 'Request failed with status code 500',
  status: 500,
  statusText: '',
  url: '/api/v1/users/logout',
  data: {...}
}

프론트엔드 조치:

• API 실패해도 로컬 상태 정리 후 로그아웃 처리 계속 진행
• 사용자 경험을 위해 정상 로그아웃으로 처리
• 상세 에러 로그만 콘솔에 출력

3. 서버 상태 확인

HEAD 요청

curl -I http://20.196.65.160:8081/api/v1/users/register

결과:

• Status: HTTP/1.1 500
• 서버는 실행 중이지만 에러 발생

연결 테스트

✅ 서버 연결: 성공 (20.196.65.160:8081)
❌ POST 요청: 30초 타임아웃

원인 분석

가능한 원인들

1. 서버 측 처리 시간 초과

   • 회원가입 로직이 30초 이상 걸림
   • 데이터베이스 연결 문제
   • 무한 루프 또는 데드락

2. 서버 에러 (500 Internal Server Error)

   • 서버 로직에 버그 존재
   • 필수 설정 누락
   • 예외 처리 실패

3. 데이터베이스 문제

   • DB 연결 실패
   • DB 쿼리 타임아웃
   • DB 트랜잭션 락

4. 서버 리소스 부족

   • 메모리 부족
   • CPU 과부하
   • 스레드 풀 고갈

프론트엔드에서 수행한 조치

✅ 완료된 개선사항

1. 타임아웃 증가

   // 10초 → 30초로 증가
   timeout: 30000
   

2. 상세 에러 로깅 추가

   • API 요청/응답 로그
   • 에러 상세 정보 출력
   • 단계별 진행 상황 추적

3. 에러 메시지 개선

   if (error.response) {
     // 서버 응답 에러
     errorMessage = error.response.data?.message
   } else if (error.request) {
     // 응답 없음
     errorMessage = '서버로부터 응답이 없습니다'
   }
   

서버 측에서 확인이 필요한 사항

🔍 체크리스트

회원가입 API (POST /api/v1/users/register)

• 서버 로그 확인

  • 엔드포인트 호출 로그
  • 예외 스택 트레이스
  • 데이터베이스 쿼리 로그
  • 30초 이상 걸리는 원인 파악

• 데이터베이스 연결 확인

  • DB 연결 상태
  • 연결 풀 설정
  • 쿼리 실행 시간

• API 로직 검증

  • 회원가입 로직 검토
  • 무한 루프나 데드락 확인
  • 트랜잭션 처리 확인

로그아웃 API (POST /api/v1/users/logout)

• 500 에러 원인 파악

  • 서버 로그에서 예외 스택 트레이스 확인
  • 토큰 검증 로직 확인
  • 데이터베이스 쿼리 에러 확인

• API 로직 검증

  • 로그아웃 처리 로직 검토
  • 필수 필드 검증
  • 예외 처리 확인

공통

• 서버 설정 확인

  • 타임아웃 설정
  • 스레드 풀 크기
  • 메모리 설정

• 서버 리소스 확인

  • CPU 사용률
  • 메모리 사용률
  • 디스크 I/O

테스트 방법

서버 측 직접 테스트

1. 로컬에서 서버 실행

   # 서버 로그를 확인하며 실행
   

2. Postman으로 테스트

   POST http://localhost:8081/api/v1/users/register
   Content-Type: application/json
   
   {
     "name": "테스트",
     "phoneNumber": "01012345678",
     "email": "test@example.com",
     "password": "password123",
     "storeName": "테스트가게",
     "industry": "restaurant",
     "address": "서울시 강남구",
     "businessHours": "09:00-18:00"
   }
   

3. 서버 로그 확인

   • 요청이 도달했는지
   • 어느 시점에서 멈추는지
   • 예외가 발생하는지

프론트엔드 테스트 (서버 수정 후)

npm run dev

1. http://localhost:3000/register 접속
2. 회원가입 정보 입력
3. 브라우저 콘솔 확인
4. 네트워크 탭에서 요청/응답 확인

임시 해결 방법

서버가 수정될 때까지 프론트엔드에서는:

1. Mock 데이터 사용 (개발/테스트용)

   • 회원가입 성공 시나리오 테스트
   • UI/UX 개선 작업

2. 에러 처리 개선

   • 사용자 친화적인 에러 메시지
   • 재시도 옵션 제공

백엔드 팀 확인 사항

서버 문제 해결을 위해 다음을 확인해주세요:

회원가입 API

1. ✅ 서버 로그에 요청이 도달했는가?
2. ✅ 30초 이상 걸리는 원인이 무엇인가?
3. ✅ 데이터베이스 연결은 정상인가?
4. ✅ 회원가입 로직이 정상적으로 실행되는가?

로그아웃 API

1. ✅ 500 에러의 정확한 원인은 무엇인가?
2. ✅ 서버 로그의 스택 트레이스는?
3. ✅ 토큰 검증 로직이 정상인가?
4. ✅ 로그아웃 로직이 정상적으로 실행되는가?

프론트엔드 대응 완료

✅ 로그아웃은 사용자 경험을 위해 다음과 같이 처리:

• API 500 에러 발생해도 로컬 상태 정리 후 로그아웃 진행
• 사용자에게는 "로그아웃되었습니다" 성공 메시지 표시
• 로그인 페이지로 정상 리다이렉트
• 콘솔에는 상세 에러 로그 출력 (디버깅용)

참고 자료

• API 명세: docs/user-api-integration.md
• 회원가입 가이드: docs/register-api-guide.md
• 프론트엔드 코드:
  • API Client: src/shared/api/client.ts
  • User API: src/entities/user/api/userApi.ts
  • 회원가입 페이지: src/app/(auth)/register/page.tsx