# 위키링크(WikiLink) 표준화 및 연결 무결성 명세

> **일시**: 2026-02-11 02:58
> **상태**: 🟢 완료 (운영 배포 준비)
> **주제**: 에디터, 백링크, 저장소 간 링크 형식 일원화

---

## 1. 배경 및 목적
기존의 다원화된 링크 문법( `[[ID|Label]]`, `[Label](/docs/ID)` 등)으로 인해 에디터 로드 시 링크가 '일반 링크'로 강등되거나, 한글 제목이 중첩 인코딩(Double Encoding)되어 깨지는 현상이 발생함. 이를 해결하기 위해 전체 시스템의 링크 형식을 **표준 마크다운** 기반으로 통일함.

## 2. 기술적 사양 (Technical Specs)

### 2.1. 데이터 저장 형식 (Storage Format)
- **표준**: `[제목](/docs/ID)`
- **이유**: Next.js App Router와 SEO 친화적이며, 에디터가 아닌 조회 환경(`ReactMarkdown`)에서도 별도의 커스텀 룰 없이 정상 작동함.

### 2.2. 에디터 처리 로직 (Tiptap / WikiLinkExtension)
- **로드 시**: `markdown-it` 파서가 `/docs/`로 시작하는 링크를 `wikiLink` 노드로 자동 인식.
- **인코딩 처리**: `parseHTML` 단계에서 `decodeURIComponent`를 호출하여 원본 텍스트를 복원.
- **UI 렌더링**: `wikiLink` 노드에 인디고 배경과 밑줄을 부여하여 '일반 링크'와 시각적으로 차별화.

### 2.3. 백링크 연동 (BacklinksPanel)
- **자동 링크**: 'Link now' 기능 실행 시 기존 `[[ ]]` 문법 대신 `[제목](/docs/ID)` 문법을 삽입하여 시스템 전체의 무결성을 유지.

## 3. 보안 및 클릭 핸들링 (Iron-clad Security)
에디터 내에서 위키링크가 '작동하는 링크'로 인식되어 페이지 이동을 유발하는 것을 막기 위해 다음 3단계 방어 레이어를 적용함:
1. **CSS**: `pointer-events: none` 적용.
2. **ProseMirror Event**: `handleClick` 핸들러에서 이동 차단.
3. **Capture Phase Listener**: 에디터 DOM에 가장 강력한 캡처링 단계 리스너를 부착하여 모든 기본 링크 동작을 소멸시킴.

## 4. 기대 효과
- **데이터 일관성**: 저장소와 에디터 간 데이터 왕복(Round-trip) 시 데이터 유실 제로.
- **사용자 경험**: 한글 제목의 완벽한 표시 및 에디터 내부의 평화로운 편집 환경 확보.

---

*본 문서는 `.agent/workflows/create-doc.md` 및 `dev-workflow.md` 지침에 따라 기록된 기술 명세입니다.*