kt-event-marketing-fe/USER_API_CHANGES.md

# User API 타입 변경사항 (2025-01-30)

## 📋 주요 변경사항 요약

### **userId 및 storeId 타입 변경: `number` → `string` (UUID)**

백엔드 API 스펙에 따라 userId와 storeId가 UUID 형식의 문자열로 변경되었습니다.

| 항목 | 기존 (Old) | 변경 (New) |
|------|-----------|-----------|
| **userId** | `number` (예: `1`) | `string` (예: `"550e8400-e29b-41d4-a716-446655440000"`) |
| **storeId** | `number` (예: `1`) | `string` (예: `"6ba7b810-9dad-11d1-80b4-00c04fd430c8"`) |

---

## 🔄 영향을 받는 인터페이스

### LoginResponse

**Before:**
```typescript
interface LoginResponse {
  token: string;
  userId: number;
  userName: string;
  role: string;
  email: string;
}
```

**After:**
```typescript
interface LoginResponse {
  token: string;
  userId: string; // UUID format
  userName: string;
  role: string;
  email: string;
}
```

### RegisterResponse

**Before:**
```typescript
interface RegisterResponse {
  token: string;
  userId: number;
  userName: string;
  storeId: number;
  storeName: string;
}
```

**After:**
```typescript
interface RegisterResponse {
  token: string;
  userId: string; // UUID format
  userName: string;
  storeId: string; // UUID format
  storeName: string;
}
```

### ProfileResponse

**Before:**
```typescript
interface ProfileResponse {
  userId: number;
  userName: string;
  phoneNumber: string;
  email: string;
  role: string;
  storeId: number;
  storeName: string;
  industry: string;
  address: string;
  businessHours: string;
  createdAt: string;
  lastLoginAt: string;
}
```

**After:**
```typescript
interface ProfileResponse {
  userId: string; // UUID format
  userName: string;
  phoneNumber: string;
  email: string;
  role: string;
  storeId: string; // UUID format
  storeName: string;
  industry: string;
  address: string;
  businessHours: string;
  createdAt: string;
  lastLoginAt: string;
}
```

### User

**Before:**
```typescript
interface User {
  userId: number;
  userName: string;
  email: string;
  role: string;
  phoneNumber?: string;
  storeId?: number;
  storeName?: string;
  industry?: string;
  address?: string;
  businessHours?: string;
}
```

**After:**
```typescript
interface User {
  userId: string; // UUID format
  userName: string;
  email: string;
  role: string;
  phoneNumber?: string;
  storeId?: string; // UUID format
  storeName?: string;
  industry?: string;
  address?: string;
  businessHours?: string;
}
```

---

## 📝 수정된 파일 목록

### 1. Type Definitions
- ✅ `src/entities/user/model/types.ts`
  - `LoginResponse.userId`: `number` → `string`
  - `RegisterResponse.userId`: `number` → `string`
  - `RegisterResponse.storeId`: `number` → `string`
  - `ProfileResponse.userId`: `number` → `string`
  - `ProfileResponse.storeId`: `number` → `string`
  - `User.userId`: `number` → `string`
  - `User.storeId`: `number` → `string`

### 2. Stores
- ✅ `src/stores/authStore.ts`
  - `User.id`: UUID 주석 추가

### 3. Components
- ✅ No changes required (타입 추론 사용)
  - `src/features/auth/model/useAuth.ts`
  - `src/app/(auth)/login/page.tsx`
  - `src/app/(auth)/register/page.tsx`

---

## 🧪 API 응답 예시

### 로그인 응답

**Before:**
```json
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "userId": 1,
  "userName": "홍길동",
  "role": "USER",
  "email": "user@example.com"
}
```

**After:**
```json
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "userName": "홍길동",
  "role": "USER",
  "email": "user@example.com"
}
```

### 회원가입 응답

**Before:**
```json
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "userId": 1,
  "userName": "홍길동",
  "storeId": 1,
  "storeName": "홍길동 고깃집"
}
```

**After:**
```json
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "userName": "홍길동",
  "storeId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "storeName": "홍길동 고깃집"
}
```

### 프로필 조회 응답

**Before:**
```json
{
  "userId": 1,
  "userName": "홍길동",
  "phoneNumber": "01012345678",
  "email": "user@example.com",
  "role": "USER",
  "storeId": 1,
  "storeName": "홍길동 고깃집",
  "industry": "restaurant",
  "address": "서울특별시 강남구",
  "businessHours": "09:00-18:00",
  "createdAt": "2025-01-01T00:00:00",
  "lastLoginAt": "2025-01-10T12:00:00"
}
```

**After:**
```json
{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "userName": "홍길동",
  "phoneNumber": "01012345678",
  "email": "user@example.com",
  "role": "USER",
  "storeId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "storeName": "홍길동 고깃집",
  "industry": "restaurant",
  "address": "서울특별시 강남구",
  "businessHours": "09:00-18:00",
  "createdAt": "2025-01-01T00:00:00",
  "lastLoginAt": "2025-01-10T12:00:00"
}
```

---

## 🚨 주의사항

### 1. localStorage 초기화 필요
기존에 number 타입으로 저장된 사용자 정보가 있다면 localStorage를 초기화해야 합니다:

```javascript
// 브라우저 콘솔에서 실행
localStorage.removeItem('accessToken');
localStorage.removeItem('user');
```

### 2. UUID 형식
- UUID는 표준 UUID v4 형식입니다: `550e8400-e29b-41d4-a716-446655440000`
- 하이픈(`-`)을 포함한 36자 문자열
- 비교 시 대소문자 구분 없음 (일반적으로 소문자 사용)

### 3. 기존 Mock 데이터
기존에 number 타입으로 작성된 Mock 데이터는 UUID 문자열로 변경해야 합니다:

**Before:**
```typescript
const mockUser = {
  userId: 1,
  storeId: 1,
  // ...
};
```

**After:**
```typescript
const mockUser = {
  userId: "550e8400-e29b-41d4-a716-446655440000",
  storeId: "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  // ...
};
```

### 4. 하위 호환성
- 이전 number 타입과는 호환되지 않습니다
- 기존 세션은 모두 무효화됩니다
- 사용자는 다시 로그인해야 합니다

---

## ✅ 마이그레이션 체크리스트

- [x] TypeScript 인터페이스 업데이트
- [x] 타입 정의 파일 수정 완료
- [x] 빌드 테스트 통과
- [ ] localStorage 초기화 (사용자)
- [ ] 개발 서버 테스트 (사용자)
- [ ] 실제 API 연동 테스트 (사용자)

---

## 🔗 관련 문서

- API 문서: http://kt-event-marketing-api.20.214.196.128.nip.io/api/v1/users/swagger-ui/index.html
- OpenAPI Spec: http://kt-event-marketing-api.20.214.196.128.nip.io/api/v1/users/v3/api-docs

---

## 📌 변경 이유

**백엔드 아키텍처 개선:**
- 분산 시스템에서 ID 충돌 방지
- 데이터베이스 독립적인 고유 식별자
- 보안 강화 (ID 추측 불가)
- 마이크로서비스 간 데이터 통합 용이

**UUID의 장점:**
- 전역적으로 고유한 식별자 (Globally Unique Identifier)
- Auto-increment ID의 한계 극복
- 분산 환경에서 중앙 조정 없이 생성 가능
- 보안성 향상 (순차적 ID 노출 방지)

---

## 🔄 롤백 방법

만약 이전 버전으로 돌아가야 한다면:

1. Git을 통한 코드 복원:
   ```bash
   git log --oneline  # 커밋 찾기
   git revert <commit-hash>  # 또는 특정 커밋으로 복원
   ```

2. localStorage 초기화:
   ```javascript
   localStorage.removeItem('accessToken');
   localStorage.removeItem('user');
   ```

3. 개발 서버 재시작:
   ```bash
   npm run dev
   ```

---

**문서 작성일**: 2025-01-30
**마지막 업데이트**: 2025-01-30
**변경 적용 버전**: v1.1.0