superport/docs/migration/MIGRATION_GUIDE.md

Superport API Migration Guide

최종 업데이트: 2025-08-13
분석 대상: /Users/maximilian.j.sul/Documents/flutter/superport_api/
프론트엔드 영향: Flutter Clean Architecture 기반

📋 목차

• 주요 변경사항 요약
• Breaking Changes
• 신규 기능
• 프론트엔드 마이그레이션
• API 엔드포인트 변경사항
• 데이터베이스 스키마 변경
• 실행 계획

---

🚨 주요 변경사항 요약

✅ 완료된 주요 기능

1. 소프트 딜리트 시스템 전면 구현
2. 권한 기반 접근 제어 강화
3. API 엔드포인트 표준화
4. 페이지네이션 최적화
5. 에러 처리 개선

🔄 변경 영향도 매트릭스

영역	변경 수준	영향도	대응 필요도
Authentication	중간	🟡 Medium	토큰 구조 업데이트
Companies API	높음	🔴 High	DTO 모델 전면 수정
Equipment API	높음	🔴 High	상태 관리 로직 수정
Users API	중간	🟡 Medium	권한 처리 로직 수정
Licenses API	낮음	🟢 Low	소프트 딜리트 대응
Overview API	신규	🔵 New	새로운 통합 필요

---

⚠️ Breaking Changes

1. 소프트 딜리트 도입

변경 내용: 모든 주요 엔티티에서 물리 삭제 → 논리 삭제로 변경

영향을 받는 API:

DELETE /companies/{id}     → is_active = false
DELETE /equipment/{id}     → is_active = false  
DELETE /licenses/{id}      → is_active = false
DELETE /warehouse-locations/{id} → is_active = false

프론트엔드 수정 필요사항:

// Before (기존)
class CompanyListRequest {
  final int? page;
  final int? perPage;
}

// After (수정 필요)
class CompanyListRequest {
  final int? page;
  final int? perPage;
  final bool? isActive;  // 추가 필요
}

2. 응답 형식 표준화

변경 내용: 모든 API 응답이 표준 형식으로 통일

Before:

{
  "data": [...],
  "total": 100
}

After:

{
  "status": "success",
  "message": "Operation completed successfully",
  "data": [...],
  "meta": {
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 100,
      "total_pages": 5
    }
  }
}

3. 권한 시스템 변경

변경 내용: JWT 클레임 구조 및 권한 체크 로직 강화

새로운 JWT 구조:

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

권한별 접근 제한:

• staff: 조회 권한만, 삭제 권한 없음
• manager: 모든 권한, 단 사용자 관리 제외
• admin: 모든 권한

---

🆕 신규 기능

1. Overview API (대시보드용)

새로운 엔드포인트:

GET /overview/stats              # 대시보드 통계
GET /overview/recent-activities  # 최근 활동
GET /overview/equipment-status   # 장비 상태 분포
GET /overview/license-expiry     # 라이선스 만료 요약

통합 예시:

// 새로 추가할 UseCase
class GetDashboardStatsUseCase {
  Future<Either<Failure, DashboardStats>> call(int? companyId) async {
    return await overviewRepository.getDashboardStats(companyId);
  }
}

2. Lookups API (마스터 데이터)

새로운 엔드포인트:

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

활용 방안:

• 드롭다운 옵션 동적 로딩
• 캐싱을 통한 성능 최적화

3. Health Check API

새로운 엔드포인트:

GET /health          # 서버 상태 체크

프론트엔드 활용:

• 앱 시작 시 서버 연결 상태 확인
• 주기적 헬스체크 구현

---

🎯 프론트엔드 마이그레이션

Phase 1: DTO 모델 업데이트

1.1 Company DTO 수정

// 기존 CreateCompanyRequest에 추가
@JsonSerializable()
class CreateCompanyRequest {
  // 기존 필드들...
  final List<String>? companyTypes;  // 추가
  final bool? isPartner;             // 추가  
  final bool? isCustomer;            // 추가
}

// 새로운 필터링 옵션
@JsonSerializable()
class CompanyListRequest {
  final int? page;
  final int? perPage;
  final bool? isActive;              // 추가 (소프트 딜리트)
}

1.2 Equipment DTO 수정

// Equipment 상태 Enum 확장
enum EquipmentStatus {
  @JsonValue('available') available,
  @JsonValue('inuse') inuse,
  @JsonValue('maintenance') maintenance,
  @JsonValue('disposed') disposed,    // 새로 추가
}

// 페이지네이션 쿼리 확장
@JsonSerializable()
class EquipmentListRequest {
  final int? page;
  final int? perPage;
  final String? status;
  final int? companyId;
  final int? warehouseLocationId;
  final bool? isActive;              // 추가
}

Phase 2: Repository 인터페이스 수정

2.1 소프트 딜리트 지원

abstract class CompanyRepository {
  // 기존 메서드 시그니처 수정
  Future<Either<Failure, PaginatedResponse<Company>>> getCompanies({
    int? page,
    int? perPage,
    bool? isActive,  // 추가
  });
  
  // 삭제 메서드 동작 변경 (소프트 딜리트)
  Future<Either<Failure, Unit>> deleteCompany(int id);
  
  // 복구 메서드 추가
  Future<Either<Failure, Company>> restoreCompany(int id);  // 신규
}

2.2 새로운 Repository 추가

// 새로 추가할 Repository
abstract class OverviewRepository {
  Future<Either<Failure, DashboardStats>> getDashboardStats(int? companyId);
  Future<Either<Failure, PaginatedResponse<Activity>>> getRecentActivities({
    int? page,
    int? perPage,
    String? entityType,
    int? companyId,
  });
  Future<Either<Failure, EquipmentStatusDistribution>> getEquipmentStatusDistribution(int? companyId);
  Future<Either<Failure, LicenseExpirySummary>> getLicenseExpirySummary(int? companyId);
}

abstract class LookupRepository {
  Future<Either<Failure, Map<String, List<LookupItem>>>> getAllLookups();
  Future<Either<Failure, List<LookupItem>>> getLookupsByType(String type);
}

Phase 3: API 클라이언트 수정

3.1 Retrofit 인터페이스 업데이트

@RestApi()
abstract class SuperportApiClient {
  // Overview API 추가
  @GET('/overview/stats')
  Future<ApiResponse<DashboardStats>> getDashboardStats(
    @Query('company_id') int? companyId,
  );

  @GET('/overview/license-expiry')
  Future<ApiResponse<LicenseExpirySummary>> getLicenseExpirySummary(
    @Query('company_id') int? companyId,
  );

  // Lookups API 추가
  @GET('/lookups')
  Future<ApiResponse<Map<String, List<LookupItem>>>> getAllLookups();

  // 기존 API 파라미터 추가
  @GET('/companies')
  Future<ApiResponse<PaginatedResponse<Company>>> getCompanies(
    @Query('page') int? page,
    @Query('per_page') int? perPage,
    @Query('is_active') bool? isActive,  // 추가
  );
}

3.2 응답 형식 변경 대응

// 기존 ApiResponse 클래스 수정
@JsonSerializable()
class ApiResponse<T> {
  final String status;          // 추가
  final String? message;        // 추가
  final T data;
  final ResponseMeta? meta;     // 변경 (기존 meta와 구조 다름)
}

@JsonSerializable()
class ResponseMeta {
  final PaginationMeta? pagination;  // 중첩 구조로 변경
}

Phase 4: 상태 관리 업데이트

4.1 Controller 수정

class CompanyController extends ChangeNotifier {
  // 소프트 딜리트 상태 관리
  bool _showDeleted = false;
  bool get showDeleted => _showDeleted;

  void toggleShowDeleted() {
    _showDeleted = !_showDeleted;
    _loadCompanies();  // 목록 다시 로드
    notifyListeners();
  }

  // 복구 기능 추가
  Future<void> restoreCompany(int id) async {
    final result = await _restoreCompanyUseCase(id);
    result.fold(
      (failure) => _handleError(failure),
      (company) {
        _companies[id] = company;
        notifyListeners();
      },
    );
  }
}

4.2 새로운 Controller 추가

class DashboardController extends ChangeNotifier {
  DashboardStats? _stats;
  List<Activity> _recentActivities = [];
  bool _isLoading = false;

  // Getters...

  Future<void> loadDashboardData() async {
    _isLoading = true;
    notifyListeners();

    // 병렬로 데이터 로드
    await Future.wait([
      _loadStats(),
      _loadRecentActivities(),
    ]);

    _isLoading = false;
    notifyListeners();
  }
}

---

📡 API 엔드포인트 변경사항

새로 추가된 엔드포인트

Method	Endpoint	설명	우선순위
GET	/overview/stats	대시보드 통계	🔴 높음
GET	/overview/license-expiry	라이선스 만료 요약	🟡 중간
GET	/overview/equipment-status	장비 상태 분포	🟡 중간
GET	/overview/recent-activities	최근 활동 내역	🟢 낮음
GET	/lookups	전체 마스터 데이터	🟡 중간
GET	/lookups/type	타입별 마스터 데이터	🟢 낮음
GET	/health	서버 상태 체크	🟢 낮음

기존 엔드포인트 변경사항

Endpoint	변경 내용	마이그레이션 필요도
GET /companies	is_active 파라미터 추가	🔴 필수
GET /equipment	is_active 파라미터 추가	🔴 필수
DELETE /companies/{id}	소프트 딜리트로 변경	🔴 필수
DELETE /equipment/{id}	권한 체크 강화	🟡 권장
모든 응답	표준 형식으로 통일	🔴 필수

---

🗄️ 데이터베이스 스키마 변경

새로 추가된 컬럼

테이블	컬럼	타입	설명
companies	is_active	BOOLEAN	소프트 딜리트 플래그
companies	is_partner	BOOLEAN	파트너사 여부
companies	is_customer	BOOLEAN	고객사 여부
companies	company_types	TEXT[]	회사 유형 배열
equipment	is_active	BOOLEAN	소프트 딜리트 플래그
licenses	is_active	BOOLEAN	소프트 딜리트 플래그
warehouse_locations	is_active	BOOLEAN	소프트 딜리트 플래그
addresses	is_active	BOOLEAN	소프트 딜리트 플래그
users	is_active	BOOLEAN	소프트 딜리트 플래그

새로 추가된 인덱스

-- 소프트 딜리트 최적화용 인덱스
CREATE INDEX idx_companies_is_active ON companies(is_active);
CREATE INDEX idx_equipment_is_active ON equipment(is_active);
CREATE INDEX idx_licenses_is_active ON licenses(is_active);

-- 복합 인덱스 (성능 최적화)
CREATE INDEX idx_equipment_company_id_is_active ON equipment(company_id, is_active);
CREATE INDEX idx_licenses_company_id_is_active ON licenses(company_id, is_active);

---

🛠️ 실행 계획

Phase 1: 백엔드 API 통합 (1주차)

• Overview API 통합 (/overview/license-expiry 우선)
• 소프트 딜리트 대응 (필터링 로직)
• 응답 형식 변경 대응

Phase 2: 프론트엔드 모델 업데이트 (2주차)

• DTO 클래스 수정 (Freezed 재생성)
• Repository 인터페이스 확장
• API 클라이언트 업데이트

Phase 3: UI/UX 개선 (3주차)

• 소프트 딜리트 UI 구현 (복구 버튼, 필터링)
• 대시보드 통계 위젯 구현
• 권한별 UI 제어 강화

Phase 4: 성능 최적화 (4주차)

• Lookups API 캐싱 구현
• 페이지네이션 최적화
• 에러 처리 개선

Phase 5: 테스트 및 배포 (5주차)

• 단위 테스트 업데이트
• 통합 테스트 실행
• 프로덕션 배포

---

🧪 테스트 업데이트 가이드

1. 단위 테스트 수정

// Repository 테스트 수정 예시
group('CompanyRepository', () {
  test('should return active companies when isActive is true', () async {
    // Given
    when(mockApiClient.getCompanies(
      page: 1,
      perPage: 20,
      isActive: true,  // 추가된 파라미터 테스트
    )).thenAnswer((_) async => mockActiveCompaniesResponse);

    // When
    final result = await repository.getCompanies(
      page: 1,
      perPage: 20,
      isActive: true,
    );

    // Then
    expect(result.isRight(), true);
  });
});

2. Widget 테스트 수정

testWidgets('should show restore button for deleted companies', (tester) async {
  // Given
  final deletedCompany = Company(id: 1, name: 'Test', isActive: false);
  
  // When
  await tester.pumpWidget(CompanyListItem(company: deletedCompany));
  
  // Then
  expect(find.text('복구'), findsOneWidget);
  expect(find.byIcon(Icons.restore), findsOneWidget);
});

3. 통합 테스트 수정

group('Company CRUD Integration', () {
  test('soft delete should set is_active to false', () async {
    // Create company
    final company = await createTestCompany();
    
    // Delete (soft delete)
    await apiClient.deleteCompany(company.id);
    
    // Verify soft delete
    final companies = await apiClient.getCompanies(isActive: false);
    expect(companies.data.any((c) => c.id == company.id), true);
  });
});

---

🚨 주의사항

1. 데이터 마이그레이션

• 기존 삭제된 데이터는 복구 불가능
• 소프트 딜리트 전환 후에만 복구 가능

2. 성능 영향

• is_active 필터링으로 인한 쿼리 복잡도 증가
• 인덱스 활용으로 성능 최적화 필요

3. 권한 관리

• 새로운 권한 체크 로직 확인 필요
• Staff 권한 사용자의 기능 제한 확인

4. 캐싱 전략

• Lookups API 응답 캐싱 구현 권장
• 대시보드 통계 캐싱으로 성능 개선

---

📞 지원 및 문의

개발팀 연락처

• 백엔드 API: superport_api 레포지토리 이슈 생성
• 프론트엔드: 현재 레포지토리 이슈 생성
• 데이터베이스: DBA 팀 문의

유용한 리소스

• API_SCHEMA.md - 완전한 API 명세서
• ENTITY_MAPPING.md - 데이터베이스 구조
• 백엔드 소스: /Users/maximilian.j.sul/Documents/flutter/superport_api/

---

마이그레이션 가이드 버전: 1.0
최종 검토: 2025-08-13
담당자: Full-Stack Development Team