fix: API 응답 파싱 오류 수정 및 에러 처리 개선

주요 변경사항: - 창고 관리 API 응답 구조와 DTO 불일치 수정 - WarehouseLocationDto에 code, manager_phone 필드 추가 - RemoteDataSource에서 API 응답을 DTO 구조에 맞게 변환 - 회사 관리 API 응답 파싱 오류 수정 - CompanyResponse의 필수 필드를 nullable로 변경 - PaginatedResponse 구조 매핑 로직 개선 - 에러 처리 및 로깅 개선 - Service Layer에 상세 에러 로깅 추가 - Controller에서 에러 타입별 처리 - 새로운 유틸리티 추가 - ResponseInterceptor: API 응답 정규화 - DebugLogger: 디버깅 도구 - HealthCheckService: 서버 상태 확인 - 문서화 - API 통합 테스트 가이드 - 에러 분석 보고서 - 리팩토링 계획서
2025-07-31 19:15:39 +09:00
parent ad2c699ff7
commit f08b7fec79
89 changed files with 10521 additions and 892 deletions
--- a/doc/api_schema_mismatch_analysis.md
+++ b/doc/api_schema_mismatch_analysis.md
@@ -0,0 +1,143 @@
+# 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 연동을 준비하는 것이 최선의 방법입니다.