From 2d81194185de90a5d0e7dad7b8cb3f8e0424b563 Mon Sep 17 00:00:00 2001 From: happybell80 Date: Tue, 23 Dec 2025 15:15:46 +0900 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20=EA=B5=AC=EC=8A=A4=ED=8C=9C=20?= =?UTF-8?q?=EC=9C=84=ED=82=A4=EB=8F=85=EC=8A=A4=20=EC=8A=A4=ED=83=80?= =?UTF-8?q?=EC=9D=BC=20=EB=B8=94=EB=A1=9C=EA=B7=B8=20=EC=8B=9C=EB=82=98?= =?UTF-8?q?=EB=A6=AC=EC=98=A4=20=EB=B0=8F=20=EA=B5=AC=ED=98=84=20=EA=B3=84?= =?UTF-8?q?=ED=9A=8D=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...팜_위키독스_블로그_구현계획.md | 116 ++++++++++++++++++ ...팜_위키독스_블로그_시나리오.md | 93 ++++++++++++++ 2 files changed, 209 insertions(+) create mode 100644 journey/plans/250123_구스팜_위키독스_블로그_구현계획.md create mode 100644 journey/scenarios/250123_구스팜_위키독스_블로그_시나리오.md diff --git a/journey/plans/250123_구스팜_위키독스_블로그_구현계획.md b/journey/plans/250123_구스팜_위키독스_블로그_구현계획.md new file mode 100644 index 0000000..9711fb5 --- /dev/null +++ b/journey/plans/250123_구스팜_위키독스_블로그_구현계획.md @@ -0,0 +1,116 @@ +# 구스팜 위키독스 스타일 블로그 구현 계획 + +**날짜**: 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` (프론트엔드 원칙) + diff --git a/journey/scenarios/250123_구스팜_위키독스_블로그_시나리오.md b/journey/scenarios/250123_구스팜_위키독스_블로그_시나리오.md new file mode 100644 index 0000000..33dd45d --- /dev/null +++ b/journey/scenarios/250123_구스팜_위키독스_블로그_시나리오.md @@ -0,0 +1,93 @@ +# 구스팜 위키독스 스타일 블로그 시나리오 + +**작성일**: 2025-01-23 +**작성자**: happybell80 +**상태**: 시나리오 설계 중 + +--- + +## 1. 독자 시나리오 + +### 순차 학습 +- 목차에서 다음 글 클릭 → 진행률 표시 → 완독 후 다음 장 자동 추천 +- 시리즈 시작부터 순서대로 읽으며 학습 흐름 유지 + +### 검색/탐색 +- 검색어 입력 → 관련 장/절 하이라이트 → 클릭으로 바로 이동 +- 내부 링크 `[[다른 문서]]` 클릭 → 관련 시리즈 추천 + +### 북마크/이어보기 +- 중간 저장 → 재방문 시 "이어보기" 버튼 → 마지막 읽은 위치로 복귀 +- 여러 시리즈 동시 진행 시 각각의 진행률 표시 + +### 관련 콘텐츠 발견 +- 본문 내부 링크 클릭 → 관련 시리즈 추천 +- 태그 기반 유사 콘텐츠 자동 추천 + +--- + +## 2. 작성자 시나리오 + +### 시리즈 기획 +- 새 책 생성 → 장/절 구조 미리 설계 → 빈 틀 생성 후 순차 작성 +- 목차 구조만 먼저 만들고 나중에 콘텐츠 채우기 + +### 협업 편집 +- 여러 작성자가 동시 편집 → 변경 이력 추적 → 리뷰 후 병합 +- 실시간 편집 충돌 방지 및 해결 + +### 콘텐츠 재구성 +- 장 순서 변경(drag & drop) → 자동으로 목차/네비게이션 업데이트 +- 장/절 이동 시 내부 링크 자동 업데이트 + +--- + +## 3. 관리자 시나리오 + +### 통계 분석 +- 시리즈별 조회수/완독률 → 인기 장/절 파악 → 콘텐츠 전략 조정 +- 사용자 행동 패턴 분석 (어디서 이탈하는지, 어떤 경로로 탐색하는지) + +### A/B 테스트 +- 목차 위치(좌측/우측), 검색 UI 비교 → 전환율 측정 +- 레이아웃 최적화를 위한 데이터 기반 의사결정 + +--- + +## 4. 핵심 UX 요소 + +### 좌측 트리 목차 +- 현재 위치 하이라이트 +- 접기/펼치기 기능 +- 진행률 표시 (읽은 장/절 표시) + +### 우측 본문 +- 제목/저자/날짜 정보 +- 마크다운 렌더링 (KaTeX 수식 지원) +- 이전/다음 네비게이션 + +### 상단 헤더 +- 시리즈명 + 저자 +- 진행률 프로그레스바 +- 검색 기능 + +--- + +## 5. 기술적 요구사항 + +### 데이터 구조 +- Book (시리즈) → Chapter (장) → Section (절/포스트) 계층 구조 +- 기존 `blog` 테이블 확장 또는 `books`, `chapters` 테이블 신설 + +### 레이아웃 +- 좌측 목차 250px 고정 (sticky) +- 우측 본문 반응형 (모바일에서는 목차 토글) + +### 내부 링크 +- `[[문서명]]` 형식 자동 변환 +- 링크된 문서 존재 여부 검증 + +--- + +*위키독스 스타일의 계층적 문서 관리 시스템으로 구스팜 블로그를 확장* + From b833883f9f7f744521847ea3183d0e34266ecfb7 Mon Sep 17 00:00:00 2001 From: happybell80 Date: Tue, 23 Dec 2025 15:20:33 +0900 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20=EA=B5=AC=EC=8A=A4=ED=8C=9C=20?= =?UTF-8?q?=EB=B8=94=EB=A1=9C=EA=B7=B8=20=EB=AC=B8=EC=84=9C=EB=A5=BC=20?= =?UTF-8?q?=EA=B5=AC=EC=8A=A4=ED=8C=9C=20DOCS=EB=A1=9C=20=EC=9D=B4?= =?UTF-8?q?=EB=8F=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...팜_위키독스_블로그_구현계획.md | 116 ------------------ ...팜_위키독스_블로그_시나리오.md | 93 -------------- 2 files changed, 209 deletions(-) delete mode 100644 journey/plans/250123_구스팜_위키독스_블로그_구현계획.md delete mode 100644 journey/scenarios/250123_구스팜_위키독스_블로그_시나리오.md diff --git a/journey/plans/250123_구스팜_위키독스_블로그_구현계획.md b/journey/plans/250123_구스팜_위키독스_블로그_구현계획.md deleted file mode 100644 index 9711fb5..0000000 --- a/journey/plans/250123_구스팜_위키독스_블로그_구현계획.md +++ /dev/null @@ -1,116 +0,0 @@ -# 구스팜 위키독스 스타일 블로그 구현 계획 - -**날짜**: 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` (프론트엔드 원칙) - diff --git a/journey/scenarios/250123_구스팜_위키독스_블로그_시나리오.md b/journey/scenarios/250123_구스팜_위키독스_블로그_시나리오.md deleted file mode 100644 index 33dd45d..0000000 --- a/journey/scenarios/250123_구스팜_위키독스_블로그_시나리오.md +++ /dev/null @@ -1,93 +0,0 @@ -# 구스팜 위키독스 스타일 블로그 시나리오 - -**작성일**: 2025-01-23 -**작성자**: happybell80 -**상태**: 시나리오 설계 중 - ---- - -## 1. 독자 시나리오 - -### 순차 학습 -- 목차에서 다음 글 클릭 → 진행률 표시 → 완독 후 다음 장 자동 추천 -- 시리즈 시작부터 순서대로 읽으며 학습 흐름 유지 - -### 검색/탐색 -- 검색어 입력 → 관련 장/절 하이라이트 → 클릭으로 바로 이동 -- 내부 링크 `[[다른 문서]]` 클릭 → 관련 시리즈 추천 - -### 북마크/이어보기 -- 중간 저장 → 재방문 시 "이어보기" 버튼 → 마지막 읽은 위치로 복귀 -- 여러 시리즈 동시 진행 시 각각의 진행률 표시 - -### 관련 콘텐츠 발견 -- 본문 내부 링크 클릭 → 관련 시리즈 추천 -- 태그 기반 유사 콘텐츠 자동 추천 - ---- - -## 2. 작성자 시나리오 - -### 시리즈 기획 -- 새 책 생성 → 장/절 구조 미리 설계 → 빈 틀 생성 후 순차 작성 -- 목차 구조만 먼저 만들고 나중에 콘텐츠 채우기 - -### 협업 편집 -- 여러 작성자가 동시 편집 → 변경 이력 추적 → 리뷰 후 병합 -- 실시간 편집 충돌 방지 및 해결 - -### 콘텐츠 재구성 -- 장 순서 변경(drag & drop) → 자동으로 목차/네비게이션 업데이트 -- 장/절 이동 시 내부 링크 자동 업데이트 - ---- - -## 3. 관리자 시나리오 - -### 통계 분석 -- 시리즈별 조회수/완독률 → 인기 장/절 파악 → 콘텐츠 전략 조정 -- 사용자 행동 패턴 분석 (어디서 이탈하는지, 어떤 경로로 탐색하는지) - -### A/B 테스트 -- 목차 위치(좌측/우측), 검색 UI 비교 → 전환율 측정 -- 레이아웃 최적화를 위한 데이터 기반 의사결정 - ---- - -## 4. 핵심 UX 요소 - -### 좌측 트리 목차 -- 현재 위치 하이라이트 -- 접기/펼치기 기능 -- 진행률 표시 (읽은 장/절 표시) - -### 우측 본문 -- 제목/저자/날짜 정보 -- 마크다운 렌더링 (KaTeX 수식 지원) -- 이전/다음 네비게이션 - -### 상단 헤더 -- 시리즈명 + 저자 -- 진행률 프로그레스바 -- 검색 기능 - ---- - -## 5. 기술적 요구사항 - -### 데이터 구조 -- Book (시리즈) → Chapter (장) → Section (절/포스트) 계층 구조 -- 기존 `blog` 테이블 확장 또는 `books`, `chapters` 테이블 신설 - -### 레이아웃 -- 좌측 목차 250px 고정 (sticky) -- 우측 본문 반응형 (모바일에서는 목차 토글) - -### 내부 링크 -- `[[문서명]]` 형식 자동 변환 -- 링크된 문서 존재 여부 검증 - ---- - -*위키독스 스타일의 계층적 문서 관리 시스템으로 구스팜 블로그를 확장* -