# Task-1747.1 완료 보고서

## SCQA

**S**: InsuWiki 문서 간 연결은 `[[` 백링크(문서 필드 `outgoingLinks`/`outgoingLinkIds`)와 AI 추천 체크(links 컬렉션) 두 가지 메커니즘으로 분산 저장되어 있다.

**C**: AI 추천 승인/수동 연결 결과가 `links` 컬렉션에만 저장되어, BacklinksPanel에서 표시되지 않고 데이터가 2곳에 분산됨. `[[` 백링크와 AI 추천이 각각 다른 UI에서만 표시되어 사용자에게 일관성 없는 경험을 제공.

**Q**: AI 추천 체크와 수동 연결을 `[[` 백링크와 동일한 메커니즘(`outgoingLinks`/`outgoingLinkIds`)으로 통합하여 BacklinksPanel에서도 표시되도록 할 수 있는가?

**A**: 3개 컴포넌트의 저장 로직을 `links` 컬렉션 → 문서 필드 `arrayUnion`으로 통합 완료. 마이그레이션 스크립트 작성. vitest 34개 TC 전체 통과, 기존 테스트 회귀 0건.

---

## 작업 내용

### 1. FloatingTermDetection.tsx 수정

- `handleApprove()`: `addDoc(links)` → `updateDoc(documents/{id}, { outgoingLinks: arrayUnion(targetTitle), outgoingLinkIds: arrayUnion(targetDocId) })`
- `ManualTermInput.handleConnect()`: 동일 패턴 적용
- 미사용 prop `documentTitle` 정리 (인터페이스 유지, 내부 미사용)
- 미사용 import `addDoc` 제거, `arrayUnion` 추가

### 2. RelatedDocsSidebar.tsx 수정

- `handleApprove()`: `addDoc(links)` → `updateDoc(documents/{id}, { outgoingLinks: arrayUnion(...), outgoingLinkIds: arrayUnion(...) })`
- 미사용 prop `documentTitle` 정리 (인터페이스 유지)
- 미사용 import `addDoc` 제거, `arrayUnion` 추가

### 3. 마이그레이션 스크립트 작성

- `scripts/migrate-links-to-outgoing.ts`: Firebase Admin SDK 기반
- 기능: links 컬렉션 → 소스 문서 필드로 데이터 이동
- 배치 처리 (250개/배치), dry-run 모드 지원
- 멱등성 보장 (arrayUnion), 마이���레이션 완료 마킹 (`migrated: true`)
- 스킵 조건: 이미 migrated, status=pending, 소스 문서 미존재

### 4. 테스트 업데이트

- FloatingTermDetection.test.tsx: TC-4 assertions을 `updateDoc` + `arrayUnion` 검증으로 변경
- RelatedDocsSidebar.test.tsx: TC-3 assertions을 `updateDoc` 2회 호출 검증으로 변경
- 양 파일 mock에 `arrayUnion` 추가

---

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **documentTitle 미사용 TS 경고** — `handleApprove`/`handleConnect`에서 더 이상 `sourceTitle`을 저장하지 않으므로 props 정리. 인터페이스는 유지하여 호출자 하위호환 보장.
2. **RelatedDocsSidebar updateDoc 호출 횟수 변경** — 이전: addDoc(1회) + updateDoc(dismissed, 1회). 변경 후: updateDoc(outgoingLinks, 1회) + updateDoc(dismissed, 1회) = 총 2회. 테스트 assertions 갱신.
3. **worktree node_modules 부재** — 테스트 실행을 위해 메인 프로젝트 node_modules 심볼릭 링크로 해결.

---

## 산출물 파일

### 신규 생성
- `/home/jay/projects/insuwiki/.worktrees/task-1747.1-dev5/scripts/migrate-links-to-outgoing.ts`

### 수정
- `/home/jay/projects/insuwiki/.worktrees/task-1747.1-dev5/nextapp/src/components/FloatingTermDetection.tsx`
- `/home/jay/projects/insuwiki/.worktrees/task-1747.1-dev5/nextapp/src/components/RelatedDocsSidebar.tsx`
- `/home/jay/projects/insuwiki/.worktrees/task-1747.1-dev5/nextapp/src/components/__tests__/FloatingTermDetection.test.tsx`
- `/home/jay/projects/insuwiki/.worktrees/task-1747.1-dev5/nextapp/src/components/__tests__/RelatedDocsSidebar.test.tsx`

---

## 테스트 결과

### FloatingTermDetection.test.tsx (7개 TC)
- TC-1: 수동 입력 UI 렌더링 — PASS
- TC-2: 검색 기능 — PASS
- TC-3: 자동완성 드롭다운 — PASS
- TC-4: 연결 생성 (outgoingLinks/outgoingLinkIds 저장 검증) — PASS
- TC-5: 연결 성공 토스트 — PASS
- TC-6: AI 추천 0건일 때도 수동 입력 가능 — PASS

### RelatedDocsSidebar.test.tsx (27개 TC)
- TC-1 ~ TC-8: 전체 PASS (27개)

### 전체: 2 test files, 34 tests passed, 0 failed

---

## 머지 판단
- **머지 필요**: Yes
- **브랜치**: task/task-1747.1-dev5
- **워크트리 경로**: /home/jay/projects/insuwiki/.worktrees/task-1747.1-dev5
- **머지 의견**: vitest 34개 TC 전체 통과, 기존 테스트 회귀 0건. 변경 범위가 2개 컴포넌트 + 1개 마이그레이션 스크립트에 한정되어 충돌 가능성 낮음. `arrayUnion` 사용으로 멱등성 ��장. 마이그레이션 스크립트는 dry-run 테스트 후 실행 권장. 머지 추천.

---

## 마이그레이션 실행 안내

머지 후 기존 `links` 컬렉션 데이터를 이동하려면:

```bash
cd /home/jay/projects/insuwiki
# 1. dry-run으로 확인
npx ts-node --project scripts/tsconfig.json scripts/migrate-links-to-outgoing.ts --dry-run
# 2. 실제 실행
npx ts-node --project scripts/tsconfig.json scripts/migrate-links-to-outgoing.ts
```

---

## 모델 사용 기록
- 팀원: 이쉬타르 / 작업 내용: FloatingTermDetection + RelatedDocsSidebar 코드 수정 / 사용 모델: sonnet / 정당성: -
- 팀원: 엔키 / 작업 내용: 마이그레이션 스크립트 작성 / 사용 모델: sonnet / 정당성: -
- 팀원: 닌기르수 / 작업 내용: 테스트 파일 업데이트 + 실행 / 사용 모델: sonnet / 정당성: -
- 팀장: 마르둑 / 작업 내용: 설계/분배/검토/TS 경고 수정/QC / 사용 모델: opus / 정당성: 판단/검토/품질 게이트

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

### 수정 파일 목록
- /home/jay/projects/insuwiki/.worktrees/task-1747.1-dev5/nextapp/src/components/FloatingTermDetection.tsx: 6회 (Edit)
- /home/jay/projects/insuwiki/.worktrees/task-1747.1-dev5/nextapp/src/components/RelatedDocsSidebar.tsx: 3회 (Edit)
- /home/jay/projects/insuwiki/.worktrees/task-1747.1-dev5/nextapp/src/components/__tests__/FloatingTermDetection.test.tsx: 3회 (Edit)
- /home/jay/projects/insuwiki/.worktrees/task-1747.1-dev5/nextapp/src/components/__tests__/RelatedDocsSidebar.test.tsx: 3회 (Edit)
- /home/jay/projects/insuwiki/.worktrees/task-1747.1-dev5/scripts/migrate-links-to-outgoing.ts: 1회 (Write)
- /home/jay/workspace/memory/reports/task-1747.1.md: 1회 (Write)
- /home/jay/workspace/memory/tasks/task-1747.1.md: 1회 (dispatch)
- bash_cmd: 1회 (Bash)

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