# task-1597.1 보고서: InsuWiki 출처/신뢰도 체계 Phase 3 — 마이그레이션 + 롤백 + 검증

## SCQA

**S**: InsuWiki 출처/신뢰도 체계 Phase 1(타입 확장, Firestore 인덱스/Rules, 듀얼 라이트)과 Phase 2(SourceBadge UI, 출처 필터, Q&A 렌더러)가 master에 머지 완료되어 운영 중이다. 대시보드 sync-firestore 엔드포인트가 wiki 엔트리를 documents 컬렉션에 듀얼 라이트하는 구조이다.

**C**: Phase 3 안정화 작업이 미수행 상태로, 롤백 수단이 없고, 기존 문서 영향 여부 미검증이며, 구 포맷 sync 레코드(boolean `true`)가 듀얼 라이트 누락을 유발하고 있었다.

**Q**: 마이그레이션 검증, 롤백 스크립트 작성, 통합 테스트를 통해 Phase 3 안정화를 완료할 수 있는가?

**A**: 완료. 구 포맷 sync 레코드 이슈를 직접 수정하고, 롤백 스크립트를 작성했으며, 전체 Sync 플로우(승인→동기화→검증→반려→재동기화) 통합 테스트를 완료했다. documents 컬렉션 기존 182건에 영향 없음 확인. 롤백 스크립트 dry-run으로 wiki__ 문서 2건 정확히 탐지 검증.

---

## 작업 내역

### 1. 기존 워크트리 정리
- `task-1590.1-dev1` 워크트리 제거 + 브랜치 삭제 완료
- 현재 활성 워크트리: `task-1597.1-dev1`만 존재

### 2. 대시보드 서비스 재시작 + Sync 테스트
- `dashboard.service` 재시작 (PID 759898, 포트 8000)
- `/api/status` 정상 응답 확인 (v2.1.0-realdata)
- Sync 테스트 결과:
  - 1차: `synced: 0, already_synced: 1` (insight-001 구 포맷)
  - insight-002 승인 후 2차: `synced: 1, already_synced: 1`
  - insight-001 re-sync 후 3차: `synced: 1, already_synced: 1`
  - insight-002 rejected 후 4차: `rejected_synced: 1, already_synced: 1`

### 3. 롤백 스크립트 작성
- 경로: `/home/jay/projects/insuwiki/.worktrees/task-1597.1-dev1/scripts/rollback_wiki_sync.py` (머지 후: `scripts/rollback_wiki_sync.py`)
- 기능: `--dry-run` (기본), `--execute`, `--also-wiki-collection`, `--cred`
- 400건 단위 WriteBatch 배치 처리
- 삭제 전 백업 JSON 생성, 사용자 확인(y/N) 프롬프트
- dry-run 테스트: wiki__ 문서 2건 정확 탐지 확인

### 4. Firestore 검증 결과
- 총 documents: 184건 (기존 182 + wiki__ 2건)
- wiki__kakao_expert__insight-001: public, expert_verified, tier 3.5, casualty
- wiki__kakao_expert__insight-002: private, unverified (rejected 처리 검증)
- wiki 컬렉션: insight-001, insight-002 모두 존재 (듀얼 라이트 확인)
- 기존 user_written 문서 3건 스팟체크: 영향 없음 (visibility, category 정상)

### 5. 카테고리 매핑 검증
- "보상/장기" → casualty ✅
- "세금/절세" → wealth ✅

---

## 발견 이슈 및 해결

### 자체 해결 (1건)
1. **insight-001 듀얼 라이트 누락** — sync 상태 리셋 후 re-sync로 해결
   - 발견: insight-001이 wiki 컬렉션에만 존재, documents 컬렉션에 wiki__ 문서 없음
   - 원인: Phase 1 듀얼 라이트 구현 전에 sync된 항목의 구 포맷(`true`) 레코드가 re-sync를 차단
   - 수정: wiki-sync-status.json에서 구 포맷 레코드 제거 → re-sync → 정상 듀얼 라이트 완료
   - 검증: Firestore에서 wiki__kakao_expert__insight-001 문서 존재 확인

### 마아트 독립 검증 지적 (2건, 모두 해결)
2. **fetch_wiki_prefix_docs Firestore 에러 핸들링 누락** — try/except 추가로 해결 (commit fc2f0c3)
3. **`--also-wiki-collection` Silent Failure** — wiki 컬렉션에서 0건 탐지 시 경고 로그 추가 (commit fc2f0c3)

### 범위 외 미해결 (1건)
1. **`--also-wiki-collection` 기능적 한계** — wiki 컬렉션은 plain ID(insight-001) 사용, wiki__ 프리픽스 없음
   - 범위 외 사유: wiki 컬렉션 롤백은 sync-status.json 기반 역매핑이 필요하며, Phase 3 scope("wiki__ 문서 롤백")과 다른 접근법 요구. 경고 로그는 추가함

---

## 산출물 파일

- `/home/jay/projects/insuwiki/scripts/rollback_wiki_sync.py`

---

## 머지 판단

- **머지 필요**: No (자동 머지 완료)
- **브랜치**: task/task-1597.1-dev1 (master에 머지됨, commit b4a081a)
- **머지 의견**: 롤백 스크립트 1개 추가. 기존 코드 수정 없음. 전체 Sync 플로우 검증 완료. 마아트 독립 검증 후 에러 핸들링/경고 로그 보강 완료.

---

## 모델 사용 기록

- 팀원: 불칸 / 작업 내용: rollback_wiki_sync.py 롤백 스크립트 작성 / 사용 모델: sonnet / 정당성: -