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

lib/features/approvals/history/presentation/controllers/approval_history_controller.dart

@@ -4,8 +4,12 @@ import 'package:superport_v2/core/common/models/paginated_result.dart';
 import '../../domain/entities/approval_history_record.dart';
 import '../../domain/repositories/approval_history_repository.dart';
 
+/// 결재 이력에서 필터링 가능한 행위 타입.
 enum ApprovalHistoryActionFilter { all, approve, reject, comment }
 
+/// 결재 이력 화면의 목록/필터 상태를 관리하는 컨트롤러.
+///
+/// 기간, 검색어, 행위 타입에 따라 목록을 조회하고 페이지 사이즈를 조절한다.
 class ApprovalHistoryController extends ChangeNotifier {
   ApprovalHistoryController({required ApprovalHistoryRepository repository})
     : _repository = repository;
@@ -30,6 +34,9 @@ class ApprovalHistoryController extends ChangeNotifier {
   String? get errorMessage => _errorMessage;
   int get pageSize => _result?.pageSize ?? _pageSize;
 
+  /// 현재 필터 조건에 맞춰 결재 이력 목록을 불러온다.
+  ///
+  /// 페이지 번호는 1 이상을 기대하며, 실패 시 [_errorMessage]에 사유를 기록한다.
   Future<void> fetch({int page = 1}) async {
     _isLoading = true;
     _errorMessage = null;
@@ -60,22 +67,26 @@ class ApprovalHistoryController extends ChangeNotifier {
     }
   }
 
+  /// 검색어를 업데이트해 다음 조회 시 적용될 수 있도록 한다.
   void updateQuery(String value) {
     _query = value;
     notifyListeners();
   }
 
+  /// 행위 타입 필터를 갱신한다.
   void updateActionFilter(ApprovalHistoryActionFilter filter) {
     _actionFilter = filter;
     notifyListeners();
   }
 
+  /// 조회 기간을 설정한다. null을 전달하면 해당 조건을 제거한다.
   void updateDateRange(DateTime? from, DateTime? to) {
     _from = from;
     _to = to;
     notifyListeners();
   }
 
+  /// 검색어/행위/기간 필터를 초기화한다.
   void clearFilters() {
     _query = '';
     _actionFilter = ApprovalHistoryActionFilter.all;
@@ -84,11 +95,13 @@ class ApprovalHistoryController extends ChangeNotifier {
     notifyListeners();
   }
 
+  /// 축적된 오류 메시지를 초기화한다.
   void clearError() {
     _errorMessage = null;
     notifyListeners();
   }
 
+  /// 페이지 사이즈를 변경한다. 0 이하 값은 무시한다.
   void updatePageSize(int value) {
     if (value <= 0) {
       return;

lib/features/approvals/history/presentation/pages/approval_history_page.dart

@@ -353,6 +353,7 @@ class _ApprovalHistoryEnabledPageState
   }
 }
 
+/// 결재 이력 데이터를 표 형태로 렌더링하는 위젯.
 class _ApprovalHistoryTable extends StatelessWidget {
   const _ApprovalHistoryTable({
     required this.histories,