feat(approvals): 결재 접근 차단 대응과 전표 전이 메모 전달 강화

- approvals 모듈에서 APPROVAL_ACCESS_DENIED 응답을 포착하여 ApprovalAccessDeniedException으로 변환하고 접근 거부 시 토스트·대시보드 리다이렉트를 처리 - approval history 조회가 서버 action id에 맞춰 필터링되도록 repository·controller·테스트를 보강 - 재고 트랜잭션 상태 전이 API 호출에 note를 전달하도록 repository·컨트롤러·통합/단위 테스트를 업데이트 - 승인 플로우 QA 체크리스트 및 연동 문서를 최신 계약과 테스트 흐름으로 업데이트
2025-10-31 16:43:14 +09:00
parent d76f765814
commit 3e83408aa7
35 changed files with 1056 additions and 470 deletions
--- a/test/features/approvals/history/presentation/controllers/approval_history_controller_test.dart
+++ b/test/features/approvals/history/presentation/controllers/approval_history_controller_test.dart
@@ -101,6 +101,16 @@ void main() {
    approvalRepository = _MockApprovalRepository();
    recallUseCase = _MockRecallApprovalUseCase();
    resubmitUseCase = _MockResubmitApprovalUseCase();
+    when(
+      () =>
+          approvalRepository.listActions(activeOnly: any(named: 'activeOnly')),
+    ).thenAnswer(
+      (_) async => [
+        ApprovalAction(id: 11, name: 'approve', code: 'approve'),
+        ApprovalAction(id: 12, name: 'reject', code: 'reject'),
+        ApprovalAction(id: 13, name: 'comment', code: 'comment'),
+      ],
+    );
    controller = ApprovalHistoryController(
      repository: repository,
      approvalRepository: approvalRepository,
@@ -115,7 +125,7 @@ void main() {
        page: any(named: 'page'),
        pageSize: any(named: 'pageSize'),
        query: any(named: 'query'),
-        action: any(named: 'action'),
+        approvalActionId: any(named: 'approvalActionId'),
        from: any(named: 'from'),
        to: any(named: 'to'),
      ),
@@ -130,7 +140,7 @@ void main() {
        page: 1,
        pageSize: 20,
        query: null,
-        action: null,
+        approvalActionId: null,
        from: null,
        to: null,
      ),
@@ -143,7 +153,7 @@ void main() {
        page: any(named: 'page'),
        pageSize: any(named: 'pageSize'),
        query: any(named: 'query'),
-        action: any(named: 'action'),
+        approvalActionId: any(named: 'approvalActionId'),
        from: any(named: 'from'),
        to: any(named: 'to'),
      ),
@@ -160,7 +170,7 @@ void main() {
        page: 2,
        pageSize: 20,
        query: 'APP',
-        action: 'approve',
+        approvalActionId: 11,
        from: DateTime(2024, 4, 1),
        to: DateTime(2024, 4, 30),
      ),
@@ -173,7 +183,7 @@ void main() {
        page: any(named: 'page'),
        pageSize: any(named: 'pageSize'),
        query: any(named: 'query'),
-        action: any(named: 'action'),
+        approvalActionId: any(named: 'approvalActionId'),
        from: any(named: 'from'),
        to: any(named: 'to'),
      ),
@@ -254,7 +264,7 @@ void main() {
        page: any(named: 'page'),
        pageSize: any(named: 'pageSize'),
        query: any(named: 'query'),
-        action: any(named: 'action'),
+        approvalActionId: any(named: 'approvalActionId'),
        from: any(named: 'from'),
        to: any(named: 'to'),
      ),
@@ -282,7 +292,7 @@ void main() {
        page: 1,
        pageSize: 20,
        query: null,
-        action: null,
+        approvalActionId: null,
        from: null,
        to: null,
      ),
@@ -319,7 +329,7 @@ void main() {
        page: any(named: 'page'),
        pageSize: any(named: 'pageSize'),
        query: any(named: 'query'),
-        action: any(named: 'action'),
+        approvalActionId: any(named: 'approvalActionId'),
        from: any(named: 'from'),
        to: any(named: 'to'),
      ),
--- a/test/features/approvals/history/presentation/pages/approval_history_page_test.dart
+++ b/test/features/approvals/history/presentation/pages/approval_history_page_test.dart
@@ -8,12 +8,13 @@ import 'package:shadcn_ui/shadcn_ui.dart';
 import 'package:superport_v2/core/common/models/paginated_result.dart';
 import 'package:superport_v2/features/approvals/domain/entities/approval.dart';
 import 'package:superport_v2/features/approvals/domain/entities/approval_flow.dart';
-import 'package:superport_v2/features/approvals/history/domain/entities/approval_history_record.dart';
-import 'package:superport_v2/features/approvals/history/domain/repositories/approval_history_repository.dart';
-import 'package:superport_v2/features/approvals/history/presentation/pages/approval_history_page.dart';
 import 'package:superport_v2/features/approvals/domain/repositories/approval_repository.dart';
 import 'package:superport_v2/features/approvals/domain/usecases/recall_approval_use_case.dart';
 import 'package:superport_v2/features/approvals/domain/usecases/resubmit_approval_use_case.dart';
+import 'package:superport_v2/features/approvals/history/domain/entities/approval_history_record.dart';
+import 'package:superport_v2/features/approvals/history/domain/repositories/approval_history_repository.dart';
+import 'package:superport_v2/features/approvals/history/presentation/controllers/approval_history_controller.dart';
+import 'package:superport_v2/features/approvals/history/presentation/pages/approval_history_page.dart';
 import 'package:superport_v2/features/auth/application/auth_service.dart';
 import 'package:superport_v2/features/auth/domain/entities/auth_permission.dart';
 import 'package:superport_v2/features/auth/domain/entities/auth_session.dart';
@@ -214,6 +215,17 @@ void main() {
    sl.registerLazySingleton<ResubmitApprovalUseCase>(() => resubmitUseCase);
    sl.registerLazySingleton<AuthService>(() => authService);

+    when(
+      () =>
+          approvalRepository.listActions(activeOnly: any(named: 'activeOnly')),
+    ).thenAnswer(
+      (_) async => [
+        ApprovalAction(id: 11, name: 'approve', code: 'approve'),
+        ApprovalAction(id: 12, name: 'reject', code: 'reject'),
+        ApprovalAction(id: 13, name: 'comment', code: 'comment'),
+      ],
+    );
+
    when(
      () => approvalRepository.fetchDetail(
        any(),
@@ -259,7 +271,7 @@ void main() {
        page: any(named: 'page'),
        pageSize: any(named: 'pageSize'),
        query: any(named: 'query'),
-        action: any(named: 'action'),
+        approvalActionId: any(named: 'approvalActionId'),
        from: any(named: 'from'),
        to: any(named: 'to'),
      ),
@@ -288,13 +300,54 @@ void main() {
        page: any(named: 'page'),
        pageSize: 20,
        query: 'APP-2024',
-        action: null,
+        approvalActionId: null,
        from: null,
        to: null,
      ),
    ).called(greaterThanOrEqualTo(1));
  });

+  testWidgets('행위 필터 선택 시 approval_action_id로 재조회한다', (tester) async {
+    dotenv.testLoad(fileInput: 'FEATURE_APPROVALS_ENABLED=true\n');
+
+    final capturedActionIds = <int?>[];
+    when(
+      () => historyRepository.list(
+        page: any(named: 'page'),
+        pageSize: any(named: 'pageSize'),
+        query: any(named: 'query'),
+        approvalActionId: any(named: 'approvalActionId'),
+        from: any(named: 'from'),
+        to: any(named: 'to'),
+      ),
+    ).thenAnswer((invocation) async {
+      capturedActionIds.add(
+        invocation.namedArguments[#approvalActionId] as int?,
+      );
+      return PaginatedResult<ApprovalHistoryRecord>(
+        items: [record, secondRecord],
+        page: 1,
+        pageSize: 20,
+        total: 2,
+      );
+    });
+
+    await tester.pumpWidget(_buildApp(const ApprovalHistoryPage()));
+    await tester.pumpAndSettle();
+
+    final controller = tester
+        .widgetList<AnimatedBuilder>(find.byType(AnimatedBuilder))
+        .map((builder) => builder.animation)
+        .whereType<ApprovalHistoryController>()
+        .first;
+
+    controller.updateActionFilter(ApprovalHistoryActionFilter.approve);
+    await controller.fetch(page: 1);
+    await tester.pump();
+
+    expect(capturedActionIds, contains(11));
+  });
+
  testWidgets('회수 시 상세 재조회 실패 안내를 노출한다', (tester) async {
    dotenv.testLoad(fileInput: 'FEATURE_APPROVALS_ENABLED=true\n');

@@ -303,7 +356,7 @@ void main() {
        page: any(named: 'page'),
        pageSize: any(named: 'pageSize'),
        query: any(named: 'query'),
-        action: any(named: 'action'),
+        approvalActionId: any(named: 'approvalActionId'),
        from: any(named: 'from'),
        to: any(named: 'to'),
      ),
--- a/test/features/approvals/presentation/controllers/approval_controller_test.dart
+++ b/test/features/approvals/presentation/controllers/approval_controller_test.dart
@@ -8,6 +8,7 @@ import 'package:superport_v2/features/approvals/domain/entities/approval.dart';
 import 'package:superport_v2/features/approvals/domain/entities/approval_draft.dart';
 import 'package:superport_v2/features/approvals/domain/entities/approval_template.dart';
 import 'package:superport_v2/features/approvals/domain/entities/approval_proceed_status.dart';
+import 'package:superport_v2/features/approvals/domain/errors/approval_access_denied_exception.dart';
 import 'package:superport_v2/features/approvals/domain/repositories/approval_repository.dart';
 import 'package:superport_v2/features/approvals/domain/repositories/approval_template_repository.dart';
 import 'package:superport_v2/features/approvals/domain/usecases/get_approval_draft_use_case.dart';
@@ -163,6 +164,29 @@ void main() {
      expect(statusCodes, isNull);
    });

+    test('403 접근 거부 시 accessDenied 플래그를 노출한다', () async {
+      when(
+        () => repository.list(
+          page: any(named: 'page'),
+          pageSize: any(named: 'pageSize'),
+          transactionId: any(named: 'transactionId'),
+          approvalStatusId: any(named: 'approvalStatusId'),
+          requestedById: any(named: 'requestedById'),
+          statusCodes: any(named: 'statusCodes'),
+          includePending: any(named: 'includePending'),
+          includeHistories: any(named: 'includeHistories'),
+          includeSteps: any(named: 'includeSteps'),
+        ),
+      ).thenThrow(const ApprovalAccessDeniedException(message: '테스트 접근 제한'));
+
+      await controller.fetch();
+
+      expect(controller.isAccessDenied, isTrue);
+      expect(controller.accessDeniedMessage, '테스트 접근 제한');
+      expect(controller.result, isNull);
+      expect(controller.errorMessage, isNull);
+    });
+
    // 검색어/상태/기간 필터가 Repository 호출에 반영되는지 확인한다.
    test('필터 전달을 검증한다', () async {
      controller.updateTransactionFilter(55);
@@ -316,6 +340,23 @@ void main() {
      expect(controller.canProceedSelected, isTrue);
    });

+    test('상세 조회에서 접근 거부 시 accessDenied를 기록한다', () async {
+      when(
+        () => repository.fetchDetail(
+          any(),
+          includeSteps: any(named: 'includeSteps'),
+          includeHistories: any(named: 'includeHistories'),
+        ),
+      ).thenThrow(const ApprovalAccessDeniedException(message: '상세 접근 제한'));
+
+      await controller.selectApproval(sampleApproval.id!);
+
+      expect(controller.isAccessDenied, isTrue);
+      expect(controller.accessDeniedMessage, '상세 접근 제한');
+      expect(controller.selected, isNull);
+      verifyNever(() => repository.canProceed(any()));
+    });
+
    test('에러 발생 시 errorMessage 설정', () async {
      when(
        () => repository.fetchDetail(
--- a/test/features/approvals/presentation/pages/approval_page_test.dart
+++ b/test/features/approvals/presentation/pages/approval_page_test.dart
@@ -9,6 +9,7 @@ import 'package:superport_v2/core/common/models/paginated_result.dart';
 import 'package:superport_v2/core/permissions/permission_manager.dart';
 import 'package:superport_v2/features/approvals/domain/entities/approval.dart';
 import 'package:superport_v2/features/approvals/domain/entities/approval_template.dart';
+import 'package:superport_v2/features/approvals/domain/errors/approval_access_denied_exception.dart';
 import 'package:superport_v2/features/approvals/domain/repositories/approval_repository.dart';
 import 'package:superport_v2/features/approvals/domain/repositories/approval_template_repository.dart';
 import 'package:superport_v2/features/approvals/presentation/controllers/approval_controller.dart';
@@ -111,6 +112,8 @@ void main() {
          transactionId: any(named: 'transactionId'),
          approvalStatusId: any(named: 'approvalStatusId'),
          requestedById: any(named: 'requestedById'),
+          statusCodes: any(named: 'statusCodes'),
+          includePending: any(named: 'includePending'),
          includeHistories: any(named: 'includeHistories'),
          includeSteps: any(named: 'includeSteps'),
        ),
@@ -137,5 +140,27 @@ void main() {
      await tester.pumpAndSettle();
      expect(find.text('승인대기'), findsWidgets);
    });
+
+    testWidgets('접근 거부 시 경고 토스트를 노출한다', (tester) async {
+      when(
+        () => repository.list(
+          page: any(named: 'page'),
+          pageSize: any(named: 'pageSize'),
+          transactionId: any(named: 'transactionId'),
+          approvalStatusId: any(named: 'approvalStatusId'),
+          requestedById: any(named: 'requestedById'),
+          statusCodes: any(named: 'statusCodes'),
+          includePending: any(named: 'includePending'),
+          includeHistories: any(named: 'includeHistories'),
+          includeSteps: any(named: 'includeSteps'),
+        ),
+      ).thenThrow(const ApprovalAccessDeniedException(message: '열람 권한이 없습니다.'));
+
+      await tester.pumpWidget(_buildApp(const ApprovalPage()));
+      await tester.pump();
+      await tester.pump(const Duration(milliseconds: 50));
+
+      expect(find.text('열람 권한이 없습니다.'), findsWidgets);
+    });
  });
 }
--- a/test/features/inventory/inbound/presentation/controllers/inbound_controller_test.dart
+++ b/test/features/inventory/inbound/presentation/controllers/inbound_controller_test.dart
@@ -336,7 +336,7 @@ void main() {

      final updated = _buildTransaction(statusName: '승인대기');
      when(
-        () => transactionRepository.submit(any()),
+        () => transactionRepository.submit(any(), note: any(named: 'note')),
      ).thenAnswer((_) async => updated);
      when(
        () => transactionRepository.list(filter: any(named: 'filter')),
@@ -353,7 +353,10 @@ void main() {

      expect(result.status, equals('승인대기'));
      expect(controller.records.first.status, equals('승인대기'));
-      verify(() => transactionRepository.submit(initial.id!)).called(1);
+      verify(
+        () =>
+            transactionRepository.submit(initial.id!, note: any(named: 'note')),
+      ).called(1);
    });

    test('fetchTransactions 실패 시 Failure 메시지를 노출한다', () async {
--- a/test/features/inventory/outbound/presentation/controllers/outbound_controller_test.dart
+++ b/test/features/inventory/outbound/presentation/controllers/outbound_controller_test.dart
@@ -106,7 +106,7 @@ void main() {
        () => transactionRepository.create(any()),
      ).thenAnswer((_) async => original);
      when(
-        () => transactionRepository.complete(any()),
+        () => transactionRepository.complete(any(), note: any(named: 'note')),
      ).thenAnswer((_) async => completed);

      await controller.createTransaction(
--- a/test/features/inventory/rental/presentation/controllers/rental_controller_test.dart
+++ b/test/features/inventory/rental/presentation/controllers/rental_controller_test.dart
@@ -164,7 +164,7 @@ void main() {
        status: StockTransactionStatus(id: 2, name: '완료'),
      );
      when(
-        () => transactionRepository.complete(any()),
+        () => transactionRepository.complete(any(), note: any(named: 'note')),
      ).thenAnswer((_) async => updated);
      when(
        () => transactionRepository.list(filter: any(named: 'filter')),
--- a/test/features/inventory/transactions/data/stock_transaction_repository_remote_test.dart
+++ b/test/features/inventory/transactions/data/stock_transaction_repository_remote_test.dart
@@ -215,16 +215,20 @@ void main() {
      ),
    );

-    await repository.submit(10);
+    await repository.submit(10, note: '승인 요청');

-    verify(
-      () => apiClient.post<Map<String, dynamic>>(
-        path,
-        data: any(named: 'data'),
-        options: any(named: 'options'),
-        cancelToken: any(named: 'cancelToken'),
-      ),
-    ).called(1);
+    final payload =
+        verify(
+              () => apiClient.post<Map<String, dynamic>>(
+                path,
+                data: captureAny(named: 'data'),
+                options: any(named: 'options'),
+                cancelToken: any(named: 'cancelToken'),
+              ),
+            ).captured[0]
+            as Map<String, dynamic>;
+    expect(payload['id'], 10);
+    expect(payload['note'], '승인 요청');
  });

  test('complete는 /complete 엔드포인트를 호출한다', () async {
@@ -244,16 +248,20 @@ void main() {
      ),
    );

-    await repository.complete(10);
+    await repository.complete(10, note: '처리 완료');

-    verify(
-      () => apiClient.post<Map<String, dynamic>>(
-        path,
-        data: any(named: 'data'),
-        options: any(named: 'options'),
-        cancelToken: any(named: 'cancelToken'),
-      ),
-    ).called(1);
+    final payload =
+        verify(
+              () => apiClient.post<Map<String, dynamic>>(
+                path,
+                data: captureAny(named: 'data'),
+                options: any(named: 'options'),
+                cancelToken: any(named: 'cancelToken'),
+              ),
+            ).captured[0]
+            as Map<String, dynamic>;
+    expect(payload['id'], 10);
+    expect(payload['note'], '처리 완료');
  });

  test('approve는 /approve 엔드포인트를 호출한다', () async {
@@ -273,16 +281,20 @@ void main() {
      ),
    );

-    await repository.approve(11);
+    await repository.approve(11, note: '승인 확정');

-    verify(
-      () => apiClient.post<Map<String, dynamic>>(
-        path,
-        data: any(named: 'data'),
-        options: any(named: 'options'),
-        cancelToken: any(named: 'cancelToken'),
-      ),
-    ).called(1);
+    final payload =
+        verify(
+              () => apiClient.post<Map<String, dynamic>>(
+                path,
+                data: captureAny(named: 'data'),
+                options: any(named: 'options'),
+                cancelToken: any(named: 'cancelToken'),
+              ),
+            ).captured[0]
+            as Map<String, dynamic>;
+    expect(payload['id'], 11);
+    expect(payload['note'], '승인 확정');
  });

  test('reject는 /reject 엔드포인트를 호출한다', () async {
@@ -302,16 +314,20 @@ void main() {
      ),
    );

-    await repository.reject(12);
+    await repository.reject(12, note: '재작업 필요');

-    verify(
-      () => apiClient.post<Map<String, dynamic>>(
-        path,
-        data: any(named: 'data'),
-        options: any(named: 'options'),
-        cancelToken: any(named: 'cancelToken'),
-      ),
-    ).called(1);
+    final payload =
+        verify(
+              () => apiClient.post<Map<String, dynamic>>(
+                path,
+                data: captureAny(named: 'data'),
+                options: any(named: 'options'),
+                cancelToken: any(named: 'cancelToken'),
+              ),
+            ).captured[0]
+            as Map<String, dynamic>;
+    expect(payload['id'], 12);
+    expect(payload['note'], '재작업 필요');
  });

  test('cancel은 /cancel 엔드포인트를 호출한다', () async {
@@ -331,15 +347,52 @@ void main() {
      ),
    );

-    await repository.cancel(13);
+    await repository.cancel(13, note: '상신 취소');

-    verify(
+    final payload =
+        verify(
+              () => apiClient.post<Map<String, dynamic>>(
+                path,
+                data: captureAny(named: 'data'),
+                options: any(named: 'options'),
+                cancelToken: any(named: 'cancelToken'),
+              ),
+            ).captured[0]
+            as Map<String, dynamic>;
+    expect(payload['id'], 13);
+    expect(payload['note'], '상신 취소');
+  });
+
+  test('transition note는 공백 입력 시 제외된다', () async {
+    const path = '/api/v1/stock-transactions/99/submit';
+    when(
      () => apiClient.post<Map<String, dynamic>>(
        path,
        data: any(named: 'data'),
        options: any(named: 'options'),
        cancelToken: any(named: 'cancelToken'),
      ),
-    ).called(1);
+    ).thenAnswer(
+      (_) async => Response<Map<String, dynamic>>(
+        data: detailBody(),
+        requestOptions: RequestOptions(path: path),
+        statusCode: 200,
+      ),
+    );
+
+    await repository.submit(99, note: '   ');
+
+    final payload =
+        verify(
+              () => apiClient.post<Map<String, dynamic>>(
+                path,
+                data: captureAny(named: 'data'),
+                options: any(named: 'options'),
+                cancelToken: any(named: 'cancelToken'),
+              ),
+            ).captured[0]
+            as Map<String, dynamic>;
+    expect(payload['id'], 99);
+    expect(payload.containsKey('note'), isFalse);
  });
 }
--- a/test/features/masters/group_permission/presentation/controllers/group_permission_controller_test.dart
+++ b/test/features/masters/group_permission/presentation/controllers/group_permission_controller_test.dart
@@ -257,5 +257,36 @@ void main() {
      expect(restored, isNotNull);
      verify(() => permissionRepository.restore(1)).called(1);
    });
+
+    test('restore 이후 includeDeleted 상태를 유지하며 재조회한다', () async {
+      controller.updateIncludeDeleted(true);
+      when(
+        () => permissionRepository.list(
+          page: any(named: 'page'),
+          pageSize: any(named: 'pageSize'),
+          groupId: any(named: 'groupId'),
+          menuId: any(named: 'menuId'),
+          isActive: any(named: 'isActive'),
+          includeDeleted: any(named: 'includeDeleted'),
+        ),
+      ).thenAnswer((_) async => createResult([samplePermission]));
+      when(
+        () => permissionRepository.restore(any()),
+      ).thenAnswer((_) async => samplePermission);
+
+      await controller.fetch();
+      await controller.restore(1);
+
+      verify(
+        () => permissionRepository.list(
+          page: any(named: 'page'),
+          pageSize: any(named: 'pageSize'),
+          groupId: any(named: 'groupId'),
+          menuId: any(named: 'menuId'),
+          isActive: any(named: 'isActive'),
+          includeDeleted: true,
+        ),
+      ).called(greaterThanOrEqualTo(1));
+    });
  });
 }
--- a/test/helpers/inventory_test_stubs.dart
+++ b/test/helpers/inventory_test_stubs.dart
@@ -327,7 +327,7 @@ class _StubStockTransactionRepository implements StockTransactionRepository {
  }

  @override
-  Future<StockTransaction> submit(int id) async {
+  Future<StockTransaction> submit(int id, {String? note}) async {
    final failure = _stubConfig.submitFailure;
    if (failure != null) {
      throw failure;
@@ -336,22 +336,22 @@ class _StubStockTransactionRepository implements StockTransactionRepository {
  }

  @override
-  Future<StockTransaction> complete(int id) async {
+  Future<StockTransaction> complete(int id, {String? note}) async {
    return _mutateTransaction(id, _applyCompleteStatus);
  }

  @override
-  Future<StockTransaction> approve(int id) async {
+  Future<StockTransaction> approve(int id, {String? note}) async {
    return _mutateTransaction(id, (transaction) => transaction);
  }

  @override
-  Future<StockTransaction> reject(int id) async {
+  Future<StockTransaction> reject(int id, {String? note}) async {
    return _mutateTransaction(id, (transaction) => transaction);
  }

  @override
-  Future<StockTransaction> cancel(int id) async {
+  Future<StockTransaction> cancel(int id, {String? note}) async {
    return _mutateTransaction(id, (transaction) => transaction);
  }