# 🔍 검색 기능 UI/UX 심층 개선 — 전체 에이전트 회의록

> **일시**: 2026-02-16 13:39
> **참석자**: PM, Planner, UX, Frontend, Backend, Data, QA, Legal, Reflect
> **안건**: 일반 검색 & AI 검색 UI/UX 전면 개선 방안 심층 검토

---

## 📋 회의 배경

현재 `SearchModal.tsx`에 구현된 2가지 검색 기능:

| 모드 | 방식 | 현재 상태 |
|------|------|-----------|
| **일반 검색** | 클라이언트 측 키워드 매칭 (초성/한글 지원) | 기본 동작 |
| **AI 매직 검색** | Gemini API 시맨틱 임베딩 + RAG 답변 | BYOK 기반 |

부장님 평가: **"UI/UX 측면에서 개선 가능한 부분이 너무 많이 보인다."**

---

## 🗣️ 에이전트별 발언

### 1. 🎯 PM (Project Manager)

> "이번 회의의 목표는 **빠르게 구현 가능한 Quick Win**과 **중장기 과제**를 분리하는 것입니다."

**현황 진단:**
- 검색 모달이 단일 컴포넌트(474줄)에 모두 집중 → 유지보수 어려움
- 일반 검색과 AI 검색의 UX 흐름이 완전히 다른데 같은 UI 안에 공존
- 모바일 대응이 `sm:` 브레이크포인트 하나로만 처리되어 세밀함 부족

**제안:**
1. 컴포넌트 분리: `SearchModal` → `SearchInput` + `NormalResults` + `AIResults` + `APIKeyGuide`
2. 개선 우선순위를 **MoSCoW**로 분류하여 Phase별 진행

---

### 2. 📐 Planner (기획 전문가)

> "사용자 플로우를 보면, **검색 → 결과 확인 → 문서 이동** 이 3단계에서 마찰이 너무 많습니다."

**핵심 문제점 분석:**

| # | 문제 | 심각도 | 영향 범위 |
|---|------|:------:|-----------|
| 1 | 검색 모드 전환 시 기존 입력값이 유지되지만 결과가 초기화됨 | 🟡 | UX 혼란 |
| 2 | AI 검색 결과가 나오기까지 **로딩 상태 피드백 부족** (단순 "분석 중..." 텍스트) | 🔴 | 사용자 이탈 |
| 3 | 일반 검색 결과에 **카테고리/태그 필터**가 없어 문서가 많아지면 탐색 어려움 | 🟡 | 확장성 |
| 4 | 검색 히스토리 없음 → 동일 검색 반복 | 🟢 | 편의성 |
| 5 | AI 답변에 대한 **후속 질문(Follow-up)** 불가 | 🔴 | 기능 완성도 |
| 6 | 검색 결과 0건일 때 **대안 제시** 없음 ("이런 걸 찾으셨나요?") | 🟡 | 전환율 |

**유저 플로우 개선안:**
```
[현재] 모달 열기 → 탭 선택 → 입력 → 결과 확인 → 클릭
[개선] 모달 열기 → 즉시 타이핑 → 실시간 결과 + AI 추천 동시 표시 → 클릭
```

---

### 3. 🎨 UX (사용자 경험 전문가)

> "현재 UI는 '검색 도구'처럼 보입니다. **'지식 탐색 허브'**로 전환해야 합니다."

**UI/UX 심층 리뷰:**

#### 🔴 Critical (즉시 개선 필요)

1. **탭 전환 UX가 직관적이지 않음**
   - "일반 검색" / "AI IntelliSearch" 라벨이 기능 차이를 설명하지 못함
   - 사용자가 "왜 두 개가 있지?"라는 의문 → **통합된 하나의 검색 경험** 제안
   - 💡 **제안**: 기본은 일반 검색, 결과 없거나 질문형 입력 시 **자동으로 AI 전환 유도**

2. **검색 입력창 디자인**
   - 모바일에서 검색 아이콘 + 입력창 + 매직 검색 버튼이 한 줄에 빽빽함
   - 💡 **제안**: 매직 검색 버튼을 입력창 아래로 분리하여 **풀 너비 CTA** 버튼으로 배치

3. **결과 스크롤 영역 너무 작음** (`max-h-[60vh]`)
   - 키보드가 올라오는 모바일에서 실제 사용 가능한 영역이 30% 미만
   - 💡 **제안**: 모바일에서는 `100dvh` 전체 화면 모드 + 결과 영역 극대화

#### 🟡 Important (개선 권장)

4. **AI 답변 카드 가독성**
   - 진한 indigo 배경에 흰 텍스트 → 장문 답변 시 눈 피로
   - 💡 **제안**: 밝은 배경 + 마크다운 렌더링 (볼드, 리스트 등)

5. **출처(Sources) 표시 방식**
   - 2열 그리드가 모바일에서 텍스트 잘림 발생
   - 💡 **제안**: 모바일에서는 1열 리스트 + 관련도 뱃지

6. **Empty State 개선**
   - 검색 전 초기 화면이 "궁금한 보험 지식을 물어보세요!" 한 줄 뿐
   - 💡 **제안**: 인기 검색어, 최근 본 문서, 추천 질문을 함께 표시

#### 🟢 Nice to Have

7. **검색 애니메이션**: 결과 진입 시 stagger 애니메이션 적용
8. **다크모드 대응**: 현재 라이트 모드만 지원
9. **키보드 네비게이션**: ↑↓ 키로 결과 간 이동은 있지만 시각적 하이라이트 부재

---

### 4. 💻 Frontend (프론트엔드 전문가)

> "474줄짜리 단일 컴포넌트는 리팩토링이 시급합니다."

**기술적 개선 사항:**

| 영역 | 현재 | 개선안 |
|------|------|--------|
| 컴포넌트 구조 | 단일 파일 474줄 | 5~6개 서브 컴포넌트로 분리 |
| 상태 관리 | `useState` 11개 | `useReducer` 또는 커스텀 훅으로 통합 |
| 디바운싱 | 미적용 (타이핑마다 전체 필터링) | `useDeferredValue` 또는 300ms 디바운스 |
| 접근성 | `role`, `aria-*` 속성 부재 | Combobox 패턴 (WAI-ARIA) 적용 |
| 키보드 | 기본 이벤트만 처리 | `Tab`, `Esc`, `Enter` 풀 지원 |
| 렌더링 | 전체 문서 로드 후 클라이언트 필터링 | 가상 스크롤 (`react-window`) 적용 검토 |

**컴포넌트 분리 제안:**
```
SearchModal/
├── index.tsx           (모달 shell + 상태 관리)
├── SearchInput.tsx     (입력창 + 모드 전환)
├── NormalResults.tsx   (일반 검색 결과 리스트)
├── AIResults.tsx       (AI 답변 + 출처 표시)
├── APIKeyGuide.tsx     (API 키 안내 카드)
├── EmptyState.tsx      (초기/빈 결과 상태)
└── hooks/
    └── useSearchState.ts (통합 상태 관리)
```

---

### 5. ⚙️ Backend (백엔드 전문가)

> "현재 일반 검색이 **클라이언트에서 전체 문서를 로드**하고 있습니다. 문서가 100개만 넘어도 성능 문제가 생깁니다."

**성능 및 아키텍처 문제:**

1. **일반 검색: 클라이언트 전체 로드 문제**
   - `getDocs(query(collection(db, 'documents'), orderBy('updatedAt', 'desc'), limit(50)))` → 매번 50개 로드
   - 💡 **제안**: Firestore 서버사이드 텍스트 검색 또는 Algolia/Typesense 연동

2. **AI 검색: API 호출 최적화**
   - 현재 매 검색마다 임베딩 생성 → 비용 누적
   - 💡 **제안**: 임베딩 캐싱 + 유사 질문 감지로 재활용

3. **API 에러 핸들링 부족**
   - Gemini API 장애 시 사용자에게 구체적 안내 부재
   - 💡 **제안**: 에러 유형별 사용자 친화적 메시지 + 재시도 버튼

---

### 6. 🗂️ Data (데이터 전문가)

> "검색 품질을 높이려면 **데이터 레이어에서의 개선**이 필수입니다."

**데이터 관점 개선안:**

1. **검색 인덱스 구축**
   - 현재: 제목(title)과 본문(content)에서 단순 문자열 매칭
   - 개선: 태그, 카테고리, 작성자 메타데이터를 활용한 **패싯 검색(Faceted Search)**

2. **자동완성(Autocomplete) 데이터**
   - 문서 제목 + 자주 검색되는 키워드 → Trie 또는 Prefix 인덱스 구축
   - 타이핑 즉시 추천 결과 표시

3. **검색 로그 수집**
   - 사용자 검색어 패턴 분석 → 인기 검색어, 검색 실패 키워드 파악
   - 향후 검색 품질 개선의 데이터 기반 마련

4. **문서 임베딩 사전 생성**
   - AI 검색 시 실시간 임베딩 생성 대신, 문서 저장 시점에 임베딩 미리 생성하여 저장
   - 검색 응답 시간 대폭 단축

---

### 7. 🧪 QA (품질 보증 전문가)

> "검색 기능에 대한 **테스트 커버리지가 0%**입니다. 개선 전에 테스트부터 작성해야 합니다."

**품질 이슈:**

| 카테고리 | 이슈 | 위험도 |
|----------|------|:------:|
| 접근성 | `input`에 `aria-label` 없음 | 🔴 |
| 접근성 | 검색 결과에 `role="listbox"` 패턴 미적용 | 🟡 |
| 보안 | API 키가 클라이언트에서 직접 Gemini API 호출에 사용됨 | 🟡 |
| 성능 | 검색 시 전체 문서 50개를 매번 로드 | 🔴 |
| 에러 | 네트워크 오류 시 무한 로딩 상태 가능 | 🔴 |
| UX | 검색 결과 0건 시 돌아갈 수 없는 상태 없음 | 🟡 |

**테스트 계획:**
- [ ] 일반 검색: 한글, 초성, 영문 혼합 검색 테스트
- [ ] AI 검색: API 키 유/무, 네트워크 오류 시나리오
- [ ] 모바일: 다양한 뷰포트에서 레이아웃 깨짐 테스트
- [ ] 접근성: 스크린 리더 호환성 검증
- [ ] 성능: 문서 100개 이상 환경에서의 응답 속도

---

### 8. ⚖️ Legal (법률 전문가)

> "AI 검색 결과에 대한 **면책 조항이 빠져 있습니다.**"

**법적 리스크:**

1. **AI 답변 면책 부재** 🔴
   - AI가 생성한 보험 관련 답변은 법적 조언으로 오해될 수 있음
   - 💡 **필수**: AI 답변 하단에 면책 문구 표시
   - 예: *"본 답변은 AI가 위키 문서를 기반으로 생성한 참고 정보이며, 정확한 보험 상담은 전문 설계사에게 문의해주세요."*

2. **API 키 보관 정책** 🟡
   - 사용자 개인 API 키를 `localStorage`에 저장 중
   - 💡 **제안**: 키 마스킹 표시 + 세션 만료 시 자동 삭제 옵션 안내

3. **검색 로그 수집 시 개인정보** 🟡
   - Data팀이 제안한 검색 로그 수집 시 개인정보보호법 준수 필요
   - 검색어 자체가 개인정보를 포함할 수 있음 → 익명화 처리 필수

---

### 9. 🧠 Reflect (지식 관리 전문가)

> "현재 검색은 '찾기 도구'입니다. Reflect 철학에 맞게 **'지식 탐색 경험'**으로 진화시켜야 합니다."

**Frictionless 원칙 기반 개선안:**

1. **Zero Friction 검색 진입**
   - 현재: 돋보기 클릭 → 모달 열기 → 탭 선택 → 타이핑
   - 개선: `Cmd/Ctrl + K` → **즉시 타이핑 시작** (탭 구분 없이 하이브리드 검색)

2. **하이브리드 검색 솔루션** ⭐
   - 일반/AI를 사용자가 직접 선택하지 않고, **시스템이 자동 판단**
   - 단순 키워드 → 즉시 일반 검색 결과 표시
   - 질문형 입력 ("~해줘", "~뭐야?") 감지 시 → AI 검색 자동 활성화 + 일반 결과도 함께 표시

3. **Knowledge Graph 연동**
   - 검색 결과에 **관련 문서 네트워크** 시각화
   - "이 문서를 참조하는 다른 문서" 표시 = 양방향 백링크 활용

4. **대화형 검색 (Follow-up)**
   - AI 답변에 대해 **추가 질문** 가능하도록 확장
   - 대화 맥락 유지 → 점점 깊은 탐색 가능

---

## 📊 종합 개선안 우선순위 (MoSCoW)

### 🔴 Must Have (Phase 1 — 즉시)
| # | 개선 항목 | 담당 | 난이도 |
|---|-----------|------|:------:|
| M1 | AI 답변 하단 면책 조항 추가 | Legal + Frontend | ⭐ |
| M2 | 검색 로딩 상태 개선 (스켈레톤/프로그레스) | Frontend + UX | ⭐⭐ |
| M3 | 모바일 결과 영역 확대 (전체화면 모드) | Frontend | ⭐⭐ |
| M4 | AI 검색 에러 핸들링 강화 | Backend + Frontend | ⭐⭐ |
| M5 | 접근성(a11y) 기본 속성 추가 | Frontend + QA | ⭐ |

### 🟡 Should Have (Phase 2 — 1~2주)
| # | 개선 항목 | 담당 | 난이도 |
|---|-----------|------|:------:|
| S1 | 컴포넌트 리팩토링 (5~6개 분리) | Frontend + PM | ⭐⭐⭐ |
| S2 | 검색 디바운싱 + 성능 최적화 | Frontend | ⭐⭐ |
| S3 | Empty State 개선 (추천 질문, 인기 검색) | UX + Frontend | ⭐⭐ |
| S4 | AI 답변 마크다운 렌더링 | Frontend | ⭐⭐ |
| S5 | 출처 표시 모바일 1열 레이아웃 | Frontend + UX | ⭐ |

### 🟢 Could Have (Phase 3 — 1개월)
| # | 개선 항목 | 담당 | 난이도 |
|---|-----------|------|:------:|
| C1 | 하이브리드 검색 (자동 모드 판단) | Reflect + Backend + Frontend | ⭐⭐⭐⭐ |
| C2 | 자동완성 / 검색어 추천 | Data + Backend + Frontend | ⭐⭐⭐ |
| C3 | 대화형 AI 검색 (Follow-up) | Backend + Reflect | ⭐⭐⭐⭐ |
| C4 | 검색 로그 수집 및 분석 | Data + Legal | ⭐⭐⭐ |
| C5 | 다크모드 대응 | Frontend | ⭐⭐ |

### ⬜ Won't Have (defer)
- 풀 Elasticsearch 도입 (현재 문서 수 대비 과투자)
- 음성 검색 UI 통합 (별도 기능으로 분리 유지)
- Knowledge Graph 시각화 (별도 페이지로 구현 권장)

---

## 🎬 다음 단계 (Action Items)

1. ~~**부장님 리뷰**: 우선순위 동의 여부 확인~~ ✅ 완료
2. ~~**Phase 1 구현 계획서** 작성 (approval 후 즉시 착수)~~ ✅ 완료 & 배포
3. ~~**리팩토링 설계**: 컴포넌트 분리 방안 상세 설계~~ ✅ Phase 2 완료 & 배포
4. **Phase 3** (Could Have): 하이브리드 검색, 자동완성, 대화형 AI 등 — 미정

> **[2026-02-16 15:05 추가]** 🎙️ 음성 검색 UI 통합이 별도로 완료되었습니다.
> - `SearchInput.tsx`에 마이크 버튼 추가 (음성 → 자동 검색)
> - 모바일 최적화 (Android Chrome / iOS Safari 14.5+)
> - 커밋: `97a7e75`, `f4878a1`

---

> 🤖 Generated with InsuWiki Agent Meeting System

---

## ⚠️ 추가 맥락: 설계사 전용 서비스

> **부장님 지시 (2026-02-16 13:44)**: InsuWiki는 **우리 사업단 소속 보험 설계사**들을 위한 내부 서비스. 안내 문구 및 기능 설계 시 이 맥락을 반드시 반영할 것.

### 적용 방향

| 영역 | 현재 (일반적) | 개선 (설계사 맞춤) |
|------|-------------|-------------------|
| 검색 placeholder | "찾으려는 문서 제목이나 키워드 입력..." | "약관, 상품, 판매 노하우 검색..." |
| AI placeholder | "질문해 보세요" | "고객 상담에 필요한 지식을 질문해 보세요" |
| Empty State | "궁금한 보험 지식을 물어보세요!" | "상담·판매에 필요한 지식을 찾아보세요!" |
| AI 면책 조항 | "전문 설계사에게 문의해주세요" | "본 AI 답변은 참고용이며, 정확한 내용은 약관 원문을 확인해 주세요." |
| 추천 질문 예시 | 일반 보험 질문 | "○○보험 면책기간?", "환급률 비교", "CI vs 건강보험 차이" |
| AI 답변 톤 | 일반 정보 전달 | 전문적이면서도 고객에게 바로 설명 가능한 수준 |