주석화 진행상황 정리하고 핵심 모듈에 한글 주석 추가

lib/features/masters/user/data/dtos/user_dto.dart

@@ -3,6 +3,7 @@ import 'package:superport_v2/core/common/utils/json_utils.dart';
 
 import '../../domain/entities/user.dart';
 
+/// 사용자(User) API 응답을 표현하는 DTO.
 class UserDto {
   UserDto({
     this.id,
@@ -30,6 +31,7 @@ class UserDto {
   final DateTime? createdAt;
   final DateTime? updatedAt;
 
+  /// JSON에서 사용자 정보를 파싱한다.
   factory UserDto.fromJson(Map<String, dynamic> json) {
     return UserDto(
       id: json['id'] as int?,
@@ -48,6 +50,7 @@ class UserDto {
     );
   }
 
+  /// DTO를 도메인 [UserAccount] 엔티티로 변환한다.
   UserAccount toEntity() => UserAccount(
     id: id,
     employeeNo: employeeNo,
@@ -62,6 +65,7 @@ class UserDto {
     updatedAt: updatedAt,
   );
 
+  /// 페이징 응답을 [PaginatedResult]로 변환한다.
   static PaginatedResult<UserAccount> parsePaginated(
     Map<String, dynamic>? json,
   ) {
@@ -79,12 +83,14 @@ class UserDto {
   }
 }
 
+/// 사용자에 연결된 그룹 정보를 담는 DTO.
 class UserGroupDto {
   UserGroupDto({required this.id, required this.groupName});
 
   final int id;
   final String groupName;
 
+  /// JSON에서 그룹 정보를 파싱한다.
   factory UserGroupDto.fromJson(Map<String, dynamic> json) {
     return UserGroupDto(
       id: json['id'] as int,
@@ -92,9 +98,11 @@ class UserGroupDto {
     );
   }
 
+  /// DTO를 [UserGroup] 엔티티로 변환한다.
   UserGroup toEntity() => UserGroup(id: id, groupName: groupName);
 }
 
+/// 문자열/DateTime을 파싱해 [DateTime]으로 변환한다.
 DateTime? _parseDate(Object? value) {
   if (value == null) return null;
   if (value is DateTime) return value;

lib/features/masters/user/data/repositories/user_repository_remote.dart

@@ -6,6 +6,7 @@ import '../../domain/entities/user.dart';
 import '../../domain/repositories/user_repository.dart';
 import '../dtos/user_dto.dart';
 
+/// 사용자 마스터 API를 호출하는 원격 저장소.
 class UserRepositoryRemote implements UserRepository {
   UserRepositoryRemote({required ApiClient apiClient}) : _api = apiClient;
 
@@ -13,6 +14,7 @@ class UserRepositoryRemote implements UserRepository {
 
   static const _basePath = '/employees';
 
+  /// 사용자 목록을 조회한다.
   @override
   Future<PaginatedResult<UserAccount>> list({
     int page = 1,
@@ -36,6 +38,7 @@ class UserRepositoryRemote implements UserRepository {
     return UserDto.parsePaginated(response.data ?? const {});
   }
 
+  /// 사용자를 생성한다.
   @override
   Future<UserAccount> create(UserInput input) async {
     final response = await _api.post<Map<String, dynamic>>(
@@ -47,6 +50,7 @@ class UserRepositoryRemote implements UserRepository {
     return UserDto.fromJson(data).toEntity();
   }
 
+  /// 사용자 정보를 수정한다.
   @override
   Future<UserAccount> update(int id, UserInput input) async {
     final response = await _api.patch<Map<String, dynamic>>(
@@ -58,11 +62,13 @@ class UserRepositoryRemote implements UserRepository {
     return UserDto.fromJson(data).toEntity();
   }
 
+  /// 사용자를 삭제한다.
   @override
   Future<void> delete(int id) async {
     await _api.delete<void>('$_basePath/$id');
   }
 
+  /// 삭제된 사용자를 복구한다.
   @override
   Future<UserAccount> restore(int id) async {
     final response = await _api.post<Map<String, dynamic>>(

lib/features/masters/user/domain/entities/user.dart

@@ -1,3 +1,4 @@
+/// 사용자(User) 도메인 엔티티.
 class UserAccount {
   UserAccount({
     this.id,
@@ -25,6 +26,7 @@ class UserAccount {
   final DateTime? createdAt;
   final DateTime? updatedAt;
 
+  /// 선택된 속성만 변경한 새 인스턴스를 반환한다.
   UserAccount copyWith({
     int? id,
     String? employeeNo,
@@ -54,6 +56,7 @@ class UserAccount {
   }
 }
 
+/// 사용자에 연결된 그룹 정보.
 class UserGroup {
   UserGroup({required this.id, required this.groupName});
 
@@ -61,6 +64,7 @@ class UserGroup {
   final String groupName;
 }
 
+/// 사용자 생성/수정 입력 모델.
 class UserInput {
   UserInput({
     required this.employeeNo,
@@ -80,6 +84,7 @@ class UserInput {
   final bool isActive;
   final String? note;
 
+  /// API 요청 바디로 직렬화한다.
   Map<String, dynamic> toPayload() {
     return {
       'employee_no': employeeNo,

lib/features/masters/user/domain/repositories/user_repository.dart

@@ -2,7 +2,9 @@ import 'package:superport_v2/core/common/models/paginated_result.dart';
 
 import '../entities/user.dart';
 
+/// 사용자 데이터를 다루는 도메인 저장소 인터페이스.
 abstract class UserRepository {
+  /// 사용자 목록을 조회한다.
   Future<PaginatedResult<UserAccount>> list({
     int page = 1,
     int pageSize = 20,
@@ -11,11 +13,15 @@ abstract class UserRepository {
     bool? isActive,
   });
 
+  /// 사용자를 생성한다.
   Future<UserAccount> create(UserInput input);
 
+  /// 사용자 정보를 수정한다.
   Future<UserAccount> update(int id, UserInput input);
 
+  /// 사용자를 삭제한다.
   Future<void> delete(int id);
 
+  /// 삭제된 사용자를 복구한다.
   Future<UserAccount> restore(int id);
 }

lib/features/masters/user/presentation/controllers/user_controller.dart

@@ -6,8 +6,10 @@ import '../../../group/domain/repositories/group_repository.dart';
 import '../../domain/entities/user.dart';
 import '../../domain/repositories/user_repository.dart';
 
+/// 사용자 활성 여부 필터.
 enum UserStatusFilter { all, activeOnly, inactiveOnly }
 
+/// 사용자 마스터 화면 상태를 관리하는 컨트롤러.
 class UserController extends ChangeNotifier {
   UserController({
     required UserRepository userRepository,
@@ -38,6 +40,7 @@ class UserController extends ChangeNotifier {
   String? get errorMessage => _errorMessage;
   List<Group> get groups => _groups;
 
+  /// 권한 그룹 목록을 로드한다.
   Future<void> loadGroups() async {
     _isLoadingGroups = true;
     notifyListeners();
@@ -52,6 +55,7 @@ class UserController extends ChangeNotifier {
     }
   }
 
+  /// 사용자 목록을 조회한다.
   Future<void> fetch({int page = 1}) async {
     _isLoading = true;
     _errorMessage = null;
@@ -78,21 +82,25 @@ class UserController extends ChangeNotifier {
     }
   }
 
+  /// 검색어를 변경한다.
   void updateQuery(String value) {
     _query = value;
     notifyListeners();
   }
 
+  /// 그룹 필터를 변경한다.
   void updateGroupFilter(int? groupId) {
     _groupFilter = groupId;
     notifyListeners();
   }
 
+  /// 사용자 상태 필터를 변경한다.
   void updateStatusFilter(UserStatusFilter filter) {
     _statusFilter = filter;
     notifyListeners();
   }
 
+  /// 사용자를 생성한다.
   Future<UserAccount?> create(UserInput input) async {
     _setSubmitting(true);
     try {
@@ -108,6 +116,7 @@ class UserController extends ChangeNotifier {
     }
   }
 
+  /// 사용자 정보를 수정한다.
   Future<UserAccount?> update(int id, UserInput input) async {
     _setSubmitting(true);
     try {
@@ -123,6 +132,7 @@ class UserController extends ChangeNotifier {
     }
   }
 
+  /// 사용자를 삭제한다.
   Future<bool> delete(int id) async {
     _setSubmitting(true);
     try {
@@ -138,6 +148,7 @@ class UserController extends ChangeNotifier {
     }
   }
 
+  /// 삭제된 사용자를 복구한다.
   Future<UserAccount?> restore(int id) async {
     _setSubmitting(true);
     try {
@@ -153,11 +164,13 @@ class UserController extends ChangeNotifier {
     }
   }
 
+  /// 에러 메시지를 초기화한다.
   void clearError() {
     _errorMessage = null;
     notifyListeners();
   }
 
+  /// 제출 상태 플래그를 갱신하고 리스너에게 알린다.
   void _setSubmitting(bool value) {
     _isSubmitting = value;
     notifyListeners();

lib/features/masters/user/presentation/pages/user_page.dart

@@ -15,6 +15,7 @@ import '../../domain/entities/user.dart';
 import '../../domain/repositories/user_repository.dart';
 import '../controllers/user_controller.dart';
 
+/// 사용자 관리 페이지. 기능 플래그에 따라 사양/실제 화면을 보여준다.
 class UserPage extends StatelessWidget {
   const UserPage({super.key});
 
@@ -80,6 +81,7 @@ class UserPage extends StatelessWidget {
   }
 }
 
+/// 사용자 기능이 활성화된 경우 사용하는 실제 화면 위젯.
 class _UserEnabledPage extends StatefulWidget {
   const _UserEnabledPage();
 
@@ -87,6 +89,7 @@ class _UserEnabledPage extends StatefulWidget {
   State<_UserEnabledPage> createState() => _UserEnabledPageState();
 }
 
+/// 사용자 목록과 필터 상태를 관리하는 상태 클래스.
 class _UserEnabledPageState extends State<_UserEnabledPage> {
   late final UserController _controller;
   final TextEditingController _searchController = TextEditingController();