# Reflect Backlink & Aggregation 기능 명세서

**날짜**: 2026-02-08
**작성자**: Jay (PM) & Sua (Reflect UX Expert)
**참석자**: Backend Dev, Frontend Dev

---

## 1. 개요 (Overview)
*   **목표**: `WikiLink` 기능([[링크]])을 단순 하이퍼링크가 아닌, **Reflect 앱의 핵심 기능인 "주제 중심의 컨텐츠 집합(Aggregation)"**으로 진화시킨다.
*   **문제점**: 현재는 `[[없는문서]]`를 클릭하면 "새 문서 만들기"로만 유도된다. 하지만 Reflect의 철학은 **"문서가 없어도 연결된 모든 정보를 보여주는 것"**이다.
*   **핵심 가치**: 사용자는 문서를 먼저 만들지 않고, 생각을 먼저 연결(`[[Link]]`)한다. 나중에 그 링크를 따라가면, 흩어진 생각들이 모여있는 것을 발견하게 된다.

---

## 2. 사용자 시나리오 (User Story)

### 상황 1: 없는 문서(Phantom Doc) 링크 클릭 시
1.  사용자가 `[[커피]]`를 입력하거나 클릭한다.
2.  "커피"라는 문서는 아직 생성된 적이 없다.
3.  하지만 시스템은 **`[[커피]]`를 언급한 모든 문서들의 목록(Backlinks)**을 보여준다.
    *   예: "회의록 A": ...팀원들과 [[커피]]를 마시며 논의...
    *   예: "아이디어 노트": ...[[커피]] 구독 서비스 아이디어...
4.  사용자는 이 목록을 보고 "아, 커피 관련 내용이 이렇게 모여있네"라고 인지한다.
5.  필요시 "커피"라는 정식 문서를 생성(Materialize)한다.

### 상황 2: 있는 문서(Real Doc) 링크 클릭 시
1.  사용자가 `[[프로젝트A]]`를 클릭한다.
2.  "프로젝트A" 문서의 본문 내용이 보인다.
3.  문서 하단(또는 우측 사이드바)에 **"Linked Mentions"** 섹션이 나타난다.
4.  여기에는 다른 문서들이 `[[프로젝트A]]`를 언급한 문맥(Context/Snippet)이 표시된다.

---

## 3. 기술적 요구사항 (Technical Specs)

### 3.1 Backend (Firestore)
*   **목표**: 역참조(Backlink) 쿼리를 효율적으로 수행해야 함.
*   **데이터 필드 추가**:
    *   `documents` 컬렉션의 문서 필드에 `outgoingLinks` (Array of Strings) 추가.
    *   문서 저장 시, 본문에서 `[[...]]` 패턴을 추출하여 이 배열을 업데이트한다.
    *   예: `outgoingLinks: ["커피", "프로젝트A"]`
*   **인덱싱**: `outgoingLinks` 필드에 대해 `array-contains` 쿼리가 가능하도록 인덱싱(Firestore 기본 지원) 활용.

### 3.2 Frontend (UI/UX)
*   **문서 뷰어 페이지 (`/docs/[id]`)**:
    *   `id`가 실제 문서가 아닌 경우에도 페이지를 렌더링해야 함. (일종의 "가상 페이지" 모드)
    *   **Backlinks Panel 컴포넌트** 개발:
        *   Firestore 쿼리: `where('outgoingLinks', 'array-contains', currentDocIdOrTitle)`
        *   결과 표시: 링크를 걸고 있는 문서의 제목 + 해당 링크 주변의 텍스트(Snippet) 미리보기.

---

## 4. 구현 계획 (Implementation Plan)

### Step 1: 문서 저장 로직 개선
*   `WikiLinkExtension` 또는 `ReflectEditor`의 `onChange` 핸들러에서 `[[...]]`을 파싱.
*   Firestore 저장 시 `outgoingLinks` 필드에 추출한 링크(Title 또는 ID)들을 저장.

### Step 2: 백링크 쿼리 함수 구현
*   `lib/firestore/links.ts` (가칭) 생성.
*   `getBacklinks(targetTitle)` 함수 구현: `documents` 컬렉션에서 `outgoingLinks`에 `targetTitle`이 포함된 문서 검색.

### Step 3: 백링크 UI 구현
*   `components/BacklinksPanel.tsx` 생성.
*   문서 상세 페이지 하단에 이 컴포넌트 배치.
*   없는 문서일 경우 "This page doesn't exist yet, but here are the references:" 메시지와 함께 백링크 목록 표시.

---

## 5. 논의 사항 (Discussion)
*   **동기화 문제**: 문서 제목이 바뀌면(`Rename`), 그 문서를 가리키던 링크들은?
    *   *Jay (PM)*: "지금은 MVP 단계이므로, Rename 시 백링크 업데이트는 추후(Refactoring Phase)로 미룹시다. 우선은 ID 기반보다는 **Title 기반 연결**을 먼저 구현하여 '연결성' 자체에 집중합시다."
*   **Unlinked Mentions**: `[[...]]` 없이 텍스트로만 "커피"라고 쓴 것도 찾을 것인가?
    *   *Sua (UX)*: "Reflect의 강력함은 거기서 나오지만, 기술적으로 비용이 큽니다(Full-text Search). 1단계에서는 **명시적 링크(`[[]]`)**만 처리합시다."

---

**승인 요청**: 위 명세대로 진행하시겠습니까?