# task-1363.1: InsuRo 네비게이션 하이브리드 전환 구현

**작성자**: 오딘 (개발2팀장)
**작성일**: 2026-04-03
**작업 유형**: 프론트엔드 구현 (Lv.2)

---

## SCQA

**S**: InsuRo 좌측 사이드바(`AppSidebar.tsx`)는 7개 섹션 / 23개 메뉴 항목으로 구성되어 있으며, task-1362.1 설계 검토 결과 **옵션 B(하이브리드: 상단 4개 도메인 탭 + 좌측 컨텍스트 서브메뉴)** 가 선정되었다.

**C**: 제이회장님이 메뉴 항목 수(23개+)로 인한 시각적 불안을 지적했으며, 설계안을 실제 코드로 구현하여 기존 사이드바를 교체해야 한다. 기존 라우팅 경로 변경 없이, premiumOnly/adminOnly 로직도 보존해야 하는 제약이 있다.

**Q**: 기존 38개 페이지의 라우팅과 인증 로직을 유지하면서 하이브리드 네비게이션으로 전환할 수 있는가?

**A**: 6개 신규 컴포넌트(navigationConfig, TopNavBar, ContextSubMenu, MobileBottomNav, PremiumCtaCard, index)를 생성하고 DashboardLayout.tsx 1개 파일만 수정하여 전환 완료. 서브메뉴 최대 5개 항목으로 시각적 밀도 78% 감소. TypeScript 에러 0건, Vite 빌드 성공, getActiveTabFromPath 라우팅 테스트 15/15 통과.

---

## 구현 내용

### 신규 컴포넌트 (6개)
- **navigationConfig.ts**: 4개 도메인 탭 + 20개 서브메뉴 + 11개 관리자 메뉴 데이터 정의, URL→탭 매핑 함수
- **TopNavBar.tsx**: 상단 네비 바 (로고, 4탭, 플랜 배지, 유저 드롭다운)
- **ContextSubMenu.tsx**: 좌측 180px 서브메뉴 (선택 탭 항목 최대 5개 + PREMIUM CTA)
- **MobileBottomNav.tsx**: 모바일 바텀 탭 바 + Drawer 서브메뉴
- **PremiumCtaCard.tsx**: 무료 유저 업그레이드 CTA 카드
- **index.ts**: barrel export

### 수정 컴포넌트 (1개)
- **DashboardLayout.tsx**: SidebarProvider/AppSidebar 제거 → TopNavBar + ContextSubMenu + MobileBottomNav 통합

### 보존된 기능
- premiumOnly: PREMIUM 배지 + 클릭 가드 + UpgradeModal
- adminOnly: 유저 드롭다운 내 관리자 섹션 (isSystemAdmin 체크)
- Supabase auth: 기존 세션/프로필/조직 로딩 패턴 동일
- URL 구조: 기존 라우트 경로 변경 없음 (38개 페이지 무수정)

---

## 산출물

- `/home/jay/projects/InsuRo/.worktrees/task-1363.1-dev2/src/components/navigation/navigationConfig.ts`
- `/home/jay/projects/InsuRo/.worktrees/task-1363.1-dev2/src/components/navigation/TopNavBar.tsx`
- `/home/jay/projects/InsuRo/.worktrees/task-1363.1-dev2/src/components/navigation/ContextSubMenu.tsx`
- `/home/jay/projects/InsuRo/.worktrees/task-1363.1-dev2/src/components/navigation/MobileBottomNav.tsx`
- `/home/jay/projects/InsuRo/.worktrees/task-1363.1-dev2/src/components/navigation/PremiumCtaCard.tsx`
- `/home/jay/projects/InsuRo/.worktrees/task-1363.1-dev2/src/components/navigation/index.ts`
- `/home/jay/projects/InsuRo/.worktrees/task-1363.1-dev2/src/components/DashboardLayout.tsx`

---

## 테스트 결과

- TypeScript (`tsc --noEmit`): 에러 0건
- Vite 빌드: 성공 (7.29s, 133 precache entries)
- getActiveTabFromPath 단위 테스트: 15/15 통과 (crm, ai-marketing, analytics-tools, info-settings, 하위 경로, 해시 링크, 미매핑 경로 폴백 포함)

---

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **관리자 메뉴 아이콘 불일치** — "AI 엔진 설정"이 Zap 아이콘으로, "조직 관리"가 Users 아이콘으로 잘못 설정됨. 원본 AppSidebar와 일치하도록 Sparkles, Building2로 수정
2. **MobileBottomNav 미사용 import** — DrawerClose 미사용 import + handleItemClick의 미사용 title 파라미터 제거
3. **미매핑 라우트 폴백** — /settings, /pricing, /admin/* 등 도메인 탭에 속하지 않는 경로는 "crm" 탭으로 기본 폴백 처리 (유저 드롭다운에서 접근 가능한 페이지들이므로 적절)

---

## 셀프 QC

- [x] 1. 영향 파일: DashboardLayout.tsx 1개만 수정, 38개 페이지 인터페이스 변경 없음
- [x] 2. 엣지 케이스: 미매핑 URL 폴백, hash 링크, 하위 경로 매칭, premiumOnly 클릭 가드
- [x] 3. 작업 지시 일치: 구현 범위 9개 항목 모두 충족
- [x] 4. 에러 처리/보안: Supabase auth 패턴 유지, XSS 위험 없음
- [x] 5. 테스트: TypeScript 0 에러, Vite 빌드 성공, 라우팅 15건 테스트
- [x] 6. 발견 이슈: 3건 자체 해결, 미해결 0건
- [x] 7. 아키텍처 원칙: SRP 준수 (컴포넌트별 단일 역할), DRY (navigationConfig 중앙화)
- [x] 8. 인터페이스 변경: DashboardLayout props 변경 없음 (children만)

---

## 머지 판단

- **머지 필요**: Yes
- **브랜치**: task/task-1363.1-dev2
- **워크트리 경로**: /home/jay/projects/InsuRo/.worktrees/task-1363.1-dev2
- **머지 의견**: TypeScript 에러 0건, Vite 빌드 성공, 기존 라우팅 무수정. AppSidebar.tsx는 미사용 상태로 보존되어 롤백 용이. 충돌 가능성 낮음 (DashboardLayout.tsx 1개 파일만 수정).

---

## 모델 사용 기록

- 팀원: 프레이야 / 작업: TopNavBar + navigationConfig + index.ts 구현 / 모델: sonnet
- 팀원: 프레이야 / 작업: ContextSubMenu + MobileBottomNav + PremiumCtaCard 구현 / 모델: sonnet
- 팀원: 프레이야 / 작업: DashboardLayout 통합 / 모델: sonnet