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() 메서드 제거
 }

lib/screens/user/controllers/user_list_controller.dart

@@ -1,41 +1,42 @@
 import 'package:flutter/material.dart';
 import 'package:get_it/get_it.dart';
 import 'package:superport/models/user_model.dart';
-import 'package:superport/services/user_service.dart';
-import 'package:superport/core/utils/error_handler.dart';
 import 'package:superport/core/controllers/base_list_controller.dart';
 import 'package:superport/data/models/common/pagination_params.dart';
+import 'package:superport/domain/usecases/user/get_users_usecase.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';
 
-/// 담당자 목록 화면의 상태 및 비즈니스 로직을 담당하는 컨트롤러 (리팩토링 버전)
-/// BaseListController를 상속받아 공통 기능을 재사용
+/// 사용자 목록 화면 컨트롤러 (서버 API v0.2.1 대응)
+/// Clean Architecture Presentation Layer - 새로운 UseCase 패턴 적용
 class UserListController extends BaseListController<User> {
-  late final UserService _userService;
+  late final GetUsersUseCase _getUsersUseCase;
+  late final CreateUserUseCase _createUserUseCase;
+  late final CheckUsernameAvailabilityUseCase _checkUsernameUseCase;
+  late final UserRepository _userRepository;
   
-  // 필터 옵션
-  int? _filterCompanyId;
-  String? _filterRole;
+  // 필터 옵션 (서버 API v0.2.1 지원 필드만)
+  UserRole? _filterRole;
   bool? _filterIsActive;
-  bool _includeInactive = false; // 비활성 사용자 포함 여부
+  bool _includeInactive = false;
   
   // Getters
   List<User> get users => items;
-  int? get filterCompanyId => _filterCompanyId;
-  String? get filterRole => _filterRole;
+  UserRole? get filterRole => _filterRole;
   bool? get filterIsActive => _filterIsActive;
   bool get includeInactive => _includeInactive;
   
-  // 비활성 포함 토글
-  void toggleIncludeInactive() {
-    _includeInactive = !_includeInactive;
-    loadData(isRefresh: true);
-  }
+  // 사용자명 중복 체크 상태
+  bool _usernameCheckInProgress = false;
+  bool get isCheckingUsername => _usernameCheckInProgress;
 
   UserListController() {
-    if (GetIt.instance.isRegistered<UserService>()) {
-      _userService = GetIt.instance<UserService>();
-    } else {
-      throw Exception('UserService not registered in GetIt');
-    }
+    _getUsersUseCase = GetIt.instance<GetUsersUseCase>();
+    _createUserUseCase = GetIt.instance<CreateUserUseCase>();
+    _checkUsernameUseCase = GetIt.instance<CheckUsernameAvailabilityUseCase>();
+    _userRepository = GetIt.instance<UserRepository>();
   }
 
   @override
@@ -43,77 +44,70 @@ class UserListController extends BaseListController<User> {
     required PaginationParams params,
     Map<String, dynamic>? additionalFilters,
   }) async {
-    // API 호출 (이제 PaginatedResponse 반환)
-    final response = await ErrorHandler.handleApiCall<dynamic>(
-      () => _userService.getUsers(
-        page: params.page,
-        perPage: params.perPage,
-        isActive: _filterIsActive,
-        companyId: _filterCompanyId,
-        role: _filterRole,
-        includeInactive: _includeInactive,
-        // search 파라미터 제거 (API에서 지원하지 않음)
-      ),
-      onError: (failure) {
-        throw failure;
+    final getUsersParams = GetUsersParams(
+      page: params.page,
+      perPage: params.perPage,
+      role: _filterRole,
+      isActive: _filterIsActive,
+    );
+    
+    final result = await _getUsersUseCase(getUsersParams);
+    
+    return result.fold(
+      (failure) => throw _mapFailureToException(failure),
+      (paginatedResponse) {
+        final meta = PaginationMeta(
+          currentPage: paginatedResponse.page,
+          perPage: paginatedResponse.size,
+          total: paginatedResponse.totalElements,
+          totalPages: paginatedResponse.totalPages,
+          hasNext: !paginatedResponse.last,
+          hasPrevious: !paginatedResponse.first,
+        );
+        
+        return PagedResult(items: paginatedResponse.items, meta: meta);
       },
     );
-    
-    // PaginatedResponse를 PagedResult로 변환
-    final meta = PaginationMeta(
-      currentPage: response.page,
-      perPage: response.size,
-      total: response.totalElements,
-      totalPages: response.totalPages,
-      hasNext: !response.last,
-      hasPrevious: !response.first,
-    );
-    
-    return PagedResult(items: response.items, meta: meta);
   }
 
   @override
   bool filterItem(User item, String query) {
     final q = query.toLowerCase();
     return item.name.toLowerCase().contains(q) ||
-           (item.email?.toLowerCase().contains(q) ?? false) ||
-           (item.username?.toLowerCase().contains(q) ?? false);
+           item.email.toLowerCase().contains(q) ||
+           item.username.toLowerCase().contains(q);
   }
 
-  /// 사용자 목록 초기 로드 (호환성 유지)
-  Future<void> loadUsers({bool refresh = false}) async {
-    await loadData(isRefresh: refresh);
-  }
-
-  /// 필터 설정
+  /// 필터 설정 (서버 API v0.2.1 지원 필드만)
   void setFilters({
-    int? companyId,
-    String? role,
+    UserRole? role,
     bool? isActive,
+    String? roleString,
   }) {
-    _filterCompanyId = companyId;
-    _filterRole = role;
+    // String으로 들어온 role을 UserRole로 변환
+    if (roleString != null) {
+      try {
+        _filterRole = UserRole.fromString(roleString);
+      } catch (e) {
+        _filterRole = null;
+      }
+    } else {
+      _filterRole = role;
+    }
     _filterIsActive = isActive;
     loadData(isRefresh: true);
   }
 
   /// 필터 초기화
   void clearFilters() {
-    _filterCompanyId = null;
     _filterRole = null;
     _filterIsActive = null;
     search('');
     loadData(isRefresh: true);
   }
 
-  /// 회사별 필터링
-  void filterByCompany(int? companyId) {
-    _filterCompanyId = companyId;
-    loadData(isRefresh: true);
-  }
-
-  /// 역할별 필터링
-  void filterByRole(String? role) {
+  /// 역할별 필터링 (새 권한 시스템)
+  void filterByRole(UserRole? role) {
     _filterRole = role;
     loadData(isRefresh: true);
   }
@@ -124,77 +118,95 @@ class UserListController extends BaseListController<User> {
     loadData(isRefresh: true);
   }
 
-  /// 사용자 추가
-  Future<void> addUser(User user) async {
-    await ErrorHandler.handleApiCall<void>(
-      () => _userService.createUser(
-        username: user.username ?? '',
-        email: user.email ?? '',
-        password: 'temp123', // 임시 비밀번호
-        name: user.name,
-        role: user.role,
-        companyId: user.companyId,
-        branchId: user.branchId,
-      ),
-      onError: (failure) {
-        throw failure;
-      },
+  /// 사용자 생성
+  Future<void> createUser({
+    required String username,
+    required String email,
+    required String password,
+    required String name,
+    String? phone,
+    required UserRole role,
+  }) async {
+    final params = CreateUserParams(
+      username: username,
+      email: email,
+      password: password,
+      name: name,
+      phone: phone,
+      role: role,
     );
     
-    await refresh();
+    final result = await _createUserUseCase(params);
+    
+    result.fold(
+      (failure) {
+        throw _mapFailureToException(failure);
+      },
+      (user) {
+        // 성공 시 목록 새로고침
+        refresh();
+      },
+    );
   }
 
   /// 사용자 수정
-  Future<void> updateUser(User user) async {
-    await ErrorHandler.handleApiCall<void>(
-      () => _userService.updateUser(
-        user.id!,
-        name: user.name,
-        email: user.email,
-        companyId: user.companyId,
-        branchId: user.branchId,
-        role: user.role,
-        position: user.position,
-      ),
-      onError: (failure) {
-        throw failure;
-      },
+  Future<void> updateUser(User user, {String? newPassword}) async {
+    final result = await _userRepository.updateUser(
+      user.id!,
+      user,
+      newPassword: newPassword,
     );
     
-    updateItemLocally(user, (u) => u.id == user.id);
+    result.fold(
+      (failure) {
+        throw _mapFailureToException(failure);
+      },
+      (updatedUser) {
+        updateItemLocally(updatedUser, (u) => u.id == updatedUser.id);
+      },
+    );
   }
 
-  /// 사용자 삭제
+  /// 사용자 삭제 (소프트 딜리트)
   Future<void> deleteUser(int id) async {
-    await ErrorHandler.handleApiCall<void>(
-      () => _userService.deleteUser(id),
-      onError: (failure) {
-        throw failure;
-      },
-    );
+    final result = await _userRepository.deleteUser(id);
     
-    removeItemLocally((u) => u.id == id);
-  }
-
-  /// 사용자 활성/비활성 토글
-  Future<void> toggleUserActiveStatus(User user) async {
-    final updatedUser = user.copyWith(isActive: !user.isActive);
-    await updateUser(updatedUser);
-  }
-
-  /// 비밀번호 재설정
-  Future<void> resetPassword(int userId, String newPassword) async {
-    await ErrorHandler.handleApiCall<void>(
-      () => _userService.resetPassword(
-        userId: userId,
-        newPassword: newPassword,
-      ),
-      onError: (failure) {
-        throw failure;
+    result.fold(
+      (failure) {
+        throw _mapFailureToException(failure);
+      },
+      (_) {
+        removeItemLocally((u) => u.id == id);
       },
     );
   }
 
+  /// 사용자명 중복 확인
+  Future<bool> checkUsernameAvailability(String username) async {
+    _usernameCheckInProgress = true;
+    notifyListeners();
+    
+    try {
+      final params = CheckUsernameAvailabilityParams(username: username);
+      final result = await _checkUsernameUseCase(params);
+      
+      return result.fold(
+        (failure) {
+          throw _mapFailureToException(failure);
+        },
+        (isAvailable) => isAvailable,
+      );
+    } finally {
+      _usernameCheckInProgress = false;
+      notifyListeners();
+    }
+  }
+
+  /// 사용자 역할 한글명 반환
+  String getRoleDisplayName(UserRole role) {
+    return role.displayName;
+  }
+
   /// 사용자 ID로 단일 사용자 조회
   User? getUserById(int id) {
     try {
@@ -204,21 +216,49 @@ class UserListController extends BaseListController<User> {
     }
   }
 
-  /// 검색 쿼리 설정 (호환성 유지)
+  /// UI 호환성을 위한 메서드들
+  
+  /// 검색어 설정 (UI 호환용)
   void setSearchQuery(String query) {
-    search(query); // BaseListController의 search 메서드 사용
-  }
-
-  /// 사용자 상태 변경
-  Future<void> changeUserStatus(User user, bool isActive) async {
-    final updatedUser = user.copyWith(isActive: isActive);
-    await updateUser(updatedUser);
-  }
-
-  /// 지점명 가져오기 (임시 구현)
-  String getBranchName(int? branchId) {
-    if (branchId == null) return '본사';
-    return '지점 $branchId'; // 실제로는 CompanyService에서 가져와야 함
+    search(query);
   }
   
+  /// 데이터 로드 (UI 호환용)
+  void loadUsers({bool refresh = false}) {
+    if (refresh) {
+      this.refresh();
+    } else {
+      loadData();
+    }
+  }
+  
+  /// 사용자 상태 변경
+  Future<void> changeUserStatus(User user, bool newStatus) async {
+    final updatedUser = user.copyWith(isActive: newStatus);
+    await updateUser(updatedUser);
+  }
+  
+  /// 비활성 사용자 포함 토글
+  void toggleIncludeInactive() {
+    _includeInactive = !_includeInactive;
+    _filterIsActive = _includeInactive ? null : true;
+    loadData(isRefresh: true);
+  }
+
+  /// Failure를 Exception으로 매핑하는 헬퍼 메서드
+  Exception _mapFailureToException(Failure failure) {
+    if (failure is ValidationFailure) {
+      return Exception('입력값 검증 실패: ${failure.message}');
+    } else if (failure is NotFoundFailure) {
+      return Exception('사용자를 찾을 수 없습니다: ${failure.message}');
+    } else if (failure is DuplicateFailure) {
+      return Exception('중복된 데이터가 있습니다: ${failure.message}');
+    } else if (failure is AuthenticationFailure) {
+      return Exception('인증이 필요합니다: ${failure.message}');
+    } else if (failure is AuthorizationFailure) {
+      return Exception('권한이 없습니다: ${failure.message}');
+    } else {
+      return Exception('오류가 발생했습니다: ${failure.message}');
+    }
+  }
 }