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

lib/features/masters/menu/data/dtos/menu_dto.dart

@@ -3,6 +3,7 @@ import 'package:superport_v2/core/common/utils/json_utils.dart';
 
 import '../../domain/entities/menu.dart';
 
+/// 메뉴(Menu) API 응답을 표현하는 DTO.
 class MenuDto {
   MenuDto({
     this.id,
@@ -30,6 +31,7 @@ class MenuDto {
   final DateTime? createdAt;
   final DateTime? updatedAt;
 
+  /// JSON에서 메뉴 정보를 파싱한다.
   factory MenuDto.fromJson(Map<String, dynamic> json) {
     return MenuDto(
       id: json['id'] as int?,
@@ -50,6 +52,7 @@ class MenuDto {
     );
   }
 
+  /// DTO를 도메인 [MenuItem]으로 변환한다.
   MenuItem toEntity() => MenuItem(
     id: id,
     menuCode: menuCode,
@@ -64,6 +67,7 @@ class MenuDto {
     updatedAt: updatedAt,
   );
 
+  /// 페이징 응답을 [PaginatedResult]로 변환한다.
   static PaginatedResult<MenuItem> parsePaginated(Map<String, dynamic>? json) {
     final rawItems = JsonUtils.extractList(json, keys: const ['items']);
     final items = rawItems
@@ -79,12 +83,14 @@ class MenuDto {
   }
 }
 
+/// 하위 메뉴 요약 정보를 담는 DTO.
 class MenuSummaryDto {
   MenuSummaryDto({required this.id, required this.menuName});
 
   final int id;
   final String menuName;
 
+  /// JSON에서 요약 정보를 파싱한다.
   factory MenuSummaryDto.fromJson(Map<String, dynamic> json) {
     return MenuSummaryDto(
       id: json['id'] as int,
@@ -92,9 +98,11 @@ class MenuSummaryDto {
     );
   }
 
+  /// DTO를 [MenuSummary] 엔티티로 변환한다.
   MenuSummary toEntity() => MenuSummary(id: id, menuName: menuName);
 }
 
+/// 문자열/DateTime을 파싱해 [DateTime]으로 변환한다.
 DateTime? _parseDate(Object? value) {
   if (value == null) return null;
   if (value is DateTime) return value;

lib/features/masters/menu/data/repositories/menu_repository_remote.dart

@@ -6,6 +6,7 @@ import '../../domain/entities/menu.dart';
 import '../../domain/repositories/menu_repository.dart';
 import '../dtos/menu_dto.dart';
 
+/// 메뉴 마스터 API를 호출하는 원격 저장소.
 class MenuRepositoryRemote implements MenuRepository {
   MenuRepositoryRemote({required ApiClient apiClient}) : _api = apiClient;
 
@@ -13,6 +14,7 @@ class MenuRepositoryRemote implements MenuRepository {
 
   static const _basePath = '/menus';
 
+  /// 메뉴 목록을 조회한다.
   @override
   Future<PaginatedResult<MenuItem>> list({
     int page = 1,
@@ -38,6 +40,7 @@ class MenuRepositoryRemote implements MenuRepository {
     return MenuDto.parsePaginated(response.data ?? const {});
   }
 
+  /// 새 메뉴를 생성한다.
   @override
   Future<MenuItem> create(MenuInput input) async {
     final response = await _api.post<Map<String, dynamic>>(
@@ -49,6 +52,7 @@ class MenuRepositoryRemote implements MenuRepository {
     return MenuDto.fromJson(data).toEntity();
   }
 
+  /// 메뉴 정보를 수정한다.
   @override
   Future<MenuItem> update(int id, MenuInput input) async {
     final response = await _api.patch<Map<String, dynamic>>(
@@ -60,11 +64,13 @@ class MenuRepositoryRemote implements MenuRepository {
     return MenuDto.fromJson(data).toEntity();
   }
 
+  /// 메뉴를 삭제한다.
   @override
   Future<void> delete(int id) async {
     await _api.delete<void>('$_basePath/$id');
   }
 
+  /// 삭제된 메뉴를 복구한다.
   @override
   Future<MenuItem> restore(int id) async {
     final response = await _api.post<Map<String, dynamic>>(

lib/features/masters/menu/presentation/controllers/menu_controller.dart

@@ -4,6 +4,7 @@ import 'package:superport_v2/core/common/models/paginated_result.dart';
 import '../../domain/entities/menu.dart';
 import '../../domain/repositories/menu_repository.dart';
 
+/// 메뉴 사용 여부 필터.
 enum MenuStatusFilter { all, activeOnly, inactiveOnly }
 
 /// 메뉴 마스터 상태 컨트롤러
@@ -38,6 +39,7 @@ class MenuController extends ChangeNotifier {
   String? get errorMessage => _errorMessage;
   List<MenuItem> get parents => _parents;
 
+  /// 상위 메뉴 목록을 로드해 드롭다운에 표시한다.
   Future<void> loadParents() async {
     _isLoadingParents = true;
     notifyListeners();
@@ -56,6 +58,7 @@ class MenuController extends ChangeNotifier {
     }
   }
 
+  /// 메뉴 목록을 조회한다.
   Future<void> fetch({int page = 1}) async {
     _isLoading = true;
     _errorMessage = null;
@@ -83,26 +86,31 @@ class MenuController extends ChangeNotifier {
     }
   }
 
+  /// 검색어를 변경한다.
   void updateQuery(String value) {
     _query = value;
     notifyListeners();
   }
 
+  /// 상위 메뉴 필터를 변경한다.
   void updateParentFilter(int? parentId) {
     _parentFilter = parentId;
     notifyListeners();
   }
 
+  /// 메뉴 사용 여부 필터를 변경한다.
   void updateStatusFilter(MenuStatusFilter filter) {
     _statusFilter = filter;
     notifyListeners();
   }
 
+  /// 삭제 포함 여부를 변경한다.
   void updateIncludeDeleted(bool value) {
     _includeDeleted = value;
     notifyListeners();
   }
 
+  /// 메뉴를 생성한다.
   Future<MenuItem?> create(MenuInput input) async {
     _setSubmitting(true);
     try {
@@ -119,6 +127,7 @@ class MenuController extends ChangeNotifier {
     }
   }
 
+  /// 메뉴 정보를 수정한다.
   Future<MenuItem?> update(int id, MenuInput input) async {
     _setSubmitting(true);
     try {
@@ -135,6 +144,7 @@ class MenuController extends ChangeNotifier {
     }
   }
 
+  /// 메뉴를 삭제한다.
   Future<bool> delete(int id) async {
     _setSubmitting(true);
     try {
@@ -151,6 +161,7 @@ class MenuController extends ChangeNotifier {
     }
   }
 
+  /// 삭제된 메뉴를 복구한다.
   Future<MenuItem?> restore(int id) async {
     _setSubmitting(true);
     try {
@@ -167,11 +178,13 @@ class MenuController extends ChangeNotifier {
     }
   }
 
+  /// 에러 메시지를 초기화한다.
   void clearError() {
     _errorMessage = null;
     notifyListeners();
   }
 
+  /// 제출 상태 플래그를 갱신하고 리스너에 알린다.
   void _setSubmitting(bool value) {
     _isSubmitting = value;
     notifyListeners();

lib/features/masters/menu/presentation/pages/menu_page.dart

@@ -13,6 +13,7 @@ import '../../domain/entities/menu.dart';
 import '../../domain/repositories/menu_repository.dart';
 import '../controllers/menu_controller.dart' as menu;
 
+/// 메뉴 관리 페이지. 기능 플래그에 따라 사양/실제 화면을 전환한다.
 class MenuPage extends StatelessWidget {
   const MenuPage({super.key});
 
@@ -89,6 +90,7 @@ class MenuPage extends StatelessWidget {
   }
 }
 
+/// 메뉴 기능이 활성화된 경우 사용하는 실제 화면 위젯.
 class _MenuEnabledPage extends StatefulWidget {
   const _MenuEnabledPage();
 
@@ -96,6 +98,7 @@ class _MenuEnabledPage extends StatefulWidget {
   State<_MenuEnabledPage> createState() => _MenuEnabledPageState();
 }
 
+/// 메뉴 목록과 필터를 관리하는 상태 클래스.
 class _MenuEnabledPageState extends State<_MenuEnabledPage> {
   late final menu.MenuController _controller;
   final TextEditingController _searchController = TextEditingController();