# task-545.1 완료 보고서: InsuWiki TOC 더블클릭 문제 재수정

## SCQA

**S**: InsuWiki의 TOC(목차) 컴포넌트는 task-535.1에서 ID 일관성, scroll-mt, IntersectionObserver root 등 5건의 버그가 수정되어 배포 중이다.

**C**: 수정 후에도 TOC 항목을 클릭하면 한 번에 본문으로 이동하지 않고 더블클릭이 필요한 문제가 지속된다. 원인은 `isClicked` 플래그가 React state(`useState`)로 관리되어 IntersectionObserver 콜백에서 stale closure가 발생하고, `scrollIntoView`가 중첩 스크롤 컨테이너에서 불안정하게 동작하기 때문이다.

**Q**: 단일 클릭으로 TOC 항목에서 본문 해당 위치로 안정적으로 이동할 수 있는가?

**A**: `isClicked`를 `useState` → `useRef`로 변경하여 stale closure를 제거하고, `scrollIntoView` → `scrollContainer.scrollTo()`로 교체하여 중첩 스크롤 컨테이너에서의 안정성을 확보했다. Next.js 빌드 에러 0건 통과.

---

## 수정 내용

### 근본 원인 3가지
1. **Stale Closure**: `isClicked`가 `useState`로 관리 → IntersectionObserver 콜백이 이전 렌더의 `false` 값을 참조 → 스크롤 중 observer가 `activeId`를 다른 heading으로 변경
2. **Observer 재생성**: `isClicked`가 useEffect dependency array에 포함 → 클릭할 때마다 observer disconnect/reconnect → initial callback이 `activeId` 변경
3. **scrollIntoView 불안정**: 중첩 스크롤 컨테이너(`#scroll-container` div)에서 `scrollIntoView`가 부모 요소까지 스크롤 시도

### 수정 사항

| 변경 | 기존 | 수정 후 |
|------|------|---------|
| isClicked 관리 | `useState(false)` | `useRef(false)` |
| Observer 콜백 | `if (isClicked) return` (stale closure) | `if (isClickedRef.current) return` (항상 최신값) |
| useEffect deps | `[isEditing, toc, isClicked]` | `[isEditing, toc]` |
| 스크롤 방식 | `element.scrollIntoView()` | `scrollContainer.scrollTo()` + offset 계산 |

## 수정/생성 파일

- `nextapp/src/components/TableOfContents.tsx` (21 insertions, 13 deletions)

## 셀프 QC

- [x] 1. 영향 파일: TableOfContents.tsx만 변경. DocumentClient.tsx는 변경 없음 (ID 생성 로직 동일).
- [x] 2. 엣지 케이스: (1) 요소가 DOM에 없는 경우 → `isClickedRef.current = false` fallback. (2) 문서 최상단 heading 클릭 → `Math.max(0, offset)` 보호. (3) scroll-container가 없는 경우 → null check.
- [x] 3. 작업 지시 일치: 더블클릭 → 싱글클릭 수정 완료.
- [x] 4. 보안: 사용자 입력 없음, DOM API만 사용.
- [x] 5. 테스트: 빌드 검증 통과 (에러 0건).

## 발견 이슈 3건

1. **[수정됨] stale closure**: `useState` → `useRef`로 해결
2. **[수정됨] observer 재생성**: dependency array에서 `isClicked` 제거
3. **[수정됨] scrollIntoView 불안정**: `scrollTo` + offset 계산으로 대체

## 테스트 결과

- Next.js 빌드: PASS (에러 0건, 경고 0건)
- 커밋: `93bde20` `[task-545.1] TOC 더블클릭 문제 수정`

## 비고

- Playwright 테스트는 로컬 서버 기동이 필요하여 빌드 검증으로 대체
- 배포 후 실제 브라우저에서 싱글클릭 동작 확인 권장