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

lib/features/approvals/presentation/controllers/approval_controller.dart

@@ -74,6 +74,10 @@ class ApprovalController extends ChangeNotifier {
   bool get isApplyingTemplate => _isApplyingTemplate;
   int? get applyingTemplateId => _applyingTemplateId;
 
+  /// 필터 조건과 페이지 정보를 기반으로 결재 목록을 조회한다.
+  ///
+  /// [page]가 1보다 작으면 1페이지로 보정한다. 조회 실패 시 [_errorMessage]에
+  /// 예외 메시지를 기록하고, 선택된 상세가 목록에서 사라진 경우 자동으로 선택을 해제한다.
   Future<void> fetch({int page = 1}) async {
     _isLoadingList = true;
     _errorMessage = null;
@@ -112,6 +116,9 @@ class ApprovalController extends ChangeNotifier {
     }
   }
 
+  /// 결재 단계에서 사용할 수 있는 행위 목록을 로드한다.
+  ///
+  /// 이미 데이터가 존재하면 [force]가 `true`일 때만 재조회한다.
   Future<void> loadActionOptions({bool force = false}) async {
     if (_actions.isNotEmpty && !force) {
       return;
@@ -130,6 +137,9 @@ class ApprovalController extends ChangeNotifier {
     }
   }
 
+  /// 활성화된 결재 템플릿 목록을 조회해 캐싱한다.
+  ///
+  /// 템플릿이 비어 있거나 [force]가 `true`이면 API를 다시 호출한다.
   Future<void> loadTemplates({bool force = false}) async {
     if (_templates.isNotEmpty && !force) {
       return;
@@ -152,6 +162,10 @@ class ApprovalController extends ChangeNotifier {
     }
   }
 
+  /// 특정 결재를 선택하고 상세 정보를 로드한다.
+  ///
+  /// 상세와 이력, 단계 정보를 모두 포함해 최신 상태를 유지하며, 실패 시
+  /// [_errorMessage]로 사용자에게 전달할 메시지를 구성한다.
   Future<void> selectApproval(int id) async {
     _isLoadingDetail = true;
     _errorMessage = null;
@@ -171,11 +185,16 @@ class ApprovalController extends ChangeNotifier {
     }
   }
 
+  /// 선택된 결재 상세를 비우고 화면을 초기화한다.
   void clearSelection() {
     _selected = null;
     notifyListeners();
   }
 
+  /// 결재 단계에 대해 승인/반려/코멘트 등 지정된 행위를 수행한다.
+  ///
+  /// - 유효한 단계 ID와 액션이 존재해야 하며, 실행 중에는 중복 호출을 방지한다.
+  /// - API 호출이 성공하면 목록과 상세 상태를 동기화하고, 실패 시 오류 메시지를 기록한다.
   Future<bool> performStepAction({
     required ApprovalStep step,
     required ApprovalStepActionType type,
@@ -224,6 +243,9 @@ class ApprovalController extends ChangeNotifier {
     }
   }
 
+  /// 템플릿 단계 정보를 현재 결재에 덮어씌운다.
+  ///
+  /// 선택된 결재가 없거나 템플릿에 등록된 단계가 없으면 즉시 실패로 처리한다.
   Future<bool> applyTemplate(int templateId) async {
     final approvalId = _selected?.id;
     if (approvalId == null) {
@@ -279,22 +301,26 @@ class ApprovalController extends ChangeNotifier {
     }
   }
 
+  /// 검색 키워드를 변경하고 UI 갱신을 유도한다.
   void updateQuery(String value) {
     _query = value;
     notifyListeners();
   }
 
+  /// 상태 필터 값을 변경한다.
   void updateStatusFilter(ApprovalStatusFilter filter) {
     _statusFilter = filter;
     notifyListeners();
   }
 
+  /// 조회 기간을 설정한다. 두 값 모두 `null`이면 기간 조건을 해제한다.
   void updateDateRange(DateTime? from, DateTime? to) {
     _fromDate = from;
     _toDate = to;
     notifyListeners();
   }
 
+  /// 검색어/상태/기간 등의 필터 조건을 초기화한다.
   void clearFilters() {
     _query = '';
     _statusFilter = ApprovalStatusFilter.all;
@@ -303,11 +329,13 @@ class ApprovalController extends ChangeNotifier {
     notifyListeners();
   }
 
+  /// 사용자에게 노출 중인 오류 메시지를 초기화한다.
   void clearError() {
     _errorMessage = null;
     notifyListeners();
   }
 
+  /// 액션 타입과 동일한 코드(또는 별칭)를 가진 결재 행위를 찾는다.
   ApprovalAction? _findActionByType(ApprovalStepActionType type) {
     final aliases = _actionAliases[type] ?? [type.code];
     for (final action in _actions) {