docs:메뉴 뱃지 기능 가이드 추가

- 사이드바 메뉴 뱃지 구현 방법 - ViewServiceProvider에서 View::share 사용 필수 - 새로운 뱃지 추가 방법 안내 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-31 16:52:05 +09:00
parent ec74d63120
commit 3b68847bb6
1 changed files with 170 additions and 0 deletions
--- a/guides/메뉴뱃지기능.md
+++ b/guides/메뉴뱃지기능.md
@@ -0,0 +1,170 @@
+# 사이드바 메뉴 뱃지 기능
+
+> 메뉴 옆에 알림 건수를 표시하는 뱃지 기능 가이드
+
+---
+
+## 개요
+
+사이드바 메뉴에 대기 건수, 알림 등을 빨간색 뱃지로 표시하는 기능입니다.
+
+**예시:**
+```
+영업파트너 승인 (3)   ← 빨간 원형 뱃지로 "3" 표시
+```
+
+---
+
+## 구현 위치
+
+| 파일 | 역할 |
+|------|------|
+| `app/Providers/ViewServiceProvider.php` | 뱃지 데이터 조회 및 전역 공유 |
+| `resources/views/components/sidebar/menu-item.blade.php` | 뱃지 렌더링 |
+
+---
+
+## 작동 원리
+
+### 1. ViewServiceProvider에서 뱃지 데이터 생성
+
+```php
+View::composer('partials.sidebar', function ($view) {
+    $menuBadges = [
+        'byRoute' => [],  // 라우트명 기준
+        'byUrl' => [],    // URL 기준
+    ];
+
+    // 예: 영업파트너 승인 대기 건수
+    if ($approvalStats['pending'] > 0) {
+        $menuBadges['byRoute']['sales.managers.approvals'] = $approvalStats['pending'];
+        $menuBadges['byUrl']['/sales/managers/approvals'] = $approvalStats['pending'];
+    }
+
+    // View::share로 전역 공유 (중요!)
+    View::share('menuBadges', $menuBadges);
+});
+```
+
+### 2. menu-item.blade.php에서 뱃지 표시
+
+```php
+// 라우트명 또는 URL로 뱃지 건수 조회
+$badgeCount = 0;
+if (isset($menuBadges)) {
+    if ($routeName && isset($menuBadges['byRoute'][$routeName])) {
+        $badgeCount = $menuBadges['byRoute'][$routeName];
+    }
+    elseif ($menu->url && isset($menuBadges['byUrl'][$menu->url])) {
+        $badgeCount = $menuBadges['byUrl'][$menu->url];
+    }
+}
+```
+
+```html
+@if($badgeCount > 0)
+    <span class="sidebar-text inline-flex items-center justify-center
+                 min-w-[1.25rem] h-5 px-1.5 text-xs font-bold
+                 text-white bg-red-500 rounded-full">
+        {{ $badgeCount > 99 ? '99+' : $badgeCount }}
+    </span>
+@endif
+```
+
+---
+
+## 새로운 뱃지 추가 방법
+
+### Step 1: ViewServiceProvider 수정
+
+`app/Providers/ViewServiceProvider.php`에서 뱃지 데이터 추가:
+
+```php
+// 예: 새로운 승인 대기 건수 추가
+$pendingCount = SomeService::getPendingCount();
+if ($pendingCount > 0) {
+    // 라우트명으로 등록 (메뉴에 route_name 설정된 경우)
+    $menuBadges['byRoute']['some.route.name'] = $pendingCount;
+
+    // URL로 등록 (메뉴가 URL로만 설정된 경우)
+    $menuBadges['byUrl']['/some/menu/url'] = $pendingCount;
+}
+```
+
+### Step 2: 메뉴 URL 또는 라우트명 확인
+
+메뉴 DB에서 해당 메뉴의 `url` 또는 `options->route_name`을 확인합니다.
+
+```sql
+SELECT name, url, options FROM menus WHERE name LIKE '%메뉴명%';
+```
+
+---
+
+## 주의사항
+
+### View::share 필수
+
+**중요:** `View::composer`로 전달한 변수는 **Blade 컴포넌트 내부에서 접근 불가**합니다.
+
+```php
+// ❌ 잘못된 방법 - 컴포넌트에서 접근 불가
+$view->with('menuBadges', $menuBadges);
+
+// ✅ 올바른 방법 - 전역 공유
+View::share('menuBadges', $menuBadges);
+```
+
+### 성능 고려
+
+- 뱃지 데이터 조회는 **매 요청마다** 실행됩니다
+- 무거운 쿼리는 캐싱 고려 필요
+- 현재는 간단한 COUNT 쿼리만 사용
+
+---
+
+## 현재 적용된 뱃지
+
+| 메뉴 | URL | 조건 |
+|------|-----|------|
+| 영업파트너 승인 | `/sales/managers/approvals` | 승인 대기 건수 > 0 |
+
+---
+
+## 스타일 커스터마이징
+
+### 색상 변경
+
+```html
+<!-- 빨간색 (기본) -->
+<span class="bg-red-500 text-white">
+
+<!-- 파란색 -->
+<span class="bg-blue-500 text-white">
+
+<!-- 노란색 -->
+<span class="bg-yellow-500 text-gray-900">
+```
+
+### 크기 변경
+
+```html
+<!-- 작은 뱃지 -->
+<span class="min-w-[1rem] h-4 text-[10px]">
+
+<!-- 큰 뱃지 -->
+<span class="min-w-[1.5rem] h-6 text-sm">
+```
+
+---
+
+## 관련 파일
+
+- `app/Providers/ViewServiceProvider.php` - 뱃지 데이터 공급
+- `app/Services/Sales/SalesManagerService.php` - 승인 통계 조회 (`getApprovalStats()`)
+- `resources/views/components/sidebar/menu-item.blade.php` - 뱃지 렌더링
+- `resources/views/partials/sidebar.blade.php` - 사이드바 레이아웃
+
+---
+
+*작성일: 2026-01-31*