# 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 with _$ApiResponse { const factory ApiResponse({ required bool success, // ❌ 잘못된 필드명 required String message, T? data, String? error, }) = _ApiResponse; } ``` #### API 스키마 (정답) ```json { "status": "success", // ✅ 올바른 필드명 "message": "Operation completed successfully", "data": { /* 실제 데이터 */ }, "meta": { /* 메타데이터 (페이지네이션 등) */ } } ``` **영향도**: 🔥 **극심함** - 모든 API 호출이 영향받음 **수정 방법**: ```dart // 수정된 ApiResponse @Freezed(genericArgumentFactories: true) class ApiResponse with _$ApiResponse { const factory ApiResponse({ required String status, // success/error required String message, T? data, ResponseMeta? meta, // 새로 추가 }) = _ApiResponse; } // 새로운 메타 클래스 @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 dataList = responseData['data']; final pagination = responseData['pagination'] ?? {}; // ❌ return PaginatedResponse( 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 dataList = responseData['data']; final meta = responseData['meta']?['pagination'] ?? {}; return PaginatedResponse( 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> 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? 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는 앱 안정성에 직접적인 영향을 미칩니다. 즉시 해결이 필요합니다.