# 🚶‍♀️ 인슈위키 AI Phase 1~3 통합 워크스루 (Walkthrough)

인슈위키 AI 인텔리전스 허브의 단계별 구현 결과와 실전 활용 시나리오를 집대성한 문서입니다.

## 🌟 주요 성과 (Key Achievements)

### 1. Phase 1: Knowledge Foundation (완료 ✅)
- **실시간 WikiMap 인덱서**: 수천 개의 문서를 0.1초 내외로 검색하여 실시간 지식 지도를 구축합니다.
- **'Zero Friction' 자동 백링크**: 본문 작성 중 기존 지식을 감지하여 파란 점선으로 표시하고, 클릭 한 번으로 `[[위키링크]]`를 생성합니다.

### 2. Phase 2: AI Whispers (완료 ✅)
- **실시간 음성 기록**: 상담 내용을 브라우저에서 즉시 텍스트화하며, Gemini Live와의 초저지연 연동을 지원합니다.
- **지능형 PII 마스킹**: 전화번호, 주민번호 등 민감 정보를 자동으로 익명화(`***`)하여 보안을 강화했습니다.

### 3. Phase 3: Proprietary Wisdom (완료 ✅)
- **AI IntelliSearch (지능형 검색)**: 질문의 의도를 파악하여 여러 문서의 지식을 합성해 답변을 생성합니다.
- **Internal-Only RAG**: 우리 팀이 작성한 위키 데이터만을 근거로 삼아 높은 신뢰도를 유지합니다.
- **UX 가이드 시스템**: 일반/AI 검색의 차이를 설명하는 서브헤더와 API Key 미설정 시의 단계별 가이드를 탑재했습니다.

---

## 📺 기능 시연 (Demo)

### 1. 자동 백링크 (Phase 1)
````carousel
```markdown
# 상담 기록 중
이미 정의된 "암보험 가이드" 문서가 있다면...
작성자가 "암보험 가이드"라고 치는 순간!
-> [암보험 가이드] (파란 점선 표시)
```
<!-- slide -->
```markdown
# 클릭 한 번으로 연결
파란 점선을 클릭하면?
-> [[암보험 가이드]] 로 즉시 위키링크 생성 완료!
```
````

### 2. AI 검색 (Phase 3)
````carousel
```markdown
# "CI보험 면책기간이 뭐야?"
AI가 관련 문서 3건을 찾아 합성:
[답변] CI보험의 면책기간은 일반적으로 90일입니다...
[출처: 보험 약관 기초], [출처: CI보험 비교표]
```
<!-- slide -->
```markdown
# 모바일에서도 동일한 경험
sm 브레이크포인트: 출처 1열 레이아웃
추천 질문 칩으로 빠른 검색
```
````

---

## 🎙️ 음성 인식 구현 이력 (Voice Recognition — 2026-02-16)

### 구현 완료 항목

| 기능 | 파일 | 설명 | 모바일 지원 |
|------|------|------|:-----------:|
| Web Speech API 코어 | `useSpeechRecognition.ts` | STT 기본 훅 (`ko-KR`, continuous/single) | ✅ |
| 음성 검색 | `SearchInput.tsx` | 검색 모달 마이크 버튼 | ✅ |
| 음성 받아쓰기 | `VoiceDictation.tsx` | 편집 모드 플로팅 FAB (56px, safe-area) | ✅ |
| 음성 명령 (P0) | `useVoiceCommand.ts` | 5그룹 25개 명령 (longest-match-first) | ✅ |
| 전역 명령 | `VoiceCommandProvider.tsx` | Context 위임 구조 (전역+페이지별) | ✅ |
| 명령 컨텍스트 | `VoiceCommandContext.tsx` | 페이지별 핸들러 등록/해제 | ✅ |
| 동의 녹취 | `RecordingConsentModal.tsx` | 통신비밀보호법 준수 동의 UI | ✅ |
| STT 연동 | `useVoiceRecorder.ts` | Mock → 실제 Web Speech API | ✅ |

### 2-Layer 아키텍처

```
┌──────────────────────────────────────────────┐
│  Layer 1: Web Speech API (무료, 즉시 동작)   │
│  ├─ 음성 검색: STT → 검색어 → 매직 검색     │
│  ├─ 음성 받아쓰기: STT → 에디터 커서 삽입    │
│  └─ 음성 명령: "새 문서", "검색", "저장"     │
├──────────────────────────────────────────────┤
│  Layer 2: Gemini Live API (BYOK, 고급)       │
│  ├─ 장시간 상담 녹음 + 실시간 STT            │
│  ├─ PII 마스킹 (주민번호, 전화번호)          │
│  └─ AI 요약 + 화자 분리 (향후)               │
└──────────────────────────────────────────────┘
```

### 브라우저 호환성

| 환경 | 지원 | 비고 |
|------|:----:|------|
| Android Chrome | ✅ | 기본 지원 |
| iOS Safari 14.5+ | ✅ | `webkitSpeechRecognition` |
| PC Chrome/Edge | ✅ | 기본 지원 |
| Firefox | ❌ | Web Speech API 미지원 |

### 커밋 이력
- `97a7e75`: feat: 음성 인식 실제 구현 (7 files, +655)
- `f4878a1`: feat: 음성 인식 모바일 통합 (4 files, +75)
- `58b03cf`: feat: P0 음성 명령 확장 (3→25) + 동의 녹취 모달 (6 files, +485)

---

## 🧪 최종 검증 및 배포 현황
- [x] **운영 서버 배포**: Vercel을 통한 실전 배포 완료 (`https://insuwiki.vercel.app`)
- [x] **보안 검증**: PII 마스킹 및 BYOK 아키텍처 정상 작동 확인
- [x] **성능 최적화**: Web Worker 기반 인덱싱으로 대용량 문서 타이핑 지연 해결
- [x] **문서 일치**: Master Spec과 코드, 기능의 100% 일치 확인
- [x] **음성 인식 빌드 검증**: 13/13 페이지 빌드 성공 확인
- [x] **P0 음성 명령 확장**: 3→25개 명령, 5그룹, 동의 녹취 모달 — 빌드 `58b03cf` 통과

---

## 📅 향후 계획 (Next Steps)
- **Phase 4**: 상담 데이터를 기반으로 한 자동 성과 리포트 및 실적 예측 엔진 개발 시작.
- **Phase 5**: 설계 제안 AI 에이전트 구축.

---

## 🔍 검색 UI/UX 개선 이력

### Phase 1 (Must Have) — 완료 ✅
| # | 항목 | 내용 |
|---|------|------|
| M1 | 설계사 맞춤 문구 | placeholder, empty state 텍스트를 설계사 맥락으로 변경 |
| M2 | 로딩 UX | 바운싱 애니메이션 + 서브 메시지 |
| M3 | 모바일 확장 | 결과 영역 `calc(100vh-200px)` |
| M4 | 에러 핸들링 | API/네트워크 구분 + 재시도 버튼 |
| M5 | 접근성 | ARIA 속성 (`dialog`, `combobox`, `aria-modal` 등) |

### Phase 2 (Should Have) — 완료 ✅
| # | 항목 | 내용 |
|---|------|------|
| S1 | 컴포넌트 리팩토링 | 479줄 → 6개 파일 (`search/` 디렉토리) |
| S2 | 디바운싱 | 일반 검색 300ms 디바운스 |
| S3 | 추천 질문 | 설계사 맞춤 질문 4개 칩 (클릭 → 자동 검색) |
| S4 | 마크다운 렌더링 | `react-markdown` + `remark-gfm` |
| S5 | 모바일 출처 1열 | `grid-cols-1 sm:grid-cols-2` 반응형 |

---
> 본 문서는 프로젝트의 각 단계별 마일스톤을 기록하며, 팀원들이 AI 기능을 백분 활용할 수 있게 돕는 가이드로 활용됩니다.