Personal Wiki SPA – Product Requirements Document Overview 이 문서는 개인 위키 (Wiki) Single Page Application (SPA) 프로젝트의 제품 요구 사항과 구현 계획을 정리한 것입니다. 이 애플리케이션은 React 및 TypeScript로 구축되며, Vite를 기반으로 설정되었습니다. 사용자는 자체 위키 페이지를 생성, 편집, 삭제할 수 있고, 작성된 페이지들을 검색할 수 있습니다. UI는 Microsoft Learn과 같은 공식 문서 스타일의 단순하고 가독성 높은 디자인을 지향합니다. 접근성을 고려하여 Radix UI 라이브러리를 활용하고, Tailwind CSS로 UI 스타일링을 수행합니다. 데이터 관리와 API 연동은 TanStack React Query v5.90.7을 통해 처리하며, 현재 단계에서는 더미 데이터와 가짜 API로 클라이언트 사이드에서 동작하도록 합니다. 프로젝트 구조는 Feature-Sliced Design (FSD) 아키텍처 원칙을 준수하여 기능 단위로 모듈화됩니다[1][2]. Goals (목표) • 위키 페이지 CRUD: 사용자가 위키 페이지를 생성(Create), 읽기(Read), 편집(Update) 및 삭제(Delete)할 수 있는 기본 기능 제공. • 검색 기능: 키워드로 페이지 제목이나 내용을 검색하여 빠르게 찾아볼 수 있는 기능 제공. • 사용자 경험: Official 문서처럼 깔끔하고 일관된 UI/UX 제공. 반응형 디자인으로 다양한 화면 크기에서 가독성 유지. • 프론트엔드 아키텍처: Feature-Sliced Design에 따라 폴더 구조를 기능 중심으로 조직화하여 유지보수성과 확장성 확보[1]. 또한, TanStack React Query를 통한 효율적인 서버 상태 관리로 데이터 페칭/캐싱 최적화 및 코드 단순화를 달성[3]. • 접근성과 성능: Radix UI의 접근성 높은 컴포넌트를 활용하여 사용자 인터랙션 (모달 등)에 표준 준수 및 접근성 확보[4]. CSR(Client-Side Rendering) SPA로 사용자 입력에 빠르게 반응. Non-Goals (범위에서 제외되는 항목) • 사용자 인증: 로그인/권한 관리 등 사용자 인증 기능은 구현하지 않습니다 (모든 사용자는 동일한 권한으로 간주). • 버전 관리 및 고급 위키 기능: 페이지의 버전 이력 추적, 컨텐츠 역사 비교, 이미지/첨부파일 업로드 등의 복잡한 위키 부가 기능은 현재 범위에 포함하지 않습니다. • 실제 백엔드 구현: 이 프로젝트에서는 서버 API와의 통신을 모방한 더미 데이터로 대체합니다. 따라서 백엔드 서비스, DB 연동, 배포 등의 사항은 고려하지 않습니다 (추후 실제 서버 연결 용이성을 위해 인터페이스만 구축). • 다국어 지원: 기본적으로 하나의 언어(예: 한국어)로 위키 페이지를 작성한다고 가정하며, i18n 다국어 지원은 포함하지 않습니다. Features and Requirements (기능 명세) 1. 페이지 관리 (Page Management CRUD) • 페이지 생성: 사용자는 새로운 위키 페이지를 생성할 수 있습니다. 페이지 생성 시 제목(title)과 본문(content)을 입력받는 폼을 제공하며, “생성” 버튼으로 제출합니다. 제출 후 새 페이지가 저장되고 애플리케이션에 즉시 반영됩니다. 생성된 페이지는 고유 ID를 부여받고, 목록 및 검색에 노출됩니다. • 페이지 보기: 저장된 위키 페이지를 화면에서 열람할 수 있습니다. 제목은 헤드라인으로 표시하고 본문 콘텐츠는 본문 영역에 표시합니다. 뷰 화면에서는 편집 및 삭제 작업을 수행할 수 있는 UI 버튼을 제공합니다. 라우팅을 지원하여, 각 페이지는 고유 URL (/pages/{id} 형태 등)로 접근 가능하게 합니다 (예: 즐겨찾기나 직접 URL로 접근 시 해당 페이지 표시). • 페이지 편집: 기존 페이지의 제목과 본문을 수정할 수 있습니다. “편집” 버튼을 누르면 편집 폼이 나타나며, 현재 저장된 제목/내용을 편집할 수 있습니다. 수정 완료 후 “저장”하면 변경사항이 저장되고, 페이지 보기 화면에 갱신된 내용이 반영됩니다. 편집 중 “취소”를 선택하면 변경사항 없이 페이지 보기 화면으로 돌아갑니다. • 페이지 삭제: 사용자는 페이지를 삭제할 수 있습니다. “삭제” 버튼을 클릭하면 한 번 더 확인을 받는 확인 대화상자(modal)를 표시하여 오작동을 방지합니다. 확인 시 해당 페이지를 삭제하고, 사용자에게 삭제 완료를 알린 뒤 페이지 목록 화면으로 리다이렉트합니다. 삭제된 페이지는 목록과 검색 결과에서 즉시 제거됩니다. 2. 검색 기능 (Search) • 키워드 검색: 다수의 위키 페이지 중 원하는 정보를 빠르게 찾을 수 있도록 검색 바를 제공합니다. 사용자가 키워드를 입력하면 페이지 제목이나 내용에 해당 키워드가 포함된 페이지들을 필터링하여 목록으로 표시합니다. 검색은 실시간으로 수행되며(입력 시 즉시 필터링) 또는 검색 버튼 액션으로 구현합니다. • 검색 결과 표시: 검색 키워드에 대응되는 페이지들의 제목 리스트를 보여주며, 각 결과 항목을 클릭하면 해당 페이지 보기로 이동합니다. 검색어에 맞는 결과가 없을 경우 “일치하는 페이지가 없습니다”와 같은 안내를 표시합니다. • UX 고려사항: 검색어 입력란은 페이지 목록 화면 상단에 배치하거나 상단 네비게이션 바에 일괄 배치합니다. 사용자 편의를 위해 검색어를 입력 중에도 기존 페이지 목록을 필터링하여 보여주거나, 필요 시 엔터키로 검색 확정하는 방식을 지원합니다. 검색 기능도 React Query를 활용해 구현하되, 현재 단계에서는 클라이언트 측 더미 데이터를 대상으로 합니다. Technical Architecture (기술 아키텍처) Tech Stack • 프론트엔드 프레임워크: React (버전 19+), TypeScript. Vite (버전 7.1+)를 사용하여 프로젝트를 부트스트랩하였으며, 개발 편의성과 빌드 속도를 위해 선택되었습니다. • 언어 및 컴파일러: TypeScript로 구현하여 정적 타입 체크와 개발자 생산성을 높입니다. Vite + SWC 조합으로 빠른 HMR(Hot Module Reload)과 빌드 최적화를 활용합니다. • 상태 관리 및 데이터 통신: TanStack React Query 5.90.7을 사용하여 서버 상태를 관리합니다. React Query는 데이터 페칭, 캐싱, 동기화, 업데이트 등을 간결한 코드로 손쉽게 구현하게 해주며[3], API 호출 결과를 캐시하여 불필요한 재요청을 방지하고 앱 성능을 향상시킵니다. React Query의 훅(useQuery, useMutation 등)을 통해 CRUD API와 검색 기능을 구현하고, 로딩/에러 상태도 일관성 있게 관리합니다. • UI 컴포넌트 라이브러리: Radix UI를 도입하여 접근성이 보장된 기본 컴포넌트(Primitive)를 활용합니다. Radix UI는 스타일이 적용되지 않은(headless) 낮은 수준의 UI 구성 요소들을 제공하여 개발자가 Tailwind CSS로 자유롭게 꾸밀 수 있게 하면서도, 키보드 내비게이션, ARIA 레이블 등 접근성 로직이 내장되어 있습니다[4]. 예를 들어 페이지 삭제 확인 모달은 Radix UI의 AlertDialog 컴포넌트를 사용하여 구현함으로써, 포커스 트랩핑 및 스크린리더 지원 등 접근성 요소를 쉽게 확보합니다. • 스타일링: Tailwind CSS를 사용해 UI 스타일을 구현합니다. Tailwind CSS의 유틸리티 클래스들을 통해 빠르게 스타일링하고, 디자인 시스템과 일관성을 유지합니다. 별도의 CSS 파일 대신 Tailwind config를 설정하여 테마 색상, 폰트 등을 정의하고, 필요한 경우 커스텀 클래스를 구성합니다. Official 문서 느낌의 심플한 레이아웃 (예: 넓은 여백, 명조계열 폰트, 선명한 헤딩 스타일 등)을 Tailwind를 통해 손쉽게 조정합니다. • 라우팅: React Router (v6+)를 도입하여 SPA 내 클라이언트 사이드 라우팅을 관리합니다. 사용자가 여러 페이지를 탐색할 수 있도록, 주요 화면 (페이지 목록, 페이지 상세, 페이지 편집, 등)에 대해 라우트를 정의합니다. 각 페이지는 URL로 매핑되어 브라우저 뒤로가기/새로고침 시에도 일관된 화면을 보여줍니다. • 프로젝트 구조: 기능 중심의 Feature-Sliced Design (FSD) 아키텍처를 적용합니다. FSD의 핵심은 프로젝트를 기능별(Feature)로 나누고, 계층(Layer)을 두어 역할을 분리하는 것입니다[1]. 본 프로젝트에서는 아래와 같은 폴더 계층을 갖습니다: • src/app: 애플리케이션 엔트리 포인트와 전역 설정 (예: App.tsx, 라우터 및 QueryClient Provider 설정). • src/entities: 애플리케이션의 비즈니스 도메인 모델을 정의합니다. 예를 들어 entities/page 폴더에는 Page 객체 인터페이스 정의와 더미 데이터 및 API 함수들이 포함됩니다. (FSD에서 entities는 비즈니스 객체 및 해당 로직을 캡슐화합니다.) • src/features: 재사용 가능한 기능 모듈을 구현합니다. 예를 들어 features/page에는 페이지 목록이나 페이지 폼과 같이 Page와 관련된 UI 컴포넌트와 훅, 상태 로직 등이 들어가고, features/search에는 검색 바 컴포넌트와 관련 로직이 들어갑니다. 개별 Feature는 자체 폴더 구조를 가지며, 필요한 경우 내부에 ui (UI 컴포넌트), model (상태로직), api 등을 구분할 수 있습니다. • src/pages: 라우팅 대상이 되는 페이지 컴포넌트를 관리합니다. 각 페이지 컴포넌트는 여러 features와 entities를 조합하여 하나의 완성된 화면(View)을 구성합니다. 예컨대 pages/PageListPage.tsx (전체 페이지 목록 화면), pages/PageDetailPage.tsx (단일 페이지 조회 화면), pages/PageEditPage.tsx (편집 화면) 등이 구현됩니다. • src/shared: 프로젝트 전반에서 쓰이는 공용 모듈 (유틸리티 함수, 공통 컴포넌트 등)을 둡니다. 예를 들어 공통 레이아웃이나 버튼 컴포넌트, 혹은 공통 훅이 있다면 shared 밑에 두어 어느 feature에서도 import 할 수 있도록 합니다. 단, FSD 원칙에 따라 shared 요소의 남용을 피하고 꼭 필요한 경우에만 사용합니다. 이러한 구조를 통해 폴더별, 모듈별 Public API를 명확히 노출하고 (index 파일을 통해 export 제어) 계층 간 의존성 방향을 아래로만 흐르도록 제한합니다. 즉, 상위 계층(pages)은 하위 (features, entities, shared)를 참조할 수 있지만, entities가 features나 pages를 역으로 참조하지는 않습니다. 이를 통해 변경이 발생해도 영향 범위가 최소화되고, 기능 단위로 독립적인 개발과 테스트가 가능해집니다[2]. Data Model and API Design (데이터 모델 및 API 설계) 데이터 모델 – Page 애플리케이션의 주요 데이터 객체는 페이지(Page)입니다. 각 Page는 아래와 같은 속성을 가집니다: - id (string): 페이지를 식별하는 고유 ID. (예: UUID 문자열 또는 간단한 슬러그) - title (string): 페이지 제목. 목록 및 헤드라인에 표시되며, 검색에 사용됩니다. - content (string): 페이지 내용 본문. 위키 페이지의 텍스트로, Markdown 또는 일반 텍스트 형식 (현재 단계에서는 서식 없는 텍스트로 간주). - createdAt (Date or string timestamp): 페이지 생성 시각 (옵션, UI에는 쓰이지 않을 수 있으나 정렬이나 로그에 활용 가능). - updatedAt (Date or string timestamp): 페이지 최종 수정 시각 (옵션). 참고: 현재 MVP 구현에서는 createdAt/updatedAt을 사용하지 않더라도, 추후 확장을 고려해 데이터 모델에 포함시켜 둡니다. 또한 작성자(author) 정보나 버전(version) 이력 등은 범위 밖이므로 포함하지 않습니다. 더미 데이터 (Dummy Data) 초기 상태에서 앱이 활용할 몇 개의 더미 페이지 데이터를 정의합니다. 예를 들어 애플리케이션 로드 시 아래와 같은 Page 목록을 하드코딩해둘 수 있습니다: [ { "id": "page-1", "title": "Getting Started", "content": "이것은 개인 위키의 시작 페이지입니다. 여기에 내용을 작성하세요." }, { "id": "page-2", "title": "About This Wiki", "content": "이 위키는 React와 TypeScript로 제작되었으며, Tailwind CSS로 스타일링되었습니다." } ] 이 데이터는 클라이언트 내 메모리에 저장되며, 앱 구동 시 전역 상태로 들고 있거나 혹은 localStorage를 통해 지속성(persistence)을 부여할 수 있습니다. (초기 개발 단계에서는 하드코딩하고, 필요하면 localStorage 저장/로드 추가를 고려) 클라이언트 API (더미 API 구현) 실제 백엔드가 없으므로, 클라이언트 측에 가짜 API 모듈을 만들어 React Query 훅이 이 함수를 통해 데이터를 가져오도록 합니다. API 모듈 (src/entities/page/api.ts 등)에는 다음 함수들이 포함됩니다: - getPages(): 모든 Page 목록을 반환. (예: Promise). 구현은 내부적으로 위의 더미 데이터 배열을 resolve하는 것으로 대체합니다. - getPage(id): 특정 ID의 Page를 반환. (예: Promise). 더미 구현은 배열에서 해당 id를 가진 객체를 찾아 반환합니다. 만약 존재하지 않을 경우 undefined나 에러 throw. - createPage(data): 새로운 Page를 생성. (예: Promise 반환). 전달된 title, content를 기반으로 새로운 Page 객체를 만들고 (id는 UUID 생성 또는 Date.now() 기반 unique string), 더미 데이터 배열에 추가합니다. 성공 시 생성된 Page를 반환합니다. - updatePage(id, data): 기존 Page 수정. (예: Promise). 주어진 id의 Page 객체를 찾아 title과 content를 업데이트하고, updatedAt 타임스탬프를 갱신합니다. 성공 시 수정된 Page 객체 반환. 대상이 없으면 에러 또는 null 처리. - deletePage(id): 페이지 삭제. (예: Promise). 주어진 id의 Page를 배열에서 제거합니다. 성공 여부를 불리언이나 void로 표시. 각 함수는 실제 서버 통신 대용이므로, 약간의 지연을 주어 비동기 처리를 시뮬레이트합니다. (예: setTimeout으로 100~300ms 후 resolve). 이렇게 하면 React Query의 로딩 상태 및 캐싱 메커니즘을 테스트하기 용이합니다. 엔드포인트 설계 (참고용) 향후 실제 백엔드가 구현된다면, 아래와 같은 RESTful API 엔드포인트를 상정할 수 있습니다: - GET /api/pages → 모든 페이지 조회 (쿼리 파라미터로 검색 키워드 지원 가능, 예: /api/pages?query=foo) - GET /api/pages/{id} → 특정 페이지 상세 조회 - POST /api/pages → 페이지 생성 (Request Body로 title, content 등 전송) - PUT /api/pages/{id} → 페이지 전체 수정 (Body로 title, content) - DELETE /api/pages/{id} → 페이지 삭제 그러나 본 프런트엔드 프로젝트에서는 위 엔드포인트들을 클라이언트 내 더미 함수로 대체하며, 실제 HTTP 요청은 발생하지 않습니다. React Query의 사용 패턴만 실제와 동일하게 유지하여, 나중에 이 더미 함수를 Axios 등을 통한 실제 API 호출로 교체하기 쉽도록 합니다. User Interface (사용자 인터페이스) 레이아웃 및 내비게이션 • 전역 레이아웃: 앱 상단에 고정된 헤더를 두어 프로젝트 명(예: “My Wiki”)을 표시하고, 우측에 검색 창을 배치합니다. 헤더는 Tailwind를 이용해 단순한 Top Nav Bar 형태로 구현합니다. 메인 콘텐츠 영역은 각 라우트별 화면이 표시되는 영역입니다. • 페이지 목록 화면: 애플리케이션의 홈("/")에 해당하며, 위키 페이지들의 목록이 표시됩니다. 각 항목은 카드나 리스트 아이템 형태로 페이지 제목을 보여주고, 클릭 시 해당 페이지 상세보기로 이동합니다. 목록 상단에는 "새 페이지 만들기" 버튼을 배치하여, 클릭 시 페이지 생성 폼 화면으로 전환합니다. 또한 헤더의 검색 입력을 통해 목록이 필터링됩니다 (또는 별도의 검색 영역이 상단에 있을 수도 있음). • 페이지 상세보기 화면: 선택된 특정 페이지의 내용을 보여주는 화면입니다. URL은 "/pages/:id" 형태로 라우팅됩니다. 제목을 큰 글자로 표시하고, 내용(content)을 단락으로 렌더링합니다. (Markdown이 지원된다면 Marked 같은 파서를 이용해 HTML로 변환해 표시할 수 있으나, 현재는 텍스트를

로 출력). 이 화면 상단 또는 하단에 편집, 삭제 버튼이 제공됩니다. 사용자가 "편집"을 누르면 편집 화면("/pages/:id/edit")으로 이동하며, "삭제"를 누르면 삭제 확인 모달이 뜹니다. • 페이지 생성/편집 화면: 새 페이지 생성 폼과 기존 페이지 편집 폼은 유사한 UI를 사용하므로, 하나의 폼 컴포넌트로 재사용합니다. 라우팅은 생성의 경우 "/pages/new", 편집은 "/pages/:id/edit"로 구분됩니다. 제목 입력 필드()와 내용 입력 필드(