# task-2232 완료 보고서: InsuRo → InsuWiki 소식지 데이터 연계

**팀**: dev4-team (비슈누 팀장)
**작업 레벨**: Lv.4
**날짜**: 2026-04-27

---

## SCQA

**S**: InsuRo에서 소식지/보험료 PDF를 업로드하면 텍스트 추출 + AI 분석이 수행되지만, 이 데이터가 InsuWiki에서는 활용되지 않는다.

**C**: 보험사별 최신 소식지 정보를 InsuWiki 사용자도 확인하고 싶지만, 두 시스템 간 데이터 연계가 없어 별도 수작업이 필요하다.

**Q**: InsuRo → InsuWiki 단방향 push로 소식지 데이터를 자동 연계할 수 있는가?

**A**: BackgroundTasks + httpx.AsyncClient로 InsuRo 업로드 완료 시 InsuWiki API에 자동 push. API 키 인증 + 스키마 검증 + Firestore Admin SDK 전용 저장. 양쪽 빌드 성공, 인증 차단 확인. 마아트 FAIL 2건 즉시 수정 완료.

---

## 수정 파일 목록

### InsuWiki (worktree: task/task-2232-dev4)

| 파일 | 변경 내용 | grep 검증 | 상태 |
|------|-----------|-----------|------|
| nextapp/src/app/api/newsletter-sync/route.ts (신규) | POST 수신 API: API 키 인증 + 6필드 스키마 검증 + Firestore 저장 | grep "newsletter_updates" OK (4건) | verified |
| nextapp/src/components/NewsletterUpdates.tsx (신규) | Server Component: 보험사별 그룹화 + 최신순 + 펼치기 | grep "NewsletterUpdates" OK | verified |
| firestore.rules | newsletter_updates 컬렉션 Admin SDK 전용 규칙 | grep "newsletter_updates" OK (2건) | verified |

### InsuRo (worktree: task/task-2232-dev4)

| 파일 | 변경 내용 | grep 검증 | 상태 |
|------|-----------|-----------|------|
| server/main.py:3590 | upload_to_drive에 BackgroundTasks 파라미터 추가 | grep "background_tasks: BackgroundTasks" OK | verified |
| server/main.py:3703-3725 | InsuWiki sync 코드 (DB에서 추출 텍스트 재조회 포함) | grep "sync_text" OK (5건) | verified |
| server/main.py:3735-3760 | _push_to_insuwiki 함수 (httpx.AsyncClient + 상태 검사) | grep "_push_to_insuwiki" OK (2건) | verified |
| server/.env.example | INSUWIKI_SYNC_URL, INSURO_SYNC_API_KEY 추가 | grep "INSUWIKI_SYNC_URL" OK | verified |

---

## 발견 이슈 및 해결

### 이슈 1: extracted_text push 빈 값 문제 (자체 발견)
- **발견**: AI 파싱 분기에서 `extracted_text` Form 파라미터가 빈 값인 경우, push에도 빈 텍스트 전달
- **해결**: parse_result에 extracted_text_length 키가 있으면 DB에서 추출 텍스트 재조회
- **커밋**: 7e38013

### 이슈 2: getFirestore() 인자 불일치 (마아트 FAIL-1)
- **발견**: NewsletterUpdates.tsx에서 `getFirestore()` 인자 없이 호출 → Mock 환경 런타임 에러 가능
- **해결**: `const app = getFirebaseAdmin(); const db = getFirestore(app);` 패턴 통일
- **커밋**: 6d1941d

### 이슈 3: source_id 필드 미저장 (마아트 FAIL-2)
- **발견**: route.ts의 Firestore set()에 source_id 필드 누락 → 역참조 불가
- **해결**: `source_id: source_id as string` 필드 추가
- **커밋**: 6d1941d

### 이슈 4: HTTP 응답 상태 미검사 (마아트 WARN)
- **발견**: _push_to_insuwiki에서 4xx/5xx 응답을 info로만 기록
- **해결**: 400+ 응답 시 logger.warning으로 레벨 구분
- **커밋**: fd709df

---

## 빌드 결과

- InsuRo: `npm run build` 성공 (12.13s, dist/sw.js 포함)
- InsuWiki: `npm run build` 성공 (TypeScript 컴파일 + Static Pages 생성, /api/newsletter-sync 라우트 확인)

---

## L1 스모크테스트 결과

- 서버 재시작: 성공 (InsuRo 8099포트, InsuWiki 3099포트)
- API 응답 확인:
  - InsuRo OpenAPI 스펙: upload-to-drive 엔드포인트 존재, background_tasks 파라미터 미노출 (자동 주입)
  - InsuWiki newsletter-sync: API 키 없이 호출 → 401 Unauthorized 정상 차단
- 스크린샷: 해당없음 (API 백엔드 작업)

---

## 마아트 독립 검증 결과

- 검증일: 2026-04-27
- PASS: 9건 (보안, 단방향 push, 비동기 패턴, 입력 검증 등)
- FAIL: 2건 → 즉시 수정 완료 (getFirestore 인자, source_id 필드)
- WARN: 3건 → 1건 수정 (HTTP 상태 검사), 2건 참고 (sync_text 순서 의존, extracted_text_length 조건)

---

## 머지 판단

### InsuRo
- **머지 필요**: Yes
- **브랜치**: task/task-2232-dev4
- **워크트리 경로**: /home/jay/projects/InsuRo/.worktrees/task-2232-dev4
- **머지 의견**: 빌드 성공, 서버 시작 확인, 마아트 검증 FAIL 모두 수정. push 실패 시 업로드 비영향 보장됨. 환경변수 미설정 시 push 자동 스킵.

### InsuWiki
- **머지 필요**: Yes
- **브랜치**: task/task-2232-dev4
- **워크트리 경로**: /home/jay/projects/insuwiki/.worktrees/task-2232-dev4
- **머지 의견**: TypeScript 컴파일 성공, API 인증 차단 확인, Firestore rules 클라이언트 차단 확인.

---

## 환경변수 설정 필요 (배포 전)

양쪽에 동일한 `INSURO_SYNC_API_KEY` 값을 설정해야 합니다:
- InsuRo: `server/.env` → `INSURO_SYNC_API_KEY=<UUID>`, `INSUWIKI_SYNC_URL=https://insuwiki.vercel.app/api/newsletter-sync`
- InsuWiki: Vercel 환경변수 → `INSURO_SYNC_API_KEY=<UUID>`

---

## Codex 사전 검증

- 결과: PASS
- 파일: /home/jay/workspace/memory/events/task-2232.codex-gate
- 반영: httpx.AsyncClient + BackgroundTasks 사용, 복합 키, 스키마 검증 추가

---

## 모델 사용 기록

- 카르티케야 (백엔드): sonnet — Phase 1+2 구현 (API Route, push 함수, firestore rules, .env)
- 사라스바티 (프론트엔드): sonnet — Phase 3 구현 (NewsletterUpdates Server Component)
- 마아트 (QC): sonnet — 독립 검증 (5개 파일 리뷰)
- 비슈누 (팀장): opus — 설계, 검토, 통합, 이슈 수정

---

## 3문서 상태

- plan.md: in-progress → completed
- context-notes.md: 3 Step Why + Codex 반영 설계 변경 기록
- checklist.md: 12/14 완료 (QC + 최종 보고 잔여)

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


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


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


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


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


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


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