DOCS/journey/plans/250123_구스팜_위키독스_블로그_구현계획.md

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

날짜: 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 (프론트엔드 원칙)