docs: 5130→MNG 마이그레이션 추적 문서 추가

- MIGRATION_TRACKER.md: Phase별 작업 추적 (Phase 1 완료) - mng-menu-system-plan.md: MNG 메뉴 시스템 계획
2025-12-16 10:45:49 +09:00
parent 72a322eb0f
commit 5e6508c3ea
2 changed files with 652 additions and 0 deletions
--- a/plans/mng-menu-system-plan.md
+++ b/plans/mng-menu-system-plan.md
@@ -0,0 +1,485 @@
+# MNG 메뉴 시스템: DB 기반 동적 메뉴 전환 계획
+
+> 작성일: 2025-12-16
+> 목적: mng 사이드바를 DB 기반으로 전환하여 직원별 권한에 따라 메뉴 동적 표시
+> 선택: **Option A - DB 메뉴 기반**
+
+---
+
+## 1. 현재 시스템 분석
+
+### 1.1 현재 구조 (AS-IS)
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    현재 mng 메뉴 시스템                          │
+├─────────────────────────────────────────────────────────────────┤
+│  sidebar.blade.php (하드코딩)                                   │
+│    ├── 일반 메뉴 (7개 그룹)                                      │
+│    ├── 개발도구 메뉴                                             │
+│    └── R&D Labs 메뉴                                            │
+├─────────────────────────────────────────────────────────────────┤
+│  권한 체크: hq.member 미들웨어만 (HQ 소속 확인)                   │
+│  메뉴별 권한 체크: 없음 (전체 접근)                               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 1.2 목표 구조 (TO-BE)
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    목표 mng 메뉴 시스템                          │
+├─────────────────────────────────────────────────────────────────┤
+│  DB (menus 테이블, tenant_id=1)                                 │
+│    ├── 일반 메뉴 (역할/부서/개인 권한으로 제어)                   │
+│    ├── 개발도구 메뉴 (슈퍼관리자 전용)                           │
+│    └── R&D Labs 메뉴 (슈퍼관리자 전용)                          │
+├─────────────────────────────────────────────────────────────────┤
+│  동적 사이드바 렌더링: SidebarMenuService → Blade Component      │
+│  권한 체크: 메뉴별 permission (menu:{id}.view)                   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 1.3 DB 테이블 구조
+
+**menus 테이블** (기존)
+```
+id, tenant_id, parent_id, global_menu_id
+name, url, icon, sort_order
+is_active, hidden, is_customized, is_external, external_url
+created_by, updated_by, deleted_by, created_at, updated_at, deleted_at
+```
+
+**permissions 테이블** (Spatie)
+```
+id, tenant_id, name, guard_name, created_at, updated_at
+```
+
+**권한 연결 테이블**
+- `role_has_permissions`: 역할-권한 매핑
+- `department_permissions`: 부서-권한 매핑 (is_allowed)
+- `user_permission_overrides`: 개인-권한 오버라이드 (is_allowed)
+
+---
+
+## 2. 권한 체계 설계
+
+### 2.1 권한 우선순위
+
+```
+개인 DENY > 개인 ALLOW > 부서 DENY > 부서 ALLOW > 역할 권한 > 기본 거부
+```
+
+### 2.2 메뉴 권한 명명 규칙
+
+```
+menu:{menu_id}.view       # 메뉴 조회 (사이드바 표시)
+menu:{menu_id}.create     # 생성 권한
+menu:{menu_id}.update     # 수정 권한
+menu:{menu_id}.delete     # 삭제 권한
+```
+
+### 2.3 특수 메뉴 처리
+
+| 메뉴 유형 | 권한 처리 |
+|-----------|----------|
+| 일반 메뉴 | 역할/부서/개인 권한으로 제어 |
+| 개발도구 | `is_super_admin` 체크 또는 특별 권한 |
+| R&D Labs | `is_super_admin` 체크 또는 특별 권한 |
+
+---
+
+## 3. 개발 계획
+
+### Phase 1: DB 스키마 및 시딩 (1-2일)
+
+#### 3.1.1 mng 메뉴용 컬럼 추가 (선택적)
+
+```php
+// 마이그레이션: add_mng_flag_to_menus_table
+Schema::table('menus', function (Blueprint $table) {
+    $table->string('menu_type', 20)->default('normal')
+          ->comment('메뉴 유형: normal, dev_tool, lab')
+          ->after('external_url');
+    $table->string('route_name', 100)->nullable()
+          ->comment('Laravel 라우트 이름')
+          ->after('menu_type');
+});
+```
+
+#### 3.1.2 mng 메뉴 시더 생성
+
+```php
+// database/seeders/MngMenuSeeder.php
+class MngMenuSeeder extends Seeder
+{
+    public function run(): void
+    {
+        $tenantId = 1; // HQ 테넌트
+
+        $menus = [
+            // 일반 메뉴
+            ['name' => '대시보드', 'url' => '/dashboard', 'icon' => 'home', 'route_name' => 'dashboard', 'menu_type' => 'normal'],
+
+            // 그룹: 프로젝트 관리
+            ['name' => '프로젝트 관리', 'url' => null, 'icon' => 'folder', 'menu_type' => 'normal', 'children' => [
+                ['name' => '프로젝트 대시보드', 'url' => '/project-management', 'route_name' => 'pm.index'],
+                ['name' => '프로젝트', 'url' => '/project-management/projects', 'route_name' => 'pm.projects.index'],
+                ['name' => '일일 스크럼', 'url' => '/daily-logs', 'route_name' => 'daily-logs.index'],
+            ]],
+
+            // ... 기타 메뉴 그룹
+
+            // 개발도구 (슈퍼관리자 전용)
+            ['name' => '개발 도구', 'url' => null, 'icon' => 'cog', 'menu_type' => 'dev_tool', 'children' => [
+                ['name' => 'API 플로우 테스터', 'url' => '/dev-tools/flow-tester', 'route_name' => 'dev-tools.flow-tester.index'],
+                ['name' => 'API 요청 로그', 'url' => '/dev-tools/api-logs', 'route_name' => 'dev-tools.api-logs.index'],
+            ]],
+
+            // R&D Labs (슈퍼관리자 전용)
+            ['name' => 'R&D Labs', 'url' => null, 'icon' => 'beaker', 'menu_type' => 'lab', 'children' => [
+                // S, A, M 탭 구조
+            ]],
+        ];
+
+        $this->seedMenus($tenantId, $menus);
+    }
+}
+```
+
+### Phase 2: 사용자별 메뉴 조회 서비스 (2-3일)
+
+#### 3.2.1 SidebarMenuService 생성
+
+```php
+// app/Services/SidebarMenuService.php
+class SidebarMenuService
+{
+    /**
+     * 현재 사용자가 접근 가능한 메뉴 트리 조회
+     */
+    public function getUserMenuTree(?User $user = null): Collection
+    {
+        $user = $user ?? auth()->user();
+        $tenantId = session('selected_tenant_id', 1);
+
+        // 1. 테넌트의 모든 활성 메뉴 조회
+        $allMenus = Menu::where('tenant_id', $tenantId)
+            ->where('is_active', true)
+            ->where('hidden', false)
+            ->orderBy('sort_order')
+            ->get();
+
+        // 2. 슈퍼관리자는 모든 메뉴 표시
+        if ($user->is_super_admin) {
+            return $this->buildMenuTree($allMenus);
+        }
+
+        // 3. 일반 사용자: 권한 기반 필터링
+        $permittedMenuIds = $this->getPermittedMenuIds($user, $tenantId);
+
+        // 4. 개발도구/Labs 제외 (일반 사용자)
+        $filteredMenus = $allMenus->filter(function ($menu) use ($permittedMenuIds) {
+            // 개발도구/Labs는 일반 사용자에게 표시 안함
+            if (in_array($menu->menu_type, ['dev_tool', 'lab'])) {
+                return false;
+            }
+            return in_array($menu->id, $permittedMenuIds);
+        });
+
+        return $this->buildMenuTree($filteredMenus);
+    }
+
+    /**
+     * 사용자가 접근 가능한 메뉴 ID 목록 조회
+     * 우선순위: 개인 DENY > 개인 ALLOW > 부서 DENY > 부서 ALLOW > 역할
+     */
+    private function getPermittedMenuIds(User $user, int $tenantId): array
+    {
+        // 역할 기반 권한
+        $rolePermissions = $this->getRoleMenuPermissions($user, $tenantId);
+
+        // 부서 기반 권한 (ALLOW/DENY)
+        $deptPermissions = $this->getDepartmentMenuPermissions($user, $tenantId);
+
+        // 개인 오버라이드 (ALLOW/DENY)
+        $userOverrides = $this->getUserMenuOverrides($user, $tenantId);
+
+        // 권한 병합 (우선순위 적용)
+        return $this->mergePermissions($rolePermissions, $deptPermissions, $userOverrides);
+    }
+
+    private function buildMenuTree(Collection $menus, ?int $parentId = null): Collection
+    {
+        return $menus->where('parent_id', $parentId)
+            ->map(function ($menu) use ($menus) {
+                $menu->children = $this->buildMenuTree($menus, $menu->id);
+                return $menu;
+            });
+    }
+}
+```
+
+### Phase 3: 동적 사이드바 컴포넌트 (2-3일)
+
+#### 3.3.1 Blade 컴포넌트 구조
+
+```
+resources/views/
+├── components/
+│   └── sidebar/
+│       ├── menu-tree.blade.php      # 메뉴 트리 전체
+│       ├── menu-group.blade.php     # 그룹 (접기/펼치기)
+│       ├── menu-item.blade.php      # 개별 메뉴 아이템
+│       └── menu-icon.blade.php      # 아이콘 렌더링
+└── partials/
+    └── sidebar-dynamic.blade.php    # 동적 사이드바 (기존 대체)
+```
+
+#### 3.3.2 메뉴 트리 컴포넌트
+
+```blade
+{{-- components/sidebar/menu-tree.blade.php --}}
+@props(['menus'])
+
+<ul class="space-y-1">
+    @foreach($menus as $menu)
+        @if($menu->children->isNotEmpty())
+            <x-sidebar.menu-group :menu="$menu" />
+        @else
+            <x-sidebar.menu-item :menu="$menu" />
+        @endif
+    @endforeach
+</ul>
+```
+
+#### 3.3.3 ViewServiceProvider에서 메뉴 공유
+
+```php
+// app/Providers/ViewServiceProvider.php
+class ViewServiceProvider extends ServiceProvider
+{
+    public function boot(): void
+    {
+        View::composer('partials.sidebar-dynamic', function ($view) {
+            $menuService = app(SidebarMenuService::class);
+            $view->with('sidebarMenus', $menuService->getUserMenuTree());
+        });
+    }
+}
+```
+
+### Phase 4: 라우트 권한 미들웨어 (1-2일)
+
+#### 3.4.1 메뉴 권한 체크 미들웨어
+
+```php
+// app/Http/Middleware/CheckMenuPermission.php
+class CheckMenuPermission
+{
+    public function handle(Request $request, Closure $next, ?string $permission = null)
+    {
+        $user = $request->user();
+
+        // 슈퍼관리자는 패스
+        if ($user->is_super_admin) {
+            return $next($request);
+        }
+
+        // 권한 체크
+        $routeName = $request->route()->getName();
+        $menu = Menu::where('route_name', $routeName)->first();
+
+        if (!$menu) {
+            return $next($request); // 메뉴 없으면 패스
+        }
+
+        $permissionName = $permission ?? "menu:{$menu->id}.view";
+
+        if (!$this->hasMenuPermission($user, $menu, $permissionName)) {
+            abort(403, '접근 권한이 없습니다.');
+        }
+
+        return $next($request);
+    }
+}
+```
+
+#### 3.4.2 라우트에 미들웨어 적용
+
+```php
+// routes/web.php
+Route::middleware(['auth', 'hq.member', 'menu.permission'])->group(function () {
+    // 기존 라우트들...
+});
+```
+
+---
+
+## 4. 마이그레이션 전략
+
+### 4.1 단계별 전환
+
+```
+Phase 1: 준비 (하드코딩 + DB 병행)
+├── DB에 mng 메뉴 시딩
+├── SidebarMenuService 개발
+└── 기존 sidebar.blade.php 유지
+
+Phase 2: 테스트 (환경변수로 전환)
+├── .env에 MNG_DYNAMIC_SIDEBAR=false
+├── 동적 사이드바 개발 완료
+└── 슈퍼관리자만 동적 사이드바 테스트
+
+Phase 3: 전환 (동적 사이드바 활성화)
+├── MNG_DYNAMIC_SIDEBAR=true
+├── 권한 시딩 및 역할 배정
+└── 기존 sidebar.blade.php 백업
+
+Phase 4: 안정화
+├── 하드코딩 사이드바 제거
+├── 권한 관리 UI 활성화
+└── 문서화 완료
+```
+
+### 4.2 롤백 계획
+
+```php
+// partials/sidebar.blade.php
+@if(config('app.mng_dynamic_sidebar', false))
+    @include('partials.sidebar-dynamic')
+@else
+    @include('partials.sidebar-static')  // 기존 하드코딩
+@endif
+```
+
+---
+
+## 5. 파일 변경 목록
+
+### 신규 생성
+
+| 파일 | 설명 |
+|------|------|
+| `database/migrations/xxxx_add_menu_type_to_menus.php` | menu_type, route_name 컬럼 추가 |
+| `database/seeders/MngMenuSeeder.php` | mng 메뉴 시더 |
+| `database/seeders/MngMenuPermissionSeeder.php` | mng 메뉴 권한 시더 |
+| `app/Services/SidebarMenuService.php` | 사용자별 메뉴 조회 |
+| `app/Http/Middleware/CheckMenuPermission.php` | 메뉴 권한 미들웨어 |
+| `app/Providers/ViewServiceProvider.php` | 뷰 컴포저 |
+| `resources/views/partials/sidebar-dynamic.blade.php` | 동적 사이드바 |
+| `resources/views/components/sidebar/*.blade.php` | 사이드바 컴포넌트들 |
+
+### 수정
+
+| 파일 | 변경 내용 |
+|------|----------|
+| `app/Http/Kernel.php` | CheckMenuPermission 미들웨어 등록 |
+| `config/app.php` | mng_dynamic_sidebar 설정 추가 |
+| `routes/web.php` | 미들웨어 적용 |
+| `resources/views/partials/sidebar.blade.php` | 조건부 렌더링 |
+
+---
+
+## 6. 예상 일정
+
+| Phase | 작업 | 예상 기간 |
+|-------|------|----------|
+| Phase 1 | DB 스키마 및 시딩 | 1-2일 |
+| Phase 2 | SidebarMenuService | 2-3일 |
+| Phase 3 | 동적 사이드바 컴포넌트 | 2-3일 |
+| Phase 4 | 권한 미들웨어 | 1-2일 |
+| 테스트 | 통합 테스트 및 버그 수정 | 2-3일 |
+| **총합** | | **8-13일** |
+
+---
+
+## 7. 체크리스트
+
+### 개발 전
+
+- [ ] 현재 mng 메뉴 목록 완전히 정리 (그룹/항목/라우트)
+- [ ] 권한 명명 규칙 확정
+- [ ] 개발도구/Labs 접근 정책 확정
+
+### Phase 1 완료 조건
+
+- [ ] 마이그레이션 실행 성공
+- [ ] mng 메뉴 시더 실행 성공
+- [ ] DB에 모든 mng 메뉴 존재 확인
+
+### Phase 2 완료 조건
+
+- [ ] SidebarMenuService 단위 테스트 통과
+- [ ] 슈퍼관리자 전체 메뉴 조회 확인
+- [ ] 일반 사용자 권한 기반 필터링 확인
+
+### Phase 3 완료 조건
+
+- [ ] 동적 사이드바 렌더링 정상
+- [ ] 메뉴 접기/펼치기 동작
+- [ ] 활성 메뉴 하이라이트 동작
+- [ ] 사이드바 collapse 상태 동작
+
+### Phase 4 완료 조건
+
+- [ ] 미들웨어 권한 체크 동작
+- [ ] 403 에러 페이지 표시
+- [ ] 권한 없는 메뉴 URL 직접 접근 차단
+
+### 전환 완료 조건
+
+- [ ] 모든 테스트 통과
+- [ ] 기존 기능 동일 동작 확인
+- [ ] 성능 영향 최소화 확인 (캐싱)
+- [ ] 롤백 가능 확인
+
+---
+
+## 8. 추가 고려사항
+
+### 8.1 캐싱 전략
+
+```php
+// 사용자별 메뉴 캐싱 (권한 변경 시 무효화)
+Cache::remember("user:{$userId}:menus", 3600, function () use ($userId) {
+    return $this->getUserMenuTree(User::find($userId));
+});
+```
+
+### 8.2 권한 변경 시 캐시 무효화
+
+```php
+// 역할 권한 변경 시
+Cache::tags(['menus'])->flush();
+
+// 개인 권한 변경 시
+Cache::forget("user:{$userId}:menus");
+```
+
+### 8.3 감사 로그
+
+```php
+// 메뉴 접근 로그 (선택적)
+AuditLog::create([
+    'action' => 'menu_access',
+    'target_type' => 'menu',
+    'target_id' => $menu->id,
+    'actor_id' => auth()->id(),
+]);
+```
+
+---
+
+## 9. 다음 단계
+
+이 계획을 승인하시면 다음 순서로 진행합니다:
+
+1. **현재 mng 메뉴 전체 목록 정리** (그룹/항목/라우트/아이콘)
+2. **마이그레이션 및 시더 작성**
+3. **SidebarMenuService 개발**
+4. **동적 사이드바 컴포넌트 개발**
+5. **권한 미들웨어 적용**
+6. **테스트 및 전환**
+
+진행하시겠습니까?