f08b7fec79
주요 변경사항: - 창고 관리 API 응답 구조와 DTO 불일치 수정 - WarehouseLocationDto에 code, manager_phone 필드 추가 - RemoteDataSource에서 API 응답을 DTO 구조에 맞게 변환 - 회사 관리 API 응답 파싱 오류 수정 - CompanyResponse의 필수 필드를 nullable로 변경 - PaginatedResponse 구조 매핑 로직 개선 - 에러 처리 및 로깅 개선 - Service Layer에 상세 에러 로깅 추가 - Controller에서 에러 타입별 처리 - 새로운 유틸리티 추가 - ResponseInterceptor: API 응답 정규화 - DebugLogger: 디버깅 도구 - HealthCheckService: 서버 상태 확인 - 문서화 - API 통합 테스트 가이드 - 에러 분석 보고서 - 리팩토링 계획서
143 lines
4.2 KiB
Markdown
143 lines
4.2 KiB
Markdown
# 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 연동을 준비하는 것이 최선의 방법입니다. |