# 프런트엔드 메뉴 권한 정합성 작업 리스트

백엔드가 menus/group_menu_permissions 구조를 정리하는 동안 프런트엔드에서 병행해야 하는 상세 작업을 아래와 같이 정리한다. 모든 작업은 `AGENTS.md` 가이드(주석 한국어, Clean Architecture, 테스트 필수)에 따라 진행하며, 완료 후 `flutter analyze`, `flutter test`를 실행한다.

## 1. 권한 리소스/폴백 정비

1. **`PermissionResources` 별칭 테이블 보강**
   - 파일: `lib/core/permissions/permission_resources.dart`
   - 액션: `/inventory/receipts|issues|rentals`, `/inventory/vendors|products|warehouses|customers`, `/settings/*` 등 백엔드 `menus.route_path` 전부를 `_aliases`에 1:1 매핑.
   - 기대효과: 서버가 내려주는 menu_code/route_path와 사이드바 권한 체크가 정확히 연결.

2. **`PermissionManager` 기본 정책 수정**
   - 파일: `lib/core/permissions/permission_manager.dart`, `.env.development`, `.env.example`
   - 액션:
     - 서버/오버라이드 권한이 없으면 `Environment.hasPermission` 결과를 사용하기 전에 기본 거부하도록 방어 로직 추가.
     - 개발용 `.env`에 필요한 최소 권한만 `PERMISSION__/path=view` 형태로 명시해 무제한 허용을 차단.
   - 기대효과: 권한 정보 미수신 시 UI가 안전하게 차단되고, 테스트/QA에서 화이트리스트가 그대로 재현.

## 2. 메뉴 데이터 소스 일원화

3. **메뉴 라우트/사이드바 리팩터링**
   - 파일: `lib/widgets/app_shell.dart`, `lib/core/routing/app_router.dart`, `lib/core/navigation/menu_route_definitions.dart`, 신규 헬퍼 모듈.
   - 액션:
     - `appSections` 상수를 폐지하고, `GET /menus` 결과(menu_code, parent_code, display_order, route_path)를 캐시해 사이드바를 구성.
     - `menu_code → 위젯 builder` 매핑 테이블을 별도 파일로 만들고 GoRouter 정의에서 사용.
     - 사이드바, 권한 드롭다운, 라우터가 모두 동일 menu_code/route_path를 참조하도록 구조화.
   - 기대효과: menus 테이블 변경이 자동으로 UI에 반영되고 경로 불일치 문제 제거.

4. **MenuCatalog(캐시) 도입 및 의존성 주입**
   - 파일: `lib/main.dart`, `lib/core/navigation/menu_catalog.dart`(신규), `lib/features/masters/menu/*`
   - 액션:
     - 앱 시작 시 메뉴 목록을 한 번만 불러 캐시하는 Catalog를 만들고 `PermissionScope` 옆에서 주입.
     - 메뉴 관리 화면/권한 드롭다운이 Catalog 데이터를 재사용하도록 controller 로직 정리.

## 3. 그룹 권한 UI 연동

5. **메뉴 선택 로직을 menu_code 기반으로 변경**
   - 파일: `lib/features/masters/group_permission/presentation/...`
   - 액션:
     - 컨트롤러와 다이얼로그가 `menu_id` 대신 `menu_code`를 사용해 CRUD 요청을 보냄.
     - 메뉴 드롭다운 옵션을 Catalog(or `/menus`)에서 가져와 라벨/정렬 통일.

6. **권한 동기화 시 menu_code 매칭 검증**
   - 파일: `lib/features/masters/group_permission/application/permission_synchronizer.dart`
   - 액션: `MenuRouteDefinition` 또는 Catalog를 참조해 `PermissionManager`에 적용되는 리소스 키가 서버 route_path와 일치하는지 확인하는 테스트 추가.

## 4. 테스트 & CI

7. **사이드바 권한 테스트 보강**
   - 파일: `test/widgets/app_shell_test.dart`, `test/navigation/navigation_flow_test.dart`
   - 액션:
     - 서버에서 받은 `menu_code`/`route_path`에 따라 노출되는 메뉴가 달라지는 위젯 테스트 작성.
     - 개발 env 권한 없이도 테스트가 실패하지 않도록 PermissionManager 오버라이드 유틸 추가.

8. **CI 스크립트 추가**
   - 파일: `tool/check_menu_manifest.dart`(신규), `ci/scripts/*`
   - 액션: menus 테이블 표(`doc/stock_approval_system_spec_v4.md`), 라우트 정의, 앱 메뉴 캐시 간 코드/경로 일관성을 검사하는 Dart 스크립트를 추가하고 CI 단계에서 실행.

## 5. 문서/QA

9. **문서 업데이트**
   - 파일: `doc/frontend_backend_alignment_report.md`, 신규 QA 체크리스트.
   - 액션: “사이드바=menus 테이블 1:1” 규칙, 권한 폴백 정책, 테스트 플로우를 문서화.

10. **QA 시나리오**
    - 항목: 화이트리스트 그룹별 계정으로 로그인 → 사이드바 캡처 → 권한 드롭다운 메뉴 제한 확인 → 메뉴 관리에서 route_path 일치 여부 확인.
    - 산출물: `doc/qa/menu_permission_alignment_checklist.md` 등으로 공유.

각 작업은 백로그 티켓으로 분할해 순차 진행하며, 메뉴 API 변경 시점과 맞춰 릴리즈 플래그로 토글할 수 있도록 구성한다.