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 테스트 (명령줄)**
```bash
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 요청
```bash
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. **타임아웃 증가**
   ```typescript
   // 10초 → 30초로 증가
   timeout: 30000
   ```

2. **상세 에러 로깅 추가**
   - API 요청/응답 로그
   - 에러 상세 정보 출력
   - 단계별 진행 상황 추적

3. **에러 메시지 개선**
   ```typescript
   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. **로컬에서 서버 실행**
   ```bash
   # 서버 로그를 확인하며 실행
   ```

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. **서버 로그 확인**
   - 요청이 도달했는지
   - 어느 시점에서 멈추는지
   - 예외가 발생하는지

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

```bash
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`