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

lib/features/approvals/step/presentation/controllers/approval_step_controller.dart

@@ -5,6 +5,9 @@ import '../../domain/entities/approval_step_input.dart';
 import '../../domain/entities/approval_step_record.dart';
 import '../../domain/repositories/approval_step_repository.dart';
 
+/// 결재 단계 관리 화면을 위한 상태 컨트롤러.
+///
+/// 단계 목록 조회, 필터링, 단건 생성/수정을 담당한다.
 class ApprovalStepController extends ChangeNotifier {
   ApprovalStepController({required ApprovalStepRepository repository})
     : _repository = repository;
@@ -31,6 +34,7 @@ class ApprovalStepController extends ChangeNotifier {
   bool get isLoadingDetail => _isLoadingDetail;
   ApprovalStepRecord? get selected => _selected;
 
+  /// 단계 목록을 조회한다. 페이지와 검색 조건을 함께 적용한다.
   Future<void> fetch({int page = 1}) async {
     _isLoading = true;
     _errorMessage = null;
@@ -53,21 +57,27 @@ class ApprovalStepController extends ChangeNotifier {
     }
   }
 
+  /// 검색어를 변경해 다음 조회에 반영한다.
   void updateQuery(String value) {
     _query = value;
     notifyListeners();
   }
 
+  /// 선택한 단계 상태 ID를 갱신한다. null이면 전체 상태를 의미한다.
   void updateStatusId(int? value) {
     _statusId = value;
     notifyListeners();
   }
 
+  /// 승인자 ID 필터를 변경한다. null이면 필터를 해제한다.
   void updateApproverId(int? value) {
     _approverId = value;
     notifyListeners();
   }
 
+  /// 특정 결재 단계의 상세를 조회한다.
+  ///
+  /// 성공 시 [_selected]에 저장하고, 실패 시 오류 메시지를 기록한다.
   Future<ApprovalStepRecord?> fetchDetail(int id) async {
     _isLoadingDetail = true;
     _errorMessage = null;
@@ -85,11 +95,13 @@ class ApprovalStepController extends ChangeNotifier {
     }
   }
 
+  /// 현재 선택된 단계를 초기화한다.
   void clearSelection() {
     _selected = null;
     notifyListeners();
   }
 
+  /// 저장된 오류 메시지를 초기화한다.
   void clearError() {
     _errorMessage = null;
     notifyListeners();
@@ -98,6 +110,7 @@ class ApprovalStepController extends ChangeNotifier {
   bool get hasActiveFilters =>
       _query.trim().isNotEmpty || _statusId != null || _approverId != null;
 
+  /// 검색어/상태/승인자 필터를 기본값으로 리셋한다.
   void resetFilters() {
     _query = '';
     _statusId = null;
@@ -105,6 +118,7 @@ class ApprovalStepController extends ChangeNotifier {
     notifyListeners();
   }
 
+  /// 새로운 단계를 생성하고 현재 페이지를 다시 불러온다.
   Future<ApprovalStepRecord?> createStep(ApprovalStepInput input) async {
     _isSaving = true;
     _errorMessage = null;
@@ -123,6 +137,7 @@ class ApprovalStepController extends ChangeNotifier {
     }
   }
 
+  /// 기존 단계를 수정하고 목록을 갱신한다.
   Future<ApprovalStepRecord?> updateStep(
     int id,
     ApprovalStepInput input,