# 한글 초성 검색(Initial Consonant Search) 기능 구현 회의록

> **일시**: 2026-02-23 01:57
> **참석자**: PM, Frontend, Backend, QA, UX
> **안건/주제**: 위키 문서 링크(`[[`) 시 한글 자음(초성)만 입력해도 문서가 자동 추천되도록 검색 기능 개선

---

## 1. 이슈 개요 및 원인 분석 (Root Cause Analysis)

### 발견된 이슈 (Korean Consonant Search Failure)
- **현상**: 사용자가 위키 문서(예: "누수플랜")를 연결하기 위해 `[[ㄴ` 혹은 `[[누` 와 같이 부분적이거나 초성만 입력했을 때, 연관된 문서가 추천 목록(Autocomplete)에 즉각 수면 위로 올라오지 않는 현상.
- **원인**:
  - 기존에 적용된 검색 엔진인 `Fuse.js`는 영어의 알파벳 매칭을 기준으로 설계되어, 한글의 독특한 "초성-중성-종성" 조합/분리 시스템을 전혀 인식하지 못했습니다.
  - 이로 인해 "ㄴ" 과 "누"를 완전히 매칭 확률이 희박한 다른 글자로 인식하여 연관 검색 목록 점수(Score) 산정 대상에서 제외시키는 문제가 있었습니다.

---

## 2. 해결 방안 및 조치 내역 (Actions Taken)

1. **초성 추출 최적화 유틸리티 자체 구현 (`src/lib/utils/hangul.ts`)**
   - 무거운 범용 한글 처리 NPM 패키지(예: `hangul-js`, `es-hangul` 등)를 클라이언트 사이드에 통째로 불러오지 않고 성능을 극대화하기 위해, 19개의 초성만 간단명료하게 빼낼 수 있는 **15줄짜리 경량 유니코드 변환 로직(`getChoseong`)을 순수 JavaScript로 직접 제작**했습니다.
   - 영어, 숫자, 공백은 변형 없이 그대로 둡니다.

2. **검색 파이프라인 및 `Fuse.js` 인덱싱 구조 수정 (`src/components/ReflectEditor.tsx`)**
   - 위키 문서 목록(`wikiMap`)을 로드하여 검색 풀을 만들 때, 각 제목마다 뒤에서 `getChoseong`을 실행시켜 "초성으로만 이루어진 제목 문자열(예: `ㄴㅅㅍㄹ`)"을 몰래 생성하여 데이터에 끼워 넣었습니다.
   - 이후 검색 엔진인 `Fuse.js`가 문서를 찾을 대상(keys)을 `['title']` 1개에서 `['title', 'choseong']` 2개 파트로 확장하도록 세팅했습니다.
   - **결과**: 사용자가 `[[ㄴㅅㅍㄹ` 이나 `[[누ㅅ` 을 입력하면 새로 생성된 `choseong` 속성과 핏이 맞아떨어져, 원본 제목("누수플랜")이 0순위로 추천되게 됩니다.

---

## 3. 검증 내역 (Verification)

1. **코어 검색 엔진 테스트**: Node.js 상에서 Mock Data를 띄워 `getChoseong`과 `Fuse.js` 결합 동작을 점검하였고, `초성 일치`만으로 완벽하게 연관 문서 객체를 찾아내는 것을 확인했습니다.
2. **TypeScript 런타임 빌드**: `npm run build`를 통해 `hangul.ts`의 이식성과 타입 체크 무결성을 성공적으로 검증했습니다 (Exit Code: 0).