# 구스팜 위키독스 스타일 블로그 구현 계획

**날짜**: 2025-01-23
**목표**: 위키독스 스타일 계층적 블로그 시스템

---

## 목적

- 시리즈(Book) → 장(Chapter) → 절(Section) 구조로 콘텐츠 체계화
- 좌측 트리 목차 + 우측 본문 레이아웃
- 내부 링크 `[[문서명]]` 자동 변환
- 진행률 추적 및 북마크 기능

---

## 아키텍처

### DB 스키마

**books 테이블**:
- `id`, `title`, `author`, `summary`, `cover_image`, `created_at`, `updated_at`

**chapters 테이블**:
- `id`, `book_id`, `title`, `order`, `created_at`

**blog 테이블 확장**:
- 기존 컬럼 유지
- `book_id` (FK), `chapter_id` (FK), `order` (절 순서) 추가

### API 엔드포인트

- `GET /api/books` - 시리즈 목록
- `GET /api/books/:id` - 시리즈 상세 (목차 포함)
- `GET /api/books/:id/chapters` - 장 목록
- `GET /api/blog?book_id=:id` - 시리즈별 포스트
- `GET /api/blog/:id/prev-next` - 이전/다음 포스트

---

## 구현 Phase

### Phase 1: 데이터 구조 (1주)

- [ ] `books`, `chapters` 테이블 생성
- [ ] `blog` 테이블에 `book_id`, `chapter_id`, `order` 컬럼 추가
- [ ] 마이그레이션 스크립트 작성
- [ ] Repository 함수 구현 (`book_repository.py`, `chapter_repository.py`)

**참고**: `goosefarminvesting/backend/src/goosefarm/db.py` (Supabase 클라이언트 패턴)

### Phase 2: 백엔드 API (1주)

- [ ] `routers/book.py` 생성 - 시리즈 CRUD
- [ ] `routers/chapter.py` 생성 - 장 CRUD
- [ ] `routers/blog.py` 수정 - 시리즈 필터링 추가
- [ ] 이전/다음 포스트 조회 로직 구현

**참고**: `goosefarminvesting/backend/src/goosefarm/routers/blog.py` (기존 블로그 API 패턴)

### Phase 3: 프론트엔드 컴포넌트 (2주)

- [ ] `BookSidebar.tsx` - 트리 목차 (접기/펼치기, 현재 위치 하이라이트)
- [ ] `BookHeader.tsx` - 시리즈 정보 + 진행률 프로그레스바
- [ ] `PrevNextNav.tsx` - 이전/다음 네비게이션
- [ ] `TableOfContents.tsx` - 본문 우측 미니 목차 (h2/h3 앵커)

**참고**: `goosefarminvesting/frontend/src/pages/BlogPage.tsx` (기존 블로그 페이지 구조)

### Phase 4: 레이아웃 및 스타일링 (1주)

- [ ] 좌측 목차 250px 고정 (sticky) 레이아웃
- [ ] 모바일 반응형 (목차 토글 버튼)
- [ ] 진행률 표시 UI
- [ ] 내부 링크 스타일링

### Phase 5: 내부 링크 처리 (1주)

- [ ] 마크다운 파서에 `[[문서명]]` 형식 인식 추가
- [ ] 링크 자동 변환 로직 (remark/rehype 플러그인)
- [ ] 링크된 문서 존재 여부 검증
- [ ] 링크 클릭 시 해당 문서로 이동

**참고**: `goosefarminvesting/frontend/src/components/blog/BlogEditor.tsx` (TipTap 에디터)

### Phase 6: 북마크/진행률 (1주)

- [ ] 사용자별 읽은 위치 저장 (localStorage 또는 DB)
- [ ] "이어보기" 기능 구현
- [ ] 진행률 계산 로직 (읽은 장/절 수)
- [ ] 여러 시리즈 동시 진행 지원

---

## 기술 스택

### 프론트엔드
- React 19 + TypeScript
- TipTap 에디터 (마크다운 확장)
- remark/rehype (마크다운 파싱)
- Recharts (진행률 프로그레스바)

### 백엔드
- FastAPI (기존 구조 유지)
- Supabase (PostgreSQL)

---

## 참고

- 위키독스 사이트 구조 분석
- `goosefarminvesting/frontend/src/pages/BlogPage.tsx` (기존 블로그 구현)
- `goosefarminvesting/backend/src/goosefarm/routers/blog.py` (기존 API 패턴)
- `DOCS/book/300_architecture/311_FastAPI_구조_원칙.md` (백엔드 원칙)
- `DOCS/book/300_architecture/313_React_구조_원칙.md` (프론트엔드 원칙)