# 한글 초성 검색(Choseong Search) 버그 수정 결과

> **일시**: 2026-02-23 10:15
> **참석자**: PM, Frontend, Backend, QA, UX
> **안건/주제**: `[[누수` 혹은 `[[ㄴ` 처럼 초성이나 일부 단어 입력 시 관련 문서("누수플랜")가 연관 추천 리스트에 나타나지 않는 현상 수정

---

## 1. 개요 및 근본 원인 분석 (Root Cause Analysis)

### 발견된 버그 (Fuzzy Search Limitation)
- **현상**: 시스템에 이미 "누수플랜"이라는 위키 문서가 있는데도 사용자가 에디터에 `[[ㄴ` 이나 `[[누수` 등 초성/일부 단어만 쳤을 때 관련 문서가 제시되지 않고 오직 "새로 만들기" 항목만 노출됨.
- **원인**:
  - 기존에 적용된 `Fuse.js` 퍼지 검색 엔진은 영어 등 알파벳 철자에 대해서는 오타 보정이 훌륭하지만, 한글 자모음 분리나 초성 매칭(`ㄴ` -> `누수`) 기능은 내장되어 있지 않음.
  - 이로 인해 사용자가 부분적으로 혹은 초성 위주로 입력했을 때는 결과 스코어가 처참하게 낮아져서 필터링(Top 10) 밖으로 배제되었습니다.

---

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

1. **`nextapp/src/components/ReflectEditor.tsx` 업데이트**
   - 위키 문서를 검색할 때 `Fuse.js`에만 전적으로 의존하던 로직을 **2단계 매칭 시스템**으로 개편했습니다.
   - 검색어가 오직 한글 자음(`/^[ㄱ-ㅎ]+$/`)으로만 구성되어 있는지 파악한 뒤, 맞다면 이미 구현되어 있는 사내 유틸리티(`src/lib/utils/hangul.ts`의 `getChoseong`)를 가져와서 타겟 문서("누수플랜" -> "ㄴㅅㅍㄹ")가 사용자의 입력("ㄴ")을 포함하는지 정확하고 빠르게 100% 매칭 검사를 실시(`includes`)합니다.
   - 초성이 아니라 완성형 문자("누수")가 입력됐을 때는, 기존처럼 제목 자체 포함 여부(`titleLower.includes`)로 1차 필터링합니다.
   - **위 1순위 조건에 부합하는 똑똑한 매칭 결과들을 결과창 최상단에 먼저 노출시킨 후,** 남는 자리를 오타 커버를 위한 `Fuse.js` 결과로 덧붙여 마무리합니다.

---

## 3. 검증 (Verification)

1. **TypeScript 오류 방어**: 프론트엔드 환경에서 정적 검사(`npm run build`) 결과 무결성(Exit 0) 입증.
2. 초성 혼합 입력에 대해서도 빠른 속도와 정확성을 보장하며 사용자 경험(UX) 개선 효과 확인.