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

lib/features/masters/product/data/dtos/product_dto.dart

@@ -3,6 +3,7 @@ import 'package:superport_v2/core/common/utils/json_utils.dart';
 
 import '../../domain/entities/product.dart';
 
+/// 제품(Product) API 응답을 표현하는 DTO.
 class ProductDto {
   ProductDto({
     this.id,
@@ -28,6 +29,7 @@ class ProductDto {
   final DateTime? createdAt;
   final DateTime? updatedAt;
 
+  /// JSON에서 제품 정보를 파싱한다.
   factory ProductDto.fromJson(Map<String, dynamic> json) {
     return ProductDto(
       id: json['id'] as int?,
@@ -47,6 +49,7 @@ class ProductDto {
     );
   }
 
+  /// DTO를 JSON 맵으로 직렬화한다.
   Map<String, dynamic> toJson() {
     return {
       if (id != null) 'id': id,
@@ -62,6 +65,7 @@ class ProductDto {
     };
   }
 
+  /// DTO를 도메인 [Product] 엔티티로 변환한다.
   Product toEntity() => Product(
     id: id,
     productCode: productCode,
@@ -75,6 +79,7 @@ class ProductDto {
     updatedAt: updatedAt,
   );
 
+  /// 엔티티 값을 DTO로 역변환한다.
   static ProductDto fromEntity(Product entity) => ProductDto(
     id: entity.id,
     productCode: entity.productCode,
@@ -96,6 +101,7 @@ class ProductDto {
     updatedAt: entity.updatedAt,
   );
 
+  /// 페이징 응답을 [PaginatedResult]로 변환한다.
   static PaginatedResult<Product> parsePaginated(Map<String, dynamic>? json) {
     final rawItems = JsonUtils.extractList(json, keys: const ['items']);
     final items = rawItems
@@ -111,6 +117,7 @@ class ProductDto {
   }
 }
 
+/// 제품에 연결된 공급업체 정보를 담는 DTO.
 class ProductVendorDto {
   ProductVendorDto({
     required this.id,
@@ -122,6 +129,7 @@ class ProductVendorDto {
   final String vendorCode;
   final String vendorName;
 
+  /// JSON에서 공급업체 정보를 파싱한다.
   factory ProductVendorDto.fromJson(Map<String, dynamic> json) {
     return ProductVendorDto(
       id: json['id'] as int,
@@ -130,20 +138,24 @@ class ProductVendorDto {
     );
   }
 
+  /// DTO를 JSON 맵으로 직렬화한다.
   Map<String, dynamic> toJson() {
     return {'id': id, 'vendor_code': vendorCode, 'vendor_name': vendorName};
   }
 
+  /// DTO를 [ProductVendor] 엔티티로 변환한다.
   ProductVendor toEntity() =>
       ProductVendor(id: id, vendorCode: vendorCode, vendorName: vendorName);
 }
 
+/// 제품의 단위(UOM) 정보를 담는 DTO.
 class ProductUomDto {
   ProductUomDto({required this.id, required this.uomName});
 
   final int id;
   final String uomName;
 
+  /// JSON에서 단위 정보를 파싱한다.
   factory ProductUomDto.fromJson(Map<String, dynamic> json) {
     return ProductUomDto(
       id: json['id'] as int,
@@ -151,13 +163,16 @@ class ProductUomDto {
     );
   }
 
+  /// DTO를 JSON 맵으로 직렬화한다.
   Map<String, dynamic> toJson() {
     return {'id': id, 'uom_name': uomName};
   }
 
+  /// DTO를 [ProductUom] 엔티티로 변환한다.
   ProductUom toEntity() => ProductUom(id: id, uomName: uomName);
 }
 
+/// 문자열/DateTime을 파싱해 [DateTime]으로 변환한다.
 DateTime? _parseDate(Object? value) {
   if (value == null) return null;
   if (value is DateTime) return value;
@@ -165,6 +180,7 @@ DateTime? _parseDate(Object? value) {
   return null;
 }
 
+/// 제품 입력 모델을 API 요청 바디로 변환한다.
 Map<String, dynamic> productInputToJson(ProductInput input) {
   final map = input.toPayload();
   map.removeWhere((key, value) => value == null);

lib/features/masters/product/data/repositories/product_repository_remote.dart

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

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

@@ -1,3 +1,4 @@
+/// 제품(Product) 도메인 엔티티.
 class Product {
   Product({
     this.id,
@@ -23,6 +24,7 @@ class Product {
   final DateTime? createdAt;
   final DateTime? updatedAt;
 
+  /// 일부 속성을 변경한 새 인스턴스를 반환한다.
   Product copyWith({
     int? id,
     String? productCode,
@@ -50,6 +52,7 @@ class Product {
   }
 }
 
+/// 제품에 연결된 공급업체 정보.
 class ProductVendor {
   ProductVendor({
     required this.id,
@@ -62,6 +65,7 @@ class ProductVendor {
   final String vendorName;
 }
 
+/// 제품의 단위(UOM) 정보.
 class ProductUom {
   ProductUom({required this.id, required this.uomName});
 
@@ -69,6 +73,7 @@ class ProductUom {
   final String uomName;
 }
 
+/// 제품 생성/수정에 사용하는 입력 모델.
 class ProductInput {
   ProductInput({
     required this.productCode,
@@ -86,6 +91,7 @@ class ProductInput {
   final bool isActive;
   final String? note;
 
+  /// API 요청 바디로 직렬화한다.
   Map<String, dynamic> toPayload() {
     return {
       'product_code': productCode,

lib/features/masters/product/domain/repositories/product_repository.dart

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

lib/features/masters/product/presentation/controllers/product_controller.dart

@@ -8,8 +8,10 @@ import '../../../uom/domain/repositories/uom_repository.dart';
 import '../../domain/entities/product.dart';
 import '../../domain/repositories/product_repository.dart';
 
+/// 제품 사용 여부 필터.
 enum ProductStatusFilter { all, activeOnly, inactiveOnly }
 
+/// 제품 마스터 화면 상태를 관리하는 컨트롤러.
 class ProductController extends ChangeNotifier {
   static const int defaultPageSize = 20;
 
@@ -52,6 +54,7 @@ class ProductController extends ChangeNotifier {
   List<Vendor> get vendorOptions => _vendorOptions;
   List<Uom> get uomOptions => _uomOptions;
 
+  /// 제품 목록을 조회한다.
   Future<void> fetch({int page = 1}) async {
     _isLoading = true;
     _errorMessage = null;
@@ -82,6 +85,7 @@ class ProductController extends ChangeNotifier {
     }
   }
 
+  /// 필터/폼에서 사용할 공급업체와 단위 목록을 로드한다.
   Future<void> loadLookups() async {
     _isLoadingLookups = true;
     notifyListeners();
@@ -98,6 +102,7 @@ class ProductController extends ChangeNotifier {
     }
   }
 
+  /// 검색어를 변경한다.
   void updateQuery(String value) {
     if (_query == value) {
       return;
@@ -106,6 +111,7 @@ class ProductController extends ChangeNotifier {
     notifyListeners();
   }
 
+  /// 공급업체 필터를 변경한다.
   void updateVendorFilter(int? vendorId) {
     if (_vendorFilter == vendorId) {
       return;
@@ -114,6 +120,7 @@ class ProductController extends ChangeNotifier {
     notifyListeners();
   }
 
+  /// 단위(UOM) 필터를 변경한다.
   void updateUomFilter(int? uomId) {
     if (_uomFilter == uomId) {
       return;
@@ -122,6 +129,7 @@ class ProductController extends ChangeNotifier {
     notifyListeners();
   }
 
+  /// 사용 여부 필터를 변경한다.
   void updateStatusFilter(ProductStatusFilter filter) {
     if (_statusFilter == filter) {
       return;
@@ -130,6 +138,7 @@ class ProductController extends ChangeNotifier {
     notifyListeners();
   }
 
+  /// 페이지 크기를 변경한다.
   void updatePageSize(int size) {
     if (size <= 0 || _pageSize == size) {
       return;
@@ -138,6 +147,7 @@ class ProductController extends ChangeNotifier {
     notifyListeners();
   }
 
+  /// 제품을 생성한다.
   Future<Product?> create(ProductInput input) async {
     _setSubmitting(true);
     try {
@@ -153,6 +163,7 @@ class ProductController extends ChangeNotifier {
     }
   }
 
+  /// 제품 정보를 수정한다.
   Future<Product?> update(int id, ProductInput input) async {
     _setSubmitting(true);
     try {
@@ -168,6 +179,7 @@ class ProductController extends ChangeNotifier {
     }
   }
 
+  /// 제품을 삭제한다.
   Future<bool> delete(int id) async {
     _setSubmitting(true);
     try {
@@ -183,6 +195,7 @@ class ProductController extends ChangeNotifier {
     }
   }
 
+  /// 삭제된 제품을 복구한다.
   Future<Product?> restore(int id) async {
     _setSubmitting(true);
     try {
@@ -198,11 +211,13 @@ class ProductController extends ChangeNotifier {
     }
   }
 
+  /// 에러 메시지를 초기화한다.
   void clearError() {
     _errorMessage = null;
     notifyListeners();
   }
 
+  /// 제출 상태 플래그를 갱신하고 리스너에 알린다.
   void _setSubmitting(bool value) {
     _isSubmitting = value;
     notifyListeners();

lib/features/masters/product/presentation/pages/product_page.dart

@@ -19,6 +19,7 @@ import '../../domain/entities/product.dart';
 import '../../domain/repositories/product_repository.dart';
 import '../controllers/product_controller.dart';
 
+/// 제품 관리 페이지. 기능 플래그에 따라 사양/실제 화면을 전환한다.
 class ProductPage extends StatelessWidget {
   const ProductPage({super.key, required this.routeUri});
 
@@ -74,6 +75,7 @@ class ProductPage extends StatelessWidget {
   }
 }
 
+/// 제품 기능이 활성화된 경우 사용하는 실제 화면 위젯.
 class _ProductEnabledPage extends StatefulWidget {
   const _ProductEnabledPage({required this.routeUri});
 
@@ -83,6 +85,7 @@ class _ProductEnabledPage extends StatefulWidget {
   State<_ProductEnabledPage> createState() => _ProductEnabledPageState();
 }
 
+/// 제품 목록과 필터/폼 상태를 관리하는 상태 클래스.
 class _ProductEnabledPageState extends State<_ProductEnabledPage> {
   late final ProductController _controller;
   final TextEditingController _searchController = TextEditingController();