# task-604.1 완료 보고: InsuWiki TOC "살아있는 목차" UX 개선

## SCQA

**S**: InsuWiki의 TableOfContents 컴포넌트(474줄)가 뷰/편집 모드에서 목차 기능을 제공 중이며, IntersectionObserver 기반 스크롤 추적, 계층형 번호 부여, 스크롤 격리 등이 구현되어 있다.

**C**: 3가지 UX 문제가 있다. (1) 페이지 로드 시 TOC가 "잠든" 상태로 시작 — 스크롤/클릭 전까지 활성 항목 없음, (2) 콘텐츠에 헤딩이 없으면 TOC 영역이 빈 칸 — 신규 유저가 목차 존재를 모름, (3) active 항목 하이라이팅이 약함 — 텍스트 색상+bold만으로는 현재 위치 파악 어려움.

**Q**: 3건의 UX 개선을 기존 테스트 회귀 없이 적용할 수 있는가?

**A**: 3건 모두 구현 완료. vitest 36건 전체 통과(기존 21건 + 신규 15건), Next.js 빌드 성공. 기존 level 필터링(1~2만 표시) 미변경.

## 수정 내용

### 1. 페이지 로드 시 즉시 활성화
- **파일**: `TableOfContents.tsx:213-230`
- IntersectionObserver 초기화 직후 `requestAnimationFrame`으로 DOM 렌더 완료 시점에 뷰포트 내 첫 번째 헤딩 탐색
- `scroll-container`의 `getBoundingClientRect()` 기준 상단 140px 제외 영역에서 첫 번째 visible 헤딩을 `setActiveId`
- 편집 모드(`isEditing=true`)에서는 실행되지 않음 (기존 guard 유지)

### 2. TOC 비어있을 때 가이드 표시
- **파일**: `TableOfContents.tsx:362-394`
- `toc.length === 0 && isEditing`: 안내 메시지 표시 ("# 제목 또는 - 목록을 추가하면 목차가 자동 생성됩니다")
- `toc.length === 0 && !isEditing`: 기존대로 null 반환
- desktop(aside)과 mobile(div) 양쪽 모두 처리
- 스타일: `text-xs text-slate-400 italic px-2 py-4`

### 3. 현재 위치 표시 강화
- **파일**: `TableOfContents.tsx:47-49` (색상 변수), `504-508` (desktop), `438-442` (mobile)
- 좌측 세로 바: `border-l-2` + variant별 색상 (`border-indigo-500` / `border-emerald-500`)
- 배경색: `bg-indigo-50` / `bg-emerald-50`
- 폰트: `font-semibold`
- 비활성: `border-transparent text-gray-500 hover:bg-gray-50`
- 전환 애니메이션: `transition-all duration-200`
- 기존 active dot + underline 애니메이션 → 세로 바 스타일로 대체 (미사용 변수 `activeDotColor`, `underlineColor` 제거)
- TOC 사이드바 자동 스크롤: 기존 구현(line 298-303) 유지 확인

## 생성/수정 파일

- `nextapp/src/components/TableOfContents.tsx` (474줄 → 523줄)
- `nextapp/src/components/__tests__/TableOfContents.test.tsx` (417줄 → 825줄)

## 테스트 결과

- **vitest**: 36 passed / 0 failed (148ms)
  - 기존 테스트 21건 (2건 새 동작 반영하여 수정)
  - 신규 테스트 15건 추가
- **Next.js 빌드**: 성공 (Compiled successfully in 13.8s, 정적 페이지 생성 완료)

### 신규 테스트 커버리지

- 수정 1 (즉시 활성화): 2건 — 뷰포트 내 헤딩 감지, 뷰포트 밖 헤딩 미감지
- 수정 2 (빈 TOC 가이드): 6건 — 편집 모드 메시지 표시, 뷰 모드 null, 스타일 검증, desktop/mobile 양쪽
- 수정 3 (표시 강화): 7건 — wiki/daily variant 세로 바 색상, 배경색, border-l-2, mobile 강화, 전환 애니메이션

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **worktree에 .env.local 미복사** — 빌드 시 Firebase 인증 실패 → .env.local 복사 후 빌드 성공
2. **미사용 변수 잔존 (`activeDotColor`, `underlineColor`)** — 수정 3에서 dot/underline 제거 후 참조 없는 변수 발견 → 선언부 삭제
3. **기존 테스트 2건 assertion 불일치** — `pl-4` → `ml-4` 변경, `null` 반환 → 가이드 메시지 표시 변경에 따른 테스트 업데이트

### 범위 외 미해결 (0건)
없음.

## 셀프 QC

- [x] 1. 다른 파일 영향: DocumentClient.tsx 변경 불필요 (isEditing prop 이미 전달 중). TableOfContents.tsx만 변경.
- [x] 2. 엣지 케이스: toc 빈 상태 + isEditing 조합, 뷰포트 밖 헤딩, scroll-container 미존재 시 fallback
- [x] 3. 작업 지시 일치: 3건 수정사항 모두 지시서와 정확히 일치. level 필터링(1~2) 미변경 확인.
- [x] 4. 에러 처리/보안: DOM 요소 null 체크, optional chaining 사용
- [x] 5. 테스트 커버리지: 36건 전체 통과, 3건 수정사항별 테스트 케이스 포함
- [x] 6. 발견 이슈 모두 직접 해결

## 머지 판단
- **머지 필요**: Yes
- **브랜치**: task/task-604.1-dev1
- **워크트리 경로**: /home/jay/projects/insuwiki/.worktrees/task-604.1-dev1
- **머지 의견**: vitest 36건 전체 통과, Next.js 빌드 성공, TypeScript 컴파일 에러 0건. 기존 기능(level 필터링, IntersectionObserver, 클릭 핸들러) 회귀 없음. 충돌 가능성 낮음 (TableOfContents.tsx 단일 파일 변경).