Files

JiWoong Sul f08b7fec79 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

4.2 KiB

Raw Blame History

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

📋 요약

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

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

🔍 상세 분석

1. 서버측 스키마 분석

API 응답 형식

// 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의 계정

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

update_passwords_to_argon2.sql의 계정

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

RELEASE_NOTES의 예시

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

📊 문제점 요약

클라이언트측 문제

없음 - Flutter 클라이언트는 올바르게 구현되어 있습니다:

✅ snake_case 필드 매핑 (@JsonKey 사용)
✅ 다양한 응답 형식 처리 (ResponseInterceptor)
✅ username/email 모두 지원
✅ 적절한 에러 처리

서버측 문제

테스트 계정 정보 불명확
- 실제 프로덕션 서버의 테스트 계정 정보가 문서화되지 않음
- 이메일 도메인 변경 (.com → .kr)
- 패스워드 변경 가능성 (password123 → admin123!)
패스워드 해시 알고리즘 마이그레이션
- bcrypt에서 argon2로 변경
- 기존 테스트 계정들의 패스워드가 무엇인지 불명확

💡 해결 방안

즉시 가능한 해결책

1. Mock 모드 사용 (권장)

// lib/core/config/environment.dart
Environment.useApi = false;  // Mock 모드 활성화

테스트 계정: admin@superport.com / admin123

2. 로그 활성화하여 디버깅

Environment.enableLogging = true;  // 상세 로그 출력

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

실제 테스트 계정 정보 제공
- 정확한 username/email
- 현재 사용 가능한 패스워드
- 계정의 role 및 권한
API 문서 업데이트
- 현재 프로덕션 서버의 정확한 스펙
- 테스트 환경 접속 정보
- 인증 방식 상세 설명
개발/스테이징 서버 제공
- 프로덕션과 동일한 환경의 테스트 서버
- 자유롭게 테스트 가능한 계정

🔧 권장 개발 프로세스

당장은 Mock 모드로 개발 진행
- 모든 기능을 Mock 데이터로 구현 및 테스트
- UI/UX 개발에 집중
서버 팀과 협업
- 정확한 API 스펙 확인
- 테스트 계정 정보 획득
- 개발 서버 접근 권한 요청
점진적 통합
- 기능별로 실제 API 연동 테스트
- 문제 발생시 즉시 피드백

📝 결론

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

4.2 KiB Raw Blame History