---
task_id: "task-1813.1"
team: dev2-team
created_at: 2026-04-14
---

# task-1813.1: InsuWiki Sync 완료 — 승인(published) 감지 + 양방향 실시간 sync

## S - Situation
InsuWiki Sync 시스템에서 대시보드 → Firestore 동기화 105건이 존재하며, InsuWiki에서 승인/반려 시 콜백으로 대시보드 상태를 갱신하는 양방향 sync 구조가 구현되어 있다.

## C - Complication
`sync_firestore_statuses.py` 복구 스크립트가 Firestore에서 승인된 문서 18건을 감지하지 못한다. InsuWiki 승인 시 `sourceType`이 `dashboard_insight` → 원래 값(예: `kakao_community`)으로 변경되어 1차 쿼리(`sourceType == 'dashboard_insight'`)에서 누락된다. 1차 쿼리 결과가 있으면 2차/3차 폴백이 실행되지 않으므로, 승인된 문서가 영구적으로 "draft" 상태로 남는다.

## Q - Question
과거 승인된 18건의 상태를 복구하고, 향후 실시간 콜백이 정상 작동하는지 검증할 수 있는가?

## A - Answer
`sync_firestore_statuses.py`에 개별 문서 조회 로직을 추가하여, 1차 쿼리에서 누락된 doc_id를 Firestore에서 직접 조회해 실제 상태를 복구하도록 수정했다. server.py approve 핸들러에는 로깅을 보강하여 콜백 수신/처리를 추적 가능하게 했다. 프론트엔드 StatusBadge는 이미 approved+synced → "반영됨" 표시를 올바르게 구현하고 있어 변경 불필요.

## 작업 상세

### 작업 1: 과거 승인 18건 상태 복구 — sync_firestore_statuses.py 수정
- **원인**: `query_firestore()`의 1차 쿼리가 `sourceType == 'dashboard_insight'`로 필터하지만, InsuWiki 승인 시 sourceType이 변경되어 해당 문서가 쿼리 결과에서 제외됨
- **수정**: `main()` 함수의 미발견 doc_id 처리 로직(lines 175-200)을 변경
  - 1차 쿼리에서 미발견 시 → `db.collection("documents").document(doc_id).get()`으로 개별 조회
  - 문서 존재: `extract_status()`로 실제 상태 적용
  - 문서 미존재: 승인 후 삭제된 것으로 판단, status="approved" 설정
  - 조회 실패: 기존 상태 유지 (폴백)
- `recovered_count` 추적 변수 및 결과 JSON에 `sync_recovered` 필드 추가

### 작업 2: 실시간 양방향 sync 콜백 검증
- **콜백 경로 검증**: InsuWiki route.ts → `POST /api/wiki/entries/{entryId}/approve` → server.py 핸들러
  - entryId: `docData.insightEntryId || docId.split('__').pop()` (예: insight-001)
  - body: `{ status: "approved" | "rejected" }`
  - 핸들러: wiki-statuses.json + wiki-sync-status.json 동시 업데이트 + Firestore 역방향 업데이트
- **결과**: 콜백 흐름 정상 확인. body format 호환 확인.
- **보강**: approve 핸들러에 logging.info/error 3개소 추가

### 작업 3: Sync 이전 → Sync 완료 이동 시 상태 초기화 검증
- **Sync 버튼 핸들러** (server.py POST /api/wiki/sync-firestore):
  - draft 항목: `sourceType: "dashboard_insight"`, `status: "pending"`으로 Firestore 등록
  - `_wiki_sync_status[eid] = {"status": entry_status, "doc_id": doc_id}` 기록
  - 이후 InsuWiki 승인 → 콜백 → 대시보드 상태 갱신
- **결과**: 플로우 정상 확인. 초기 상태 "draft" 설정 후 콜백 수신 시 정상 갱신.

### 프론트엔드 검증
- **StatusBadge** (InsuWikiView.js:729-748): `status === 'approved' && synced` → "반영됨" (에메랄드 배지) 올바르게 구현
- **API 응답** (server.py:3481-3483): `status`는 `_wiki_statuses`에서, `synced`는 `_wiki_sync_status` 존재 여부로 결정
- **변경 불필요**

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **sync script 1차 쿼리 누락** — 개별 Firestore doc 조회 로직 추가로 해결 (sync_firestore_statuses.py:175-200)
2. **approve 핸들러 로깅 부재** — logging.info/error 3개소 추가 (server.py:6530, 6573, 6576-6577)
3. **pyright 타입 스텁 에러** — firebase_admin sync SDK의 타입 스텁 한계로 `type: ignore` 3개소 추가 (sync_firestore_statuses.py:178-181)

### 범위 외 미해결 (1건)
1. **server.py 기존 pyright 에러 10건** — 범위 외 사유: 기존 코드의 import 경로 문제, 복잡도 경고, 미사용 import. 본 작업과 무관

## 셀프 QC 체크리스트
- [x] 1. 영향 파일: sync_firestore_statuses.py, server.py (2개 파일만 수정)
- [x] 2. 엣지 케이스: doc_id 없음 → 스킵, Firestore 조회 실패 → 폴백, to_dict() None → `or {}` 처리
- [x] 3. 작업 지시 일치: 3개 작업 모두 수행 완료
- [x] 4. 에러 처리/보안: Exception 처리, entry_id 검증(../ 방어) 유지
- [x] 5. 테스트: 관련 테스트 파일 미존재 (sync script 전용 테스트 없음). python syntax 검증 OK
- [x] 6. 발견 이슈 직접 해결 3건, 범위 외 1건
- [x] 7. SOLID/DRY 위반 없음
- [x] 8. 인터페이스 변경 없음 (기존 API 유지, 결과 JSON에 필드 1개 추가만)

## 산출물
- `/home/jay/workspace/dashboard/scripts/sync_firestore_statuses.py`
- `/home/jay/workspace/dashboard/server.py`

## 검증 시나리오 결과
1. **과거 승인 18건**: sync script 수정으로 개별 Firestore 조회 → 실제 status 적용 가능 (실행은 `--dry-run`으로 사전 확인 후 수행 권장)
2. **프론트엔드 표시**: StatusBadge 로직 approved+synced → "반영됨" 정상 확인
3. **실시간 콜백**: InsuWiki → 대시보드 콜백 경로 코드 레벨 검증 PASS. body format 호환.
4. **Sync 이전 불변**: `pre_sync` 필터가 `_wiki_sync_status`에 없는 항목만 표시, sync script는 기존 105건만 순회 → 영향 없음
5. **데이터 무결성**: wiki-sync-status.json 105건 유지 (assert 검증 유지)

## QC 검증 결과

- **Overall**: WARN (8 PASS, 4 SKIP, 1 WARN)
- **test_runner**: PASS — pytest 36건 (sync 18건 + server 18건) 통과
- **pyright_check**: PASS (sync script 0 errors). server.py 기존 복잡도 에러 2건은 본 작업 범위 외
- **tdd_check**: WARN — TDD 순서 위반 (구현 먼저 수정 후 테스트 작성)
- **style_check**: PASS
- **TRUST 5**: T=pass, R=pass, U=pass, S=pass, T=pass

## 마아트 독립 검증 (critical)
- **최종 판정**: PASS
- 코드 정확성: PASS — 3분기 복구 로직(exists/not-exists/exception) 전체 검증
- 데이터 무결성: PASS — assert 불변성, 105건/106건 유지, pre_sync 보호 확인
- 콜백 흐름: PASS — entry_id 파싱, status 검증, 양 파일 + Firestore 업데이트 확인
- 테스트 커버리지: PASS — 18/18 통과 (0.09s)
- 보안/PII: PASS — 민감 정보 노출 없음
- 비기능 지적 2건: `import logging` 위치(모듈 최상단 권장), `dir()` vs `locals()` (다음 리팩터링 시 반영 권고)

## 모델 사용 기록
- 토르 (백엔드): sync_firestore_statuses.py 수정 + server.py 로깅 보강 / sonnet
- 헤임달 (테스터): 데이터 무결성 + 콜백 흐름 + 프론트엔드 검증 / sonnet
- 프레이야 (프론트엔드): 코드 변경 불필요로 미소환

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

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

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