# task-178.1 완료 보고서

## 작업 내용
CL-7 과거 약관 버전 조회 기능 구현 (P0 + P1)

에이전트 미팅 합의 결과(memory/meetings/2026-03-03-version-history-search.md)에 따라, 보험 설계사가 가입 시점의 약관을 조회할 수 있는 기능을 구현했습니다.

## 구현 항목

### P0 - 필수
1. **InsuranceChunkArchive 타입 수정** — `archiveExpireAt` 제거, `supersededByDate: string` 추가 (영구 보존)
2. **vector-search/route.ts API 변경** — `includeOldVersions` → `targetDate: string | null`로 교체, 현행/과거 검색 분기
3. **날짜 서버사이드 검증** — YYYY-MM 형식만 허용, 미래 차단, 범위 2000-01 ~ 현재월
4. **응답 버전 컨텍스트 워터마크** — targetDate 사용 시 `versionContext` 객체 삽입

### P1 - 중요
5. **버전 목록 API** — `GET /api/ai/versions?productId=xxx`, effectiveDate 내림차순, 현행/과거 구분
6. **SearchInput.tsx UI** — 조회 기준 라디오(현행/가입시점), 가입일 입력 → 버전 자동 매핑, 드롭다운
7. **AnswerCard.tsx 구버전 표시** — 상단 amber 배너 1회, 좌측 amber border, "현행 변경됨" 차등 배지
8. **과거 버전 전용 rate limit** — 분 5 / 시간 30 / 일 100 (별도 docId prefix로 분리)

## 생성/수정 파일 목록

| 파일 | 변경 유형 |
|------|-----------|
| `nextapp/src/types/firestore.ts` | 수정 — InsuranceChunkArchive 타입 변경 |
| `nextapp/src/app/api/ai/vector-search/route.ts` | 수정 — targetDate 파라미터, 과거 검색 로직, 워터마크 |
| `nextapp/src/app/api/ai/versions/route.ts` | **신규** — 버전 목록 API |
| `nextapp/src/lib/security/rateLimiter.ts` | 수정 — ARCHIVE_LIMITS, checkArchiveRateLimit 추가 |
| `nextapp/src/components/search/SearchInput.tsx` | 수정 — 조회 기준 라디오, 가입일 입력, 버전 드롭다운 |
| `nextapp/src/components/search/AnswerCard.tsx` | 수정 — versionContext 배너, amber border, 차등 배지 |
| `nextapp/src/components/search/SearchModal.tsx` | 수정 — targetDate state 추가, SearchInput props 전달 |
| `nextapp/src/__tests__/cl7-version-history.test.ts` | **신규** — 55개 테스트 |

## 테스트 결과
- **CL-7 전용 테스트**: 55개 전부 통과 (199ms)
  - validateTargetDate 검증: 18개
  - filterMetadataByDate 경계값 (EDGE-002): 12개
  - 현행/과거 분기 로직: 5개
  - Rate limit 상수 및 export: 8개
  - 타입/COLLECTIONS 상수: 9개
  - versions API 응답 형식: 13개
- **전체 회귀 테스트**: 465/490 통과
  - 실패 25개는 `feedback/__tests__/route.test.ts`의 기존 이슈 (CL-7 무관)
- **TypeScript 타입 체크**: 에러 0개

## 버그 유무
- CL-7 관련 버그 없음
- feedback 테스트 실패는 pre-existing (CL-7 수정 파일과 무관)

## 비고
- 수정 금지 파일(firestore.indexes.json, firestore.rules, pdfIndexing.ts 등) 미접촉
- 캐시 키에 targetDate 반영하여 현행/과거 캐시 분리
- versions API 응답에서 `data.versions` 접근 버그 발견 → 즉시 수정 완료

*작성: 헤르메스 (개발1팀장) / 2026-03-03*