feat(menu-permissions): 메뉴 API 연동으로 사이드바 권한 정비

- .env.development.example과 lib/core/config/environment.dart, lib/core/permissions/permission_manager.dart에서 PERMISSION__ 폴백을 view 전용으로 좁히고 기본 정책을 명시적으로 거부하도록 재정비했다 - lib/core/navigation/*, lib/core/routing/app_router.dart, lib/widgets/app_shell.dart, lib/main.dart에서 메뉴 매니페스트·카탈로그를 도입해 /menus 응답을 캐싱하고 라우터·사이드바·Breadcrumb가 동일 menu_code/route_path를 쓰도록 리팩터링했다 - lib/core/permissions/permission_resources.dart와 그룹 권한/메뉴 마스터 모듈을 menu_code 기반 CRUD 및 Catalog 경로 정합성 검사로 전환하고 PermissionSynchronizer·PermissionBootstrapper를 확장했다 - test/helpers/test_permissions.dart, test/widgets/app_shell_test.dart 등 신규 구조를 반영하는 테스트·골든과 doc/frontend_menu_permission_tasks.md 문서를 보강했다
2025-11-12 18:29:03 +09:00
parent f767c44573
commit 753f76e952
72 changed files with 1914 additions and 704 deletions
--- a/test/core/permissions/permission_manager_test.dart
+++ b/test/core/permissions/permission_manager_test.dart
@@ -1,10 +1,16 @@
 import 'package:flutter_test/flutter_test.dart';

+import 'package:superport_v2/core/config/environment.dart';
+import 'package:superport_v2/core/navigation/route_paths.dart';
 import 'package:superport_v2/core/permissions/permission_manager.dart';
 import 'package:superport_v2/core/permissions/permission_resources.dart';

 void main() {
  group('PermissionManager', () {
+    tearDown(() {
+      Environment.setTestPermissions({});
+    });
+
    test('서버 권한을 적용하면 해당 리소스 권한이 설정된다', () {
      final manager = PermissionManager();

@@ -58,7 +64,7 @@ void main() {
      );
    });

-    test('서버 권한을 초기화하면 환경 설정으로 되돌아간다', () {
+    test('서버 권한을 초기화하면 기본 거부로 되돌아간다', () {
      final manager = PermissionManager();
      manager.applyServerPermissions({
        PermissionResources.vendors: {PermissionAction.view},
@@ -70,11 +76,27 @@ void main() {

      manager.clearServerPermissions();

-      // 환경 설정에 권한이 명시되지 않으면 기본적으로 허용한다.
+      // 환경 설정에 권한이 없으면 기본적으로 거부한다.
      expect(
        manager.can(PermissionResources.vendors, PermissionAction.edit),
+        isFalse,
+      );
+    });
+
+    test('환경 권한을 명시하면 폴백을 허용한다', () {
+      Environment.setTestPermissions({
+        PermissionResources.vendors: {'view'},
+      });
+      final manager = PermissionManager();
+
+      expect(
+        manager.can(PermissionResources.vendors, PermissionAction.view),
        isTrue,
      );
+      expect(
+        manager.can(PermissionResources.vendors, PermissionAction.edit),
+        isFalse,
+      );
    });

    test('별칭 경로도 normalize되어 권한을 확인한다', () {
@@ -88,7 +110,7 @@ void main() {
        isTrue,
      );
      expect(
-        manager.can('/inventory/outbound', PermissionAction.edit),
+        manager.can(inventoryIssuesRoutePath, PermissionAction.edit),
        isFalse,
      );
    });
--- a/test/core/permissions/permission_resources_test.dart
+++ b/test/core/permissions/permission_resources_test.dart
@@ -15,6 +15,25 @@ void main() {
      );
    });

+    test('백엔드 menus.route_path 전부를 인식한다', () {
+      expect(
+        PermissionResources.normalize('/inventory/receipts'),
+        PermissionResources.stockTransactions,
+      );
+      expect(
+        PermissionResources.normalize('/inventory/vendors'),
+        PermissionResources.vendors,
+      );
+      expect(
+        PermissionResources.normalize('/settings/group-permissions'),
+        PermissionResources.groupMenuPermissions,
+      );
+      expect(
+        PermissionResources.normalize('/utilities/zipcodes'),
+        PermissionResources.postalSearch,
+      );
+    });
+
    test('대소문자/공백/슬래시를 정리한다', () {
      expect(
        PermissionResources.normalize('  inventory/inbound/  '),
--- a/test/features/inventory/inbound_page_test.dart
+++ b/test/features/inventory/inbound_page_test.dart
@@ -5,6 +5,7 @@ import 'package:go_router/go_router.dart';
 import 'package:shadcn_ui/shadcn_ui.dart';

 import 'package:superport_v2/core/config/environment.dart';
+import 'package:superport_v2/core/navigation/route_paths.dart';
 import 'package:superport_v2/core/permissions/permission_manager.dart';
 import 'package:superport_v2/core/theme/superport_shad_theme.dart';
 import 'package:superport_v2/features/inventory/inbound/presentation/pages/inbound_page.dart';
@@ -13,6 +14,11 @@ import 'package:superport_v2/widgets/components/form_field.dart';

 import '../../helpers/inventory_test_stubs.dart';

+Future<void> _tapVisible(WidgetTester tester, Finder finder) async {
+  await tester.ensureVisible(finder);
+  await tester.tap(finder);
+}
+
 void main() {
  TestWidgetsFlutterBinding.ensureInitialized();

@@ -40,10 +46,10 @@ void main() {
    });

    final router = GoRouter(
-      initialLocation: '/inventory/inbound',
+      initialLocation: inventoryReceiptsRoutePath,
      routes: [
        GoRoute(
-          path: '/inventory/inbound',
+          path: inventoryReceiptsRoutePath,
          builder: (context, state) =>
              Scaffold(body: InboundPage(routeUri: state.uri)),
        ),
@@ -68,13 +74,13 @@ void main() {
    await tester.enterText(find.byType(EditableText).first, 'TX-20240305-010');
    await tester.pump();

-    await tester.tap(find.widgetWithText(ShadButton, '검색 적용'));
+    await _tapVisible(tester, find.widgetWithText(ShadButton, '검색 적용'));
    await tester.pumpAndSettle();

    expect(find.text('TX-20240305-010'), findsWidgets);
    expect(find.text('TX-20240301-001'), findsNothing);

-    await tester.tap(find.widgetWithText(ShadButton, '초기화'));
+    await _tapVisible(tester, find.widgetWithText(ShadButton, '초기화'));
    await tester.pumpAndSettle();

    expect(find.text('TX-20240301-001'), findsWidgets);
@@ -97,7 +103,7 @@ void main() {
            child: ShadTheme(
              data: SuperportShadTheme.light(),
              child: Scaffold(
-                body: InboundPage(routeUri: Uri.parse('/inventory/inbound')),
+                body: InboundPage(routeUri: Uri.parse(inventoryReceiptsRoutePath)),
              ),
            ),
          ),
@@ -106,7 +112,7 @@ void main() {
    );
    await tester.pumpAndSettle();

-    await tester.tap(find.widgetWithText(ShadButton, '입고 등록'));
+    await _tapVisible(tester, find.widgetWithText(ShadButton, '입고 등록'));
    await tester.pumpAndSettle();

    final transactionField = find.byWidgetPredicate(
@@ -140,12 +146,11 @@ void main() {
    );
    await tester.enterText(firstProductInput, 'XR-5000');
    await tester.pumpAndSettle();
-    await tester.tap(find.text('XR-5000').last);
+    await _tapVisible(tester, find.text('XR-5000').last);
    await tester.pumpAndSettle();

    final addLineButton = find.widgetWithText(ShadButton, '품목 추가');
-    await tester.ensureVisible(addLineButton);
-    await tester.tap(addLineButton);
+    await _tapVisible(tester, addLineButton);
    await tester.pumpAndSettle();

    final updatedProductFields = find.byType(InventoryProductAutocompleteField);
@@ -157,12 +162,11 @@ void main() {
    );
    await tester.enterText(secondProductInput, 'XR-5000');
    await tester.pumpAndSettle();
-    await tester.tap(find.text('XR-5000').last);
+    await _tapVisible(tester, find.text('XR-5000').last);
    await tester.pumpAndSettle();

    final saveButton = find.widgetWithText(ShadButton, '저장');
-    await tester.ensureVisible(saveButton);
-    await tester.tap(saveButton);
+    await _tapVisible(tester, saveButton);
    await tester.pumpAndSettle();

    expect(find.text('동일 제품이 중복되었습니다.'), findsOneWidget);
@@ -185,7 +189,7 @@ void main() {
            child: ShadTheme(
              data: SuperportShadTheme.light(),
              child: Scaffold(
-                body: InboundPage(routeUri: Uri.parse('/inventory/inbound')),
+                body: InboundPage(routeUri: Uri.parse(inventoryReceiptsRoutePath)),
              ),
            ),
          ),
@@ -194,12 +198,12 @@ void main() {
    );
    await tester.pumpAndSettle();

-    await tester.tap(find.widgetWithText(ShadButton, '입고 등록'));
+    await _tapVisible(tester, find.widgetWithText(ShadButton, '입고 등록'));
    await tester.pumpAndSettle();

    expect(find.text('저장 시 자동 생성'), findsAtLeastNWidgets(2));

-    await tester.tap(find.widgetWithText(ShadButton, '저장'));
+    await _tapVisible(tester, find.widgetWithText(ShadButton, '저장'));
    await tester.pump();

    expect(find.text('거래번호를 입력하세요.'), findsNothing);
@@ -225,7 +229,7 @@ void main() {
            child: ShadTheme(
              data: SuperportShadTheme.light(),
              child: Scaffold(
-                body: InboundPage(routeUri: Uri.parse('/inventory/inbound')),
+                body: InboundPage(routeUri: Uri.parse(inventoryReceiptsRoutePath)),
              ),
            ),
          ),
@@ -234,14 +238,14 @@ void main() {
    );
    await tester.pumpAndSettle();

-    await tester.tap(find.text('TX-20240301-001').first);
+    await _tapVisible(tester, find.text('TX-20240301-001').first);
    await tester.pumpAndSettle();

    expect(find.text('입고 상세'), findsOneWidget);

    final editButton = find.widgetWithText(ShadButton, '수정').last;
    await tester.ensureVisible(editButton);
-    await tester.tap(editButton);
+    await _tapVisible(tester, editButton);
    await tester.pump();

    await tester.pumpAndSettle(const Duration(milliseconds: 500));
--- a/test/features/inventory/inventory_pages_smoke_test.dart
+++ b/test/features/inventory/inventory_pages_smoke_test.dart
@@ -2,12 +2,15 @@ import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:shadcn_ui/shadcn_ui.dart';
+import 'package:superport_v2/core/navigation/route_paths.dart';
 import 'package:superport_v2/core/permissions/permission_manager.dart';
 import 'package:superport_v2/core/theme/superport_shad_theme.dart';
 import 'package:superport_v2/features/inventory/inbound/presentation/pages/inbound_page.dart';
 import 'package:superport_v2/features/inventory/outbound/presentation/pages/outbound_page.dart';
 import 'package:superport_v2/features/inventory/rental/presentation/pages/rental_page.dart';

+import '../../helpers/test_permissions.dart';
+
 Widget _wrapInventoryPage(Widget child) {
  return PermissionScope(
    manager: PermissionManager(),
@@ -20,6 +23,10 @@ Widget _wrapInventoryPage(Widget child) {
 }

 void main() {
+  setUp(() {
+    grantTestPermissions();
+  });
+
  testWidgets(
    'Inbound page reflects include state from route and closes dialog with Esc',
    (tester) async {
@@ -33,7 +40,9 @@ void main() {

      await tester.pumpWidget(
        _wrapInventoryPage(
-          InboundPage(routeUri: Uri.parse('/inventory/inbound?include=lines')),
+          InboundPage(
+            routeUri: Uri.parse('$inventoryReceiptsRoutePath?include=lines'),
+          ),
        ),
      );
      await tester.pumpAndSettle();
@@ -63,7 +72,9 @@ void main() {
    await tester.pumpWidget(
      _wrapInventoryPage(
        OutboundPage(
-          routeUri: Uri.parse('/inventory/outbound?include=lines,customers'),
+          routeUri: Uri.parse(
+            '$inventoryIssuesRoutePath?include=lines,customers',
+          ),
        ),
      ),
    );
@@ -85,7 +96,9 @@ void main() {

    await tester.pumpWidget(
      _wrapInventoryPage(
-        RentalPage(routeUri: Uri.parse('/inventory/rental?include=lines')),
+        RentalPage(
+          routeUri: Uri.parse('$inventoryRentalsRoutePath?include=lines'),
+        ),
      ),
    );
    await tester.pumpAndSettle();
--- a/test/features/inventory/outbound_page_test.dart
+++ b/test/features/inventory/outbound_page_test.dart
@@ -4,12 +4,18 @@ import 'package:get_it/get_it.dart';
 import 'package:shadcn_ui/shadcn_ui.dart';

 import 'package:superport_v2/core/config/environment.dart';
+import 'package:superport_v2/core/navigation/route_paths.dart';
 import 'package:superport_v2/core/permissions/permission_manager.dart';
 import 'package:superport_v2/core/theme/superport_shad_theme.dart';
 import 'package:superport_v2/features/inventory/outbound/presentation/pages/outbound_page.dart';

 import '../../helpers/inventory_test_stubs.dart';

+Future<void> _tapVisible(WidgetTester tester, Finder finder) async {
+  await tester.ensureVisible(finder);
+  await tester.tap(finder);
+}
+
 void main() {
  TestWidgetsFlutterBinding.ensureInitialized();

@@ -44,7 +50,9 @@ void main() {
            child: ShadTheme(
              data: SuperportShadTheme.light(),
              child: Scaffold(
-                body: OutboundPage(routeUri: Uri.parse('/inventory/outbound')),
+                body: OutboundPage(
+                  routeUri: Uri.parse(inventoryIssuesRoutePath),
+                ),
              ),
            ),
          ),
@@ -53,12 +61,12 @@ void main() {
    );
    await tester.pumpAndSettle();

-    await tester.tap(find.widgetWithText(ShadButton, '출고 등록'));
+    await _tapVisible(tester, find.widgetWithText(ShadButton, '출고 등록'));
    await tester.pumpAndSettle();

    expect(find.text('저장 시 자동 생성'), findsAtLeastNWidgets(2));

-    await tester.tap(find.widgetWithText(ShadButton, '저장'));
+    await _tapVisible(tester, find.widgetWithText(ShadButton, '저장'));
    await tester.pump();

    expect(find.text('거래번호를 입력하세요.'), findsNothing);
@@ -84,7 +92,9 @@ void main() {
            child: ShadTheme(
              data: SuperportShadTheme.light(),
              child: Scaffold(
-                body: OutboundPage(routeUri: Uri.parse('/inventory/outbound')),
+                body: OutboundPage(
+                  routeUri: Uri.parse(inventoryIssuesRoutePath),
+                ),
              ),
            ),
          ),
@@ -93,14 +103,14 @@ void main() {
    );
    await tester.pumpAndSettle();

-    await tester.tap(find.text('TX-20240302-010').first);
+    await _tapVisible(tester, find.text('TX-20240302-010').first);
    await tester.pumpAndSettle();

    expect(find.text('출고 상세'), findsOneWidget);

    final editButton = find.widgetWithText(ShadButton, '수정').last;
    await tester.ensureVisible(editButton);
-    await tester.tap(editButton);
+    await _tapVisible(tester, editButton);
    await tester.pump();
    await tester.pumpAndSettle(const Duration(milliseconds: 500));

--- a/test/features/inventory/rental_page_test.dart
+++ b/test/features/inventory/rental_page_test.dart
@@ -4,6 +4,7 @@ import 'package:get_it/get_it.dart';
 import 'package:shadcn_ui/shadcn_ui.dart';

 import 'package:superport_v2/core/config/environment.dart';
+import 'package:superport_v2/core/navigation/route_paths.dart';
 import 'package:superport_v2/core/permissions/permission_manager.dart';
 import 'package:superport_v2/core/theme/superport_shad_theme.dart';
 import 'package:superport_v2/features/inventory/rental/presentation/pages/rental_page.dart';
@@ -44,7 +45,9 @@ void main() {
            child: ShadTheme(
              data: SuperportShadTheme.light(),
              child: Scaffold(
-                body: RentalPage(routeUri: Uri.parse('/inventory/rental')),
+                body: RentalPage(
+                  routeUri: Uri.parse(inventoryRentalsRoutePath),
+                ),
              ),
            ),
          ),
@@ -84,7 +87,9 @@ void main() {
            child: ShadTheme(
              data: SuperportShadTheme.light(),
              child: Scaffold(
-                body: RentalPage(routeUri: Uri.parse('/inventory/rental')),
+                body: RentalPage(
+                  routeUri: Uri.parse(inventoryRentalsRoutePath),
+                ),
              ),
            ),
          ),
--- a/test/features/inventory/summary/presentation/pages/goldens/inventory_summary_detail_sheet.png
+++ b/test/features/inventory/summary/presentation/pages/goldens/inventory_summary_detail_sheet.png
--- a/test/features/inventory/summary/presentation/pages/goldens/inventory_summary_page_default.png
+++ b/test/features/inventory/summary/presentation/pages/goldens/inventory_summary_page_default.png
--- a/test/features/inventory/summary/presentation/pages/inventory_summary_page_golden_test.dart
+++ b/test/features/inventory/summary/presentation/pages/inventory_summary_page_golden_test.dart
@@ -20,6 +20,8 @@ import 'package:superport_v2/features/inventory/summary/presentation/pages/inven
 import 'package:superport_v2/features/masters/warehouse/domain/entities/warehouse.dart';
 import 'package:superport_v2/features/masters/warehouse/domain/repositories/warehouse_repository.dart';

+import '../../../../../helpers/test_permissions.dart';
+
 class _MockInventoryRepository extends Mock implements InventoryRepository {}

 class _MockWarehouseRepository extends Mock implements WarehouseRepository {}
@@ -141,6 +143,7 @@ void _stubWarehouseList(_MockWarehouseRepository repository) {

 Future<void> _pumpInventoryPage(WidgetTester tester) async {
  await tester.binding.setSurfaceSize(const Size(1600, 1200));
+  addTearDown(() => tester.binding.setSurfaceSize(null));
  await tester.pumpWidget(
    _buildApp(
      InventorySummaryPage(
@@ -153,7 +156,7 @@ Future<void> _pumpInventoryPage(WidgetTester tester) async {
 }

 void main() {
-  final binding = TestWidgetsFlutterBinding.ensureInitialized();
+  TestWidgetsFlutterBinding.ensureInitialized();

  setUpAll(() {
    registerFallbackValue(const InventorySummaryFilter());
@@ -161,6 +164,7 @@ void main() {
  });

  setUp(() async {
+    grantTestPermissions(includeWrites: false);
    final inventoryRepository = _MockInventoryRepository();
    final warehouseRepository = _MockWarehouseRepository();
    _registerDependencies(
@@ -178,7 +182,6 @@ void main() {
  });

  tearDown(() async {
-    await binding.setSurfaceSize(null);
    await GetIt.I.reset();
  });

--- a/test/features/inventory/summary/presentation/pages/inventory_summary_page_test.dart
+++ b/test/features/inventory/summary/presentation/pages/inventory_summary_page_test.dart
@@ -21,6 +21,8 @@ import 'package:superport_v2/features/inventory/summary/presentation/pages/inven
 import 'package:superport_v2/features/masters/warehouse/domain/entities/warehouse.dart';
 import 'package:superport_v2/features/masters/warehouse/domain/repositories/warehouse_repository.dart';

+import '../../../../../helpers/test_permissions.dart';
+
 class _MockInventoryRepository extends Mock implements InventoryRepository {}

 class _MockWarehouseRepository extends Mock implements WarehouseRepository {}
@@ -149,6 +151,11 @@ InventoryDetail _buildDetail() {
  );
 }

+Future<void> _tapVisible(WidgetTester tester, Finder finder) async {
+  await tester.ensureVisible(finder);
+  await tester.tap(finder);
+}
+
 void main() {
  TestWidgetsFlutterBinding.ensureInitialized();

@@ -157,6 +164,10 @@ void main() {
    registerFallbackValue(const InventoryDetailFilter());
  });

+  setUp(() {
+    grantTestPermissions();
+  });
+
  tearDown(() async {
    await GetIt.I.reset();
  });
@@ -201,7 +212,7 @@ void main() {

    expect(listCallCount, 2);

-    await tester.tap(find.bySemanticsLabel('자동 새로고침 전환'));
+    await _tapVisible(tester, find.bySemanticsLabel('자동 새로고침 전환'));
    await tester.pumpAndSettle();

    await tester.pump(const Duration(seconds: 31));
@@ -236,13 +247,16 @@ void main() {
    );
    await tester.pumpAndSettle();

-    await tester.tap(find.text('테스트 장비'));
+    await _tapVisible(tester, find.text('테스트 장비'));
    await tester.pumpAndSettle();

    expect(find.text('창고 잔량'), findsOneWidget);
    expect(find.byType(LinearProgressIndicator), findsWidgets);
    expect(find.text('최근 이벤트'), findsOneWidget);
-    expect(find.textContaining('거래처: QA 파트너'), findsOneWidget);
+    expect(
+      find.textContaining('거래처: QA 파트너'),
+      findsAtLeastNWidgets(1),
+    );
  });

  testWidgets('권한 오류가 발생하면 경고 배너를 노출한다', (tester) async {
@@ -311,7 +325,7 @@ void main() {
    );
    await tester.pump();

-    await tester.tap(find.byKey(const Key('inventory_filter_apply')));
+    await _tapVisible(tester, find.byKey(const Key('inventory_filter_apply')));
    await tester.pumpAndSettle();

    expect(capturedFilters.length, greaterThanOrEqualTo(2));
@@ -393,14 +407,14 @@ void main() {

    expect(recordedFilters, isNotEmpty);
    // 첫 정렬: 총 수량 헤더 탭 → 오름차순
-    await tester.tap(find.text('총 수량').first);
+    await _tapVisible(tester, find.text('총 수량').first);
    await tester.pumpAndSettle();
    final ascFilter = recordedFilters.last;
    expect(ascFilter.sort, 'total_quantity');
    expect(ascFilter.order, 'asc');

    // 두 번째 탭 → 내림차순
-    await tester.tap(find.text('총 수량').first);
+    await _tapVisible(tester, find.text('총 수량').first);
    await tester.pumpAndSettle();
    final descFilter = recordedFilters.last;
    expect(descFilter.sort, 'total_quantity');
--- a/test/features/login/presentation/pages/login_page_test.dart
+++ b/test/features/login/presentation/pages/login_page_test.dart
@@ -8,7 +8,8 @@ import 'package:shadcn_ui/shadcn_ui.dart';

 import 'package:superport_v2/core/services/token_storage.dart';
 import 'package:superport_v2/core/common/models/paginated_result.dart';
-import 'package:superport_v2/core/constants/app_sections.dart';
+import 'package:superport_v2/core/navigation/menu_catalog.dart';
+import 'package:superport_v2/core/navigation/route_paths.dart';
 import 'package:superport_v2/core/permissions/permission_manager.dart';
 import 'package:superport_v2/core/permissions/permission_resources.dart';
 import 'package:superport_v2/features/auth/application/auth_service.dart';
@@ -22,6 +23,9 @@ import 'package:superport_v2/features/masters/group/domain/repositories/group_re
 import 'package:superport_v2/features/masters/group_permission/domain/entities/group_permission.dart';
 import 'package:superport_v2/features/masters/group_permission/domain/repositories/group_permission_repository.dart';

+import '../../../../helpers/test_app.dart';
+import '../../../../helpers/test_permissions.dart';
+
 class _MockGroupRepository extends Mock implements GroupRepository {}

 class _MockGroupPermissionRepository extends Mock
@@ -70,6 +74,7 @@ void main() {
  late AuthService authService;

  setUp(() {
+    grantTestPermissions();
    authRepository = _MockAuthRepository();
    tokenStorage = _FakeTokenStorage();
    authService = AuthService(
@@ -127,7 +132,7 @@ void main() {
        page: any(named: 'page'),
        pageSize: any(named: 'pageSize'),
        groupId: any(named: 'groupId'),
-        menuId: any(named: 'menuId'),
+        menuCode: any(named: 'menuCode'),
        isActive: any(named: 'isActive'),
        includeDeleted: any(named: 'includeDeleted'),
      ),
@@ -139,9 +144,9 @@ void main() {
            group: GroupPermissionGroup(id: 1, groupName: '관리자'),
            menu: GroupPermissionMenu(
              id: 10,
-              menuCode: 'INBOUND',
+              menuCode: 'inventory.receipts',
              menuName: '입고',
-              path: '/inventory/inbound',
+              path: inventoryReceiptsRoutePath,
            ),
            canCreate: true,
            canRead: true,
@@ -170,10 +175,15 @@ void main() {
      ],
    );

+    final catalog = createTestMenuCatalog();
+
    await tester.pumpWidget(
      PermissionScope(
        manager: manager,
-        child: ShadApp.router(routerConfig: router),
+        child: MenuCatalogScope(
+          catalog: catalog,
+          child: ShadApp.router(routerConfig: router),
+        ),
      ),
    );

@@ -233,10 +243,15 @@ void main() {
      ],
    );

+    final catalog = createTestMenuCatalog();
+
    await tester.pumpWidget(
      PermissionScope(
        manager: manager,
-        child: ShadApp.router(routerConfig: router),
+        child: MenuCatalogScope(
+          catalog: catalog,
+          child: ShadApp.router(routerConfig: router),
+        ),
      ),
    );

--- a/test/features/masters/customer/presentation/pages/customer_page_test.dart
+++ b/test/features/masters/customer/presentation/pages/customer_page_test.dart
@@ -7,6 +7,7 @@ import 'package:shadcn_ui/shadcn_ui.dart';

 import '../../../../../helpers/tester_extensions.dart';
 import 'package:superport_v2/core/common/models/paginated_result.dart';
+import 'package:superport_v2/core/navigation/route_paths.dart';
 import 'package:superport_v2/features/masters/customer/domain/entities/customer.dart';
 import 'package:superport_v2/features/masters/customer/domain/repositories/customer_repository.dart';
 import 'package:superport_v2/features/masters/customer/presentation/pages/customer_page.dart';
@@ -43,7 +44,7 @@ void main() {
    dotenv.testLoad(fileInput: 'FEATURE_CUSTOMERS_ENABLED=false\n');

    await tester.pumpWidget(
-      _buildApp(CustomerPage(routeUri: Uri(path: '/masters/customers'))),
+      _buildApp(CustomerPage(routeUri: Uri(path: inventoryCustomersRoutePath))),
    );
    await tester.pump();

@@ -89,7 +90,7 @@ void main() {
      );

      await tester.pumpWidget(
-        _buildApp(CustomerPage(routeUri: Uri(path: '/masters/customers'))),
+        _buildApp(CustomerPage(routeUri: Uri(path: inventoryCustomersRoutePath))),
      );
      await tester.pumpAndSettle();

@@ -126,7 +127,7 @@ void main() {
      );

      await tester.pumpWidget(
-        _buildApp(CustomerPage(routeUri: Uri(path: '/masters/customers'))),
+        _buildApp(CustomerPage(routeUri: Uri(path: inventoryCustomersRoutePath))),
      );
      await tester.pumpAndSettle();

@@ -159,7 +160,7 @@ void main() {
      );

      await tester.pumpWidget(
-        _buildApp(CustomerPage(routeUri: Uri(path: '/masters/customers'))),
+        _buildApp(CustomerPage(routeUri: Uri(path: inventoryCustomersRoutePath))),
      );
      await tester.pumpAndSettle();

@@ -232,7 +233,7 @@ void main() {
      });

      await tester.pumpWidget(
-        _buildApp(CustomerPage(routeUri: Uri(path: '/masters/customers'))),
+        _buildApp(CustomerPage(routeUri: Uri(path: inventoryCustomersRoutePath))),
      );
      await tester.pumpAndSettle();

@@ -297,7 +298,7 @@ void main() {
          Center(
            child: SizedBox(
              width: 320,
-              child: CustomerPage(routeUri: Uri(path: '/masters/customers')),
+              child: CustomerPage(routeUri: Uri(path: inventoryCustomersRoutePath)),
            ),
          ),
        ),
--- a/test/features/masters/group/presentation/controllers/group_controller_test.dart
+++ b/test/features/masters/group/presentation/controllers/group_controller_test.dart
@@ -144,7 +144,7 @@ void main() {
          page: any(named: 'page'),
          pageSize: any(named: 'pageSize'),
          groupId: any(named: 'groupId'),
-          menuId: any(named: 'menuId'),
+          menuCode: any(named: 'menuCode'),
          isActive: any(named: 'isActive'),
          includeDeleted: any(named: 'includeDeleted'),
        ),
@@ -183,7 +183,7 @@ void main() {
          page: any(named: 'page'),
          pageSize: any(named: 'pageSize'),
          groupId: sampleGroup.id,
-          menuId: any(named: 'menuId'),
+          menuCode: any(named: 'menuCode'),
          isActive: any(named: 'isActive'),
          includeDeleted: any(named: 'includeDeleted'),
        ),
--- a/test/features/masters/group_permission/application/permission_synchronizer_test.dart
+++ b/test/features/masters/group_permission/application/permission_synchronizer_test.dart
@@ -2,11 +2,15 @@ import 'package:flutter_test/flutter_test.dart';
 import 'package:mocktail/mocktail.dart';

 import 'package:superport_v2/core/common/models/paginated_result.dart';
+import 'package:superport_v2/core/navigation/menu_catalog.dart';
+import 'package:superport_v2/core/navigation/route_paths.dart';
 import 'package:superport_v2/core/permissions/permission_manager.dart';
 import 'package:superport_v2/core/permissions/permission_resources.dart';
 import 'package:superport_v2/features/masters/group_permission/application/permission_synchronizer.dart';
 import 'package:superport_v2/features/masters/group_permission/domain/entities/group_permission.dart';
 import 'package:superport_v2/features/masters/group_permission/domain/repositories/group_permission_repository.dart';
+import 'package:superport_v2/features/masters/menu/domain/entities/menu.dart';
+import 'package:superport_v2/features/masters/menu/domain/repositories/menu_repository.dart';

 class _MockGroupPermissionRepository extends Mock
    implements GroupPermissionRepository {}
@@ -29,9 +33,9 @@ void main() {
        group: GroupPermissionGroup(id: 1, groupName: '관리자'),
        menu: GroupPermissionMenu(
          id: 10,
-          menuCode: 'INBOUND',
+          menuCode: 'inventory.receipts',
          menuName: '입고',
-          path: '/inventory/inbound',
+          path: inventoryReceiptsRoutePath,
        ),
        canCreate: true,
        canRead: true,
@@ -44,9 +48,9 @@ void main() {
        group: GroupPermissionGroup(id: 1, groupName: '관리자'),
        menu: GroupPermissionMenu(
          id: 11,
-          menuCode: 'OUTBOUND',
+          menuCode: 'inventory.issues',
          menuName: '출고',
-          path: '/inventory/outbound',
+          path: inventoryIssuesRoutePath,
        ),
        canCreate: false,
        canRead: true,
@@ -59,7 +63,7 @@ void main() {
          page: any(named: 'page'),
          pageSize: any(named: 'pageSize'),
          groupId: any(named: 'groupId'),
-          menuId: any(named: 'menuId'),
+          menuCode: any(named: 'menuCode'),
          isActive: any(named: 'isActive'),
          includeDeleted: any(named: 'includeDeleted'),
        ),
@@ -88,7 +92,7 @@ void main() {
          page: any(named: 'page'),
          pageSize: 1,
          groupId: 1,
-          menuId: null,
+          menuCode: null,
          isActive: true,
          includeDeleted: false,
        ),
@@ -131,7 +135,7 @@ void main() {
          page: any(named: 'page'),
          pageSize: any(named: 'pageSize'),
          groupId: any(named: 'groupId'),
-          menuId: any(named: 'menuId'),
+          menuCode: any(named: 'menuCode'),
          isActive: any(named: 'isActive'),
          includeDeleted: any(named: 'includeDeleted'),
        ),
@@ -166,5 +170,160 @@ void main() {
        contains(PermissionAction.view),
      );
    });
+
+    test('menu_code 경로 불일치는 Catalog 기준으로 보정한다', () async {
+      const legacyPath = '/legacy/inbound';
+      final repository = _MockGroupPermissionRepository();
+      final manager = PermissionManager();
+      final catalog = MenuCatalog(repository: _DummyMenuRepository());
+      catalog.replaceAll([
+        MenuItem(
+          id: 10,
+          menuCode: 'inventory.receipts',
+          menuName: '입고',
+          path: inventoryReceiptsRoutePath,
+        ),
+      ]);
+      final synchronizer = PermissionSynchronizer(
+        repository: repository,
+        manager: manager,
+        menuCatalog: catalog,
+      );
+
+      when(
+        () => repository.list(
+          page: any(named: 'page'),
+          pageSize: any(named: 'pageSize'),
+          groupId: any(named: 'groupId'),
+          menuCode: any(named: 'menuCode'),
+          isActive: any(named: 'isActive'),
+          includeDeleted: any(named: 'includeDeleted'),
+        ),
+      ).thenAnswer((_) async {
+        return PaginatedResult<GroupPermission>(
+          items: [
+            GroupPermission(
+              id: 1,
+              group: GroupPermissionGroup(id: 1, groupName: '관리자'),
+              menu: GroupPermissionMenu(
+                id: 10,
+                menuCode: 'inventory.receipts',
+                menuName: '입고',
+                path: legacyPath,
+              ),
+              canRead: true,
+            ),
+          ],
+          page: 1,
+          pageSize: 20,
+          total: 1,
+        );
+      });
+
+      await synchronizer.syncForGroup(1);
+
+      expect(
+        manager.can(inventoryReceiptsRoutePath, PermissionAction.view),
+        isTrue,
+      );
+      expect(
+        manager.can(legacyPath, PermissionAction.view),
+        isFalse,
+      );
+    });
+
+    test('menu path가 비어도 Catalog 경로를 적용한다', () async {
+      final repository = _MockGroupPermissionRepository();
+      final manager = PermissionManager();
+      final catalog = MenuCatalog(repository: _DummyMenuRepository());
+      catalog.replaceAll([
+        MenuItem(
+          id: 20,
+          menuCode: 'inventory.issues',
+          menuName: '출고',
+          path: inventoryIssuesRoutePath,
+        ),
+      ]);
+      final synchronizer = PermissionSynchronizer(
+        repository: repository,
+        manager: manager,
+        menuCatalog: catalog,
+      );
+
+      when(
+        () => repository.list(
+          page: any(named: 'page'),
+          pageSize: any(named: 'pageSize'),
+          groupId: any(named: 'groupId'),
+          menuCode: any(named: 'menuCode'),
+          isActive: any(named: 'isActive'),
+          includeDeleted: any(named: 'includeDeleted'),
+        ),
+      ).thenAnswer((_) async {
+        return PaginatedResult<GroupPermission>(
+          items: [
+            GroupPermission(
+              id: 2,
+              group: GroupPermissionGroup(id: 1, groupName: '관리자'),
+              menu: GroupPermissionMenu(
+                id: 20,
+                menuCode: 'inventory.issues',
+                menuName: '출고',
+              ),
+              canRead: true,
+            ),
+          ],
+          page: 1,
+          pageSize: 20,
+          total: 1,
+        );
+      });
+
+      await synchronizer.syncForGroup(1);
+
+      expect(
+        manager.can(inventoryIssuesRoutePath, PermissionAction.view),
+        isTrue,
+      );
+    });
  });
 }
+
+class _DummyMenuRepository implements MenuRepository {
+  @override
+  Future<MenuItem> create(MenuInput input) {
+    throw UnimplementedError();
+  }
+
+  @override
+  Future<void> delete(int id) {
+    throw UnimplementedError();
+  }
+
+  @override
+  Future<PaginatedResult<MenuItem>> list({
+    int page = 1,
+    int pageSize = 20,
+    String? query,
+    int? parentId,
+    bool? isActive,
+    bool includeDeleted = false,
+  }) async {
+    return PaginatedResult<MenuItem>(
+      items: const [],
+      page: page,
+      pageSize: pageSize,
+      total: 0,
+    );
+  }
+
+  @override
+  Future<MenuItem> restore(int id) {
+    throw UnimplementedError();
+  }
+
+  @override
+  Future<MenuItem> update(int id, MenuInput input) {
+    throw UnimplementedError();
+  }
+}
--- a/test/features/masters/group_permission/domain/group_permission_mapper_test.dart
+++ b/test/features/masters/group_permission/domain/group_permission_mapper_test.dart
@@ -1,5 +1,6 @@
 import 'package:flutter_test/flutter_test.dart';

+import 'package:superport_v2/core/navigation/route_paths.dart';
 import 'package:superport_v2/core/permissions/permission_manager.dart';
 import 'package:superport_v2/core/permissions/permission_resources.dart';
 import 'package:superport_v2/features/masters/group_permission/domain/entities/group_permission.dart';
@@ -13,9 +14,9 @@ void main() {
        group: GroupPermissionGroup(id: 1, groupName: '관리자'),
        menu: GroupPermissionMenu(
          id: 10,
-          menuCode: 'INBOUND',
+          menuCode: 'inventory.receipts',
          menuName: '입고',
-          path: '/inventory/inbound',
+          path: inventoryReceiptsRoutePath,
        ),
        canCreate: true,
        canRead: true,
@@ -27,9 +28,9 @@ void main() {
        group: GroupPermissionGroup(id: 1, groupName: '관리자'),
        menu: GroupPermissionMenu(
          id: 11,
-          menuCode: 'OUTBOUND',
+          menuCode: 'inventory.issues',
          menuName: '출고',
-          path: '/inventory/outbound',
+          path: inventoryIssuesRoutePath,
        ),
        canCreate: false,
        canRead: true,
--- 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
@@ -65,7 +65,7 @@ void main() {
        page: any(named: 'page'),
        pageSize: any(named: 'pageSize'),
        groupId: any(named: 'groupId'),
-        menuId: any(named: 'menuId'),
+        menuCode: any(named: 'menuCode'),
        isActive: any(named: 'isActive'),
        includeDeleted: any(named: 'includeDeleted'),
      ),
@@ -136,7 +136,7 @@ void main() {
          page: any(named: 'page'),
          pageSize: any(named: 'pageSize'),
          groupId: any(named: 'groupId'),
-          menuId: any(named: 'menuId'),
+          menuCode: any(named: 'menuCode'),
          isActive: any(named: 'isActive'),
          includeDeleted: any(named: 'includeDeleted'),
        ),
@@ -152,7 +152,7 @@ void main() {

    test('필터 값을 전달한다', () async {
      controller.updateGroupFilter(2);
-      controller.updateMenuFilter(5);
+      controller.updateMenuFilter('MENU005');
      controller.updateStatusFilter(GroupPermissionStatusFilter.inactiveOnly);
      controller.updateIncludeDeleted(true);

@@ -163,7 +163,7 @@ void main() {
          page: 3,
          pageSize: 20,
          groupId: 2,
-          menuId: 5,
+          menuCode: 'MENU005',
          isActive: false,
          includeDeleted: true,
        ),
@@ -176,7 +176,7 @@ void main() {
          page: any(named: 'page'),
          pageSize: any(named: 'pageSize'),
          groupId: any(named: 'groupId'),
-          menuId: any(named: 'menuId'),
+          menuCode: any(named: 'menuCode'),
          isActive: any(named: 'isActive'),
          includeDeleted: any(named: 'includeDeleted'),
        ),
@@ -190,12 +190,12 @@ void main() {

  test('필터 업데이트 메서드', () {
    controller.updateGroupFilter(3);
-    controller.updateMenuFilter(7);
+    controller.updateMenuFilter('MENU007');
    controller.updateStatusFilter(GroupPermissionStatusFilter.activeOnly);
    controller.updateIncludeDeleted(true);

    expect(controller.groupFilter, 3);
-    expect(controller.menuFilter, 7);
+    expect(controller.menuFilter, 'MENU007');
    expect(controller.statusFilter, GroupPermissionStatusFilter.activeOnly);
    expect(controller.includeDeleted, isTrue);
  });
@@ -207,14 +207,14 @@ void main() {
          page: any(named: 'page'),
          pageSize: any(named: 'pageSize'),
          groupId: any(named: 'groupId'),
-          menuId: any(named: 'menuId'),
+          menuCode: any(named: 'menuCode'),
          isActive: any(named: 'isActive'),
          includeDeleted: any(named: 'includeDeleted'),
        ),
      ).thenAnswer((_) async => createResult([samplePermission]));
    });

-    final input = GroupPermissionInput(groupId: 1, menuId: 2);
+    final input = GroupPermissionInput(groupId: 1, menuCode: 'MENU002');

    test('create 성공', () async {
      when(
@@ -265,7 +265,7 @@ void main() {
          page: any(named: 'page'),
          pageSize: any(named: 'pageSize'),
          groupId: any(named: 'groupId'),
-          menuId: any(named: 'menuId'),
+          menuCode: any(named: 'menuCode'),
          isActive: any(named: 'isActive'),
          includeDeleted: any(named: 'includeDeleted'),
        ),
@@ -282,7 +282,7 @@ void main() {
          page: any(named: 'page'),
          pageSize: any(named: 'pageSize'),
          groupId: any(named: 'groupId'),
-          menuId: any(named: 'menuId'),
+          menuCode: any(named: 'menuCode'),
          isActive: any(named: 'isActive'),
          includeDeleted: true,
        ),
--- a/test/features/masters/group_permission/presentation/pages/group_permission_page_test.dart
+++ b/test/features/masters/group_permission/presentation/pages/group_permission_page_test.dart
@@ -7,6 +7,7 @@ import 'package:shadcn_ui/shadcn_ui.dart';

 import '../../../../../helpers/tester_extensions.dart';
 import 'package:superport_v2/core/common/models/paginated_result.dart';
+import 'package:superport_v2/core/navigation/menu_catalog.dart';
 import 'package:superport_v2/core/permissions/permission_manager.dart';
 import 'package:superport_v2/features/masters/group/domain/entities/group.dart';
 import 'package:superport_v2/features/masters/group/domain/repositories/group_repository.dart';
@@ -26,15 +27,23 @@ class _MockMenuRepository extends Mock implements MenuRepository {}
 class _FakeGroupPermissionInput extends Fake implements GroupPermissionInput {}

 Widget _buildApp(Widget child) {
+  final menuRepository = GetIt.I.isRegistered<MenuRepository>()
+      ? GetIt.I<MenuRepository>()
+      : _MockMenuRepository();
+  final catalog = MenuCatalog(repository: menuRepository);
+  addTearDown(catalog.dispose);
  return PermissionScope(
    manager: PermissionManager(),
-    child: MaterialApp(
-      home: ShadTheme(
-        data: ShadThemeData(
-          colorScheme: const ShadSlateColorScheme.light(),
-          brightness: Brightness.light,
+    child: MenuCatalogScope(
+      catalog: catalog,
+      child: MaterialApp(
+        home: ShadTheme(
+          data: ShadThemeData(
+            colorScheme: const ShadSlateColorScheme.light(),
+            brightness: Brightness.light,
+          ),
+          child: Scaffold(body: child),
        ),
-        child: Scaffold(body: child),
      ),
    ),
  );
@@ -122,7 +131,7 @@ void main() {
          page: any(named: 'page'),
          pageSize: any(named: 'pageSize'),
          groupId: any(named: 'groupId'),
-          menuId: any(named: 'menuId'),
+          menuCode: any(named: 'menuCode'),
          isActive: any(named: 'isActive'),
          includeDeleted: any(named: 'includeDeleted'),
        ),
@@ -161,7 +170,7 @@ void main() {
          page: any(named: 'page'),
          pageSize: any(named: 'pageSize'),
          groupId: any(named: 'groupId'),
-          menuId: any(named: 'menuId'),
+          menuCode: any(named: 'menuCode'),
          isActive: any(named: 'isActive'),
          includeDeleted: any(named: 'includeDeleted'),
        ),
@@ -194,7 +203,7 @@ void main() {
          page: any(named: 'page'),
          pageSize: any(named: 'pageSize'),
          groupId: any(named: 'groupId'),
-          menuId: any(named: 'menuId'),
+          menuCode: any(named: 'menuCode'),
          isActive: any(named: 'isActive'),
          includeDeleted: any(named: 'includeDeleted'),
        ),
@@ -242,8 +251,8 @@ void main() {
            groupName: '관리자',
          ),
          menu: GroupPermissionMenu(
-            id: capturedInput!.menuId,
-            menuCode: 'DASHBOARD',
+            id: 10,
+            menuCode: capturedInput!.menuCode,
            menuName: '대시보드',
            path: '/dashboard',
          ),
@@ -292,7 +301,7 @@ void main() {

      expect(capturedInput, isNotNull);
      expect(capturedInput?.groupId, 1);
-      expect(capturedInput?.menuId, 10);
+      expect(capturedInput?.menuCode, 'MENU001');
      expect(capturedInput?.canCreate, isTrue);
      expect(capturedInput?.canUpdate, isTrue);
      expect(find.byType(Dialog), findsNothing);
--- a/test/features/masters/menu/presentation/pages/menu_page_test.dart
+++ b/test/features/masters/menu/presentation/pages/menu_page_test.dart
@@ -7,6 +7,7 @@ import 'package:shadcn_ui/shadcn_ui.dart';

 import '../../../../../helpers/tester_extensions.dart';
 import 'package:superport_v2/core/common/models/paginated_result.dart';
+import 'package:superport_v2/core/navigation/menu_catalog.dart';
 import 'package:superport_v2/features/masters/menu/domain/entities/menu.dart';
 import 'package:superport_v2/features/masters/menu/domain/repositories/menu_repository.dart';
 import 'package:superport_v2/features/masters/menu/presentation/pages/menu_page.dart';
@@ -16,13 +17,21 @@ class _MockMenuRepository extends Mock implements MenuRepository {}
 class _FakeMenuInput extends Fake implements MenuInput {}

 Widget _buildApp(Widget child) {
+  final menuRepository = GetIt.I.isRegistered<MenuRepository>()
+      ? GetIt.I<MenuRepository>()
+      : _MockMenuRepository();
+  final catalog = MenuCatalog(repository: menuRepository);
+  addTearDown(catalog.dispose);
  return MaterialApp(
-    home: ShadTheme(
-      data: ShadThemeData(
-        colorScheme: const ShadSlateColorScheme.light(),
-        brightness: Brightness.light,
+    home: MenuCatalogScope(
+      catalog: catalog,
+      child: ShadTheme(
+        data: ShadThemeData(
+          colorScheme: const ShadSlateColorScheme.light(),
+          brightness: Brightness.light,
+        ),
+        child: Scaffold(body: child),
      ),
-      child: Scaffold(body: child),
    ),
  );
 }
--- a/test/features/masters/product/presentation/pages/product_page_test.dart
+++ b/test/features/masters/product/presentation/pages/product_page_test.dart
@@ -7,6 +7,7 @@ import 'package:shadcn_ui/shadcn_ui.dart';

 import '../../../../../helpers/tester_extensions.dart';
 import 'package:superport_v2/core/common/models/paginated_result.dart';
+import 'package:superport_v2/core/navigation/route_paths.dart';
 import 'package:superport_v2/features/masters/product/domain/entities/product.dart';
 import 'package:superport_v2/features/masters/product/domain/repositories/product_repository.dart';
 import 'package:superport_v2/features/masters/product/presentation/pages/product_page.dart';
@@ -51,7 +52,7 @@ void main() {
    dotenv.testLoad(fileInput: 'FEATURE_PRODUCTS_ENABLED=false\n');

    await tester.pumpWidget(
-      _buildApp(ProductPage(routeUri: Uri(path: '/masters/products'))),
+      _buildApp(ProductPage(routeUri: Uri(path: inventoryProductsRoutePath))),
    );
    await tester.pump();

@@ -138,7 +139,7 @@ void main() {
      );

      await tester.pumpWidget(
-        _buildApp(ProductPage(routeUri: Uri(path: '/masters/products'))),
+        _buildApp(ProductPage(routeUri: Uri(path: inventoryProductsRoutePath))),
      );
      await tester.pumpAndSettle();

@@ -175,7 +176,7 @@ void main() {
      );

      await tester.pumpWidget(
-        _buildApp(ProductPage(routeUri: Uri(path: '/masters/products'))),
+        _buildApp(ProductPage(routeUri: Uri(path: inventoryProductsRoutePath))),
      );
      await tester.pumpAndSettle();

@@ -202,7 +203,7 @@ void main() {
      );

      await tester.pumpWidget(
-        _buildApp(ProductPage(routeUri: Uri(path: '/masters/products'))),
+        _buildApp(ProductPage(routeUri: Uri(path: inventoryProductsRoutePath))),
      );
      await tester.pumpAndSettle();

@@ -278,7 +279,7 @@ void main() {
      });

      await tester.pumpWidget(
-        _buildApp(ProductPage(routeUri: Uri(path: '/masters/products'))),
+        _buildApp(ProductPage(routeUri: Uri(path: inventoryProductsRoutePath))),
      );
      await tester.pumpAndSettle();

@@ -349,7 +350,7 @@ void main() {
          Center(
            child: SizedBox(
              width: 320,
-              child: ProductPage(routeUri: Uri(path: '/masters/products')),
+              child: ProductPage(routeUri: Uri(path: inventoryProductsRoutePath)),
            ),
          ),
        ),
--- a/test/features/masters/user/presentation/controllers/user_controller_test.dart
+++ b/test/features/masters/user/presentation/controllers/user_controller_test.dart
@@ -59,7 +59,7 @@ void main() {
        page: any(named: 'page'),
        pageSize: any(named: 'pageSize'),
        groupId: any(named: 'groupId'),
-        menuId: any(named: 'menuId'),
+        menuCode: any(named: 'menuCode'),
        isActive: any(named: 'isActive'),
        includeDeleted: any(named: 'includeDeleted'),
      ),
@@ -252,7 +252,7 @@ void main() {
          page: any(named: 'page'),
          pageSize: any(named: 'pageSize'),
          groupId: sampleUser.group!.id,
-          menuId: any(named: 'menuId'),
+          menuCode: any(named: 'menuCode'),
          isActive: any(named: 'isActive'),
          includeDeleted: any(named: 'includeDeleted'),
        ),
--- a/test/features/masters/user/presentation/pages/user_page_test.dart
+++ b/test/features/masters/user/presentation/pages/user_page_test.dart
@@ -7,6 +7,7 @@ import 'package:get_it/get_it.dart';
 import 'package:mocktail/mocktail.dart';
 import 'package:shadcn_ui/shadcn_ui.dart';

+import '../../../../../helpers/test_app.dart';
 import '../../../../../helpers/tester_extensions.dart';
 import 'package:superport_v2/core/common/models/paginated_result.dart';
 import 'package:superport_v2/core/permissions/permission_manager.dart';
@@ -28,20 +29,7 @@ class _MockGroupPermissionRepository extends Mock

 class _FakeUserInput extends Fake implements UserInput {}

-Widget _buildApp(Widget child) {
-  return PermissionScope(
-    manager: PermissionManager(),
-    child: MaterialApp(
-      home: ShadTheme(
-        data: ShadThemeData(
-          colorScheme: const ShadSlateColorScheme.light(),
-          brightness: Brightness.light,
-        ),
-        child: Scaffold(body: child),
-      ),
-    ),
-  );
-}
+Widget _buildApp(Widget child) => buildTestApp(child);

 void main() {
  TestWidgetsFlutterBinding.ensureInitialized();
@@ -59,7 +47,7 @@ void main() {
    dotenv.testLoad(fileInput: 'FEATURE_USERS_ENABLED=false\n');

    await tester.pumpWidget(_buildApp(const UserPage()));
-    await tester.pump();
+    await tester.pumpAndSettle();

    expect(find.text('사용자(사원) 관리'), findsOneWidget);
    expect(find.text('테이블 리스트'), findsOneWidget);
@@ -104,7 +92,7 @@ void main() {
          page: any(named: 'page'),
          pageSize: any(named: 'pageSize'),
          groupId: any(named: 'groupId'),
-          menuId: any(named: 'menuId'),
+          menuCode: any(named: 'menuCode'),
          isActive: any(named: 'isActive'),
          includeDeleted: any(named: 'includeDeleted'),
        ),
--- a/test/features/masters/vendor/presentation/pages/vendor_page_test.dart
+++ b/test/features/masters/vendor/presentation/pages/vendor_page_test.dart
@@ -7,6 +7,7 @@ import 'package:shadcn_ui/shadcn_ui.dart';

 import '../../../../../helpers/tester_extensions.dart';
 import 'package:superport_v2/core/common/models/paginated_result.dart';
+import 'package:superport_v2/core/navigation/route_paths.dart';
 import 'package:superport_v2/features/masters/vendor/domain/entities/vendor.dart';
 import 'package:superport_v2/features/masters/vendor/domain/repositories/vendor_repository.dart';
 import 'package:superport_v2/features/masters/vendor/presentation/pages/vendor_page.dart';
@@ -43,7 +44,7 @@ void main() {
    dotenv.testLoad(fileInput: 'FEATURE_VENDORS_ENABLED=false\n');

    await tester.pumpWidget(
-      _buildApp(VendorPage(routeUri: Uri(path: '/masters/vendors'))),
+      _buildApp(VendorPage(routeUri: Uri(path: inventoryVendorsRoutePath))),
    );
    await tester.pump();

@@ -75,7 +76,7 @@ void main() {
    );

    await tester.pumpWidget(
-      _buildApp(VendorPage(routeUri: Uri(path: '/masters/vendors'))),
+      _buildApp(VendorPage(routeUri: Uri(path: inventoryVendorsRoutePath))),
    );
    await tester.pumpAndSettle();

@@ -107,7 +108,7 @@ void main() {
    );

    await tester.pumpWidget(
-      _buildApp(VendorPage(routeUri: Uri(path: '/masters/vendors'))),
+      _buildApp(VendorPage(routeUri: Uri(path: inventoryVendorsRoutePath))),
    );
    await tester.pumpAndSettle();

@@ -136,7 +137,7 @@ void main() {
    );

    await tester.pumpWidget(
-      _buildApp(VendorPage(routeUri: Uri(path: '/masters/vendors'))),
+      _buildApp(VendorPage(routeUri: Uri(path: inventoryVendorsRoutePath))),
    );
    await tester.pumpAndSettle();

@@ -192,7 +193,7 @@ void main() {
    });

    await tester.pumpWidget(
-      _buildApp(VendorPage(routeUri: Uri(path: '/masters/vendors'))),
+      _buildApp(VendorPage(routeUri: Uri(path: inventoryVendorsRoutePath))),
    );
    await tester.pumpAndSettle();

@@ -244,7 +245,7 @@ void main() {
        Center(
          child: SizedBox(
            width: 320,
-            child: VendorPage(routeUri: Uri(path: '/masters/vendors')),
+            child: VendorPage(routeUri: Uri(path: inventoryVendorsRoutePath)),
          ),
        ),
      ),
--- a/test/features/masters/warehouse/presentation/pages/warehouse_page_test.dart
+++ b/test/features/masters/warehouse/presentation/pages/warehouse_page_test.dart
@@ -7,6 +7,7 @@ import 'package:shadcn_ui/shadcn_ui.dart';

 import '../../../../../helpers/tester_extensions.dart';
 import 'package:superport_v2/core/common/models/paginated_result.dart';
+import 'package:superport_v2/core/navigation/route_paths.dart';
 import 'package:superport_v2/features/masters/warehouse/domain/entities/warehouse.dart';
 import 'package:superport_v2/features/masters/warehouse/domain/repositories/warehouse_repository.dart';
 import 'package:superport_v2/features/masters/warehouse/presentation/pages/warehouse_page.dart';
@@ -48,7 +49,7 @@ void main() {
    dotenv.testLoad(fileInput: 'FEATURE_WAREHOUSES_ENABLED=false\n');

    await tester.pumpWidget(
-      _buildApp(WarehousePage(routeUri: Uri(path: '/masters/warehouses'))),
+      _buildApp(WarehousePage(routeUri: Uri(path: inventoryWarehousesRoutePath))),
    );
    await tester.pump();

@@ -112,7 +113,7 @@ void main() {
      );

      await tester.pumpWidget(
-        _buildApp(WarehousePage(routeUri: Uri(path: '/masters/warehouses'))),
+        _buildApp(WarehousePage(routeUri: Uri(path: inventoryWarehousesRoutePath))),
      );
      await tester.pumpAndSettle();

@@ -147,7 +148,7 @@ void main() {
      );

      await tester.pumpWidget(
-        _buildApp(WarehousePage(routeUri: Uri(path: '/masters/warehouses'))),
+        _buildApp(WarehousePage(routeUri: Uri(path: inventoryWarehousesRoutePath))),
      );
      await tester.pumpAndSettle();

@@ -205,7 +206,7 @@ void main() {
      });

      await tester.pumpWidget(
-        _buildApp(WarehousePage(routeUri: Uri(path: '/masters/warehouses'))),
+        _buildApp(WarehousePage(routeUri: Uri(path: inventoryWarehousesRoutePath))),
      );
      await tester.pumpAndSettle();

@@ -278,7 +279,7 @@ void main() {
          Center(
            child: SizedBox(
              width: 320,
-              child: WarehousePage(routeUri: Uri(path: '/masters/warehouses')),
+              child: WarehousePage(routeUri: Uri(path: inventoryWarehousesRoutePath)),
            ),
          ),
        ),
--- a/test/helpers/inventory_test_stubs.dart
+++ b/test/helpers/inventory_test_stubs.dart
@@ -11,6 +11,8 @@ import 'package:superport_v2/features/masters/product/domain/repositories/produc
 import 'package:superport_v2/features/masters/warehouse/domain/entities/warehouse.dart';
 import 'package:superport_v2/features/masters/warehouse/domain/repositories/warehouse_repository.dart';

+import 'test_permissions.dart';
+
 const int _inboundTypeId = 100;
 const int _outboundTypeId = 200;
 const int _rentalRentTypeId = 300;
@@ -42,6 +44,7 @@ InventoryTestStubConfig _stubConfig = const InventoryTestStubConfig();
 void registerInventoryTestStubs([
  InventoryTestStubConfig config = const InventoryTestStubConfig(),
 ]) {
+  grantTestPermissions();
  _stubConfig = config;
  lastTransactionListFilter = null;
  final lookup = _StubInventoryLookupRepository(
--- a/test/helpers/test_app.dart
+++ b/test/helpers/test_app.dart
@@ -1,17 +1,124 @@
 import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
 import 'package:shadcn_ui/shadcn_ui.dart';

+import 'package:superport_v2/core/common/models/paginated_result.dart';
+import 'package:superport_v2/core/navigation/menu_catalog.dart';
+import 'package:superport_v2/core/navigation/route_paths.dart';
 import 'package:superport_v2/core/permissions/permission_manager.dart';
 import 'package:superport_v2/core/theme/superport_shad_theme.dart';
+import 'package:superport_v2/features/masters/menu/domain/entities/menu.dart';
+import 'package:superport_v2/features/masters/menu/domain/repositories/menu_repository.dart';

 Widget buildTestApp(Widget child, {PermissionManager? permissionManager}) {
+  final catalog = createTestMenuCatalog();
  return PermissionScope(
    manager: permissionManager ?? PermissionManager(),
-    child: ShadApp(
-      debugShowCheckedModeBanner: false,
-      theme: SuperportShadTheme.light(),
-      darkTheme: SuperportShadTheme.dark(),
-      home: ScaffoldMessenger(child: Scaffold(body: child)),
+    child: MenuCatalogScope(
+      catalog: catalog,
+      child: ShadApp(
+        debugShowCheckedModeBanner: false,
+        theme: SuperportShadTheme.light(),
+        darkTheme: SuperportShadTheme.dark(),
+        home: ScaffoldMessenger(child: Scaffold(body: child)),
+      ),
    ),
  );
 }
+
+MenuCatalog createTestMenuCatalog({
+  List<MenuItem>? menus,
+  MenuRepository? repository,
+}) {
+  final catalog = MenuCatalog(
+    repository: repository ?? _TestMenuRepository(),
+  );
+  final seedMenus = menus ?? _defaultMenuItems;
+  catalog.replaceAll(List<MenuItem>.from(seedMenus));
+  addTearDown(catalog.dispose);
+  return catalog;
+}
+
+final List<MenuItem> _defaultMenuItems = List<MenuItem>.unmodifiable([
+  MenuItem(
+    id: 1,
+    menuCode: 'dashboard',
+    menuName: '대시보드',
+    path: dashboardRoutePath,
+    displayOrder: 10,
+  ),
+  MenuItem(
+    id: 2,
+    menuCode: 'inventory.summary',
+    menuName: '재고 현황',
+    path: inventorySummaryRoutePath,
+    displayOrder: 20,
+  ),
+  MenuItem(
+    id: 3,
+    menuCode: 'inventory.receipts',
+    menuName: '입고',
+    path: inventoryReceiptsRoutePath,
+    displayOrder: 21,
+  ),
+  MenuItem(
+    id: 4,
+    menuCode: 'inventory.issues',
+    menuName: '출고',
+    path: inventoryIssuesRoutePath,
+    displayOrder: 22,
+  ),
+  MenuItem(
+    id: 5,
+    menuCode: 'settings.users',
+    menuName: '사용자 관리',
+    path: settingsUsersRoutePath,
+    displayOrder: 40,
+  ),
+  MenuItem(
+    id: 6,
+    menuCode: 'settings.group_permissions',
+    menuName: '그룹 메뉴 권한',
+    path: settingsGroupPermissionsRoutePath,
+    displayOrder: 43,
+  ),
+]);
+
+class _TestMenuRepository implements MenuRepository {
+  @override
+  Future<MenuItem> create(MenuInput input) {
+    throw UnimplementedError();
+  }
+
+  @override
+  Future<void> delete(int id) {
+    throw UnimplementedError();
+  }
+
+  @override
+  Future<PaginatedResult<MenuItem>> list({
+    int page = 1,
+    int pageSize = 20,
+    String? query,
+    int? parentId,
+    bool? isActive,
+    bool includeDeleted = false,
+  }) async {
+    return PaginatedResult<MenuItem>(
+      items: const [],
+      page: 1,
+      pageSize: 0,
+      total: 0,
+    );
+  }
+
+  @override
+  Future<MenuItem> restore(int id) {
+    throw UnimplementedError();
+  }
+
+  @override
+  Future<MenuItem> update(int id, MenuInput input) {
+    throw UnimplementedError();
+  }
+}
--- a/test/helpers/test_permissions.dart
+++ b/test/helpers/test_permissions.dart
@@ -0,0 +1,29 @@
+import 'package:superport_v2/core/config/environment.dart';
+import 'package:superport_v2/core/permissions/permission_resources.dart';
+
+/// 통합 테스트에서 버튼/액션이 숨겨지지 않도록 기본 권한을 허용한다.
+void grantTestPermissions({bool includeWrites = true}) {
+  final commonActions = includeWrites ? {'all'} : {'view'};
+  Environment.setTestPermissions({
+    PermissionResources.dashboard: commonActions,
+    PermissionResources.stockTransactions: commonActions,
+    PermissionResources.approvals: commonActions,
+    PermissionResources.approvalSteps: commonActions,
+    PermissionResources.approvalHistories: commonActions,
+    PermissionResources.approvalTemplates: commonActions,
+    PermissionResources.inventorySummary: commonActions,
+    PermissionResources.groupMenuPermissions: commonActions,
+    PermissionResources.vendors: commonActions,
+    PermissionResources.products: commonActions,
+    PermissionResources.warehouses: commonActions,
+    PermissionResources.customers: commonActions,
+    PermissionResources.users: commonActions,
+    PermissionResources.groups: commonActions,
+    PermissionResources.menus: commonActions,
+    PermissionResources.postalSearch: commonActions,
+    PermissionResources.reports: commonActions,
+    PermissionResources.reportsTransactions: commonActions,
+    PermissionResources.reportsApprovals: commonActions,
+    PermissionResources.inventoryScope: {'view'},
+  });
+}
--- a/test/navigation/navigation_flow_test.dart
+++ b/test/navigation/navigation_flow_test.dart
@@ -6,7 +6,8 @@ import 'package:mocktail/mocktail.dart';
 import 'package:shadcn_ui/shadcn_ui.dart';
 import 'package:superport_v2/core/common/models/paginated_result.dart';
 import 'package:superport_v2/core/config/environment.dart';
-import 'package:superport_v2/core/constants/app_sections.dart';
+import 'package:superport_v2/core/navigation/menu_catalog.dart';
+import 'package:superport_v2/core/navigation/route_paths.dart';
 import 'package:superport_v2/core/permissions/permission_manager.dart';
 import 'package:superport_v2/core/theme/superport_shad_theme.dart';
 import 'package:superport_v2/core/services/token_storage.dart';
@@ -21,6 +22,8 @@ import 'package:superport_v2/features/masters/group/domain/repositories/group_re
 import 'package:superport_v2/features/masters/group_permission/domain/entities/group_permission.dart';
 import 'package:superport_v2/features/masters/group_permission/domain/repositories/group_permission_repository.dart';

+import '../helpers/test_app.dart';
+
 GoRouter _createTestRouter() {
  return GoRouter(
    initialLocation: loginRoutePath,
@@ -34,15 +37,15 @@ GoRouter _createTestRouter() {
        builder: (context, state) => const _TestDashboardPage(),
      ),
      GoRoute(
-        path: '/inventory/inbound',
+        path: inventoryReceiptsRoutePath,
        builder: (context, state) => const _PlaceholderPage(title: '입고 화면'),
      ),
      GoRoute(
-        path: '/inventory/outbound',
+        path: inventoryIssuesRoutePath,
        builder: (context, state) => const _PlaceholderPage(title: '출고 화면'),
      ),
      GoRoute(
-        path: '/inventory/rental',
+        path: inventoryRentalsRoutePath,
        builder: (context, state) => const _PlaceholderPage(title: '대여 화면'),
      ),
    ],
@@ -50,19 +53,23 @@ GoRouter _createTestRouter() {
 }

 class _TestApp extends StatelessWidget {
-  const _TestApp({required this.router});
+  const _TestApp({required this.router, required this.catalog});

  final GoRouter router;
+  final MenuCatalog catalog;

  @override
  Widget build(BuildContext context) {
    return PermissionScope(
      manager: PermissionManager(),
-      child: ShadApp.router(
-        routerConfig: router,
-        debugShowCheckedModeBanner: false,
-        theme: SuperportShadTheme.light(),
-        darkTheme: SuperportShadTheme.dark(),
+      child: MenuCatalogScope(
+        catalog: catalog,
+        child: ShadApp.router(
+          routerConfig: router,
+          debugShowCheckedModeBanner: false,
+          theme: SuperportShadTheme.light(),
+          darkTheme: SuperportShadTheme.dark(),
+        ),
      ),
    );
  }
@@ -90,15 +97,15 @@ class _TestDashboardPage extends StatelessWidget {
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            TextButton(
-              onPressed: () => context.go('/inventory/inbound'),
+              onPressed: () => context.go(inventoryReceiptsRoutePath),
              child: const Text('입고로 이동'),
            ),
            TextButton(
-              onPressed: () => context.go('/inventory/outbound'),
+              onPressed: () => context.go(inventoryIssuesRoutePath),
              child: const Text('출고로 이동'),
            ),
            TextButton(
-              onPressed: () => context.go('/inventory/rental'),
+              onPressed: () => context.go(inventoryRentalsRoutePath),
              child: const Text('대여로 이동'),
            ),
          ],
@@ -191,7 +198,7 @@ class _StubGroupPermissionRepository implements GroupPermissionRepository {
    int page = 1,
    int pageSize = 20,
    int? groupId,
-    int? menuId,
+    String? menuCode,
    bool? isActive,
    bool includeDeleted = false,
  }) async {
@@ -320,7 +327,8 @@ void main() {
    );

    final router = _createTestRouter();
-    await tester.pumpWidget(_TestApp(router: router));
+    final catalog = createTestMenuCatalog();
+    await tester.pumpWidget(_TestApp(router: router, catalog: catalog));
    await tester.pumpAndSettle();

    expect(find.text('Superport v2 로그인'), findsOneWidget);
--- a/test/widgets/app_shell_test.dart
+++ b/test/widgets/app_shell_test.dart
@@ -6,7 +6,8 @@ import 'package:lucide_icons_flutter/lucide_icons.dart' as lucide;
 import 'package:shadcn_ui/shadcn_ui.dart';

 import 'package:superport_v2/core/common/models/paginated_result.dart';
-import 'package:superport_v2/core/constants/app_sections.dart';
+import 'package:superport_v2/core/navigation/menu_catalog.dart';
+import 'package:superport_v2/core/navigation/route_paths.dart';
 import 'package:superport_v2/core/permissions/permission_manager.dart';
 import 'package:superport_v2/core/theme/superport_shad_theme.dart';
 import 'package:superport_v2/core/theme/theme_controller.dart';
@@ -17,6 +18,8 @@ import 'package:superport_v2/features/auth/domain/entities/auth_session.dart';
 import 'package:superport_v2/features/auth/domain/entities/authenticated_user.dart';
 import 'package:superport_v2/features/auth/domain/entities/login_request.dart';
 import 'package:superport_v2/features/auth/domain/repositories/auth_repository.dart';
+import 'package:superport_v2/features/masters/menu/domain/entities/menu.dart';
+import 'package:superport_v2/features/masters/menu/domain/repositories/menu_repository.dart';
 import 'package:superport_v2/features/masters/user/domain/entities/user.dart';
 import 'package:superport_v2/features/masters/user/domain/repositories/user_repository.dart';
 import 'package:superport_v2/widgets/app_shell.dart';
@@ -209,6 +212,15 @@ void main() {
 Future<void> _pumpAppShell(WidgetTester tester) async {
  final themeController = ThemeController();
  final permissionManager = PermissionManager();
+  if (!GetIt.I.isRegistered<MenuRepository>()) {
+    GetIt.I.registerSingleton<MenuRepository>(_StubMenuRepository());
+  }
+  final menuCatalog = MenuCatalog(repository: GetIt.I<MenuRepository>());
+  await menuCatalog.refresh();
+  if (GetIt.I.isRegistered<MenuCatalog>()) {
+    GetIt.I.unregister<MenuCatalog>();
+  }
+  GetIt.I.registerSingleton<MenuCatalog>(menuCatalog);
  final router = GoRouter(
    initialLocation: dashboardRoutePath,
    routes: [
@@ -231,18 +243,22 @@ Future<void> _pumpAppShell(WidgetTester tester) async {

  addTearDown(themeController.dispose);
  addTearDown(permissionManager.dispose);
+  addTearDown(menuCatalog.dispose);
  addTearDown(router.dispose);

  await tester.pumpWidget(
    PermissionScope(
      manager: permissionManager,
-      child: ThemeControllerScope(
-        controller: themeController,
-        child: ShadApp.router(
-          routerConfig: router,
-          theme: SuperportShadTheme.light(),
-          darkTheme: SuperportShadTheme.dark(),
-          debugShowCheckedModeBanner: false,
+      child: MenuCatalogScope(
+        catalog: menuCatalog,
+        child: ThemeControllerScope(
+          controller: themeController,
+          child: ShadApp.router(
+            routerConfig: router,
+            theme: SuperportShadTheme.light(),
+            darkTheme: SuperportShadTheme.dark(),
+            debugShowCheckedModeBanner: false,
+          ),
        ),
      ),
    ),
@@ -289,6 +305,66 @@ class _FakeAuthRepository implements AuthRepository {
  Future<AuthSession> refresh(String refreshToken) async => session;
 }

+class _StubMenuRepository implements MenuRepository {
+  @override
+  Future<MenuItem> create(MenuInput input) {
+    throw UnimplementedError();
+  }
+
+  @override
+  Future<void> delete(int id) {
+    throw UnimplementedError();
+  }
+
+  @override
+  Future<PaginatedResult<MenuItem>> list({
+    int page = 1,
+    int pageSize = 20,
+    String? query,
+    int? parentId,
+    bool? isActive,
+    bool includeDeleted = false,
+  }) async {
+    return PaginatedResult<MenuItem>(
+      items: [
+        MenuItem(
+          id: 1,
+          menuCode: 'dashboard',
+          menuName: '대시보드',
+          path: dashboardRoutePath,
+          displayOrder: 10,
+        ),
+        MenuItem(
+          id: 2,
+          menuCode: 'inventory.receipts',
+          menuName: '입고',
+          path: inventoryReceiptsRoutePath,
+          displayOrder: 20,
+          parent: MenuSummary(
+            id: 10,
+            menuName: '재고',
+            menuCode: 'inventory',
+            path: inventorySummaryRoutePath,
+          ),
+        ),
+      ],
+      page: 1,
+      pageSize: 2,
+      total: 2,
+    );
+  }
+
+  @override
+  Future<MenuItem> restore(int id) {
+    throw UnimplementedError();
+  }
+
+  @override
+  Future<MenuItem> update(int id, MenuInput input) {
+    throw UnimplementedError();
+  }
+}
+
 class _MemoryTokenStorage implements TokenStorage {
  String? _access;
  String? _refresh;