결재/인벤토리 주석화 1단계 및 계획 문서 추가

lib/features/approvals/template/presentation/controllers/approval_template_controller.dart

@@ -4,6 +4,7 @@ import 'package:superport_v2/core/common/models/paginated_result.dart';
 import '../../../domain/entities/approval_template.dart';
 import '../../../domain/repositories/approval_template_repository.dart';
 
+/// 결재 템플릿 목록에서 사용할 상태 필터.
 enum ApprovalTemplateStatusFilter { all, activeOnly, inactiveOnly }
 
 /// 결재 템플릿 화면 상태 컨트롤러
@@ -31,6 +32,9 @@ class ApprovalTemplateController extends ChangeNotifier {
   String? get errorMessage => _errorMessage;
   int get pageSize => _result?.pageSize ?? _pageSize;
 
+  /// 템플릿 목록을 조회해 캐시에 저장한다.
+  ///
+  /// 검색어/상태 조건을 함께 적용하며, 실패 시 [_errorMessage]에 예외 메시지를 기록한다.
   Future<void> fetch({int page = 1}) async {
     _isLoading = true;
     _errorMessage = null;
@@ -58,16 +62,21 @@ class ApprovalTemplateController extends ChangeNotifier {
     }
   }
 
+  /// 검색어 조건을 갱신해 다음 조회에 반영한다.
   void updateQuery(String value) {
     _query = value;
     notifyListeners();
   }
 
+  /// 템플릿 상태 필터를 변경한다.
   void updateStatusFilter(ApprovalTemplateStatusFilter filter) {
     _statusFilter = filter;
     notifyListeners();
   }
 
+  /// 특정 템플릿의 상세 정보를 조회한다.
+  ///
+  /// 단계 정보까지 포함해 반환하며 실패 시 null을 반환하고 오류 메시지를 보관한다.
   Future<ApprovalTemplate?> fetchDetail(int id) async {
     _errorMessage = null;
     notifyListeners();
@@ -81,6 +90,7 @@ class ApprovalTemplateController extends ChangeNotifier {
     }
   }
 
+  /// 새 템플릿을 생성하고 목록을 1페이지로 새로 고친다.
   Future<ApprovalTemplate?> create(
     ApprovalTemplateInput input,
     List<ApprovalTemplateStepInput> steps,
@@ -99,6 +109,7 @@ class ApprovalTemplateController extends ChangeNotifier {
     }
   }
 
+  /// 기존 템플릿을 수정하고 현재 페이지를 유지한 채 목록을 다시 가져온다.
   Future<ApprovalTemplate?> update(
     int id,
     ApprovalTemplateInput input,
@@ -118,6 +129,7 @@ class ApprovalTemplateController extends ChangeNotifier {
     }
   }
 
+  /// 템플릿을 삭제(비활성화)한 뒤 목록을 재조회한다.
   Future<bool> delete(int id) async {
     _setSubmitting(true);
     try {
@@ -133,6 +145,7 @@ class ApprovalTemplateController extends ChangeNotifier {
     }
   }
 
+  /// 삭제된 템플릿을 복구한 뒤 목록을 최신 상태로 만든다.
   Future<ApprovalTemplate?> restore(int id) async {
     _setSubmitting(true);
     try {
@@ -148,6 +161,7 @@ class ApprovalTemplateController extends ChangeNotifier {
     }
   }
 
+  /// 오류 메시지를 초기화한다.
   void clearError() {
     _errorMessage = null;
     notifyListeners();
@@ -157,12 +171,14 @@ class ApprovalTemplateController extends ChangeNotifier {
       _query.trim().isNotEmpty ||
       _statusFilter != ApprovalTemplateStatusFilter.all;
 
+  /// 검색어와 상태 필터를 기본값으로 되돌린다.
   void resetFilters() {
     _query = '';
     _statusFilter = ApprovalTemplateStatusFilter.all;
     notifyListeners();
   }
 
+  /// 페이지 사이즈를 변경한다. 0 이하 값은 무시한다.
   void updatePageSize(int value) {
     if (value <= 0) {
       return;
@@ -171,6 +187,7 @@ class ApprovalTemplateController extends ChangeNotifier {
     notifyListeners();
   }
 
+  /// 네트워크 작업 진행 여부를 갱신한다.
   void _setSubmitting(bool value) {
     _isSubmitting = value;
     notifyListeners();