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

lib/features/approvals/data/dtos/approval_dto.dart

@@ -3,6 +3,10 @@ import 'package:superport_v2/core/common/utils/json_utils.dart';
 
 import '../../domain/entities/approval.dart';
 
+/// 결재 API 응답을 표현하는 DTO.
+///
+/// - 원본 JSON 형식을 유지하면서 도메인 엔티티 변환을 제공한다.
+/// - 일부 필드는 누락 가능성을 고려하여 기본값을 지정한다.
 class ApprovalDto {
   ApprovalDto({
     this.id,
@@ -38,6 +42,7 @@ class ApprovalDto {
   final DateTime? createdAt;
   final DateTime? updatedAt;
 
+  /// API 응답 JSON을 [ApprovalDto]로 변환한다.
   factory ApprovalDto.fromJson(Map<String, dynamic> json) {
     return ApprovalDto(
       id: json['id'] as int?,
@@ -74,6 +79,7 @@ class ApprovalDto {
     );
   }
 
+  /// DTO를 도메인 [Approval] 엔티티로 변환한다.
   Approval toEntity() => Approval(
     id: id,
     approvalNo: approvalNo,
@@ -92,6 +98,7 @@ class ApprovalDto {
     updatedAt: updatedAt,
   );
 
+  /// 페이징 응답을 파싱해 [PaginatedResult]로 변환한다.
   static PaginatedResult<Approval> parsePaginated(Map<String, dynamic>? json) {
     final rawItems = JsonUtils.extractList(json, keys: const ['items']);
     final items = rawItems
@@ -107,6 +114,7 @@ class ApprovalDto {
   }
 }
 
+/// 결재 상태(Status) DTO.
 class ApprovalStatusDto {
   ApprovalStatusDto({required this.id, required this.name, this.color});
 
@@ -122,9 +130,11 @@ class ApprovalStatusDto {
     );
   }
 
+  /// DTO를 [ApprovalStatus]로 변환한다.
   ApprovalStatus toEntity() => ApprovalStatus(id: id, name: name, color: color);
 }
 
+/// 결재 요청자 DTO.
 class ApprovalRequesterDto {
   ApprovalRequesterDto({
     required this.id,
@@ -144,10 +154,12 @@ class ApprovalRequesterDto {
     );
   }
 
+  /// DTO를 [ApprovalRequester]로 변환한다.
   ApprovalRequester toEntity() =>
       ApprovalRequester(id: id, employeeNo: employeeNo, name: name);
 }
 
+/// 결재 승인자 DTO.
 class ApprovalApproverDto {
   ApprovalApproverDto({
     required this.id,
@@ -167,10 +179,12 @@ class ApprovalApproverDto {
     );
   }
 
+  /// DTO를 [ApprovalApprover]로 변환한다.
   ApprovalApprover toEntity() =>
       ApprovalApprover(id: id, employeeNo: employeeNo, name: name);
 }
 
+/// 결재 단계 DTO.
 class ApprovalStepDto {
   ApprovalStepDto({
     this.id,
@@ -206,6 +220,7 @@ class ApprovalStepDto {
     );
   }
 
+  /// DTO를 [ApprovalStep]으로 변환한다.
   ApprovalStep toEntity() => ApprovalStep(
     id: id,
     stepOrder: stepOrder,
@@ -217,6 +232,7 @@ class ApprovalStepDto {
   );
 }
 
+/// 결재 이력 DTO.
 class ApprovalHistoryDto {
   ApprovalHistoryDto({
     this.id,
@@ -258,6 +274,7 @@ class ApprovalHistoryDto {
     );
   }
 
+  /// DTO를 [ApprovalHistory]로 변환한다.
   ApprovalHistory toEntity() => ApprovalHistory(
     id: id,
     action: action.toEntity(),
@@ -269,6 +286,7 @@ class ApprovalHistoryDto {
   );
 }
 
+/// 결재 행위(Action) DTO.
 class ApprovalActionDto {
   ApprovalActionDto({required this.id, required this.name});
 
@@ -282,9 +300,11 @@ class ApprovalActionDto {
     );
   }
 
+  /// DTO를 [ApprovalAction]으로 변환한다.
   ApprovalAction toEntity() => ApprovalAction(id: id, name: name);
 }
 
+/// 문자열/DateTime 입력을 DateTime으로 변환한다.
 DateTime? _parseDate(Object? value) {
   if (value == null) return null;
   if (value is DateTime) return value;

lib/features/approvals/data/dtos/approval_template_dto.dart

@@ -3,6 +3,7 @@ import 'package:superport_v2/core/common/utils/json_utils.dart';
 
 import '../../domain/entities/approval_template.dart';
 
+/// 결재 템플릿 API 응답을 표현하는 DTO.
 class ApprovalTemplateDto {
   ApprovalTemplateDto({
     required this.id,
@@ -28,6 +29,7 @@ class ApprovalTemplateDto {
   final DateTime? updatedAt;
   final List<ApprovalTemplateStepDto> steps;
 
+  /// JSON을 [ApprovalTemplateDto]로 파싱한다.
   factory ApprovalTemplateDto.fromJson(Map<String, dynamic> json) {
     return ApprovalTemplateDto(
       id: json['id'] as int? ?? 0,
@@ -50,6 +52,7 @@ class ApprovalTemplateDto {
     );
   }
 
+  /// DTO를 [ApprovalTemplate]으로 변환한다.
   ApprovalTemplate toEntity({bool includeSteps = true}) {
     return ApprovalTemplate(
       id: id,
@@ -65,6 +68,7 @@ class ApprovalTemplateDto {
     );
   }
 
+  /// 페이징 응답을 파싱해 [PaginatedResult]를 반환한다.
   static PaginatedResult<ApprovalTemplate> parsePaginated(
     Map<String, dynamic>? json, {
     bool includeSteps = false,
@@ -83,6 +87,7 @@ class ApprovalTemplateDto {
   }
 }
 
+/// 템플릿 작성자 DTO.
 class ApprovalTemplateAuthorDto {
   ApprovalTemplateAuthorDto({
     required this.id,
@@ -102,11 +107,13 @@ class ApprovalTemplateAuthorDto {
     );
   }
 
+  /// DTO를 [ApprovalTemplateAuthor]로 변환한다.
   ApprovalTemplateAuthor toEntity() {
     return ApprovalTemplateAuthor(id: id, employeeNo: employeeNo, name: name);
   }
 }
 
+/// 템플릿 단계 DTO.
 class ApprovalTemplateStepDto {
   ApprovalTemplateStepDto({
     this.id,
@@ -131,6 +138,7 @@ class ApprovalTemplateStepDto {
     );
   }
 
+  /// DTO를 [ApprovalTemplateStep]으로 변환한다.
   ApprovalTemplateStep toEntity() {
     return ApprovalTemplateStep(
       id: id,
@@ -141,6 +149,7 @@ class ApprovalTemplateStepDto {
   }
 }
 
+/// 템플릿 승인자 DTO.
 class ApprovalTemplateApproverDto {
   ApprovalTemplateApproverDto({
     required this.id,
@@ -160,11 +169,13 @@ class ApprovalTemplateApproverDto {
     );
   }
 
+  /// DTO를 [ApprovalTemplateApprover]로 변환한다.
   ApprovalTemplateApprover toEntity() {
     return ApprovalTemplateApprover(id: id, employeeNo: employeeNo, name: name);
   }
 }
 
+/// 문자열/DateTime을 파싱해 [DateTime]으로 반환한다.
 DateTime? _parseDate(Object? value) {
   if (value == null) return null;
   if (value is DateTime) return value;