feat: API 통합을 위한 기초 인프라 구축

- 네트워크 레이어 구현 (Dio 기반 ApiClient) - 환경별 설정 관리 시스템 구축 - 의존성 주입 설정 (GetIt) - API 엔드포인트 상수 정의 - 인터셉터 구현 (Auth, Error, Logging) - 프로젝트 아키텍처 개선 (core, data, di 디렉토리 구조) - API 통합 계획서 및 요구사항 문서 작성 - 필요 패키지 추가 (dio, flutter_secure_storage, get_it 등)
2025-07-24 14:54:28 +09:00
parent e0bc5894b2
commit 2b31d3af5f
29 changed files with 3542 additions and 344 deletions
--- a/lib/core/config/environment.dart
+++ b/lib/core/config/environment.dart
@@ -0,0 +1,65 @@
+import 'package:flutter_dotenv/flutter_dotenv.dart';
+
+/// 환경 설정 관리 클래스
+class Environment {
+  static const String dev = 'development';
+  static const String prod = 'production';
+  
+  static late String _environment;
+  
+  /// 현재 환경
+  static String get current => _environment;
+  
+  /// 개발 환경 여부
+  static bool get isDevelopment => _environment == dev;
+  
+  /// 프로덕션 환경 여부
+  static bool get isProduction => _environment == prod;
+  
+  /// API 베이스 URL
+  static String get apiBaseUrl {
+    return dotenv.env['API_BASE_URL'] ?? 'http://localhost:8080/api/v1';
+  }
+  
+  /// API 타임아웃 (밀리초)
+  static int get apiTimeout {
+    final timeoutStr = dotenv.env['API_TIMEOUT'] ?? '30000';
+    return int.tryParse(timeoutStr) ?? 30000;
+  }
+  
+  /// 로깅 활성화 여부
+  static bool get enableLogging {
+    final loggingStr = dotenv.env['ENABLE_LOGGING'] ?? 'false';
+    return loggingStr.toLowerCase() == 'true';
+  }
+  
+  /// 환경 초기화
+  static Future<void> initialize([String? environment]) async {
+    _environment = environment ?? 
+        const String.fromEnvironment('ENVIRONMENT', defaultValue: dev);
+    
+    final envFile = _getEnvFile();
+    await dotenv.load(fileName: envFile);
+  }
+  
+  /// 환경별 파일 경로 반환
+  static String _getEnvFile() {
+    switch (_environment) {
+      case prod:
+        return '.env.production';
+      case dev:
+      default:
+        return '.env.development';
+    }
+  }
+  
+  /// 환경 변수 가져오기
+  static String? get(String key) {
+    return dotenv.env[key];
+  }
+  
+  /// 환경 변수 존재 여부 확인
+  static bool has(String key) {
+    return dotenv.env.containsKey(key);
+  }
+}
--- a/lib/core/constants/api_endpoints.dart
+++ b/lib/core/constants/api_endpoints.dart
@@ -0,0 +1,77 @@
+/// API 엔드포인트 상수 정의
+class ApiEndpoints {
+  // 인증
+  static const String login = '/auth/login';
+  static const String logout = '/auth/logout';
+  static const String refresh = '/auth/refresh';
+  static const String me = '/me';
+  
+  // 장비 관리
+  static const String equipment = '/equipment';
+  static const String equipmentSearch = '/equipment/search';
+  static const String equipmentIn = '/equipment/in';
+  static const String equipmentOut = '/equipment/out';
+  static const String equipmentBatchOut = '/equipment/batch-out';
+  static const String equipmentManufacturers = '/equipment/manufacturers';
+  static const String equipmentNames = '/equipment/names';
+  static const String equipmentHistory = '/equipment/history';
+  static const String equipmentRentals = '/equipment/rentals';
+  static const String equipmentRepairs = '/equipment/repairs';
+  static const String equipmentDisposals = '/equipment/disposals';
+  
+  // 회사 관리
+  static const String companies = '/companies';
+  static const String companiesSearch = '/companies/search';
+  static const String companiesNames = '/companies/names';
+  static const String companiesCheckDuplicate = '/companies/check-duplicate';
+  static const String companiesWithBranches = '/companies/with-branches';
+  static const String companiesBranches = '/companies/{id}/branches';
+  
+  // 사용자 관리
+  static const String users = '/users';
+  static const String usersSearch = '/users/search';
+  static const String usersChangePassword = '/users/{id}/change-password';
+  static const String usersStatus = '/users/{id}/status';
+  
+  // 라이선스 관리
+  static const String licenses = '/licenses';
+  static const String licensesExpiring = '/licenses/expiring';
+  static const String licensesAssign = '/licenses/{id}/assign';
+  static const String licensesUnassign = '/licenses/{id}/unassign';
+  
+  // 창고 위치 관리
+  static const String warehouseLocations = '/warehouse-locations';
+  static const String warehouseLocationsSearch = '/warehouse-locations/search';
+  static const String warehouseEquipment = '/warehouse-locations/{id}/equipment';
+  static const String warehouseCapacity = '/warehouse-locations/{id}/capacity';
+  
+  // 파일 관리
+  static const String filesUpload = '/files/upload';
+  static const String filesDownload = '/files/{id}';
+  
+  // 보고서
+  static const String reports = '/reports';
+  static const String reportsPdf = '/reports/{type}/pdf';
+  static const String reportsExcel = '/reports/{type}/excel';
+  
+  // 대시보드 및 통계
+  static const String overviewStats = '/overview/stats';
+  static const String overviewRecentActivities = '/overview/recent-activities';
+  static const String overviewEquipmentStatus = '/overview/equipment-status';
+  static const String overviewLicenseExpiry = '/overview/license-expiry';
+  
+  // 대량 처리
+  static const String bulkUpload = '/bulk/upload';
+  static const String bulkUpdate = '/bulk/update';
+  
+  // 감사 로그
+  static const String auditLogs = '/audit-logs';
+  
+  // 백업
+  static const String backupCreate = '/backup/create';
+  static const String backupRestore = '/backup/restore';
+  
+  // 검색 및 조회
+  static const String lookups = '/lookups';
+  static const String categories = '/lookups/categories';
+}
--- a/lib/core/constants/app_constants.dart
+++ b/lib/core/constants/app_constants.dart
@@ -0,0 +1,75 @@
+/// 앱 전역 상수 정의
+class AppConstants {
+  // API 관련
+  static const int defaultPageSize = 20;
+  static const int maxPageSize = 100;
+  static const Duration cacheTimeout = Duration(minutes: 5);
+  
+  // 토큰 키
+  static const String accessTokenKey = 'access_token';
+  static const String refreshTokenKey = 'refresh_token';
+  static const String tokenTypeKey = 'token_type';
+  static const String expiresInKey = 'expires_in';
+  
+  // 사용자 권한 매핑
+  static const Map<String, String> flutterToBackendRole = {
+    'S': 'admin',    // Super user
+    'M': 'manager',  // Manager
+    'U': 'staff',    // User
+    'V': 'viewer',   // Viewer
+  };
+  
+  static const Map<String, String> backendToFlutterRole = {
+    'admin': 'S',
+    'manager': 'M',
+    'staff': 'U',
+    'viewer': 'V',
+  };
+  
+  // 장비 상태
+  static const Map<String, String> equipmentStatus = {
+    'available': '사용가능',
+    'in_use': '사용중',
+    'maintenance': '유지보수',
+    'disposed': '폐기',
+    'rented': '대여중',
+  };
+  
+  // 정렬 옵션
+  static const Map<String, String> sortOptions = {
+    'created_at': '생성일',
+    'updated_at': '수정일',
+    'name': '이름',
+    'status': '상태',
+  };
+  
+  // 날짜 형식
+  static const String dateFormat = 'yyyy-MM-dd';
+  static const String dateTimeFormat = 'yyyy-MM-dd HH:mm:ss';
+  
+  // 파일 업로드
+  static const int maxFileSize = 10 * 1024 * 1024; // 10MB
+  static const List<String> allowedFileExtensions = [
+    'jpg', 'jpeg', 'png', 'pdf', 'doc', 'docx', 'xls', 'xlsx'
+  ];
+  
+  // 에러 메시지
+  static const String networkError = '네트워크 연결을 확인해주세요.';
+  static const String timeoutError = '요청 시간이 초과되었습니다.';
+  static const String unauthorizedError = '인증이 필요합니다.';
+  static const String serverError = '서버 오류가 발생했습니다.';
+  static const String unknownError = '알 수 없는 오류가 발생했습니다.';
+  
+  // 정규식 패턴
+  static final RegExp emailRegex = RegExp(
+    r'^[a-zA-Z0-9.]+@[a-zA-Z0-9]+\.[a-zA-Z]+',
+  );
+  
+  static final RegExp phoneRegex = RegExp(
+    r'^01[0-9]{1}-?[0-9]{4}-?[0-9]{4}$',
+  );
+  
+  static final RegExp businessNumberRegex = RegExp(
+    r'^[0-9]{3}-?[0-9]{2}-?[0-9]{5}$',
+  );
+}
--- a/lib/core/errors/exceptions.dart
+++ b/lib/core/errors/exceptions.dart
@@ -0,0 +1,117 @@
+/// 커스텀 예외 클래스들 정의
+
+/// 서버 예외
+class ServerException implements Exception {
+  final String message;
+  final int? statusCode;
+  final Map<String, dynamic>? errors;
+  
+  ServerException({
+    required this.message,
+    this.statusCode,
+    this.errors,
+  });
+  
+  @override
+  String toString() => 'ServerException: $message (code: $statusCode)';
+}
+
+/// 캐시 예외
+class CacheException implements Exception {
+  final String message;
+  
+  CacheException({required this.message});
+  
+  @override
+  String toString() => 'CacheException: $message';
+}
+
+/// 네트워크 예외
+class NetworkException implements Exception {
+  final String message;
+  
+  NetworkException({required this.message});
+  
+  @override
+  String toString() => 'NetworkException: $message';
+}
+
+/// 인증 예외
+class UnauthorizedException implements Exception {
+  final String message;
+  
+  UnauthorizedException({required this.message});
+  
+  @override
+  String toString() => 'UnauthorizedException: $message';
+}
+
+/// 유효성 검사 예외
+class ValidationException implements Exception {
+  final String message;
+  final Map<String, List<String>>? fieldErrors;
+  
+  ValidationException({
+    required this.message,
+    this.fieldErrors,
+  });
+  
+  @override
+  String toString() => 'ValidationException: $message';
+}
+
+/// 권한 부족 예외
+class ForbiddenException implements Exception {
+  final String message;
+  
+  ForbiddenException({required this.message});
+  
+  @override
+  String toString() => 'ForbiddenException: $message';
+}
+
+/// 리소스 찾을 수 없음 예외
+class NotFoundException implements Exception {
+  final String message;
+  final String? resourceType;
+  final String? resourceId;
+  
+  NotFoundException({
+    required this.message,
+    this.resourceType,
+    this.resourceId,
+  });
+  
+  @override
+  String toString() => 'NotFoundException: $message';
+}
+
+/// 중복 리소스 예외
+class DuplicateException implements Exception {
+  final String message;
+  final String? field;
+  final String? value;
+  
+  DuplicateException({
+    required this.message,
+    this.field,
+    this.value,
+  });
+  
+  @override
+  String toString() => 'DuplicateException: $message';
+}
+
+/// 비즈니스 로직 예외
+class BusinessException implements Exception {
+  final String message;
+  final String? code;
+  
+  BusinessException({
+    required this.message,
+    this.code,
+  });
+  
+  @override
+  String toString() => 'BusinessException: $message (code: $code)';
+}
--- a/lib/core/errors/failures.dart
+++ b/lib/core/errors/failures.dart
@@ -0,0 +1,117 @@
+import 'package:dartz/dartz.dart';
+
+/// 실패 처리를 위한 추상 클래스
+abstract class Failure {
+  final String message;
+  final String? code;
+  
+  const Failure({
+    required this.message,
+    this.code,
+  });
+  
+  @override
+  bool operator ==(Object other) =>
+      identical(this, other) ||
+      other is Failure &&
+          runtimeType == other.runtimeType &&
+          message == other.message &&
+          code == other.code;
+  
+  @override
+  int get hashCode => message.hashCode ^ code.hashCode;
+}
+
+/// 서버 실패
+class ServerFailure extends Failure {
+  final int? statusCode;
+  final Map<String, dynamic>? errors;
+  
+  const ServerFailure({
+    required String message,
+    String? code,
+    this.statusCode,
+    this.errors,
+  }) : super(message: message, code: code);
+}
+
+/// 캐시 실패
+class CacheFailure extends Failure {
+  const CacheFailure({
+    required String message,
+    String? code,
+  }) : super(message: message, code: code);
+}
+
+/// 네트워크 실패
+class NetworkFailure extends Failure {
+  const NetworkFailure({
+    required String message,
+    String? code,
+  }) : super(message: message, code: code);
+}
+
+/// 인증 실패
+class AuthenticationFailure extends Failure {
+  const AuthenticationFailure({
+    required String message,
+    String? code,
+  }) : super(message: message, code: code);
+}
+
+/// 권한 실패
+class AuthorizationFailure extends Failure {
+  const AuthorizationFailure({
+    required String message,
+    String? code,
+  }) : super(message: message, code: code);
+}
+
+/// 유효성 검사 실패
+class ValidationFailure extends Failure {
+  final Map<String, List<String>>? fieldErrors;
+  
+  const ValidationFailure({
+    required String message,
+    String? code,
+    this.fieldErrors,
+  }) : super(message: message, code: code);
+}
+
+/// 리소스 찾을 수 없음 실패
+class NotFoundFailure extends Failure {
+  final String? resourceType;
+  final String? resourceId;
+  
+  const NotFoundFailure({
+    required String message,
+    String? code,
+    this.resourceType,
+    this.resourceId,
+  }) : super(message: message, code: code);
+}
+
+/// 중복 리소스 실패
+class DuplicateFailure extends Failure {
+  final String? field;
+  final String? value;
+  
+  const DuplicateFailure({
+    required String message,
+    String? code,
+    this.field,
+    this.value,
+  }) : super(message: message, code: code);
+}
+
+/// 비즈니스 로직 실패
+class BusinessFailure extends Failure {
+  const BusinessFailure({
+    required String message,
+    String? code,
+  }) : super(message: message, code: code);
+}
+
+/// 타입 정의
+typedef FutureEither<T> = Future<Either<Failure, T>>;
+typedef FutureVoid = FutureEither<void>;
--- a/lib/core/utils/formatters.dart
+++ b/lib/core/utils/formatters.dart
@@ -0,0 +1,146 @@
+import 'package:intl/intl.dart';
+import '../constants/app_constants.dart';
+
+/// 데이터 포맷터 유틸리티 클래스
+class Formatters {
+  /// 날짜 포맷
+  static String formatDate(DateTime date) {
+    return DateFormat(AppConstants.dateFormat).format(date);
+  }
+  
+  /// 날짜+시간 포맷
+  static String formatDateTime(DateTime dateTime) {
+    return DateFormat(AppConstants.dateTimeFormat).format(dateTime);
+  }
+  
+  /// 상대적 시간 포맷 (예: 3분 전, 2시간 전)
+  static String formatRelativeTime(DateTime dateTime) {
+    final now = DateTime.now();
+    final difference = now.difference(dateTime);
+    
+    if (difference.inDays > 365) {
+      return '${(difference.inDays / 365).floor()}년 전';
+    } else if (difference.inDays > 30) {
+      return '${(difference.inDays / 30).floor()}개월 전';
+    } else if (difference.inDays > 0) {
+      return '${difference.inDays}일 전';
+    } else if (difference.inHours > 0) {
+      return '${difference.inHours}시간 전';
+    } else if (difference.inMinutes > 0) {
+      return '${difference.inMinutes}분 전';
+    } else {
+      return '방금 전';
+    }
+  }
+  
+  /// 숫자 포맷 (천 단위 구분)
+  static String formatNumber(int number) {
+    return NumberFormat('#,###').format(number);
+  }
+  
+  /// 통화 포맷
+  static String formatCurrency(int amount) {
+    return NumberFormat.currency(
+      locale: 'ko_KR',
+      symbol: '₩',
+      decimalDigits: 0,
+    ).format(amount);
+  }
+  
+  /// 전화번호 포맷
+  static String formatPhone(String phone) {
+    final cleaned = phone.replaceAll(RegExp(r'[^0-9]'), '');
+    
+    if (cleaned.length == 11) {
+      return '${cleaned.substring(0, 3)}-${cleaned.substring(3, 7)}-${cleaned.substring(7)}';
+    } else if (cleaned.length == 10) {
+      if (cleaned.startsWith('02')) {
+        return '${cleaned.substring(0, 2)}-${cleaned.substring(2, 6)}-${cleaned.substring(6)}';
+      } else {
+        return '${cleaned.substring(0, 3)}-${cleaned.substring(3, 6)}-${cleaned.substring(6)}';
+      }
+    }
+    
+    return phone;
+  }
+  
+  /// 사업자번호 포맷
+  static String formatBusinessNumber(String businessNumber) {
+    final cleaned = businessNumber.replaceAll(RegExp(r'[^0-9]'), '');
+    
+    if (cleaned.length == 10) {
+      return '${cleaned.substring(0, 3)}-${cleaned.substring(3, 5)}-${cleaned.substring(5)}';
+    }
+    
+    return businessNumber;
+  }
+  
+  /// 파일 크기 포맷
+  static String formatFileSize(int bytes) {
+    if (bytes < 1024) {
+      return '$bytes B';
+    } else if (bytes < 1024 * 1024) {
+      return '${(bytes / 1024).toStringAsFixed(1)} KB';
+    } else if (bytes < 1024 * 1024 * 1024) {
+      return '${(bytes / (1024 * 1024)).toStringAsFixed(1)} MB';
+    } else {
+      return '${(bytes / (1024 * 1024 * 1024)).toStringAsFixed(1)} GB';
+    }
+  }
+  
+  /// 백분율 포맷
+  static String formatPercentage(double value, {int decimals = 0}) {
+    return '${(value * 100).toStringAsFixed(decimals)}%';
+  }
+  
+  /// 기간 포맷 (일수)
+  static String formatDuration(int days) {
+    if (days >= 365) {
+      final years = days ~/ 365;
+      final remainingDays = days % 365;
+      if (remainingDays > 0) {
+        return '$years년 $remainingDays일';
+      }
+      return '$years년';
+    } else if (days >= 30) {
+      final months = days ~/ 30;
+      final remainingDays = days % 30;
+      if (remainingDays > 0) {
+        return '$months개월 $remainingDays일';
+      }
+      return '$months개월';
+    } else {
+      return '$days일';
+    }
+  }
+  
+  /// 상태 텍스트 변환
+  static String formatStatus(String status) {
+    return AppConstants.equipmentStatus[status] ?? status;
+  }
+  
+  /// 역할 텍스트 변환
+  static String formatRole(String role) {
+    switch (role) {
+      case 'S':
+      case 'admin':
+        return '관리자';
+      case 'M':
+      case 'manager':
+        return '매니저';
+      case 'U':
+      case 'staff':
+        return '직원';
+      case 'V':
+      case 'viewer':
+        return '열람자';
+      default:
+        return role;
+    }
+  }
+  
+  /// null 값 처리
+  static String formatNullable(String? value, {String defaultValue = '-'}) {
+    return value?.isEmpty ?? true ? defaultValue : value!;
+  }
+}
--- a/lib/core/utils/validators.dart
+++ b/lib/core/utils/validators.dart
@@ -0,0 +1,154 @@
+import '../constants/app_constants.dart';
+
+/// 유효성 검사 유틸리티 클래스
+class Validators {
+  /// 이메일 유효성 검사
+  static String? validateEmail(String? value) {
+    if (value == null || value.isEmpty) {
+      return '이메일을 입력해주세요.';
+    }
+    
+    if (!AppConstants.emailRegex.hasMatch(value)) {
+      return '올바른 이메일 형식이 아닙니다.';
+    }
+    
+    return null;
+  }
+  
+  /// 비밀번호 유효성 검사
+  static String? validatePassword(String? value) {
+    if (value == null || value.isEmpty) {
+      return '비밀번호를 입력해주세요.';
+    }
+    
+    if (value.length < 8) {
+      return '비밀번호는 8자 이상이어야 합니다.';
+    }
+    
+    if (!value.contains(RegExp(r'[0-9]'))) {
+      return '비밀번호는 숫자를 포함해야 합니다.';
+    }
+    
+    if (!value.contains(RegExp(r'[a-zA-Z]'))) {
+      return '비밀번호는 영문자를 포함해야 합니다.';
+    }
+    
+    return null;
+  }
+  
+  /// 필수 입력 검사
+  static String? validateRequired(String? value, String fieldName) {
+    if (value == null || value.trim().isEmpty) {
+      return '$fieldName을(를) 입력해주세요.';
+    }
+    return null;
+  }
+  
+  /// 전화번호 유효성 검사
+  static String? validatePhone(String? value) {
+    if (value == null || value.isEmpty) {
+      return '전화번호를 입력해주세요.';
+    }
+    
+    final cleanedValue = value.replaceAll('-', '');
+    if (!AppConstants.phoneRegex.hasMatch(cleanedValue)) {
+      return '올바른 전화번호 형식이 아닙니다.';
+    }
+    
+    return null;
+  }
+  
+  /// 사업자번호 유효성 검사
+  static String? validateBusinessNumber(String? value) {
+    if (value == null || value.isEmpty) {
+      return '사업자번호를 입력해주세요.';
+    }
+    
+    final cleanedValue = value.replaceAll('-', '');
+    if (!AppConstants.businessNumberRegex.hasMatch(cleanedValue)) {
+      return '올바른 사업자번호 형식이 아닙니다.';
+    }
+    
+    return null;
+  }
+  
+  /// 숫자 유효성 검사
+  static String? validateNumber(String? value, {
+    required String fieldName,
+    int? min,
+    int? max,
+  }) {
+    if (value == null || value.isEmpty) {
+      return '$fieldName을(를) 입력해주세요.';
+    }
+    
+    final number = int.tryParse(value);
+    if (number == null) {
+      return '숫자만 입력 가능합니다.';
+    }
+    
+    if (min != null && number < min) {
+      return '$fieldName은(는) $min 이상이어야 합니다.';
+    }
+    
+    if (max != null && number > max) {
+      return '$fieldName은(는) $max 이하여야 합니다.';
+    }
+    
+    return null;
+  }
+  
+  /// 날짜 범위 유효성 검사
+  static String? validateDateRange(
+    DateTime? startDate,
+    DateTime? endDate,
+  ) {
+    if (startDate == null || endDate == null) {
+      return null;
+    }
+    
+    if (startDate.isAfter(endDate)) {
+      return '시작일은 종료일보다 이전이어야 합니다.';
+    }
+    
+    return null;
+  }
+  
+  /// 파일 확장자 유효성 검사
+  static String? validateFileExtension(String fileName) {
+    final extension = fileName.split('.').last.toLowerCase();
+    
+    if (!AppConstants.allowedFileExtensions.contains(extension)) {
+      return '허용되지 않는 파일 형식입니다. (${AppConstants.allowedFileExtensions.join(', ')})';
+    }
+    
+    return null;
+  }
+  
+  /// 파일 크기 유효성 검사
+  static String? validateFileSize(int sizeInBytes) {
+    if (sizeInBytes > AppConstants.maxFileSize) {
+      final maxSizeMB = AppConstants.maxFileSize / (1024 * 1024);
+      return '파일 크기는 ${maxSizeMB}MB를 초과할 수 없습니다.';
+    }
+    
+    return null;
+  }
+  
+  /// 시리얼 번호 유효성 검사
+  static String? validateSerialNumber(String? value) {
+    if (value == null || value.isEmpty) {
+      return null; // 시리얼 번호는 선택사항
+    }
+    
+    if (value.length < 5) {
+      return '시리얼 번호는 5자 이상이어야 합니다.';
+    }
+    
+    if (!RegExp(r'^[A-Za-z0-9-]+$').hasMatch(value)) {
+      return '시리얼 번호는 영문, 숫자, 하이픈(-)만 사용 가능합니다.';
+    }
+    
+    return null;
+  }
+}