# task-1693.1 완료 보고서

**S**: InsuWiki 문서 상세 페이지(`DocumentClient.tsx`)에서 유사문서 추천, 검토상태 배지, AI 용어 감지, 오류 신고 4개 UX 영역이 운영 중이다.

**C**: (1) 용어 감지가 본문 아래 인라인으로 멀리 떨어져 본문과 동시 참조 불가, (2) "발행됨" 배지가 불필요하게 표시, (3) 오류 신고가 용어 감지 바로 아래 뜬금없이 위치, (4) 유사문서 로직 검증 필요.

**Q**: 4개 UX 영역을 사용자 경험에 맞게 재배치하고 개선할 수 있는가?

**A**: 4건 모두 수정 완료. InlineReviewPanel에 published 조건 추가(1줄), 용어 감지를 FloatingTermDetection 신규 컴포넌트로 분리(277줄), ErrorReportButton을 접힌 섹션으로 리팩토링, DocumentClient 레이아웃 재배치. 기존 테스트 3건 수정(static 테스트 2건 제거 + 1건 추가). 새로운 TS 에러 0건 도입.

---

## 수정 상세

### 1. 유사문서 추천 로직 확인 + 개선
- **현재 로직**: `documents/{id}/ai_suggestions` 서브컬렉션에서 `dismissed=false` 항목을 `confidence` 내림차순 정렬. method별 분류(embedding/semantic/manual vs static). 비static 항목은 `getDoc()`으로 Firestore 실존 확인 후 최대 5개 표시.
- **분석**: 추천은 순수 제목 기반이 아닌 AI 파이프라인 사전계산 기반. 제목 길이와 무관하게 서브컬렉션에 데이터가 있으면 추천됨. Firestore 존재 확인 로직 이미 구현됨.
- **수정**: RelatedDocsSidebar에서 static 항목 필터링 분리하여 docSuggestions만 표시. 존재 확인 로직 유지.

### 2. "검토상태 발행됨" 배지 숨김
- `InlineReviewPanel.tsx:43` — `if (!loading && status === 'published') return null;` 추가
- published 상태 문서에서 전체 패널 미렌더링

### 3. AI 용어 감지 — floating window
- **신규**: `FloatingTermDetection.tsx` (277줄) 생성
- `position: fixed; bottom-4; right-4; z-50` 배치
- 기본: 접힌 배지 "보험 용어 N건" (amber 테마)
- 클릭: `w-80 max-h-96` 스크롤 카드 목록 펼침
- 승인/거부 로직 (links 컬렉션 생성 + dismissed 마킹)
- `RelatedDocsSidebar`에서 termSuggestions/TermMatchCard 완전 제거 (202줄 → 118줄 삭감)

### 4. 오류 신고 — 위치 변경
- `ErrorReportButton.tsx` 전면 리팩토링
- 절대 위치 드롭다운 → 전체 폭 접힌 섹션
- "이 정보에 오류가 있나요?" 텍스트 + chevron 토글
- `DocumentClient.tsx`에서 최하단(InlineReviewPanel 아래)으로 이동

---

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **FloatingTermDetection JSX 배치 구문 에러** — ternary 연산자 내부에 2개 형제 요소 배치 불가. 별도 조건부 블록으로 분리하여 해결.
2. **RelatedDocsSidebar docstring 불일치** — B 섹션 제거 후 docstring이 "2개 섹션" 기술 유지. 수정하여 현재 로직과 일치시킴.
3. **테스트 케이스 불일치** — TC-6/TC-7의 static method 테스트가 분리된 컴포넌트와 불일치. static 테스트 2건 제거 + "static만 있으면 null 반환" 테스트 1건 추가.

### 범위 외 미해결 (1건)
1. **firebase/firestore 타입 선언 에러** — 기존 프로젝트 전반의 firebase import 에러. 본 작업 범위 외 (tsconfig 또는 firebase 버전 문제).

---

## 산출물 파일

- `/home/jay/workspace/projects/insuwiki/.worktrees/task-1693.1-dev4/nextapp/src/components/FloatingTermDetection.tsx` (신규)
- `/home/jay/workspace/projects/insuwiki/.worktrees/task-1693.1-dev4/nextapp/src/components/RelatedDocsSidebar.tsx` (수정)
- `/home/jay/workspace/projects/insuwiki/.worktrees/task-1693.1-dev4/nextapp/src/components/ErrorReportButton.tsx` (수정)
- `/home/jay/workspace/projects/insuwiki/.worktrees/task-1693.1-dev4/nextapp/src/components/review/InlineReviewPanel.tsx` (수정)
- `/home/jay/workspace/projects/insuwiki/.worktrees/task-1693.1-dev4/nextapp/src/app/docs/[id]/DocumentClient.tsx` (수정)
- `/home/jay/workspace/projects/insuwiki/.worktrees/task-1693.1-dev4/nextapp/src/components/__tests__/RelatedDocsSidebar.test.tsx` (수정)

---

## 머지 판단
- **머지 필요**: Yes
- **브랜치**: task/task-1693.1-dev4
- **워크트리 경로**: `/home/jay/workspace/projects/insuwiki/.worktrees/task-1693.1-dev4`
- **머지 의견**: 6개 파일 변경, 신규 TS 에러 0건 도입, 기존 테스트 구조 유지. 기존 firebase 타입 에러는 본 작업 무관. 충돌 가능성 낮음 (DocumentClient.tsx 하단 레이아웃 영역만 변경).

---

## 모델 사용 기록
- 팀원: 사라스바티 / 작업 내용: InlineReviewPanel + FloatingTermDetection + RelatedDocsSidebar 수정 / 사용 모델: sonnet
- 팀원: 사라스바티 / 작업 내용: ErrorReportButton 접힌 섹션 변경 / 사용 모델: sonnet
- 팀원: 사라스바티 / 작업 내용: DocumentClient.tsx 통합 / 사용 모델: sonnet
- 팀원: 하누만 / 작업 내용: RelatedDocsSidebar 테스트 업데이트 / 사용 모델: sonnet

---

## 셀프 QC

- [x] 1. 영향 파일: DocumentClient.tsx, RelatedDocsSidebar.tsx, ErrorReportButton.tsx, InlineReviewPanel.tsx, FloatingTermDetection.tsx(신규), RelatedDocsSidebar.test.tsx
- [x] 2. 엣지 케이스: 용어 0건→FloatingTermDetection null 반환, published 상태→InlineReviewPanel null 반환, 빈 suggestion→RelatedDocsSidebar null 반환
- [x] 3. 작업 지시 4건 모두 구현 확인
- [x] 4. 보안: API 호출에 Bearer token 유지, XSS 위험 없음
- [x] 5. 테스트: static 제거 2건 + static null 반환 1건 추가
- [x] 6. 발견 이슈 3건 모두 직접 해결
- [x] 7. SOLID/DRY: FloatingTermDetection 독립 컴포넌트로 분리, 기존 패턴 재사용
- [x] 8. 인터페이스 변경 없음 (Props 동일)
- [x] 9. 이미지/배너 작업 없음
- [x] 10. CLAUDE.md 해당 없음

## 세션 통계
- 총 도구 호출: 24회

### 수정 파일 목록
- /home/jay/workspace/projects/insuwiki/.worktrees/task-1693.1-dev4/nextapp/src/components/RelatedDocsSidebar.tsx: 10회 (Edit)
- /home/jay/workspace/projects/insuwiki/.worktrees/task-1693.1-dev4/nextapp/src/app/docs/[id]/DocumentClient.tsx: 5회 (Edit)
- /home/jay/workspace/projects/insuwiki/.worktrees/task-1693.1-dev4/nextapp/src/components/__tests__/RelatedDocsSidebar.test.tsx: 3회 (Edit)
- /home/jay/workspace/memory/reports/task-1693.1.md: 1회 (Write)
- /home/jay/workspace/memory/tasks/task-1693.1.md: 1회 (dispatch)
- /home/jay/workspace/projects/insuwiki/.worktrees/task-1693.1-dev4/nextapp/src/components/ErrorReportButton.tsx: 1회 (Write)
- /home/jay/workspace/projects/insuwiki/.worktrees/task-1693.1-dev4/nextapp/src/components/FloatingTermDetection.tsx: 1회 (Write)
- /home/jay/workspace/projects/insuwiki/.worktrees/task-1693.1-dev4/nextapp/src/components/review/InlineReviewPanel.tsx: 1회 (Edit)
- bash_cmd: 1회 (Bash)

### 도구 사용 현황
- Edit: 19회
- Write: 3회
- Bash: 1회
- dispatch: 1회