# task-173.1 완료 보고서
## 약관AI Phase 2 잔여 — CL-10 특약 경고 + 상품명 자동완성 + CL-7 피드백 UI

**팀**: 개발1팀 (헤르메스 팀장)
**수행일**: 2026-03-03
**상태**: 완료

---

## 작업 내용

### 작업 1: CL-10 특약 가입 확인 경고 (3중 방어)

**1-1. 시스템 프롬프트 방어**
- `functions/src/ragQuery.ts` 시스템 프롬프트에 규칙 7번 추가
- 특약 관련 키워드 포함 시 "이 특약에 가입되어 있는지 보험증권을 확인하세요" 볼드 삽입 지시

**1-2. UI 경고 배너**
- `AnswerCard.tsx`에 amber 색상 경고 배너 추가 (선택특약/추가특약/특별약관/선택담보 감지)
- 답변 본문 내 특약 키워드 인라인 하이라이트 (`highlightRiderKeywords`) + 경고 아이콘

**1-3. 출력 필터 보강**
- `answerValidator.ts`에 `appendRiderWarning()` 함수 추가
- 특약 키워드 감지 시 경고 문구 자동 append, 중복 삽입 방지 로직 포함

### 작업 2: 상품명 자동완성

**2-1. 자동완성 API**
- `nextapp/src/app/api/ai/autocomplete/route.ts` 신규 생성
- GET /api/ai/autocomplete?q= — insurance_metadata에서 productName/companyName 검색
- 한글 초성 검색 지원 (getChoseong 활용)
- isActive=true 필터, 최대 10건 반환

**2-2. SearchInput 자동완성 UI**
- debounce(300ms) 후 autocomplete API 호출
- absolute positioned 드롭다운 리스트
- 키보드 네비게이션 (ArrowUp/Down, Enter 선택, Escape 닫기)
- onBlur 시 자동 닫힘

### 작업 3: CL-7 피드백 UI

**3-1. FeedbackButtons 컴포넌트**
- `nextapp/src/components/search/FeedbackButtons.tsx` 신규 생성
- "정확해요 👍" → POST rating: "positive"
- "틀렸어요 👎" → 인라인 오답 유형 선택 확장 (면책 누락/상품 혼동/구버전 참조/기타)
- 자유 텍스트 입력, 제출/취소, 토스트 메시지

**3-2. 피드백 API 개선**
- POST 핸들러 교체: { queryId, rating, errorType, freeText, query, answer }
- `ai_feedback` 컬렉션 저장 (기존 answer_feedback과 별도)
- uid+queryId 중복 방지, freeText 500자 제한, HTML 태그 제거

**3-3. AnswerCard 통합**
- queryId prop 추가 시 FeedbackButtons 컴포넌트 렌더링
- 기존 logId/onFeedback은 deprecated로 유지 (하위 호환)

---

## 생성/수정 파일 목록

| 파일 | 구분 |
|------|------|
| functions/src/ragQuery.ts | 수정 (시스템 프롬프트 규칙 7 추가) |
| nextapp/src/lib/ai/answerValidator.ts | 수정 (appendRiderWarning 추가) |
| nextapp/src/components/search/AnswerCard.tsx | 수정 (특약 배너 + FeedbackButtons 통합) |
| nextapp/src/components/search/SearchInput.tsx | 수정 (자동완성 드롭다운) |
| nextapp/src/app/api/ai/feedback/route.ts | 수정 (POST CL-7 형식) |
| nextapp/src/types/firestore.ts | 수정 (AiFeedback 타입 + AI_FEEDBACK 컬렉션) |
| nextapp/src/app/api/ai/autocomplete/route.ts | **신규** |
| nextapp/src/components/search/FeedbackButtons.tsx | **신규** |
| nextapp/src/app/api/ai/autocomplete/__tests__/route.test.ts | **신규** (테스트) |
| nextapp/src/components/search/__tests__/FeedbackButtons.test.tsx | **신규** (테스트) |
| nextapp/src/lib/ai/answerValidator.test.ts | 수정 (appendRiderWarning 테스트 추가) |

---

## 테스트 결과

- **answerValidator.test.ts**: 43개 통과 (기존 37 + CL-10 신규 6)
- **autocomplete/route.test.ts**: 12개 통과 (인증, 파라미터, 검색, 초성, 최대건수 등)
- **FeedbackButtons.test.tsx**: 22개 통과 (렌더링, 클릭, 오답유형, 제출, 에러)
- **총 77개 테스트 전부 통과**

---

## 셀프 QC 결과

1. **다른 파일 영향**: AnswerCard에 optional props 추가로 하위 호환 유지. 기존 PATCH 핸들러 보존.
2. **엣지 케이스**: 빈 쿼리, 특수문자, 초성, 중복 피드백, 경고 중복 삽입 — 모두 처리됨.
3. **작업 지시 일치**: CL-10 3중 방어, 자동완성 API+UI, CL-7 피드백 UI — 모두 구현 완료.
4. **에러 처리/보안**: XSS 방지(stripHtmlTags), 인증(verifyAuth), 입력 검증, 중복 방지.
5. **테스트 커버리지**: 77개 테스트로 정상/에러/엣지 경로 전체 커버.

---

## 버그/이슈

- 없음

## 비고

- 기존 feedback POST 테스트(route.test.ts)는 이전 POST 형식 기반으로 작성되어 있어, 새 POST 형식과 불일치합니다. 2팀(admin) 담당 파일이므로 직접 수정하지 않았습니다. 후속으로 기존 테스트 업데이트 필요합니다.
- FeedbackButtons 컴포넌트는 rating으로 `positive`/`negative` 전송 (API 스펙과 일치).