결재/인벤토리 주석화 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,

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) {

lib/features/approvals/presentation/pages/approval_page.dart

@@ -22,6 +22,9 @@ import '../controllers/approval_controller.dart';
 
 const _approvalsResourcePath = '/approvals/requests';
 
+/// 결재 관리 최상위 페이지.
+///
+/// 기능 플래그에 따라 실제 화면 또는 비활성 안내 화면을 보여준다.
 class ApprovalPage extends StatelessWidget {
   const ApprovalPage({super.key});
 
@@ -58,6 +61,7 @@ class ApprovalPage extends StatelessWidget {
   }
 }
 
+/// 결재 기능이 활성화되었을 때 사용되는 실제 페이지 위젯.
 class _ApprovalEnabledPage extends StatefulWidget {
   const _ApprovalEnabledPage();
 
@@ -695,6 +699,9 @@ class _ApprovalTable extends StatelessWidget {
   }
 }
 
+/// 결재 상세 탭 전체를 감싸는 카드 위젯.
+///
+/// 선택 상태와 로딩 여부에 따라 안내 문구 또는 상세 정보를 노출한다.
 class _DetailSection extends StatelessWidget {
   const _DetailSection({
     required this.approval,
@@ -894,6 +901,7 @@ class _OverviewTab extends StatelessWidget {
   }
 }
 
+/// 결재 단계 목록과 템플릿 적용 컨트롤을 묶어 보여주는 탭.
 class _StepTab extends StatelessWidget {
   const _StepTab({
     required this.approval,
@@ -1227,6 +1235,7 @@ class _StepTab extends StatelessWidget {
   }
 }
 
+/// 템플릿 목록을 선택·적용하고 재조회할 수 있는 툴바 UI.
 class _TemplateToolbar extends StatelessWidget {
   const _TemplateToolbar({
     required this.templates,

lib/features/approvals/shared/widgets/approver_autocomplete_field.dart

@@ -24,6 +24,7 @@ class ApprovalApproverAutocompleteField extends StatefulWidget {
       _ApprovalApproverAutocompleteFieldState();
 }
 
+/// 승인자 자동완성 필드의 내부 상태를 관리한다.
 class _ApprovalApproverAutocompleteFieldState
     extends State<ApprovalApproverAutocompleteField> {
   late final TextEditingController _textController;
@@ -39,6 +40,7 @@ class _ApprovalApproverAutocompleteFieldState
     _syncFromId();
   }
 
+  /// 외부에서 제공된 ID 값으로부터 표시 문자열을 동기화한다.
   void _syncFromId() {
     final idText = widget.idController.text.trim();
     final id = int.tryParse(idText);
@@ -55,10 +57,12 @@ class _ApprovalApproverAutocompleteFieldState
     }
   }
 
+  /// 검색어에 매칭되는 승인자 목록을 반환한다.
   Iterable<ApprovalApproverCatalogItem> _options(String query) {
     return ApprovalApproverCatalog.filter(query);
   }
 
+  /// 특정 승인자를 선택했을 때 내부 상태와 콜백을 갱신한다.
   void _handleSelected(ApprovalApproverCatalogItem item) {
     setState(() {
       _selected = item;
@@ -68,6 +72,7 @@ class _ApprovalApproverAutocompleteFieldState
     });
   }
 
+  /// 선택된 값을 초기화한다.
   void _handleCleared() {
     setState(() {
       _selected = null;
@@ -81,6 +86,7 @@ class _ApprovalApproverAutocompleteFieldState
     return '${item.name} (${item.employeeNo}) · ${item.team}';
   }
 
+  /// 사용자가 직접 입력한 사번(ID)을 기반으로 값을 결정한다.
   void _applyManualEntry(String value) {
     final trimmed = value.trim();
     if (trimmed.isEmpty) {
@@ -104,6 +110,7 @@ class _ApprovalApproverAutocompleteFieldState
     });
   }
 
+  /// 포커스가 해제될 때 수동 입력을 확정한다.
   void _handleFocusChange() {
     if (!_focusNode.hasFocus) {
       _applyManualEntry(_textController.text);

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,

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();

lib/widgets/components/superport_table.dart

@@ -202,6 +202,7 @@ class SuperportTable extends StatelessWidget {
   }
 }
 
+/// 정렬 상태와 토글 동작을 제공하는 테이블 헤더 셀.
 class _SortableHeader extends StatelessWidget {
   const _SortableHeader({
     required this.child,
@@ -245,6 +246,7 @@ class _SortableHeader extends StatelessWidget {
   }
 }
 
+/// 페이지 이동 및 페이지 사이즈 변경을 처리하는 푸터 UI.
 class _PaginationFooter extends StatelessWidget {
   const _PaginationFooter({
     required this.pagination,