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

lib/features/masters/customer/data/dtos/customer_dto.dart

@@ -3,6 +3,7 @@ import 'package:superport_v2/core/common/utils/json_utils.dart';
 
 import '../../domain/entities/customer.dart';
 
+/// 고객(Customer) API 응답을 다루는 DTO.
 class CustomerDto {
   CustomerDto({
     this.id,
@@ -36,6 +37,7 @@ class CustomerDto {
   final DateTime? createdAt;
   final DateTime? updatedAt;
 
+  /// 원본 JSON으로부터 DTO를 생성한다.
   factory CustomerDto.fromJson(Map<String, dynamic> json) {
     return CustomerDto(
       id: json['id'] as int?,
@@ -57,6 +59,7 @@ class CustomerDto {
     );
   }
 
+  /// DTO를 JSON 맵으로 변환한다.
   Map<String, dynamic> toJson() {
     return {
       if (id != null) 'id': id,
@@ -76,6 +79,7 @@ class CustomerDto {
     };
   }
 
+  /// DTO를 도메인 [Customer] 엔티티로 변환한다.
   Customer toEntity() => Customer(
     id: id,
     customerCode: customerCode,
@@ -93,6 +97,7 @@ class CustomerDto {
     updatedAt: updatedAt,
   );
 
+  /// 페이징 응답을 파싱해 [PaginatedResult] 형식으로 반환한다.
   static PaginatedResult<Customer> parsePaginated(Map<String, dynamic>? json) {
     final rawItems = JsonUtils.extractList(json, keys: const ['items']);
     final items = rawItems
@@ -108,6 +113,7 @@ class CustomerDto {
   }
 }
 
+/// 고객 주소의 우편번호 정보를 담는 DTO.
 class CustomerZipcodeDto {
   CustomerZipcodeDto({
     required this.zipcode,
@@ -121,6 +127,7 @@ class CustomerZipcodeDto {
   final String? sigungu;
   final String? roadName;
 
+  /// JSON에서 우편번호 정보를 파싱한다.
   factory CustomerZipcodeDto.fromJson(Map<String, dynamic> json) {
     return CustomerZipcodeDto(
       zipcode: json['zipcode'] as String,
@@ -130,6 +137,7 @@ class CustomerZipcodeDto {
     );
   }
 
+  /// DTO를 JSON 맵으로 직렬화한다.
   Map<String, dynamic> toJson() {
     return {
       'zipcode': zipcode,
@@ -139,6 +147,7 @@ class CustomerZipcodeDto {
     };
   }
 
+  /// DTO를 [CustomerZipcode] 엔티티로 변환한다.
   CustomerZipcode toEntity() => CustomerZipcode(
     zipcode: zipcode,
     sido: sido,
@@ -147,6 +156,7 @@ class CustomerZipcodeDto {
   );
 }
 
+/// 문자열/DateTime 값을 파싱해 [DateTime]으로 변환한다.
 DateTime? _parseDate(Object? value) {
   if (value == null) return null;
   if (value is DateTime) return value;
@@ -154,6 +164,7 @@ DateTime? _parseDate(Object? value) {
   return null;
 }
 
+/// 고객 입력 모델을 API 요청 바디로 변환한다.
 Map<String, dynamic> customerInputToJson(CustomerInput input) {
   final map = input.toPayload();
   map.removeWhere((key, value) => value == null);

lib/features/masters/customer/data/repositories/customer_repository_remote.dart

@@ -6,6 +6,7 @@ import '../../domain/entities/customer.dart';
 import '../../domain/repositories/customer_repository.dart';
 import '../dtos/customer_dto.dart';
 
+/// 고객(API) CRUD를 호출하는 원격 저장소 구현체.
 class CustomerRepositoryRemote implements CustomerRepository {
   CustomerRepositoryRemote({required ApiClient apiClient}) : _api = apiClient;
 
@@ -13,6 +14,7 @@ class CustomerRepositoryRemote implements CustomerRepository {
 
   static const _basePath = '/customers';
 
+  /// 고객 목록을 조회한다.
   @override
   Future<PaginatedResult<Customer>> list({
     int page = 1,
@@ -37,6 +39,7 @@ class CustomerRepositoryRemote implements CustomerRepository {
     return CustomerDto.parsePaginated(response.data ?? const {});
   }
 
+  /// 고객을 생성한다.
   @override
   Future<Customer> create(CustomerInput input) async {
     final response = await _api.post<Map<String, dynamic>>(
@@ -48,6 +51,7 @@ class CustomerRepositoryRemote implements CustomerRepository {
     return CustomerDto.fromJson(data).toEntity();
   }
 
+  /// 고객 정보를 수정한다.
   @override
   Future<Customer> update(int id, CustomerInput input) async {
     final response = await _api.patch<Map<String, dynamic>>(
@@ -59,11 +63,13 @@ class CustomerRepositoryRemote implements CustomerRepository {
     return CustomerDto.fromJson(data).toEntity();
   }
 
+  /// 고객을 삭제한다.
   @override
   Future<void> delete(int id) async {
     await _api.delete<void>('$_basePath/$id');
   }
 
+  /// 삭제된 고객을 복구한다.
   @override
   Future<Customer> restore(int id) async {
     final response = await _api.post<Map<String, dynamic>>(

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

@@ -1,3 +1,4 @@
+/// 고객(Customer) 도메인 엔티티.
 class Customer {
   Customer({
     this.id,
@@ -31,6 +32,7 @@ class Customer {
   final DateTime? createdAt;
   final DateTime? updatedAt;
 
+  /// 선택한 속성만 변경한 새 인스턴스를 반환한다.
   Customer copyWith({
     int? id,
     String? customerCode,
@@ -66,6 +68,7 @@ class Customer {
   }
 }
 
+/// 고객 주소의 우편번호/행정구역 정보를 표현한다.
 class CustomerZipcode {
   CustomerZipcode({
     required this.zipcode,
@@ -80,6 +83,7 @@ class CustomerZipcode {
   final String? roadName;
 }
 
+/// 고객 생성/수정 시 사용하는 입력 모델.
 class CustomerInput {
   CustomerInput({
     required this.customerCode,
@@ -105,6 +109,7 @@ class CustomerInput {
   final bool isActive;
   final String? note;
 
+  /// API 요청 바디에 사용하기 위한 맵으로 직렬화한다.
   Map<String, dynamic> toPayload() {
     return {
       'customer_code': customerCode,

lib/features/masters/customer/domain/repositories/customer_repository.dart

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

lib/features/masters/customer/presentation/controllers/customer_controller.dart

@@ -4,10 +4,13 @@ import 'package:superport_v2/core/common/models/paginated_result.dart';
 import '../../domain/entities/customer.dart';
 import '../../domain/repositories/customer_repository.dart';
 
+/// 고객 유형 필터 옵션.
 enum CustomerTypeFilter { all, partner, general }
 
+/// 고객 활성 상태 필터 옵션.
 enum CustomerStatusFilter { all, activeOnly, inactiveOnly }
 
+/// 고객 목록 조회/등록/수정을 담당하는 프레젠테이션 컨트롤러.
 class CustomerController extends ChangeNotifier {
   static const int defaultPageSize = 20;
 
@@ -34,6 +37,7 @@ class CustomerController extends ChangeNotifier {
   int get pageSize => _pageSize;
   String? get errorMessage => _errorMessage;
 
+  /// 고객 목록을 조회한다. 필터/페이지 상태는 내부에서 유지된다.
   Future<void> fetch({int page = 1}) async {
     _isLoading = true;
     _errorMessage = null;
@@ -82,6 +86,7 @@ class CustomerController extends ChangeNotifier {
     }
   }
 
+  /// 검색어를 변경한다.
   void updateQuery(String value) {
     if (_query == value) {
       return;
@@ -90,6 +95,7 @@ class CustomerController extends ChangeNotifier {
     notifyListeners();
   }
 
+  /// 고객 유형 필터를 변경한다.
   void updateTypeFilter(CustomerTypeFilter filter) {
     if (_typeFilter == filter) {
       return;
@@ -98,6 +104,7 @@ class CustomerController extends ChangeNotifier {
     notifyListeners();
   }
 
+  /// 고객 활성 상태 필터를 변경한다.
   void updateStatusFilter(CustomerStatusFilter filter) {
     if (_statusFilter == filter) {
       return;
@@ -106,6 +113,7 @@ class CustomerController extends ChangeNotifier {
     notifyListeners();
   }
 
+  /// 페이지 크기를 변경한다.
   void updatePageSize(int size) {
     if (size <= 0 || _pageSize == size) {
       return;
@@ -114,6 +122,7 @@ class CustomerController extends ChangeNotifier {
     notifyListeners();
   }
 
+  /// 신규 고객을 생성한다.
   Future<Customer?> create(CustomerInput input) async {
     _setSubmitting(true);
     try {
@@ -129,6 +138,7 @@ class CustomerController extends ChangeNotifier {
     }
   }
 
+  /// 기존 고객을 수정한다.
   Future<Customer?> update(int id, CustomerInput input) async {
     _setSubmitting(true);
     try {
@@ -144,6 +154,7 @@ class CustomerController extends ChangeNotifier {
     }
   }
 
+  /// 고객을 삭제한다.
   Future<bool> delete(int id) async {
     _setSubmitting(true);
     try {
@@ -159,6 +170,7 @@ class CustomerController extends ChangeNotifier {
     }
   }
 
+  /// 삭제된 고객을 복구한다.
   Future<Customer?> restore(int id) async {
     _setSubmitting(true);
     try {
@@ -174,6 +186,7 @@ class CustomerController extends ChangeNotifier {
     }
   }
 
+  /// 에러 메시지를 초기화한다.
   void clearError() {
     _errorMessage = null;
     notifyListeners();

lib/features/masters/customer/presentation/pages/customer_page.dart

@@ -16,6 +16,7 @@ import '../../domain/entities/customer.dart';
 import '../../domain/repositories/customer_repository.dart';
 import '../controllers/customer_controller.dart';
 
+/// 고객 관리 화면. 기능 플래그에 따라 사양 페이지를 보여주거나 실제 목록을 노출한다.
 class CustomerPage extends StatelessWidget {
   const CustomerPage({super.key, required this.routeUri});
 
@@ -86,6 +87,7 @@ class CustomerPage extends StatelessWidget {
   }
 }
 
+/// 고객 관리 기능이 활성화된 경우 사용하는 실제 화면 위젯.
 class _CustomerEnabledPage extends StatefulWidget {
   const _CustomerEnabledPage({required this.routeUri});
 
@@ -95,6 +97,7 @@ class _CustomerEnabledPage extends StatefulWidget {
   State<_CustomerEnabledPage> createState() => _CustomerEnabledPageState();
 }
 
+/// 고객 목록 UI와 라우트 파라미터 싱크를 담당하는 상태 클래스.
 class _CustomerEnabledPageState extends State<_CustomerEnabledPage> {
   late final CustomerController _controller;
   final TextEditingController _searchController = TextEditingController();
@@ -403,6 +406,7 @@ class _CustomerEnabledPageState extends State<_CustomerEnabledPage> {
     GoRouter.of(context).go(newLocation);
   }
 
+  /// URL 파라미터에서 고객 유형 필터 값을 파싱한다.
   CustomerTypeFilter _typeFromParam(String? value) {
     switch (value) {
       case 'partner':
@@ -414,6 +418,7 @@ class _CustomerEnabledPageState extends State<_CustomerEnabledPage> {
     }
   }
 
+  /// 고객 유형 필터를 URL 파라미터 문자열로 변환한다.
   String? _encodeType(CustomerTypeFilter filter) {
     switch (filter) {
       case CustomerTypeFilter.all:
@@ -425,6 +430,7 @@ class _CustomerEnabledPageState extends State<_CustomerEnabledPage> {
     }
   }
 
+  /// URL 파라미터에서 고객 활성 상태를 파싱한다.
   CustomerStatusFilter _statusFromParam(String? value) {
     switch (value) {
       case 'active':
@@ -436,6 +442,7 @@ class _CustomerEnabledPageState extends State<_CustomerEnabledPage> {
     }
   }
 
+  /// 고객 상태 필터를 URL 파라미터 문자열로 변환한다.
   String? _encodeStatus(CustomerStatusFilter filter) {
     switch (filter) {
       case CustomerStatusFilter.all: