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

lib/features/masters/group/data/dtos/group_dto.dart

@@ -3,6 +3,7 @@ import 'package:superport_v2/core/common/utils/json_utils.dart';
 
 import '../../domain/entities/group.dart';
 
+/// 권한 그룹(Group) API 응답을 표현하는 DTO.
 class GroupDto {
   GroupDto({
     this.id,
@@ -26,6 +27,7 @@ class GroupDto {
   final DateTime? createdAt;
   final DateTime? updatedAt;
 
+  /// JSON에서 그룹 정보를 파싱한다.
   factory GroupDto.fromJson(Map<String, dynamic> json) {
     return GroupDto(
       id: json['id'] as int?,
@@ -40,6 +42,7 @@ class GroupDto {
     );
   }
 
+  /// DTO를 도메인 [Group] 엔티티로 변환한다.
   Group toEntity() => Group(
     id: id,
     groupName: groupName,
@@ -52,6 +55,7 @@ class GroupDto {
     updatedAt: updatedAt,
   );
 
+  /// 페이징 응답을 [PaginatedResult]로 변환한다.
   static PaginatedResult<Group> parsePaginated(Map<String, dynamic>? json) {
     final rawItems = JsonUtils.extractList(json, keys: const ['items']);
     final items = rawItems
@@ -67,6 +71,7 @@ class GroupDto {
   }
 }
 
+/// 문자열/DateTime을 파싱해 [DateTime]으로 반환한다.
 DateTime? _parseDate(Object? value) {
   if (value == null) return null;
   if (value is DateTime) return value;

lib/features/masters/group/data/repositories/group_repository_remote.dart

@@ -6,6 +6,7 @@ import '../../domain/entities/group.dart';
 import '../../domain/repositories/group_repository.dart';
 import '../dtos/group_dto.dart';
 
+/// 권한 그룹 API를 호출하는 원격 저장소 구현체.
 class GroupRepositoryRemote implements GroupRepository {
   GroupRepositoryRemote({required ApiClient apiClient}) : _api = apiClient;
 
@@ -13,6 +14,7 @@ class GroupRepositoryRemote implements GroupRepository {
 
   static const _basePath = '/groups';
 
+  /// 그룹 목록을 조회한다.
   @override
   Future<PaginatedResult<Group>> list({
     int page = 1,
@@ -35,6 +37,7 @@ class GroupRepositoryRemote implements GroupRepository {
     return GroupDto.parsePaginated(response.data ?? const {});
   }
 
+  /// 새 그룹을 생성한다.
   @override
   Future<Group> create(GroupInput input) async {
     final response = await _api.post<Map<String, dynamic>>(
@@ -46,6 +49,7 @@ class GroupRepositoryRemote implements GroupRepository {
     return GroupDto.fromJson(data).toEntity();
   }
 
+  /// 그룹 정보를 수정한다.
   @override
   Future<Group> update(int id, GroupInput input) async {
     final response = await _api.patch<Map<String, dynamic>>(
@@ -57,11 +61,13 @@ class GroupRepositoryRemote implements GroupRepository {
     return GroupDto.fromJson(data).toEntity();
   }
 
+  /// 그룹을 삭제한다.
   @override
   Future<void> delete(int id) async {
     await _api.delete<void>('$_basePath/$id');
   }
 
+  /// 삭제된 그룹을 복구한다.
   @override
   Future<Group> restore(int id) async {
     final response = await _api.post<Map<String, dynamic>>(

lib/features/masters/group/presentation/controllers/group_controller.dart

@@ -4,8 +4,10 @@ import 'package:superport_v2/core/common/models/paginated_result.dart';
 import '../../domain/entities/group.dart';
 import '../../domain/repositories/group_repository.dart';
 
+/// 기본 그룹 여부 필터.
 enum GroupDefaultFilter { all, defaultOnly, nonDefault }
 
+/// 그룹 사용 상태 필터.
 enum GroupStatusFilter { all, activeOnly, inactiveOnly }
 
 /// 그룹 마스터 화면 상태 컨트롤러
@@ -34,6 +36,7 @@ class GroupController extends ChangeNotifier {
   GroupStatusFilter get statusFilter => _statusFilter;
   String? get errorMessage => _errorMessage;
 
+  /// 그룹 목록을 조회한다.
   Future<void> fetch({int page = 1}) async {
     _isLoading = true;
     _errorMessage = null;
@@ -65,21 +68,25 @@ class GroupController extends ChangeNotifier {
     }
   }
 
+  /// 검색어를 변경한다.
   void updateQuery(String value) {
     _query = value;
     notifyListeners();
   }
 
+  /// 기본 그룹 여부 필터를 변경한다.
   void updateDefaultFilter(GroupDefaultFilter filter) {
     _defaultFilter = filter;
     notifyListeners();
   }
 
+  /// 사용 여부 필터를 변경한다.
   void updateStatusFilter(GroupStatusFilter filter) {
     _statusFilter = filter;
     notifyListeners();
   }
 
+  /// 새 그룹을 생성한다.
   Future<Group?> create(GroupInput input) async {
     _setSubmitting(true);
     try {
@@ -95,6 +102,7 @@ class GroupController extends ChangeNotifier {
     }
   }
 
+  /// 그룹 정보를 수정한다.
   Future<Group?> update(int id, GroupInput input) async {
     _setSubmitting(true);
     try {
@@ -110,6 +118,7 @@ class GroupController extends ChangeNotifier {
     }
   }
 
+  /// 그룹을 삭제한다.
   Future<bool> delete(int id) async {
     _setSubmitting(true);
     try {
@@ -125,6 +134,7 @@ class GroupController extends ChangeNotifier {
     }
   }
 
+  /// 삭제된 그룹을 복구한다.
   Future<Group?> restore(int id) async {
     _setSubmitting(true);
     try {
@@ -140,11 +150,13 @@ class GroupController extends ChangeNotifier {
     }
   }
 
+  /// 에러 메시지를 초기화한다.
   void clearError() {
     _errorMessage = null;
     notifyListeners();
   }
 
+  /// 제출 상태 플래그를 갱신하고 리스너에 알린다.
   void _setSubmitting(bool value) {
     _isSubmitting = value;
     notifyListeners();

lib/features/masters/group/presentation/pages/group_page.dart

@@ -13,6 +13,7 @@ import '../../domain/entities/group.dart';
 import '../../domain/repositories/group_repository.dart';
 import '../controllers/group_controller.dart';
 
+/// 권한 그룹 관리 페이지. 기능 플래그에 따라 사양 화면 또는 실제 목록을 보여준다.
 class GroupPage extends StatelessWidget {
   const GroupPage({super.key});
 
@@ -69,6 +70,7 @@ class GroupPage extends StatelessWidget {
   }
 }
 
+/// 그룹 기능이 활성화된 경우 사용하는 실제 화면 위젯.
 class _GroupEnabledPage extends StatefulWidget {
   const _GroupEnabledPage();
 
@@ -76,6 +78,7 @@ class _GroupEnabledPage extends StatefulWidget {
   State<_GroupEnabledPage> createState() => _GroupEnabledPageState();
 }
 
+/// 그룹 목록과 필터/폼 상태를 관리하는 상태 클래스.
 class _GroupEnabledPageState extends State<_GroupEnabledPage> {
   late final GroupController _controller;
   final TextEditingController _searchController = TextEditingController();