superport/doc/api_response_parsing_fix_summary.md

API 응답 파싱 오류 수정 요약

문제 상황

• API 응답은 정상적으로 수신됨 (로그에서 확인)
• 화면에는 에러 메시지 표시 (ServerFailure 또는 TypeError)
• 창고 관리와 회사 관리 페이지 모두 동일한 문제 발생

근본 원인

1. 창고 관리 (Warehouse):

   • WarehouseLocationListDto가 items 필드를 기대하나, API는 data 배열 직접 반환
   • DTO 필드와 API 응답 필드 불일치 (code, manager_phone 등)

2. 회사 관리 (Company):

   • ApiResponse가 필수 필드 message를 기대하나 API 응답에 없음
   • PaginatedResponse 구조와 API 응답 구조 불일치

수정 사항

1. WarehouseLocationDto 수정

// 실제 API 응답에 맞게 필드 수정
- code 필드 추가
- manager_phone 필드 추가  
- 없는 필드들을 nullable로 변경 (updated_at 등)

2. WarehouseRemoteDataSource 수정

// API 응답을 DTO 구조에 맞게 변환
final listData = {
  'items': dataList,  // data → items로 매핑
  'total': pagination['total'] ?? 0,
  // ... pagination 데이터 매핑
};

3. CompanyResponse DTO 수정

// API 응답에 없는 필수 필드를 nullable로 변경
- contact_position: String? (nullable)
- updated_at: DateTime? (nullable)

4. CompanyRemoteDataSource 수정

// ApiResponse/PaginatedResponse 대신 직접 파싱
// API 응답 구조를 PaginatedResponse 구조로 변환
return PaginatedResponse<CompanyListDto>(
  items: items,
  page: pagination['page'] ?? page,
  size: pagination['per_page'] ?? perPage,
  // ... 나머지 필드 매핑
);

5. 에러 처리 개선

• Service Layer에 상세 로깅 추가
• Controller에서 에러 타입별 처리
• Stack trace 로깅으로 디버깅 개선

테스트 방법

1. 웹 애플리케이션을 새로고침
2. 창고 관리 페이지 접속 → 데이터 정상 표시 확인
3. 회사 관리 페이지 접속 → 데이터 정상 표시 확인
4. 콘솔 로그에서 에러 없음 확인

향후 개선 사항

• API 응답 구조 문서화
• DTO와 API 스펙 일치성 검증 테스트 추가
• ResponseInterceptor에서 더 강력한 응답 정규화