# API 스키마 불일치 문제 종합 분석 보고서

## 📋 요약

서버측 API 스키마 변경으로 인한 로그인 실패 문제를 분석한 결과, 다음과 같은 주요 원인들을 발견했습니다:

1. **패스워드 해시 알고리즘 변경**: bcrypt → argon2
2. **이메일 도메인 불일치**: 일부 계정에서 .com → .kr로 변경
3. **실제 서버 데이터베이스와 샘플 데이터의 불일치**

## 🔍 상세 분석

### 1. 서버측 스키마 분석

#### API 응답 형식
```rust
// src/dto/auth_dto.rs
pub struct LoginResponse {
    pub access_token: String,
    pub refresh_token: String,
    pub token_type: String,
    pub expires_in: i64,
    pub user: UserInfo,
}

pub struct UserInfo {
    pub id: i32,
    pub username: String,
    pub email: String,
    pub name: String,
    pub role: String,
}
```

- ✅ **snake_case 사용**: 클라이언트가 기대하는 형식과 일치
- ✅ **응답 래핑**: `ApiResponse::success(response)` 형식으로 `{success: true, data: {...}}` 구조 사용

### 2. 인증 방식 변경 사항

#### v0.2.1 업데이트 (2025년 7월 30일)
- username 또는 email로 로그인 가능하도록 개선
- 기존: email만 사용
- 변경: username 또는 email 중 하나 사용 가능

#### 패스워드 해시 변경
- **이전**: bcrypt (`$2b$12$...`)
- **현재**: argon2 (`$argon2id$v=19$...`)
- **영향**: 기존 bcrypt 해시로는 로그인 불가

### 3. 테스트 계정 정보 불일치

#### sample_data.sql의 계정
```sql
-- 관리자 계정
username: 'admin'
email: 'admin@superport.com'  -- .com 도메인
password: 'password123'  -- bcrypt 해시
```

#### update_passwords_to_argon2.sql의 계정
```sql
-- 관리자 계정
email: 'admin@superport.kr'  -- .kr 도메인으로 변경됨
password: argon2 해시 (원본 패스워드 불명)
```

#### RELEASE_NOTES의 예시
```bash
# 패스워드가 'admin123!'로 표시됨
{"username": "admin", "password": "admin123!"}
```

## 📊 문제점 요약

### 클라이언트측 문제

**없음** - Flutter 클라이언트는 올바르게 구현되어 있습니다:
- ✅ snake_case 필드 매핑 (`@JsonKey` 사용)
- ✅ 다양한 응답 형식 처리 (ResponseInterceptor)
- ✅ username/email 모두 지원
- ✅ 적절한 에러 처리

### 서버측 문제

1. **테스트 계정 정보 불명확**
   - 실제 프로덕션 서버의 테스트 계정 정보가 문서화되지 않음
   - 이메일 도메인 변경 (.com → .kr)
   - 패스워드 변경 가능성 (password123 → admin123!)

2. **패스워드 해시 알고리즘 마이그레이션**
   - bcrypt에서 argon2로 변경
   - 기존 테스트 계정들의 패스워드가 무엇인지 불명확

## 💡 해결 방안

### 즉시 가능한 해결책

#### 1. Mock 모드 사용 (권장)
```dart
// lib/core/config/environment.dart
Environment.useApi = false;  // Mock 모드 활성화
```
- 테스트 계정: `admin@superport.com` / `admin123`

#### 2. 로그 활성화하여 디버깅
```dart
Environment.enableLogging = true;  // 상세 로그 출력
```

### 서버 관리자에게 요청할 사항

1. **실제 테스트 계정 정보 제공**
   - 정확한 username/email
   - 현재 사용 가능한 패스워드
   - 계정의 role 및 권한

2. **API 문서 업데이트**
   - 현재 프로덕션 서버의 정확한 스펙
   - 테스트 환경 접속 정보
   - 인증 방식 상세 설명

3. **개발/스테이징 서버 제공**
   - 프로덕션과 동일한 환경의 테스트 서버
   - 자유롭게 테스트 가능한 계정

## 🔧 권장 개발 프로세스

1. **당장은 Mock 모드로 개발 진행**
   - 모든 기능을 Mock 데이터로 구현 및 테스트
   - UI/UX 개발에 집중

2. **서버 팀과 협업**
   - 정확한 API 스펙 확인
   - 테스트 계정 정보 획득
   - 개발 서버 접근 권한 요청

3. **점진적 통합**
   - 기능별로 실제 API 연동 테스트
   - 문제 발생시 즉시 피드백

## 📝 결론

Flutter 클라이언트의 구현은 정상이며, 서버측의 인증 정보 불일치가 주요 원인입니다. Mock 모드를 활용하여 개발을 계속 진행하면서, 서버 팀과 협력하여 실제 API 연동을 준비하는 것이 최선의 방법입니다.