# task-822.1 완료 보고서 — Phase 1 Go/No-Go 게이트 검증

**작업 ID**: task-822.1
**팀**: dev1-team (헤르메스)
**작업일**: 2026-03-22
**프로젝트**: insuwiki

---

## SCQA

**S**: Phase 0 + Phase 1-A가 master에 머지 완료되어, insurance_terms 사전 기반 정적 매칭(4단계) Cloud Function과 사이드바 UI가 구현된 상태다.

**C**: Go/No-Go 게이트 검증을 위해 50건 문서 대상 정적 매칭을 실행한 결과, `insurance_terms` 컬렉션이 **0건**이어서 매칭 결과가 전혀 생성되지 않았다. `config/aiLinking`과 `config/normalizeMap` 설정 문서도 Firestore에 존재하지 않으며, `links` 컬렉션도 비어있어 gold standard 기반 recall 측정도 불가능하다.

**Q**: insurance_terms 데이터 없이 정적 매칭 품질 검증이 가능한가? Phase 1-B로 진행할 수 있는가?

**A**: **Phase 1-B 진행 불가.** 정적 매칭의 전제 조건인 insurance_terms 사전 데이터가 부재하여 정확도 측정 자체가 불가능하다. insurance_terms 시딩 후 `scripts/evaluate-static-matching.ts`를 재실행하여 Go/No-Go 재판정해야 한다.

---

## 수행 내역

1. worktree 생성: `task/task-822.1-dev1` 브랜치
2. Phase 1-A 구현 코드 분석 (`staticMatching.ts`, `RelatedDocsSidebar.tsx`, firestore.ts 타입)
3. `scripts/evaluate-static-matching.ts` 검증 스크립트 작성
   - 50건 문서 로드 → findMatchingTerms 실행 → precision/recall 측정 → JSON 결과 저장
   - confidence별(100/90/85/70) 자동 검증 로직 포함
   - manual 링크 기반 gold standard recall 측정 기능 포함
4. Firestore 실 데이터 대상 평가 실행

---

## 검증 결과 (정량 데이터)

- **평가 대상**: 50개 문서 (documents 컬렉션, createdAt desc 정렬)
- **insurance_terms**: 0건 (컬렉션 비어있음)
- **config/aiLinking**: 미존재
- **config/normalizeMap**: 미존재
- **links (manual)**: 0건 (gold standard 부재)
- **총 매칭 건수**: 0건
- **Precision**: 측정 불가 (0/0)
- **Recall**: 측정 불가 (gold standard 0건)
- **판정**: Phase 1-B 진행 **불가** — 전제 조건 미충족

### Firestore 데이터 현황

- `documents`: 159건 (43건 보험 관련 키워드 포함)
- `insurance_chunks`: 72건 (PDF 인덱싱 청크, insurance_terms와 구조 상이)
- `insurance_terms`: 0건
- `links`: 0건
- `config/aiLinking`: 없음
- `config/normalizeMap`: 없음

---

## 발견 이슈 및 해결

### 범위 외 미해결 (2건)

1. **insurance_terms 컬렉션 데이터 부재** — 범위 외 사유: insurance_terms 사전 데이터 시딩은 Phase 1-A 이전 단계에서 수행되어야 하나, 현재까지 미실행. `seed-normalize-map.ts`와 `seed-ai-linking-config.ts` 스크립트는 존재하지만, insurance_terms 자체를 시딩하는 스크립트는 별도 필요.
2. **config 문서 미생성** — 범위 외 사유: Phase 1-A에서 작성된 `seed-ai-linking-config.ts`, `seed-normalize-map.ts`가 Firestore에 실행되지 않음. 시드 스크립트 실행이 필요.

### 자체 해결 (1건)

1. **evaluation 스크립트 Firebase 접근** — `NODE_PATH=./functions/node_modules` 환경변수 설정으로 firebase-admin 의존성 해결.

---

## 테스트 결과

vitest 9/9 PASS (241ms)
- verifyMatchResult: exact(100) TP/FP, alias(90) TP/FP, space(85) TP, substring(70) TP, termId 없음 — 7건 PASS
- findMatchingTerms: exact match 기본동작, 빈 terms — 2건 PASS

---

## 생성/수정 파일

- `scripts/evaluate-static-matching.ts` (신규) — Go/No-Go 평가 스크립트
- `scripts/evaluation-results.json` (신규) — 평가 결과 JSON
- `scripts/__tests__/evaluate-static-matching.test.ts` (신규) — 평가 로직 단위 테스트 9건
- `nextapp/vitest.config.ts` (수정) — scripts/__tests__ 경로 추가

---

## 후속 조치 건의

1. **insurance_terms 시딩**: insurance_chunks(72건)에서 보장명/용어를 추출하거나, 별도 보험 용어 사전을 작성하여 insurance_terms 컬렉션에 시딩 필요
2. **config 시딩 실행**: `seed-ai-linking-config.ts`, `seed-normalize-map.ts` 실행하여 설정 문서 생성
3. **재검증**: 위 시딩 후 `scripts/evaluate-static-matching.ts` 재실행하여 Go/No-Go 재판정
4. 재판정 결과 precision 80%+ 달성 시 Phase 1-B 진행

---

## 머지 판단

- **머지 필요**: Yes
- **브랜치**: task/task-822.1-dev1
- **워크트리 경로**: /home/jay/projects/insuwiki/.worktrees/task-822.1-dev1
- **머지 의견**: 검증 스크립트만 추가됨 (기존 코드 변경 없음). 충돌 가능성 0. insurance_terms 시딩 후 재사용할 스크립트이므로 머지 권장.

---

## QC 자동 검증

- **overall**: PASS (2회차)
- **시도 #1**: FAIL — tdd_check FAIL (테스트 파일 미작성), file_check FAIL (.done 미생성)
- **시도 #2**: PASS — 테스트 추가 후 6 PASS, 6 SKIP
- file_check: PASS (스크립트 22987B, 테스트 17138B, 보고서 4768B)
- tdd_check: PASS (테스트+구현 파일 모두 존재)
- data_integrity: PASS
- critical_gap: PASS
- spec_compliance: PASS
- duplicate_check: PASS (최대 유사도 10.9%)