feat: 사용자 관리 시스템 백엔드 API 호환성 대폭 개선

- UserRemoteDataSource: API v0.2.1 스펙 완전 대응
  • 응답 형식 통일 (success: true 구조)
  • 페이지네이션 처리 개선
  • 에러 핸들링 강화
  • 불필요한 파라미터 제거 (includeInactive 등)

- UserDto 모델 현대화:
  • 서버 응답 구조와 100% 일치
  • 도메인 모델 변환 메서드 추가
  • Freezed 불변성 패턴 완성

- User 도메인 모델 신규 구현:
  • Clean Architecture 원칙 준수
  • UserRole enum 타입 안전성 강화
  • 비즈니스 로직 캡슐화

- 사용자 관련 UseCase 리팩토링:
  • Repository 패턴 완전 적용
  • Either<Failure, Success> 에러 처리
  • 의존성 주입 최적화

- UI 컨트롤러 및 화면 개선:
  • API 응답 변경사항 반영
  • 사용자 권한 표시 정확성 향상
  • 폼 검증 로직 강화

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

lib/screens/user/controllers/user_form_controller.dart

@@ -1,98 +1,97 @@
 import 'dart:async';
 import 'package:flutter/material.dart';
 import 'package:get_it/get_it.dart';
-import 'package:superport/models/company_model.dart';
 import 'package:superport/models/user_model.dart';
-import 'package:superport/services/user_service.dart';
-import 'package:superport/services/company_service.dart';
-import 'package:superport/utils/constants.dart';
-import 'package:superport/models/user_phone_field.dart';
+import 'package:superport/domain/usecases/user/create_user_usecase.dart';
+import 'package:superport/domain/usecases/user/check_username_availability_usecase.dart';
+import 'package:superport/domain/repositories/user_repository.dart';
+import 'package:superport/core/errors/failures.dart';
 
-// 사용자 폼의 상태 및 비즈니스 로직을 담당하는 컨트롤러
+/// 사용자 폼 컨트롤러 (서버 API v0.2.1 대응)
+/// Clean Architecture Presentation Layer - 필수 필드 검증 강화 및 전화번호 UI 개선
 class UserFormController extends ChangeNotifier {
-  final UserService _userService = GetIt.instance<UserService>();
-  final CompanyService _companyService = GetIt.instance<CompanyService>();
+  final CreateUserUseCase _createUserUseCase = GetIt.instance<CreateUserUseCase>();
+  final CheckUsernameAvailabilityUseCase _checkUsernameUseCase = GetIt.instance<CheckUsernameAvailabilityUseCase>();
+  final UserRepository _userRepository = GetIt.instance<UserRepository>();
   final GlobalKey<FormState> formKey = GlobalKey<FormState>();
 
   // 상태 변수
   bool _isLoading = false;
   String? _error;
-  // API만 사용
   
-  // 폼 필드
+  // 폼 필드 (서버 API v0.2.1 스키마 대응)
   bool isEditMode = false;
   int? userId;
-  String name = '';
-  String username = ''; // 추가
-  String password = ''; // 추가
-  int? companyId;
-  int? branchId;
-  String role = UserRoles.member;
-  String position = '';
-  String email = '';
+  String name = '';                    // 필수
+  String username = '';               // 필수, 유니크, 3자 이상
+  String email = '';                  // 필수, 유니크, 이메일 형식
+  String password = '';               // 필수, 6자 이상
+  String? phone;                      // 선택, "010-1234-5678" 형태
+  UserRole role = UserRole.staff;     // 필수, 새 권한 시스템
   
-  // username 중복 확인
+  // 전화번호 UI 지원 (드롭다운 + 텍스트 필드)
+  String phonePrefix = '010';         // 010, 02, 031 등
+  String phoneNumber = '';            // 7-8자리 숫자
+  final List<String> phonePrefixes = [
+    '010', '011', '016', '017', '018', '019',  // 휴대폰
+    '02',                                      // 서울
+    '031', '032', '033',                       // 경기도
+    '041', '042', '043', '044',                // 충청도
+    '051', '052', '053', '054', '055',         // 경상도
+    '061', '062', '063', '064',                // 전라도
+    '070',                                     // 인터넷전화
+  ];
+  
+  // 사용자명 중복 확인
   bool _isCheckingUsername = false;
   bool? _isUsernameAvailable;
   String? _lastCheckedUsername;
   Timer? _usernameCheckTimer;
-
-  // 전화번호 관련 상태
-  final List<UserPhoneField> phoneFields = [];
-  final List<String> phoneTypes = ['휴대폰', '사무실', '팩스', '기타'];
-
-  List<Company> companies = [];
-  List<Branch> branches = [];
   
   // Getters
   bool get isLoading => _isLoading;
   String? get error => _error;
   bool get isCheckingUsername => _isCheckingUsername;
   bool? get isUsernameAvailable => _isUsernameAvailable;
+  
+  /// 현재 전화번호 (드롭다운 + 텍스트 필드 → 통합 형태)
+  String get combinedPhoneNumber {
+    if (phoneNumber.isEmpty) return '';
+    return PhoneNumberUtil.combineFromUI(phonePrefix, phoneNumber);
+  }
+  
+  /// 필수 필드 완성 여부 확인
+  bool get isFormValid {
+    return name.isNotEmpty &&
+           username.isNotEmpty &&
+           email.isNotEmpty &&
+           password.isNotEmpty &&
+           _isUsernameAvailable == true;
+  }
 
   UserFormController({this.userId}) {
     isEditMode = userId != null;
     if (isEditMode) {
-      loadUser();
-    } else {
-      addPhoneField();
-    }
-    loadCompanies();
-  }
-
-  // 회사 목록 로드
-  Future<void> loadCompanies() async {
-    try {
-      final result = await _companyService.getCompanies();
-      companies = result.items;  // PaginatedResponse에서 items 추출
-      notifyListeners();
-    } catch (e) {
-      debugPrint('회사 목록 로드 실패: $e');
-      companies = [];
-      notifyListeners();
+      _loadUser();
     }
   }
 
-  // 회사 ID에 따라 지점 목록 로드
-  void loadBranches(int companyId) {
-    final company = companies.firstWhere(
-      (c) => c.id == companyId,
-      orElse: () => Company(
-        id: companyId,
-        name: '알 수 없는 회사',
-        branches: [],
-      ),
-    );
-    branches = company.branches ?? [];
-    // 지점 변경 시 이전 선택 지점이 새 회사에 없으면 초기화
-    if (branchId != null && !branches.any((b) => b.id == branchId)) {
-      branchId = null;
-    }
+  /// 전화번호 접두사 변경
+  void updatePhonePrefix(String prefix) {
+    phonePrefix = prefix;
+    phone = combinedPhoneNumber;
     notifyListeners();
   }
 
-  // 사용자 정보 로드 (수정 모드)
-  Future<void> loadUser() async {
+  /// 전화번호 번호 부분 변경
+  void updatePhoneNumber(String number) {
+    phoneNumber = number;
+    phone = combinedPhoneNumber;
+    notifyListeners();
+  }
+
+  /// 사용자 정보 로드 (수정 모드, 서버 API v0.2.1 대응)
+  Future<void> _loadUser() async {
     if (userId == null) return;
     
     _isLoading = true;
@@ -100,74 +99,64 @@ class UserFormController extends ChangeNotifier {
     notifyListeners();
     
     try {
-      final user = await _userService.getUser(userId!);
+      final result = await _userRepository.getUserById(userId!);
       
-      if (user != null) {
-        name = user.name;
-        username = user.username ?? '';
-        companyId = user.companyId;
-        branchId = user.branchId;
-        role = user.role;
-        position = user.position ?? '';
-        email = user.email ?? '';
-        if (companyId != null) {
-          loadBranches(companyId!);
-        }
-        phoneFields.clear();
-        if (user.phoneNumbers.isNotEmpty) {
-          for (var phone in user.phoneNumbers) {
-            phoneFields.add(
-              UserPhoneField(
-                type: phone['type'] ?? '휴대폰',
-                initialValue: phone['number'] ?? '',
-              ),
-            );
+      result.fold(
+        (failure) {
+          _error = _mapFailureToString(failure);
+        },
+        (user) {
+          name = user.name;
+          username = user.username;
+          email = user.email;
+          role = user.role;
+          
+          // 전화번호 UI 분리 (서버: "010-1234-5678" → UI: 접두사 + 번호)
+          if (user.phone != null && user.phone!.isNotEmpty) {
+            final phoneData = PhoneNumberUtil.splitForUI(user.phone);
+            phonePrefix = phoneData['prefix'] ?? '010';
+            phoneNumber = phoneData['number'] ?? '';
+            phone = user.phone;
           }
-        } else {
-          addPhoneField();
-        }
-      }
+        },
+      );
     } catch (e) {
-      _error = e.toString();
+      _error = '사용자 정보를 불러올 수 없습니다: ${e.toString()}';
     } finally {
       _isLoading = false;
       notifyListeners();
     }
   }
-
-  // 전화번호 필드 추가
-  void addPhoneField() {
-    phoneFields.add(UserPhoneField(type: '휴대폰'));
-    notifyListeners();
-  }
-
-  // 전화번호 필드 삭제
-  void removePhoneField(int index) {
-    if (phoneFields.length > 1) {
-      phoneFields[index].dispose();
-      phoneFields.removeAt(index);
-      notifyListeners();
-    }
-  }
   
-  // Username 중복 확인
+  /// 사용자명 중복 확인 (서버 API v0.2.1 대응)
   void checkUsernameAvailability(String value) {
-    if (value.isEmpty || value == _lastCheckedUsername) {
+    if (value.isEmpty || value == _lastCheckedUsername || value.length < 3) {
       return;
     }
     
-    // 디바운싱
+    // 디바운싱 (500ms 대기)
     _usernameCheckTimer?.cancel();
     _usernameCheckTimer = Timer(const Duration(milliseconds: 500), () async {
       _isCheckingUsername = true;
       notifyListeners();
       
       try {
-        final isDuplicate = await _userService.checkDuplicateUsername(value);
-        _isUsernameAvailable = !isDuplicate;
-        _lastCheckedUsername = value;
+        final params = CheckUsernameAvailabilityParams(username: value);
+        final result = await _checkUsernameUseCase(params);
+        
+        result.fold(
+          (failure) {
+            _isUsernameAvailable = null;
+            debugPrint('사용자명 중복 확인 실패: ${failure.message}');
+          },
+          (isAvailable) {
+            _isUsernameAvailable = isAvailable;
+            _lastCheckedUsername = value;
+          },
+        );
       } catch (e) {
         _isUsernameAvailable = null;
+        debugPrint('사용자명 중복 확인 오류: $e');
       } finally {
         _isCheckingUsername = false;
         notifyListeners();
@@ -175,33 +164,37 @@ class UserFormController extends ChangeNotifier {
     });
   }
 
-  // 사용자 저장 (UI에서 호출)
+  /// 사용자 저장 (서버 API v0.2.1 대응)
   Future<void> saveUser(Function(String? error) onResult) async {
+    // 폼 유효성 검사
     if (formKey.currentState?.validate() != true) {
-      onResult('폼 유효성 검사 실패');
+      onResult('폼 유효성 검사를 통과하지 못했습니다.');
       return;
     }
     formKey.currentState?.save();
     
-    if (companyId == null) {
-      onResult('소속 회사를 선택해주세요');
+    // 필수 필드 검증 강화
+    if (name.trim().isEmpty) {
+      onResult('이름을 입력해주세요.');
+      return;
+    }
+    if (username.trim().isEmpty) {
+      onResult('사용자명을 입력해주세요.');
+      return;
+    }
+    if (email.trim().isEmpty) {
+      onResult('이메일을 입력해주세요.');
+      return;
+    }
+    if (!isEditMode && password.trim().isEmpty) {
+      onResult('비밀번호를 입력해주세요.');
       return;
     }
     
-    // 신규 등록 시 username 중복 확인
-    if (!isEditMode) {
-      if (username.isEmpty) {
-        onResult('사용자명을 입력해주세요');
-        return;
-      }
-      if (_isUsernameAvailable == false) {
-        onResult('이미 사용중인 사용자명입니다');
-        return;
-      }
-      if (password.isEmpty) {
-        onResult('비밀번호를 입력해주세요');
-        return;
-      }
+    // 신규 등록 시 사용자명 중복 확인
+    if (!isEditMode && _isUsernameAvailable != true) {
+      onResult('사용자명 중복을 확인해주세요.');
+      return;
     }
     
     _isLoading = true;
@@ -209,46 +202,50 @@ class UserFormController extends ChangeNotifier {
     notifyListeners();
     
     try {
-      // 전화번호 목록 준비
-      String? phoneNumber;
-      for (var phoneField in phoneFields) {
-        if (phoneField.number.isNotEmpty) {
-          phoneNumber = phoneField.number;
-          break; // API는 단일 전화번호만 지원
-        }
-      }
+      // 전화번호 통합 (드롭다운 + 텍스트 → 서버 형태)
+      final phoneNumber = combinedPhoneNumber;
       
       if (isEditMode && userId != null) {
         // 사용자 수정
-        await _userService.updateUser(
-          userId!,
+        final userToUpdate = User(
+          id: userId,
+          username: username,
+          email: email,
           name: name,
-          email: email.isNotEmpty ? email : null,
-          phone: phoneNumber,
-          companyId: companyId,
-          branchId: branchId,
+          phone: phoneNumber.isEmpty ? null : phoneNumber,
           role: role,
-          position: position.isNotEmpty ? position : null,
-          password: password.isNotEmpty ? password : null,
+        );
+        
+        final result = await _userRepository.updateUser(
+          userId!,
+          userToUpdate,
+          newPassword: password.isNotEmpty ? password : null,
+        );
+        
+        result.fold(
+          (failure) => onResult(_mapFailureToString(failure)),
+          (_) => onResult(null),
         );
       } else {
         // 사용자 생성
-        await _userService.createUser(
+        final params = CreateUserParams(
           username: username,
           email: email,
           password: password,
           name: name,
+          phone: phoneNumber.isEmpty ? null : phoneNumber,
           role: role,
-          companyId: companyId!,
-          branchId: branchId,
-          phone: phoneNumber,
-          position: position.isNotEmpty ? position : null,
+        );
+        
+        final result = await _createUserUseCase(params);
+        
+        result.fold(
+          (failure) => onResult(_mapFailureToString(failure)),
+          (_) => onResult(null),
         );
       }
-      
-      onResult(null);
     } catch (e) {
-      _error = e.toString();
+      _error = '사용자 저장 중 오류가 발생했습니다: ${e.toString()}';
       onResult(_error);
     } finally {
       _isLoading = false;
@@ -256,16 +253,67 @@ class UserFormController extends ChangeNotifier {
     }
   }
 
-  // 컨트롤러 해제
+  /// 역할 한글명 반환
+  String getRoleDisplayName(UserRole role) {
+    return role.displayName;
+  }
+  
+  /// 입력값 유효성 검증 (실시간)
+  Map<String, String?> validateFields() {
+    final errors = <String, String?>{};
+    
+    if (name.trim().isEmpty) {
+      errors['name'] = '이름을 입력해주세요.';
+    }
+    
+    if (username.trim().isEmpty) {
+      errors['username'] = '사용자명을 입력해주세요.';
+    } else if (username.length < 3) {
+      errors['username'] = '사용자명은 3자 이상이어야 합니다.';
+    } else if (!RegExp(r'^[a-zA-Z0-9_]+$').hasMatch(username)) {
+      errors['username'] = '사용자명은 영문, 숫자, 언더스코어만 사용 가능합니다.';
+    }
+    
+    if (email.trim().isEmpty) {
+      errors['email'] = '이메일을 입력해주세요.';
+    } else if (!RegExp(r'^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$').hasMatch(email)) {
+      errors['email'] = '올바른 이메일 형식이 아닙니다.';
+    }
+    
+    if (!isEditMode && password.trim().isEmpty) {
+      errors['password'] = '비밀번호를 입력해주세요.';
+    } else if (!isEditMode && password.length < 6) {
+      errors['password'] = '비밀번호는 6자 이상이어야 합니다.';
+    }
+    
+    if (phoneNumber.isNotEmpty && !RegExp(r'^\d{7,8}$').hasMatch(phoneNumber)) {
+      errors['phone'] = '전화번호는 7-8자리 숫자로 입력해주세요.';
+    }
+    
+    return errors;
+  }
+
+  /// Failure를 사용자 친화적 메시지로 변환
+  String _mapFailureToString(Failure failure) {
+    if (failure is ValidationFailure) {
+      return failure.message;
+    } else if (failure is DuplicateFailure) {
+      return '이미 사용 중인 사용자명 또는 이메일입니다.';
+    } else if (failure is NotFoundFailure) {
+      return '사용자를 찾을 수 없습니다.';
+    } else if (failure is AuthenticationFailure) {
+      return '인증이 필요합니다.';
+    } else if (failure is AuthorizationFailure) {
+      return '권한이 없습니다.';
+    } else {
+      return failure.message;
+    }
+  }
+
+  /// 컨트롤러 해제
   @override
   void dispose() {
     _usernameCheckTimer?.cancel();
-    for (var phoneField in phoneFields) {
-      phoneField.dispose();
-    }
     super.dispose();
   }
-  
-  // API 모드만 사용 (Mock 데이터 제거됨)
-  // void toggleApiMode() 메서드 제거
 }