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

lib/features/approvals/data/repositories/approval_repository_remote.dart

@@ -6,6 +6,10 @@ import '../../domain/entities/approval.dart';
 import '../../domain/repositories/approval_repository.dart';
 import '../dtos/approval_dto.dart';
 
+/// 결재 API 엔드포인트를 호출하는 원격 저장소 구현체.
+///
+/// - 모든 요청은 [ApiClient]를 통해 인증/에러 매핑을 공유한다.
+/// - 엔티티 변환은 DTO 계층에 위임한다.
 class ApprovalRepositoryRemote implements ApprovalRepository {
   ApprovalRepositoryRemote({required ApiClient apiClient}) : _api = apiClient;
 
@@ -13,6 +17,7 @@ class ApprovalRepositoryRemote implements ApprovalRepository {
 
   static const _basePath = '/approvals';
 
+  /// 결재 목록을 조회한다. 필터 조건이 없으면 최신순 페이지를 반환한다.
   @override
   Future<PaginatedResult<Approval>> list({
     int page = 1,
@@ -41,6 +46,7 @@ class ApprovalRepositoryRemote implements ApprovalRepository {
     return ApprovalDto.parsePaginated(response.data ?? const {});
   }
 
+  /// 결재 상세를 조회한다. 단계/이력 포함 여부를 쿼리 파라미터로 제어한다.
   @override
   Future<Approval> fetchDetail(
     int id, {
@@ -59,6 +65,7 @@ class ApprovalRepositoryRemote implements ApprovalRepository {
     return ApprovalDto.fromJson(data).toEntity();
   }
 
+  /// 활성화된 결재 행위 목록을 조회한다.
   @override
   Future<List<ApprovalAction>> listActions({bool activeOnly = true}) async {
     final response = await _api.get<Map<String, dynamic>>(
@@ -74,6 +81,7 @@ class ApprovalRepositoryRemote implements ApprovalRepository {
     return items;
   }
 
+  /// 결재 단계 행위를 수행하고 업데이트된 결재 정보를 반환한다.
   @override
   Future<Approval> performStepAction(ApprovalStepActionInput input) async {
     final response = await _api.post<Map<String, dynamic>>(
@@ -90,6 +98,7 @@ class ApprovalRepositoryRemote implements ApprovalRepository {
     return ApprovalDto.fromJson(approvalJson).toEntity();
   }
 
+  /// 결재 단계들을 일괄로 생성하거나 재배치한다.
   @override
   Future<Approval> assignSteps(ApprovalStepAssignmentInput input) async {
     final response = await _api.post<Map<String, dynamic>>(
@@ -106,6 +115,7 @@ class ApprovalRepositoryRemote implements ApprovalRepository {
     return ApprovalDto.fromJson(approvalJson).toEntity();
   }
 
+  /// 새로운 결재를 생성한다.
   @override
   Future<Approval> create(ApprovalInput input) async {
     final response = await _api.post<Map<String, dynamic>>(
@@ -117,6 +127,7 @@ class ApprovalRepositoryRemote implements ApprovalRepository {
     return ApprovalDto.fromJson(data).toEntity();
   }
 
+  /// 결재 기본 정보를 수정한다.
   @override
   Future<Approval> update(int id, ApprovalInput input) async {
     final response = await _api.patch<Map<String, dynamic>>(
@@ -128,11 +139,13 @@ class ApprovalRepositoryRemote implements ApprovalRepository {
     return ApprovalDto.fromJson(data).toEntity();
   }
 
+  /// 결재를 삭제(비활성화)한다.
   @override
   Future<void> delete(int id) async {
     await _api.delete<void>('$_basePath/$id');
   }
 
+  /// 삭제된 결재를 복구한다.
   @override
   Future<Approval> restore(int id) async {
     final response = await _api.post<Map<String, dynamic>>(
@@ -143,6 +156,7 @@ class ApprovalRepositoryRemote implements ApprovalRepository {
     return ApprovalDto.fromJson(data).toEntity();
   }
 
+  /// 결재 단계/행위 응답에서 결재 객체 JSON을 추출한다.
   Map<String, dynamic>? _extractApprovalFromActionResponse(
     Map<String, dynamic> body,
   ) {

lib/features/approvals/data/repositories/approval_template_repository_remote.dart

@@ -6,6 +6,10 @@ import '../../domain/entities/approval_template.dart';
 import '../../domain/repositories/approval_template_repository.dart';
 import '../dtos/approval_template_dto.dart';
 
+/// 결재 템플릿 관련 API를 호출하는 원격 저장소.
+///
+/// - 템플릿/단계 CRUD와 복구 API를 캡슐화한다.
+/// - 단계 등록은 별도 엔드포인트로 처리한다.
 class ApprovalTemplateRepositoryRemote implements ApprovalTemplateRepository {
   ApprovalTemplateRepositoryRemote({required ApiClient apiClient})
     : _api = apiClient;
@@ -14,6 +18,7 @@ class ApprovalTemplateRepositoryRemote implements ApprovalTemplateRepository {
 
   static const _basePath = '/approval-templates';
 
+  /// 결재 템플릿 목록을 조회한다. 검색/활성 여부 필터를 지원한다.
   @override
   Future<PaginatedResult<ApprovalTemplate>> list({
     int page = 1,
@@ -34,6 +39,7 @@ class ApprovalTemplateRepositoryRemote implements ApprovalTemplateRepository {
     return ApprovalTemplateDto.parsePaginated(response.data);
   }
 
+  /// 템플릿 상세 정보를 조회한다. 필요 시 단계 포함 여부를 지정한다.
   @override
   Future<ApprovalTemplate> fetchDetail(
     int id, {
@@ -50,6 +56,7 @@ class ApprovalTemplateRepositoryRemote implements ApprovalTemplateRepository {
     ).toEntity(includeSteps: includeSteps);
   }
 
+  /// 템플릿을 생성하고 필요하면 단계까지 함께 등록한다.
   @override
   Future<ApprovalTemplate> create(
     ApprovalTemplateInput input, {
@@ -70,6 +77,7 @@ class ApprovalTemplateRepositoryRemote implements ApprovalTemplateRepository {
     return fetchDetail(created.id, includeSteps: true);
   }
 
+  /// 템플릿 기본 정보와 단계 구성을 수정한다.
   @override
   Future<ApprovalTemplate> update(
     int id,
@@ -87,11 +95,13 @@ class ApprovalTemplateRepositoryRemote implements ApprovalTemplateRepository {
     return fetchDetail(id, includeSteps: true);
   }
 
+  /// 템플릿을 삭제한다.
   @override
   Future<void> delete(int id) async {
     await _api.delete<void>('$_basePath/$id');
   }
 
+  /// 삭제된 템플릿을 복구한다.
   @override
   Future<ApprovalTemplate> restore(int id) async {
     final response = await _api.post<Map<String, dynamic>>(
@@ -102,6 +112,7 @@ class ApprovalTemplateRepositoryRemote implements ApprovalTemplateRepository {
     return ApprovalTemplateDto.fromJson(data).toEntity(includeSteps: false);
   }
 
+  /// 템플릿 단계 전체를 신규로 등록한다.
   Future<void> _postSteps(
     int templateId,
     List<ApprovalTemplateStepInput> steps,
@@ -117,6 +128,7 @@ class ApprovalTemplateRepositoryRemote implements ApprovalTemplateRepository {
     );
   }
 
+  /// 템플릿 단계 정보를 부분 수정한다.
   Future<void> _patchSteps(
     int templateId,
     List<ApprovalTemplateStepInput> steps,