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](#critical-issues-즉시-수정-필요)
- [Major Issues](#major-issues-우선-수정-필요)
- [Minor Issues](#minor-issues-점진적-개선)
- [Missing Features](#missing-features-신규-구현)
- [마이그레이션 로드맵](#마이그레이션-로드맵)

---

## 🚦 심각도 분류

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

---

## 🔴 Critical Issues (즉시 수정 필요)

### 1. API 응답 형식 불일치

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

#### 현재 코드 (잘못됨)
```dart
// 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 스키마 (정답)
```json
{
  "status": "success",         // ✅ 올바른 필드명
  "message": "Operation completed successfully",
  "data": { /* 실제 데이터 */ },
  "meta": { /* 메타데이터 (페이지네이션 등) */ }
}
```

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

**수정 방법**:
```dart
// 수정된 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 스키마와 다름

#### 현재 코드 응답 파싱
```dart
// 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 스키마 올바른 구조
```json
{
  "status": "success",
  "data": [...],
  "meta": {
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 150,
      "total_pages": 8,
      "has_next": true,
      "has_prev": false
    }
  }
}
```

**수정 방법**:
```dart
// 올바른 응답 파싱
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` 사용

#### 현재 코드 (혼재)
```dart
// 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 스키마 정의
```http
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 (추정)
```json
{
  "user_id": 1,
  "username": "admin",
  "role": "admin"
}
```

#### 새로운 JWT 구조
```json
{
  "sub": 1,           // user_id 대신 sub 사용
  "username": "admin", 
  "role": "admin",    // admin|manager|staff
  "exp": 1700000000,
  "iat": 1699999000
}
```

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

### 5. Equipment 상태 Enum 확장

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

#### 현재 Equipment 상태
```dart
// lib/data/models/equipment/equipment_dto.dart
enum EquipmentStatus {
  @JsonValue('available') available,
  @JsonValue('inuse') inuse,
  @JsonValue('maintenance') maintenance,
  // disposed가 누락됨
}
```

#### API 스키마 Equipment 상태
```dart
enum EquipmentStatus {
  available,   // 사용 가능
  inuse,      // 사용 중  
  maintenance, // 점검 중
  disposed,   // 폐기 ⬅️ 새로 추가됨
}
```

**수정 방법**: EquipmentStatus enum에 `disposed` 추가

### 6. Company 모델 필드 누락

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

#### 현재 CompanyResponse
```dart
@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 스키마에서 추가된 필드
```dart
// CreateCompanyRequest에 추가 필요
@JsonKey(name: 'company_types') List<String>? companyTypes,  // ✅ 이미 있음
@JsonKey(name: 'is_partner') bool? isPartner,              // ✅ 이미 있음  
@JsonKey(name: 'is_customer') bool? isCustomer,            // ✅ 이미 있음
```

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

---

## 🟢 Minor Issues (점진적 개선)

### 7. 에러 응답 처리 개선

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

#### 현재 에러 처리
```dart
// lib/data/datasources/remote/company_remote_datasource.dart
catch (e, stackTrace) {
  if (e is ApiException) rethrow;
  throw ApiException(message: 'Error creating company: $e');
}
```

#### API 스키마 표준 에러 형식
```json
{
  "status": "error",
  "message": "에러 메시지",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": [
      {
        "field": "name",
        "message": "Company name is required"
      }
    ]
  }
}
```

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

### 8. 권한별 API 접근 제어

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

#### 권한 매트릭스 (API 스키마)
| 역할 | 생성 | 조회 | 수정 | 삭제 |
|------|------|------|------|------|
| **Admin** | ✅ | ✅ | ✅ | ✅ |
| **Manager** | ✅ | ✅ | ✅ | ✅ |
| **Staff** | ⚠️ | ✅ | ⚠️ | ❌ |

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

**개선 방법**: 
```dart
// 권한 기반 UI 제어
if (currentUser.role == UserRole.staff) {
  return SizedBox(); // 삭제 버튼 숨김
}
```

### 9. 날짜/시간 형식 통일

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

#### 현재 혼재된 형식
```dart
@JsonKey(name: 'purchase_date') String? purchaseDate,    // ❌ String
@JsonKey(name: 'created_at') DateTime createdAt,         // ✅ DateTime
```

#### 권장 표준
```dart
@JsonKey(name: 'purchase_date') DateTime? purchaseDate,  // ✅ 모두 DateTime
@JsonKey(name: 'created_at') DateTime createdAt,
```

---

## 🔵 Missing Features (신규 구현)

### 10. Lookups API 미구현

**상태**: ❌ 완전히 미구현

#### API 스키마에서 제공
```http
GET /lookups          # 전체 마스터 데이터
GET /lookups/type     # 타입별 마스터 데이터
```

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

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

### 11. Health Check API 미구현

**상태**: ❌ 완전히 미구현

#### API 스키마
```http
GET /health          # 서버 상태 체크
```

**활용 방안**:
- 앱 시작 시 서버 연결 확인
- 주기적 헬스체크 (30초 간격)
- 네트워크 오류와 서버 오류 구분

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

### 12. Overview API 부분 구현

**상태**: ⚠️ **부분 구현**

#### 구현된 API
- ✅ `/overview/stats` - 대시보드 통계
- ✅ `/overview/license-expiry` - 라이선스 만료 요약

#### 미구현 API  
- ❌ `/overview/recent-activities` - 최근 활동 내역
- ❌ `/overview/equipment-status` - 장비 상태 분포

**현재 처리 방식**: 404 에러를 받으면 빈 데이터 반환
```dart
// 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_SCHEMA.md) - 완전한 API 명세서
- [CURRENT_STATE.md](./CURRENT_STATE.md) - 현재 프론트엔드 상태
- [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) - 상세 마이그레이션 가이드

---

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

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