# task-1812.1 완료 보고서: InsuWiki Sync 완료 리스트 Firestore 기준 상태 재동기화

## SCQA

**S**: InsuWiki 대시보드에서 wiki-sync-status.json(105건)과 wiki-statuses.json(16건)으로 Sync 완료 문서의 상태를 관리하고 있으며, Firestore documents 컬렉션에 87건의 sourceType=="dashboard_insight" 문서가 존재한다.

**C**: wiki-statuses.json에 16건만 존재하여 나머지 89건의 Sync 완료 문서 상태가 대시보드에 반영되지 않았다. 기존 sync_firestore_statuses.py는 wiki_entries.json(219건)을 전체 순회하여 "Sync 이전" 114건까지 건드릴 위험이 있었다.

**Q**: 기존 105건의 Sync 완료 항목만 대상으로 Firestore 기준 상태를 안전하게 재동기화할 수 있는가?

**A**: sync_firestore_statuses.py를 수정하여 wiki-sync-status.json의 기존 105건만 순회하도록 변경. wiki_entries.json 의존을 제거하고, Firestore doc_id 기반 매칭으로 상태를 갱신. 실행 결과 wiki-statuses.json이 16건 → 106건으로 확장되어 대시보드에 전체 상태 반영 완료. wiki-sync-status.json은 105건 불변 유지.

## 수행 내용

### 스크립트 수정 (`sync_firestore_statuses.py`)

**제거:**
- `WIKI_ENTRIES_PATH` 상수
- `extract_entry_id()` 함수
- wiki_entries.json 로드 및 all_entry_ids 기반 순회 루프

**변경:**
- Firestore 결과를 `fs_by_doc_id` (doc_id → status) 딕셔너리로 인덱싱
- wiki-sync-status.json의 기존 항목만 순회 (`for entry_id, sync_entry in old_sync.items()`)
- doc_id 없는 항목: 스킵 + 카운터
- Firestore 미매칭: 현재 상태 유지 + 카운터
- Firestore 매칭: status 갱신
- `assert len(new_sync) == len(old_sync)` 무결성 검증
- STATUS_MAP에 `"published": "approved"` 매핑 추가
- `--dry-run` 모드 추가 (argparse)
- Firestore 쿼리 deprecation warning 수정 (FieldFilter 사용)

## 실행 결과

| 항목 | 값 |
|------|-----|
| Firestore 조회 | 87건 |
| sync-status 전/후 | 105건 → 105건 (불변) |
| sync 상태 갱신 | 0건 (이미 일치) |
| Firestore 미매칭 (유지) | 18건 |
| statuses 신규 추가 | 90건 |
| statuses 전/후 | 16건 → 106건 |

## 검증 결과

| 시나리오 | 결과 |
|----------|------|
| Sync 이전 불변 (unsynced=114) | PASS — API: unsynced=114 |
| Sync 완료 상태 갱신 | PASS — 87건 매칭, 상태 일치 |
| 데이터 무결성 (105건 유지) | PASS — assert 통과 |
| API 정상 (synced=105, unsynced=114) | PASS — /api/wiki/stats 확인 |
| sync → statuses 누락 0건 | PASS |
| 상태 불일치 0건 | PASS |
| kakao-001 기존 데이터 보존 | PASS |

## 발견 이슈 및 해결

### 자체 해결 (2건)
1. **Firestore 쿼리 deprecation warning** — `where()` positional args를 `FieldFilter` keyword arg로 변경
   - 수정: `sync_firestore_statuses.py:18` (import 추가), `:71` (쿼리 수정)
2. **wiki-statuses.json 불완전** — 105건 중 89건이 누락되어 대시보드 미반영
   - 수정: 스크립트 로직 변경으로 new_sync 기반 statuses 갱신 추가

### 범위 외 미해결 (1건)
1. **Firestore 미매칭 18건** — 105건 중 18건이 Firestore documents 컬렉션에 존재하지 않음. 삭제되었거나 다른 컬렉션에 있을 수 있음. 범위 외 사유: Firestore 데이터 관리는 InsuWiki 서비스팀 소관.

## 산출물

- `/home/jay/workspace/dashboard/scripts/sync_firestore_statuses.py`
- `/home/jay/workspace/dashboard/data/wiki-sync-status.json`
- `/home/jay/workspace/dashboard/data/wiki-statuses.json`
- `/home/jay/workspace/dashboard/data/wiki-statuses.json.bak.20260414212211`
- `/home/jay/workspace/dashboard/data/wiki-sync-status.json.bak.20260414212211`

## QC 자동 검증 결과

- overall: 7 PASS, 1 FAIL, 5 SKIP
- file_check: PASS (9599 bytes)
- data_integrity: PASS
- test_runner: SKIP (관련 테스트 파일 0개 — 정당한 SKIP)
- tdd_check: FAIL → Lv.1 단순 스크립트 수정 작업으로 TDD 적용 대상 아님 (QC 규칙: "Lv.2+ 코딩 작업에만 의미 있음")
- pyright_check: PASS (0 errors, 0 warnings)
- style_check: PASS (black + isort OK)
- critical_gap: PASS
- spec_compliance: PASS
- duplicate_check: PASS (최대 유사도 9.2%)

## 모델 사용 기록

- 팀원: 불칸 / 작업 내용: sync_firestore_statuses.py 재작성 / 사용 모델: sonnet / 정당성: -

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

### 수정 파일 목록
- /home/jay/workspace/dashboard/scripts/sync_firestore_statuses.py: 3회 (Edit, Write)
- /home/jay/workspace/memory/reports/task-1812.1.md: 2회 (Edit, Write)
- /home/jay/workspace/memory/tasks/task-1812.1.md: 1회 (dispatch)

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