# Task-1743.1 완료 보고서

## SCQA

**S**: InsuWiki에서 문서 간 연결은 `[[` 백링크(에디터 내)와 AI 추천 체크(FloatingTermDetection 패널)의 두 가지 방식으로 동작하며, Floating 패널은 AI가 추천한 용어만 표시한다.

**C**: `[[` 백링크와 AI 추천이 동일한 Firestore 데이터 구조로 저장되는지 검증되지 않았고, 사용자가 AI에 없는 용어를 직접 입력하여 백링크를 걸 수 없어 활용성이 제한된다.

**Q**: 두 백링크 방식의 Firestore 데이터 구조가 동일한가? Floating 패널에 수동 입력 기능을 추가하여 사용자 자율 연결을 지원할 수 있는가?

**A**: 교차 검증 결과 두 방식은 **서로 다른 저장 메커니즘**을 사용한다. 수동 입력 기능은 ManualTermInput 서브컴포넌트로 구현 완료. vitest 7개 TC 전체 통과, 기존 88개 테스트 회귀 0건.

---

## 작업 1: 백링크 교차 검증 결과

### `[[` 백링크 저장 방식
- **저장 위치**: 문서의 `outgoingLinks` (제목 배열) + `outgoingLinkIds` (ID 배열) 필드
- **처리 흐름**: 에디터 → WikiLinkExtension → 문서 저장 시 `useDocumentState.ts`에서 문서 필드 업데이트
- **`links` 컬렉션 사용**: 아니오

### AI 추천 체크 저장 방식
- **저장 위치**: `links` 최상위 컬렉션에 새 문서 생성
- **처리 흐름**: FloatingTermDetection/RelatedDocsSidebar → `addDoc(links, {...})` + `ai_suggestions` dismissed 마킹
- **저장 필드**: sourceDocId, sourceTitle, targetDocId, targetTitle, method, confidence, createdBy:'system', status:'active'

### 결론
| 항목 | `[[` 백링크 | AI 추천 체크 |
|------|------------|-------------|
| 저장 위치 | 문서 필드 (outgoingLinks/outgoingLinkIds) | links 컬렉션 |
| createdBy | 없음 (문서 필드) | 'system' |
| method | 없음 | 'static'/'embedding'/'semantic' |
| BacklinksPanel 표시 | O (outgoingLinks 기반) | X (links 컬렉션 미조회) |
| RelatedDocsSidebar 표시 | X | O (ai_suggestions 기반) |

**두 방식은 동일 효과가 아님.** 각각 다른 UI에서 표시됨.

---

## 작업 2: Floating 수동 입력 기능 구현

### 구현 내용
- `ManualTermInput` 서브컴포넌트를 FloatingTermDetection.tsx에 추가
- 검색 입력 필드 (placeholder: "문서 검색...") + "연결" 버튼
- 입력 시 debounce 300ms → Firestore `documents` 컬렉션에서 `where('searchKeywords', 'array-contains', keyword)` 쿼리
- 자동완성 드롭다운으로 검색 결과 표시
- 결과 선택 후 연결 시 `links` 컬렉션에 `createdBy: 'user'`, `method: 'manual'`, `confidence: 100`, `status: 'active'`로 저장
- amber 테마 디자인 일관성 유지

### 핵심 수정 사항
- **early return 조건 변경**: `terms.length === 0`일 때도 패널 렌더링 (수동 입력 가능)
- 접힌 버튼 텍스트: AI 추천 있으면 "보험 용어 N건", 없으면 "용어 연결"
- AI 추천 목록은 terms.length > 0일 때만 조건부 렌더링

---

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **ManualTermInput 미사용** — 서브에이전트가 컴포넌트를 정의했으나 JSX에서 사용하지 않음. 팀장이 직접 확인 후 line 411에 이미 사용 중인 것을 확인 (stale 진단)
2. **AI 추천 0건 시 패널 숨김** — `if (terms.length === 0) return null` 조건으로 수동 입력도 불가능. 조건을 `if (loading) return null`로 변경하고 terms 목록을 조건부 렌더링
3. **테스트 미사용 import** — FloatingTermDetection.test.tsx에서 `Timestamp`, `React` import 제거

---

## 산출물 파일

### 신규 생성
- `/home/jay/projects/insuwiki/.worktrees/task-1743.1-dev5/nextapp/src/components/__tests__/FloatingTermDetection.test.tsx`

### 수정
- `/home/jay/projects/insuwiki/.worktrees/task-1743.1-dev5/nextapp/src/components/FloatingTermDetection.tsx`

---

## 테스트 결과

### FloatingTermDetection.test.tsx (7개 TC)
- TC-1: 수동 입력 UI 렌더링 (입력 필드 + 연결 버튼) — PASS
- TC-2: 검색 기능 (Firestore where 쿼리 실행) — PASS
- TC-3: 자동완성 드롭다운 (검색 결과 표시) — PASS
- TC-4: 연결 생성 (links 컬렉션에 createdBy:user, method:manual) — PASS
- TC-5: 연결 성공 토스트 메시지 — PASS
- TC-6: AI 추천 0건일 때도 수동 입력 가능 — PASS
- TC-7 (기존 기능): 전체 회귀 없음 — PASS

### 전체 회귀 테스트
- 5개 테스트 파일, 88개 TC 전체 PASS
- 회귀: 0건

---

## 머지 판단
- **머지 필요**: Yes
- **브랜치**: task/task-1743.1-dev5
- **워크트리 경로**: /home/jay/projects/insuwiki/.worktrees/task-1743.1-dev5
- **머지 의견**: vitest 88개 TC 전체 통과, 기존 테스트 회귀 0건. 빌드 컴파일 성공 (static page 생성 시 Firebase API 키 부재로 인한 기존 환경 에러만 존재). 코드 변경 범위가 FloatingTermDetection.tsx 1개 파일에 한정되어 충돌 가능성 낮음. 머지 추천.

---

## 모델 사용 기록
- 팀원: 이쉬타르 / 작업 내용: TDD 테스트 작성 + ManualTermInput 구현 / 사용 모델: sonnet / 정당성: -
- 팀장: 마르둑 / 작업 내용: 교차 검증 분석 + 코드 리뷰 + 로직 결함 수정 / 사용 모델: opus / 정당성: 설계/검토/품질 게이트

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

### 수정 파일 목록
- /home/jay/projects/insuwiki/.worktrees/task-1743.1-dev5/nextapp/src/components/__tests__/FloatingTermDetection.test.tsx: 9회 (Edit, Write)
- /home/jay/projects/insuwiki/.worktrees/task-1743.1-dev5/nextapp/src/components/FloatingTermDetection.tsx: 4회 (Edit)
- bash_cmd: 3회 (Bash)
- /home/jay/workspace/memory/reports/task-1743.1.md: 1회 (Write)
- /home/jay/workspace/memory/tasks/task-1743.1.md: 1회 (dispatch)

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