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>
2025-08-15 23:31:51 +09:00
parent c1063f5670
commit 93bceb8a6c
20 changed files with 2006 additions and 2017 deletions
--- a/lib/domain/repositories/user_repository.dart
+++ b/lib/domain/repositories/user_repository.dart
@@ -3,94 +3,54 @@ import '../../core/errors/failures.dart';
 import '../../models/user_model.dart';
 import '../../data/models/common/paginated_response.dart';

-/// 사용자 관리 Repository 인터페이스
-/// 사용자 계정 생성, 수정, 삭제 및 권한 관리를 담당
+/// 사용자 관리 Repository 인터페이스 (서버 API v0.2.1 대응)
+/// Clean Architecture Domain Layer - Repository 계약
 abstract class UserRepository {
-  /// 사용자 목록 조회
+  /// 사용자 목록 조회 (페이지네이션 지원)
  /// [page] 페이지 번호 (기본값: 1)
-  /// [limit] 페이지당 항목 수 (기본값: 20)
-  /// [search] 검색어 (사용자명, 이메일, 회사명 등)
-  /// [role] 역할 필터 ('S': 관리자, 'M': 멤버)
-  /// [companyId] 회사 ID 필터
+  /// [perPage] 페이지당 항목 수 (기본값: 20)  
+  /// [role] 역할 필터 (admin, manager, staff)
  /// [isActive] 활성화 상태 필터
-  /// [sortBy] 정렬 기준 ('name', 'createdAt', 'role' 등)
-  /// [sortOrder] 정렬 순서 ('asc', 'desc')
  /// Returns: 페이지네이션된 사용자 목록
  Future<Either<Failure, PaginatedResponse<User>>> getUsers({
    int? page,
-    int? limit,
-    String? search,
-    String? role,
-    int? companyId,
+    int? perPage,
+    UserRole? role,
    bool? isActive,
-    String? sortBy,
-    String? sortOrder,
  });

-  /// 사용자 상세 정보 조회
+  /// 단일 사용자 조회
  /// [id] 사용자 고유 식별자
-  /// Returns: 사용자 상세 정보 (회사, 지점 정보 포함)
+  /// Returns: 사용자 상세 정보
  Future<Either<Failure, User>> getUserById(int id);

  /// 사용자 계정 생성
-  /// [user] 생성할 사용자 정보
-  /// [password] 초기 비밀번호
+  /// [user] 생성할 사용자 정보 (username, email, name, role 필수)
+  /// [password] 초기 비밀번호 (필수, 6자 이상)
  /// Returns: 생성된 사용자 정보 (ID 포함)
-  Future<Either<Failure, User>> createUser(User user, String password);
+  Future<Either<Failure, User>> createUser({
+    required String username,
+    required String email,
+    required String password,
+    required String name,
+    String? phone,
+    required UserRole role,
+  });

  /// 사용자 정보 수정
  /// [id] 수정할 사용자 고유 식별자
  /// [user] 수정할 사용자 정보
+  /// [newPassword] 새 비밀번호 (선택적)
  /// Returns: 수정된 사용자 정보
-  Future<Either<Failure, User>> updateUser(int id, User user);
+  Future<Either<Failure, User>> updateUser(int id, User user, {String? newPassword});

-  /// 사용자 삭제
+  /// 사용자 소프트 삭제 (is_active = false)
  /// [id] 삭제할 사용자 고유 식별자
  /// Returns: 삭제 성공/실패 여부
  Future<Either<Failure, void>> deleteUser(int id);

-  /// 사용자 상태 토글 (활성화/비활성화)
-  /// [id] 상태를 변경할 사용자 고유 식별자
-  /// Returns: 상태 변경된 사용자 정보
-  Future<Either<Failure, User>> toggleUserStatus(int id);
-
-  /// 사용자 비밀번호 재설정
-  /// [id] 비밀번호를 재설정할 사용자 ID
-  /// [newPassword] 새 비밀번호
-  /// Returns: 재설정 성공/실패 여부
-  Future<Either<Failure, void>> resetPassword(int id, String newPassword);
-
-  /// 사용자 역할 변경
-  /// [id] 역할을 변경할 사용자 ID
-  /// [newRole] 새 역할 ('S': 관리자, 'M': 멤버)
-  /// Returns: 역할 변경된 사용자 정보
-  Future<Either<Failure, User>> changeUserRole(int id, String newRole);
-
-  /// 사용자명(이메일) 중복 체크
-  /// [username] 체크할 사용자명(이메일)
-  /// [excludeId] 체크에서 제외할 사용자 ID (수정 시 현재 사용자 제외용)
-  /// Returns: 중복 여부 (true: 중복됨, false: 중복되지 않음)
-  Future<Either<Failure, bool>> isDuplicateUsername(String username, {int? excludeId});
-
-  /// 회사별 사용자 목록 조회
-  /// [companyId] 회사 ID
-  /// [includeInactive] 비활성화 사용자 포함 여부
-  /// Returns: 해당 회사의 사용자 목록
-  Future<Either<Failure, List<User>>> getUsersByCompany(int companyId, {bool includeInactive = false});
-
-  /// 역할별 사용자 수 통계
-  /// Returns: 역할별 사용자 수 (관리자, 멤버)
-  Future<Either<Failure, Map<String, int>>> getUserCountByRole();
-
-  /// 사용자 검색 (자동완성용)
-  /// [query] 검색 쿼리
-  /// [companyId] 회사 ID 필터 (선택적)
-  /// [limit] 결과 제한 수 (기본값: 10)
-  /// Returns: 일치하는 사용자 정보 목록
-  Future<Either<Failure, List<User>>> searchUsers(String query, {int? companyId, int? limit});
-
-  /// 사용자 마지막 로그인 시간 업데이트
-  /// [id] 사용자 ID
-  /// Returns: 업데이트 성공/실패 여부
-  Future<Either<Failure, void>> updateLastLoginTime(int id);
+  /// 사용자명 사용 가능 여부 확인
+  /// [username] 체크할 사용자명
+  /// Returns: 사용 가능 여부 응답
+  Future<Either<Failure, bool>> checkUsernameAvailability(String username);
 }
--- a/lib/domain/usecases/user/check_username_availability_usecase.dart
+++ b/lib/domain/usecases/user/check_username_availability_usecase.dart
@@ -0,0 +1,51 @@
+import 'package:dartz/dartz.dart';
+import 'package:injectable/injectable.dart';
+import '../../../core/errors/failures.dart';
+import '../../repositories/user_repository.dart';
+import '../base_usecase.dart';
+
+/// 사용자명 중복 확인 파라미터
+class CheckUsernameAvailabilityParams {
+  final String username;
+
+  const CheckUsernameAvailabilityParams({
+    required this.username,
+  });
+}
+
+/// 사용자명 사용 가능 여부 확인 UseCase (서버 API v0.2.1 대응)
+/// 사용자 생성 및 수정 시 사용자명 중복 검증
+@injectable
+class CheckUsernameAvailabilityUseCase extends UseCase<bool, CheckUsernameAvailabilityParams> {
+  final UserRepository _userRepository;
+
+  CheckUsernameAvailabilityUseCase(this._userRepository);
+
+  @override
+  Future<Either<Failure, bool>> call(CheckUsernameAvailabilityParams params) async {
+    // 입력값 검증
+    if (params.username.trim().isEmpty) {
+      return Left(ValidationFailure(
+        message: '사용자명을 입력해주세요.',
+        errors: {'username': '사용자명을 입력해주세요.'},
+      ));
+    }
+
+    if (params.username.length < 3) {
+      return Left(ValidationFailure(
+        message: '사용자명은 3자 이상이어야 합니다.',
+        errors: {'username': '사용자명은 3자 이상이어야 합니다.'},
+      ));
+    }
+
+    // 사용자명 형식 검증 (영문, 숫자, 언더스코어만)
+    if (!RegExp(r'^[a-zA-Z0-9_]+$').hasMatch(params.username)) {
+      return Left(ValidationFailure(
+        message: '사용자명은 영문, 숫자, 언더스코어만 사용 가능합니다.',
+        errors: {'username': '사용자명은 영문, 숫자, 언더스코어만 사용 가능합니다.'},
+      ));
+    }
+
+    return await _userRepository.checkUsernameAvailability(params.username);
+  }
+}
--- a/lib/domain/usecases/user/create_user_usecase.dart
+++ b/lib/domain/usecases/user/create_user_usecase.dart
@@ -1,20 +1,18 @@
 import 'package:dartz/dartz.dart';
-import '../../../services/user_service.dart';
-import '../../../models/user_model.dart' as model;
-import '../../../core/constants/app_constants.dart';
+import 'package:injectable/injectable.dart';
+import '../../../models/user_model.dart';
 import '../../../core/errors/failures.dart';
+import '../../repositories/user_repository.dart';
 import '../base_usecase.dart';

-/// 사용자 생성 파라미터
+/// 사용자 생성 파라미터 (서버 API v0.2.1 대응)
 class CreateUserParams {
  final String username;
  final String email;
  final String password;
  final String name;
-  final String role;
-  final int companyId;
+  final UserRole role;
  final String? phone;
-  final String? position;

  const CreateUserParams({
    required this.username,
@@ -22,70 +20,41 @@ class CreateUserParams {
    required this.password,
    required this.name,
    required this.role,
-    required this.companyId,
    this.phone,
-    this.position,
  });
 }

-/// 사용자 생성 UseCase
-/// 유효성 검증 및 중복 체크 포함
-class CreateUserUseCase extends UseCase<model.User, CreateUserParams> {
-  final UserService _userService;
+/// 사용자 생성 UseCase (Clean Architecture Domain Layer)
+/// 입력값 유효성 검증 및 사용자 계정 생성
+@injectable
+class CreateUserUseCase extends UseCase<User, CreateUserParams> {
+  final UserRepository _userRepository;

-  CreateUserUseCase(this._userService);
+  CreateUserUseCase(this._userRepository);

  @override
-  Future<Either<Failure, model.User>> call(CreateUserParams params) async {
-    try {
-      // 유효성 검증
-      final validationResult = _validateUserInput(params);
-      if (validationResult != null) {
-        return Left(validationResult);
-      }
-
-      final user = await _userService.createUser(
-        username: params.username,
-        email: params.email,
-        password: params.password,
-        name: params.name,
-        role: params.role,
-        companyId: params.companyId,
-        phone: params.phone,
-        position: params.position,
-      );
-      
-      return Right(user);
-    } catch (e) {
-      if (e.toString().contains('이미 존재')) {
-        return Left(ValidationFailure(
-          message: '이미 존재하는 사용자입니다.',
-          code: 'USER_EXISTS',
-          errors: {
-            'username': '이미 사용중인 사용자명입니다.',
-            'email': '이미 등록된 이메일입니다.',
-          },
-          originalError: e,
-        ));
-      } else if (e.toString().contains('권한')) {
-        return Left(PermissionFailure(
-          message: '사용자를 생성할 권한이 없습니다.',
-          code: 'PERMISSION_DENIED',
-          originalError: e,
-        ));
-      } else {
-        return Left(ServerFailure(
-          message: '사용자 생성 중 오류가 발생했습니다.',
-          originalError: e,
-        ));
-      }
+  Future<Either<Failure, User>> call(CreateUserParams params) async {
+    // 입력값 유효성 검증
+    final validationResult = _validateUserInput(params);
+    if (validationResult != null) {
+      return Left(validationResult);
    }
+
+    return await _userRepository.createUser(
+      username: params.username,
+      email: params.email,
+      password: params.password,
+      name: params.name,
+      phone: params.phone,
+      role: params.role,
+    );
  }

+  /// 입력값 유효성 검증 (서버 API v0.2.1 규칙 적용)
  ValidationFailure? _validateUserInput(CreateUserParams params) {
    final errors = <String, String>{};

-    // 사용자명 검증
+    // 사용자명 검증 (3자 이상, 영문/숫자/언더스코어만)
    if (params.username.length < 3) {
      errors['username'] = '사용자명은 3자 이상이어야 합니다.';
    }
@@ -93,33 +62,25 @@ class CreateUserUseCase extends UseCase<model.User, CreateUserParams> {
      errors['username'] = '사용자명은 영문, 숫자, 언더스코어만 사용 가능합니다.';
    }

-    // 이메일 검증
-    if (!AppConstants.emailRegex.hasMatch(params.email)) {
+    // 이메일 검증 (기본 이메일 형식)
+    if (!RegExp(r'^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$').hasMatch(params.email)) {
      errors['email'] = '올바른 이메일 형식이 아닙니다.';
    }

-    // 비밀번호 검증
-    if (params.password.length < 8) {
-      errors['password'] = '비밀번호는 8자 이상이어야 합니다.';
-    }
-    if (!RegExp(r'^(?=.*[A-Za-z])(?=.*\d)(?=.*[@$!%*#?&])[A-Za-z\d@$!%*#?&]').hasMatch(params.password)) {
-      errors['password'] = '비밀번호는 영문, 숫자, 특수문자를 포함해야 합니다.';
+    // 비밀번호 검증 (서버 API: 6자 이상)
+    if (params.password.length < 6) {
+      errors['password'] = '비밀번호는 6자 이상이어야 합니다.';
    }

-    // 이름 검증
-    if (params.name.isEmpty) {
+    // 이름 검증 (필수)
+    if (params.name.trim().isEmpty) {
      errors['name'] = '이름을 입력해주세요.';
    }

-    // 역할 검증
-    if (!['S', 'M', 'U', 'V'].contains(params.role)) {
-      errors['role'] = '올바른 역할을 선택해주세요.';
-    }
-
-    // 전화번호 검증 (선택사항)
+    // 전화번호 검증 (선택적, "010-1234-5678" 형식)
    if (params.phone != null && params.phone!.isNotEmpty) {
-      if (!AppConstants.phoneRegex.hasMatch(params.phone!)) {
-        errors['phone'] = '올바른 전화번호 형식이 아닙니다.';
+      if (!PhoneNumberUtil.isValidFormat(params.phone!)) {
+        errors['phone'] = '전화번호는 "010-1234-5678" 형식으로 입력해주세요.';
      }
    }

--- a/lib/domain/usecases/user/get_users_usecase.dart
+++ b/lib/domain/usecases/user/get_users_usecase.dart
@@ -1,67 +1,41 @@
 import 'package:dartz/dartz.dart';
-import '../../../services/user_service.dart';
-import '../../../models/user_model.dart' as model;
+import 'package:injectable/injectable.dart';
+import '../../../models/user_model.dart';
 import '../../../core/errors/failures.dart';
+import '../../repositories/user_repository.dart';
+import '../../../data/models/common/paginated_response.dart';
 import '../base_usecase.dart';

-/// 사용자 목록 조회 파라미터
+/// 사용자 목록 조회 파라미터 (서버 API v0.2.1 대응)
 class GetUsersParams {
  final int page;
  final int perPage;
+  final UserRole? role;
  final bool? isActive;
-  final int? companyId;
-  final String? role;

  const GetUsersParams({
    this.page = 1,
    this.perPage = 20,
-    this.isActive,
-    this.companyId,
    this.role,
+    this.isActive,
  });
 }

-/// 사용자 목록 조회 UseCase
-/// 필터링 및 페이지네이션 지원
-class GetUsersUseCase extends UseCase<List<model.User>, GetUsersParams> {
-  final UserService _userService;
+/// 사용자 목록 조회 UseCase (Clean Architecture Domain Layer)
+/// 페이지네이션과 필터링을 지원하는 사용자 목록 조회
+@injectable
+class GetUsersUseCase extends UseCase<PaginatedResponse<User>, GetUsersParams> {
+  final UserRepository _userRepository;

-  GetUsersUseCase(this._userService);
+  GetUsersUseCase(this._userRepository);

  @override
-  Future<Either<Failure, List<model.User>>> call(GetUsersParams params) async {
-    try {
-      // 권한 검증 (관리자, 매니저만 사용자 목록 조회 가능)
-      // 실제 구현에서는 현재 사용자 권한 체크 필요
-      
-      final response = await _userService.getUsers(
-        page: params.page,
-        perPage: params.perPage,
-        isActive: params.isActive,
-        companyId: params.companyId,
-        role: params.role,
-      );
-      
-      // PaginatedResponse에서 items만 추출
-      return Right(response.items);
-    } catch (e) {
-      if (e.toString().contains('권한')) {
-        return Left(PermissionFailure(
-          message: '사용자 목록을 조회할 권한이 없습니다.',
-          code: 'PERMISSION_DENIED',
-          originalError: e,
-        ));
-      } else if (e.toString().contains('네트워크')) {
-        return Left(NetworkFailure(
-          message: '네트워크 연결을 확인해주세요.',
-          originalError: e,
-        ));
-      } else {
-        return Left(ServerFailure(
-          message: '사용자 목록을 불러오는 중 오류가 발생했습니다.',
-          originalError: e,
-        ));
-      }
-    }
+  Future<Either<Failure, PaginatedResponse<User>>> call(GetUsersParams params) async {
+    return await _userRepository.getUsers(
+      page: params.page,
+      perPage: params.perPage,
+      role: params.role,
+      isActive: params.isActive,
+    );
  }
 }