superport/docs/migration/INCOMPATIBILITY.md

API 호환성 문제 목록

분석 일자: 2025-08-13
대상: Superport Flutter 앱 vs Backend API Schema
기준 문서: API_SCHEMA.md, ENTITY_MAPPING.md, MIGRATION_GUIDE.md

📋 목차

• 심각도 분류
• Critical Issues
• Major Issues
• Minor Issues
• Missing Features
• 마이그레이션 로드맵

---

🚦 심각도 분류

심각도	설명	대응 시간	영향도
🔴 Critical	앱 기능 중단, 데이터 손실 위험	즉시 (1일 이내)	전체 시스템
🟡 Major	주요 기능 제한, UX 문제	1주일 이내	핵심 기능
🟢 Minor	사소한 불편, 최적화	1개월 이내	개별 기능
🔵 Enhancement	신규 기능, 성능 개선	장기 계획	추가 가치

---

🔴 Critical Issues (즉시 수정 필요)

1. API 응답 형식 불일치

문제점: 현재 코드와 API 스키마의 응답 구조가 완전히 다름

현재 코드 (잘못됨)

// lib/data/models/common/api_response.dart
@Freezed(genericArgumentFactories: true)
class ApiResponse<T> with _$ApiResponse<T> {
  const factory ApiResponse({
    required bool success,      // ❌ 잘못된 필드명
    required String message,
    T? data,
    String? error,
  }) = _ApiResponse<T>;
}

API 스키마 (정답)

{
  "status": "success",         // ✅ 올바른 필드명
  "message": "Operation completed successfully",
  "data": { /* 실제 데이터 */ },
  "meta": { /* 메타데이터 (페이지네이션 등) */ }
}

영향도: 🔥 극심함 - 모든 API 호출이 영향받음

수정 방법:

// 수정된 ApiResponse
@Freezed(genericArgumentFactories: true)
class ApiResponse<T> with _$ApiResponse<T> {
  const factory ApiResponse({
    required String status,     // success/error
    required String message,
    T? data,
    ResponseMeta? meta,         // 새로 추가
  }) = _ApiResponse<T>;
}

// 새로운 메타 클래스
@freezed
class ResponseMeta with _$ResponseMeta {
  const factory ResponseMeta({
    PaginationMeta? pagination,
  }) = _ResponseMeta;
}

2. 페이지네이션 메타데이터 구조 불일치

문제점: 페이지네이션 응답 구조가 API 스키마와 다름

현재 코드 응답 파싱

// lib/data/datasources/remote/company_remote_datasource.dart (line 88-104)
final responseData = response.data;
if (responseData['success'] == true && responseData['data'] != null) {  // ❌
  final List<dynamic> dataList = responseData['data'];
  final pagination = responseData['pagination'] ?? {};                  // ❌
  
  return PaginatedResponse<CompanyListDto>(
    items: items,
    page: pagination['page'] ?? page,
    size: pagination['per_page'] ?? perPage,
    totalElements: pagination['total'] ?? 0,                            // ❌ 필드명 불일치
    totalPages: pagination['total_pages'] ?? 1,
    // ...
  );
}

API 스키마 올바른 구조

{
  "status": "success",
  "data": [...],
  "meta": {
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 150,
      "total_pages": 8,
      "has_next": true,
      "has_prev": false
    }
  }
}

수정 방법:

// 올바른 응답 파싱
if (responseData['status'] == 'success' && responseData['data'] != null) {
  final List<dynamic> dataList = responseData['data'];
  final meta = responseData['meta']?['pagination'] ?? {};
  
  return PaginatedResponse<CompanyListDto>(
    items: items,
    page: meta['current_page'] ?? page,
    size: meta['per_page'] ?? perPage,
    totalElements: meta['total'] ?? 0,
    totalPages: meta['total_pages'] ?? 1,
    first: !(meta['has_prev'] ?? false),
    last: !(meta['has_next'] ?? false),
  );
}

3. 소프트 딜리트 파라미터 불일치

문제점: API는 is_active 파라미터를 요구하지만, 일부 코드에서는 includeInactive 사용

현재 코드 (혼재)

// lib/data/datasources/remote/company_remote_datasource.dart (line 72-78)
Future<PaginatedResponse<CompanyListDto>> getCompanies({
  // ...
  bool? isActive,              // ✅ 올바름
  bool includeInactive = false, // ❌ API 스키마에 없음
}) async {
  final queryParams = {
    if (isActive != null) 'is_active': isActive,        // ✅ 올바름
    'include_inactive': includeInactive,                // ❌ 제거해야 함
  };
}

API 스키마 정의

GET /api/v1/companies?page=1&per_page=20&is_active=true

• is_active=true: 활성 데이터만
• is_active=false: 삭제된 데이터만
• is_active 미지정: 모든 데이터

수정 방법: includeInactive 파라미터 제거 및 is_active만 사용

---

🟡 Major Issues (우선 수정 필요)

4. JWT 토큰 구조 변경

문제점: JWT 클레임 구조가 변경됨

기존 JWT (추정)

{
  "user_id": 1,
  "username": "admin",
  "role": "admin"
}

새로운 JWT 구조

{
  "sub": 1,           // user_id 대신 sub 사용
  "username": "admin", 
  "role": "admin",    // admin|manager|staff
  "exp": 1700000000,
  "iat": 1699999000
}

영향도: AuthInterceptor 및 토큰 파싱 로직 수정 필요

5. Equipment 상태 Enum 확장

문제점: 장비 상태에 새로운 값 추가됨

현재 Equipment 상태

// lib/data/models/equipment/equipment_dto.dart
enum EquipmentStatus {
  @JsonValue('available') available,
  @JsonValue('inuse') inuse,
  @JsonValue('maintenance') maintenance,
  // disposed가 누락됨
}

API 스키마 Equipment 상태

enum EquipmentStatus {
  available,   // 사용 가능
  inuse,      // 사용 중  
  maintenance, // 점검 중
  disposed,   // 폐기 ⬅️ 새로 추가됨
}

수정 방법: EquipmentStatus enum에 disposed 추가

6. Company 모델 필드 누락

문제점: Company DTO에 새로운 필드들이 누락됨

현재 CompanyResponse

@freezed
class CompanyResponse with _$CompanyResponse {
  const factory CompanyResponse({
    // ... 기존 필드들
    @JsonKey(name: 'is_partner') @Default(false) bool isPartner,
    @JsonKey(name: 'is_customer') @Default(false) bool isCustomer,
    // company_types 필드는 이미 있음
  }) = _CompanyResponse;
}

API 스키마에서 추가된 필드

// CreateCompanyRequest에 추가 필요
@JsonKey(name: 'company_types') List<String>? companyTypes,  // ✅ 이미 있음
@JsonKey(name: 'is_partner') bool? isPartner,              // ✅ 이미 있음  
@JsonKey(name: 'is_customer') bool? isCustomer,            // ✅ 이미 있음

상태: ✅ 이미 대부분 구현됨 (양호)

---

🟢 Minor Issues (점진적 개선)

7. 에러 응답 처리 개선

문제점: 에러 응답 구조가 표준화되지 않음

현재 에러 처리

// lib/data/datasources/remote/company_remote_datasource.dart
catch (e, stackTrace) {
  if (e is ApiException) rethrow;
  throw ApiException(message: 'Error creating company: $e');
}

API 스키마 표준 에러 형식

{
  "status": "error",
  "message": "에러 메시지",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": [
      {
        "field": "name",
        "message": "Company name is required"
      }
    ]
  }
}

개선 방법: 구조화된 에러 객체 생성

8. 권한별 API 접근 제어

문제점: 일부 화면에서 사용자 권한 확인 누락

권한 매트릭스 (API 스키마)

역할	생성	조회	수정	삭제
Admin	✅	✅	✅	✅
Manager	✅	✅	✅	✅
Staff	⚠️	✅	⚠️	❌

현재 상태: UI에서 권한 체크 미흡

개선 방법:

// 권한 기반 UI 제어
if (currentUser.role == UserRole.staff) {
  return SizedBox(); // 삭제 버튼 숨김
}

9. 날짜/시간 형식 통일

문제점: 날짜 필드의 타입과 형식이 일관되지 않음

현재 혼재된 형식

@JsonKey(name: 'purchase_date') String? purchaseDate,    // ❌ String
@JsonKey(name: 'created_at') DateTime createdAt,         // ✅ DateTime

권장 표준

@JsonKey(name: 'purchase_date') DateTime? purchaseDate,  // ✅ 모두 DateTime
@JsonKey(name: 'created_at') DateTime createdAt,

---

🔵 Missing Features (신규 구현)

10. Lookups API 미구현

상태: ❌ 완전히 미구현

API 스키마에서 제공

GET /lookups          # 전체 마스터 데이터
GET /lookups/type     # 타입별 마스터 데이터

예상 활용도

• 드롭다운 옵션 동적 로딩
• 장비 카테고리, 제조사 목록
• 상태 코드, 타입 코드 관리

구현 필요도: 🟡 Medium (성능 최적화에 도움)

11. Health Check API 미구현

상태: ❌ 완전히 미구현

API 스키마

GET /health          # 서버 상태 체크

활용 방안:

• 앱 시작 시 서버 연결 확인
• 주기적 헬스체크 (30초 간격)
• 네트워크 오류와 서버 오류 구분

구현 필요도: 🟢 Low (운영 편의성)

12. Overview API 부분 구현

상태: ⚠️ 부분 구현

구현된 API

• ✅ /overview/stats - 대시보드 통계
• ✅ /overview/license-expiry - 라이선스 만료 요약

미구현 API

• ❌ /overview/recent-activities - 최근 활동 내역
• ❌ /overview/equipment-status - 장비 상태 분포

현재 처리 방식: 404 에러를 받으면 빈 데이터 반환

// lib/data/datasources/remote/dashboard_remote_datasource.dart (line 61-65)
if (e.response?.statusCode == 404) {
  return Right([]);  // 빈 리스트 반환
}

---

🗓️ 마이그레이션 로드맵

Phase 1: Critical Issues 해결 (1주일)

1.1 API 응답 형식 통일 (2일)

• ApiResponse 클래스 수정 (success → status)
• ResponseMeta 클래스 신규 생성
• 모든 DataSource 응답 파싱 로직 수정
• ResponseInterceptor 업데이트

1.2 페이지네이션 구조 수정 (1일)

• PaginatedResponse 필드명 수정
• 메타데이터 중첩 구조 적용 (meta.pagination)
• BaseListController 업데이트

1.3 소프트 딜리트 정리 (2일)

• includeInactive 파라미터 제거
• is_active 파라미터만 사용하도록 통일
• 모든 DataSource 쿼리 파라미터 정리

Phase 2: Major Issues 해결 (2주일)

2.1 JWT 구조 업데이트 (3일)

• AuthInterceptor 토큰 파싱 로직 수정
• user_id → sub 변경 적용
• 권한 체크 로직 업데이트

2.2 Equipment 상태 확장 (1일)

• EquipmentStatus enum에 disposed 추가
• UI에서 폐기 상태 처리 로직 추가
• 상태별 아이콘 및 색상 추가

2.3 권한 기반 UI 제어 (1주일)

• 사용자 권한별 UI 요소 표시/숨김
• API 호출 전 권한 사전 검증
• 권한 부족 시 안내 메시지

Phase 3: Enhancement & New Features (1개월)

3.1 Lookups API 구현 (1주일)

• LookupRemoteDataSource 기능 확장
• 전역 캐싱 시스템 구축
• 드롭다운 컴포넌트에 동적 로딩 적용

3.2 Health Check 시스템 (3일)

• 서버 상태 모니터링 위젯 생성
• 주기적 헬스체크 백그라운드 작업
• 연결 상태 UI 인디케이터

3.3 Overview API 완성 (1주일)

• 최근 활동 내역 구현
• 장비 상태 분포 차트 구현
• 실시간 업데이트 기능

Phase 4: 코드 품질 개선 (진행 중)

4.1 Service → Repository 마이그레이션 완료

• User 도메인 Repository 전환
• Equipment 도메인 Repository 전환
• Company 도메인 완전 전환

4.2 테스트 커버리지 확대

• Domain Layer 단위 테스트 추가
• API 호환성 회귀 테스트 구축
• 에러 시나리오 테스트 강화

---

📊 호환성 점수

현재 호환성 평가

영역	호환성 점수	주요 문제
API 응답 형식	20% 🔴	기본 구조 완전 불일치
인증 시스템	80% 🟡	JWT 구조 부분 변경
CRUD 작업	85% 🟡	소프트 딜리트 일부 누락
데이터 모델	90% 🟢	새 필드 일부 누락
페이지네이션	60% 🟡	메타데이터 구조 변경
에러 처리	70% 🟡	표준화 미흡
권한 제어	85% 🟡	UI 레벨 권한 체크 부족
신규 API	30% 🔴	대부분 미구현

전체 호환성 점수: 65% 🟡

---

🚨 즉시 조치 사항

🔥 Urgent (24시간 내)

1. API 응답 파싱 에러 - 현재 대부분의 API 호출이 잘못된 응답 구조 사용
2. 페이지네이션 실패 - 목록 조회 시 메타데이터 파싱 오류 가능

⚡ High Priority (1주일 내)

3. 소프트 딜리트 불일치 - 삭제 기능의 일관성 문제
4. JWT 토큰 변경 - 인증 실패 가능성

📅 Planned (1개월 내)

5. 신규 API 활용 - 성능 및 기능 개선 기회
6. 권한 시스템 강화 - 보안 개선

---

📞 지원 및 문의

긴급 이슈 발생 시

1. Backend API Team: API 스키마 관련 문의
2. Frontend Team: UI/UX 영향도 검토
3. QA Team: 호환성 테스트 지원

유용한 리소스

• API_SCHEMA.md - 완전한 API 명세서
• CURRENT_STATE.md - 현재 프론트엔드 상태
• MIGRATION_GUIDE.md - 상세 마이그레이션 가이드

---

호환성 분석 버전: 1.0
최종 업데이트: 2025-08-13
담당자: Frontend Architecture Team

⚠️ 중요: 이 문서의 Critical Issues는 앱 안정성에 직접적인 영향을 미칩니다. 즉시 해결이 필요합니다.