43 KiB
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 (기능 명세)
- 페이지 관리 (Page Management CRUD) • 페이지 생성: 사용자는 새로운 위키 페이지를 생성할 수 있습니다. 페이지 생성 시 제목(title)과 본문(content)을 입력받는 폼을 제공하며, “생성” 버튼으로 제출합니다. 제출 후 새 페이지가 저장되고 애플리케이션에 즉시 반영됩니다. 생성된 페이지는 고유 ID를 부여받고, 목록 및 검색에 노출됩니다. • 페이지 보기: 저장된 위키 페이지를 화면에서 열람할 수 있습니다. 제목은 헤드라인으로 표시하고 본문 콘텐츠는 본문 영역에 표시합니다. 뷰 화면에서는 편집 및 삭제 작업을 수행할 수 있는 UI 버튼을 제공합니다. 라우팅을 지원하여, 각 페이지는 고유 URL (/pages/{id} 형태 등)로 접근 가능하게 합니다 (예: 즐겨찾기나 직접 URL로 접근 시 해당 페이지 표시). • 페이지 편집: 기존 페이지의 제목과 본문을 수정할 수 있습니다. “편집” 버튼을 누르면 편집 폼이 나타나며, 현재 저장된 제목/내용을 편집할 수 있습니다. 수정 완료 후 “저장”하면 변경사항이 저장되고, 페이지 보기 화면에 갱신된 내용이 반영됩니다. 편집 중 “취소”를 선택하면 변경사항 없이 페이지 보기 화면으로 돌아갑니다. • 페이지 삭제: 사용자는 페이지를 삭제할 수 있습니다. “삭제” 버튼을 클릭하면 한 번 더 확인을 받는 확인 대화상자(modal)를 표시하여 오작동을 방지합니다. 확인 시 해당 페이지를 삭제하고, 사용자에게 삭제 완료를 알린 뒤 페이지 목록 화면으로 리다이렉트합니다. 삭제된 페이지는 목록과 검색 결과에서 즉시 제거됩니다.
- 검색 기능 (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<Page[]>). 구현은 내부적으로 위의 더미 데이터 배열을 resolve하는 것으로 대체합니다.
- getPage(id): 특정 ID의 Page를 반환. (예: Promise<Page | undefined>). 더미 구현은 배열에서 해당 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"로 구분됩니다. 제목 입력 필드()와 내용 입력 필드( 멀티라인)을 제공하며, Tailwind CSS로 폼 스타일링을 깔끔하게 합니다. 폼 하단에 “저장” (생성의 경우 “생성”)과 “취소” 버튼이 있습니다. 취소 시 이전 페이지로 돌아가고, 저장 시 입력값에 대한 유효성 검사 후 API 호출을 트리거합니다. React Query의 useMutation을 사용하여 POST/PUT 더미 API를 호출하며, 완료되면 페이지 상세보기 화면으로 네비게이트하거나 목록으로 돌아갑니다 (상세보기 화면으로 이동하는 편이 사용자에게 즉시 결과를 확인시켜주므로 바람직). • 페이지 삭제 흐름: 페이지 상세 화면에서 “삭제” 클릭 시 Radix UI의 AlertDialog 컴포넌트를 이용하여 모달 창을 띄웁니다. 모달에는 “정말 삭제하시겠습니까? 이 동작은 되돌릴 수 없습니다.” 등의 경고 메시지와 함께 "삭제 확인" 및 "취소" 버튼을 제공합니다. 모달 밖 영역 클릭이나 취소 클릭 시 모달을 닫습니다. 삭제 확인 버튼 클릭 시 deletePage API 호출(mutation)을 수행하고, 성공 시 모달을 닫은 뒤 토스트 알림 또는 사용자 피드백 (예: “삭제되었습니다”)을 보여준 후 페이지 목록 화면으로 이동시킵니다. (토스트 구현은 필수가 아니므로, 간단히 목록으로 리디렉션하는 것으로 충분할 수 있습니다.) UI 요소 및 스타일 가이드 • 타이포그래피: Tailwind 프리셋을 활용하여 문서 느낌의 타이포그래피 스타일 적용. 예를 들어 제목(title)은 text-2xl font-bold 등으로 크고 굵게 표시, 본문은 text-base leading-relaxed로 가독성을 높임. 전체 레이아웃은 밝은 배경에 짙은 색 텍스트(다크모드 지원은 일단 제외). • 버튼: 주요 액션 버튼(생성, 저장, 삭제 등)은 Tailwind의 유틸리티 클래스로 스타일링하되, Radix UI와 조합해 키보드 포커스 스타일 및 ARIA 레이블을 신경 씀. 예: <button class="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700 focus:outline-none focus:ring">저장</button> 형식으로 일관된 버튼 스타일 사용. • 폼 입력: <input>과 <textarea> 등 폼 요소는 Tailwind 폼 리셋 클래스를 활용해 기본 브라우저 스타일을 제거하고 (@tailwind base에 포함된 form-elements resets), border와 padding 등을 준 깔끔한 input 스타일로 디자인. Radix UI의 <Label> 컴포넌트를 사용하여 접근성 있는 레이블 연결을 해줄 수 있습니다 (label 요소와 input의 id를 연결). • 모달/다이얼로그: Radix UI의 Dialog/AlertDialog 사용 시, Tailwind로 오버레이 반투명 배경(bg-gray-800 bg-opacity-50 등)과 컨텐츠 카드(bg-white rounded shadow p-6 등)를 스타일링합니다. Radix UI는 모달이 열릴 때 focus를 트랩하고 ESC로 닫기 등을 기본 지원하므로, 이러한 부분을 그대로 활용합니다[5][6]. • 반응형 디자인: 작은 화면(모바일)에서는 목록이 한 줄씩 쌓이고, 검색바와 새 페이지 버튼 등은 상단에 블록 배치됩니다. 큰 화면에서는 목록을 카드 그리드로 보여주거나, 좌측에 목록 + 우측에 상세보기처럼 2열 레이아웃을 적용할 수 있지만, 우선 단순화된 단일 열(column) 레이아웃으로 구현합니다. Tailwind의 responsive 툴 (sm:, md: prefix 등)로 필요 시 스타일 조정 예정. Implementation Plan (구현 작업 계획) 아래는 프로젝트를 단계별로 구현하기 위한 세부 Tasks 목록입니다. 각 작업은 논리적으로 구분되며, 순차적으로 진행합니다. _WindSurf Cascade_와 같은 AI 코딩 도구가 이 단계를 따라갈 수 있도록, 명확한 단위 작업으로 나열하였습니다.</li> </ul> <ol dir="auto"> <li> <p dir="auto">Project Setup and Dependencies: 초기 프로젝트 설정 및 의존성 관리. Vite + React + TypeScript 템플릿으로 생성된 프로젝트가 있다고 가정합니다. 우선 필수 패키지를 추가 설치합니다: Tailwind CSS, PostCSS, Autoprefixer, Radix UI (필요한 컴포넌트 패키지들, 예: @radix-ui/react-dialog, @radix-ui/react-alert-dialog), TanStack React Query (@<a href="mailto:tanstack/react-query@5.90" data-markdown-generated-content="">tanstack/react-query@5.90</a>.7), React Router DOM. package.json에 명시된 버전(@types 포함)은 최신을 사용합니다. 작업 내용: npm install -D tailwindcss postcss autoprefixer 및 npx tailwindcss init으로 Tailwind 설정 파일 생성; npm install @radix-ui/react-dialog @radix-ui/react-alert-dialog @radix-ui/react-icons 등 Radix UI 패키지 설치; npm install @tanstack/react-query react-router-dom 등. 설치 후 애플리케이션을 실행하여 문제가 없는지 확인합니다.</p> </li> <li> <p dir="auto">Configure Tailwind CSS: Tailwind CSS를 프로젝트에 설정합니다. Tailwind 설정 파일(tailwind.config.js)을 열어 content 경로를 설정하고 (./index.html, ./src/**/*.{js,ts,jsx,tsx} 등), 필요한 Tailwind 플러그인 또는 테마 설정 (예: 폰트 패밀리, 컬러 팔레트 커스터마이징)이 있으면 추가합니다. 글로벌 CSS (src/index.css 또는 App.css)에 Tailwind 지시어를 추가합니다:</p> <p dir="auto">@tailwind base; @tailwind components; @tailwind utilities; 브라우저 기본 스타일과 Form 스타일을 리셋하기 위해 Tailwind Preflight가 적용되었는지 확인합니다. Tailwind가 제대로 적용되었는지 검증하기 위해 간단한 요소에 클래스 (예: <div class="text-red-500">Test</div>)를 넣어 화면에서 색상이 적용되는지 확인합니다.</p> </li> <li> <p dir="auto">Integrate Radix UI Library: Radix UI 컴포넌트를 사용할 준비를 합니다. 프로젝트에 Radix UI의 AlertDialog (삭제 확인에 사용), Dialog (필요시 생성/편집 폼 모달용), 그리고 Radix Icons (필요한 아이콘이 있을 경우) 등을 설치했으므로, 실제 사용을 위해 Radix UI의 스타일 가이드를 참고합니다. Radix는 기본적으로 언스타일드 컴포넌트를 제공하므로, Tailwind와 함께 사용할 예정입니다[4]. 작업 내용: Radix 컴포넌트 사용법 익히기 (예: AlertDialog 구성 요소 – <AlertDialog.Root>, <AlertDialog.Trigger>, <AlertDialog.Content> 등). 추후 구현 단계에서 바로 활용할 수 있도록, 간단한 테스트 컴포넌트를 만들어 Radix AlertDialog가 열리고 닫히는지 콘솔 로그로 확인해봅니다 (선택 사항). Radix UI 공식 사이트의 예제 코드를 참조하여 접근성 속성(ARIA 레이블 등)이 잘 적용되도록 유의합니다.</p> </li> <li> <p dir="auto">Establish Project Structure (FSD): Feature-Sliced Design 원칙에 따라 폴더 구조를 정리합니다. src/ 디렉토리 아래에 entities, features, pages, shared 폴더를 생성합니다. 각 폴더에는 index 파일을 만들어, 바깥에서 import 할 때 경로가 노출되지 않도록 encapsulation을 관리합니다.</p> </li> <li> <p dir="auto">src/entities/page/: 페이지 엔티티 관련 모델 정의와 데이터 액세스 코드. 예: types.ts에 Page 인터페이스 정의, api.ts에 더미 API 함수 (getPages, getPage, createPage, updatePage, deletePage) 선언 및 구현.</p> </li> <li> <p dir="auto">src/features/page/: 페이지 관련 UI와 로직. 예: PageList 컴포넌트 (PageList.tsx), PageItem.tsx (목록 내 개별 아이템), PageForm.tsx (생성/편집 폼), 그리고 해당 컴포넌트들의 스타일이나 훅을 넣을 수 있습니다. 기능별로 폴더를 더 세분화해도 되지만 현재 규모에선 하나의 폴더에 모아도 무방합니다.</p> </li> <li> <p dir="auto">src/features/search/: 검색바 UI 컴포넌트 (SearchBar.tsx) 및 관련 훅/로직. (간단한 프로젝트라 이 정도로 충분)</p> </li> <li> <p dir="auto">src/pages/: 라우트에 대응하는 페이지 컴포넌트. 예: PageListPage.tsx, PageDetailPage.tsx, PageEditPage.tsx. 이들은 주로 UI 배치를 담당하며, 내부에서 features의 컴포넌트를 조립해 화면을 구성합니다.</p> </li> <li> <p dir="auto">src/shared/: 프로젝트 전반에서 쓰일 수 있는 컴포넌트나 유틸. 예: 공통 레이아웃 컴포넌트 (컨테이너, 헤더 등), 공통 Button 컴포넌트 (필요시), 또는 shared/api (Fetch wrapper 등). 현재 단계에서는 크게 필요하지 않을 수 있으므로 최소한으로 유지합니다. 작업 내용: 위 구조대로 디렉토리를 만들고, 각 위치에 placeholder 파일들을 생성해둡니다 (예: 각 컴포넌트 파일에 기본적인 React 컴포넌트 뼈대 작성, 예: export const PageList = () => { return <div>PageList</div> } 등). 이렇게 하면 나중 단계에서 각각 구현할 때 구조가 갖춰져 있어 편리합니다. 또한, FSD 취지에 맞게 모듈간 의존성 규칙을 확인합니다: entities에는 UI 코드가 없고, features는 필요한 경우 entities를 import하여 데이터 사용, pages는 features와 entities를 조합, shared는 어디서나 import 가능하지만 핵심 비즈니스 로직은 담지 않음.</p> </li> <li> <p dir="auto">Implement Data Model & Dummy API: entities/page 폴더 내에 Page 데이터 모델과 더미 API를 구현합니다.</p> </li> <li> <p dir="auto">types.ts: Page 인터페이스 정의 (interface Page { id: string; title: string; content: string; createdAt?: string; updatedAt?: string }).</p> </li> <li> <p dir="auto">data.ts (선택): 초기 더미 데이터 배열 선언. 예: let pages: Page[] = [ {...}, {...} ];로 앞서 명시한 몇 개의 예시 데이터를 포함합니다.</p> </li> <li> <p dir="auto">api.ts: 위에서 설계한 getPages, getPage, createPage, updatePage, deletePage 함수를 구현합니다. 각 함수는 Promise를 반환하며, 내부에서 setTimeout으로 약간의 지연 후 resolve합니다. o getPages(): return Promise.resolve(pages); (혹은 setTimeout으로 pages 반환). o getPage(id): const page = pages.find(p => p.id === id); return Promise.resolve(page); (못 찾으면 Promise.reject하거나 resolve(undefined) 처리). o createPage(data): { id: generateId(), ...data, createdAt: new Date().toISOString() } 형태로 객체 생성 후 pages.push()로 추가, 생성된 객체를 resolve. (ID 생성은 단순 Date.now().toString()이나 uuid 패키지 사용할 수 있으나, 의존성 줄이기 위해 간단히 구현). o updatePage(id, data): const page = pages.find(...); 찾아서 page.title = data.title; page.content = data.content; page.updatedAt = new Date().toISOString(); 한 뒤 그 객체를 resolve. 못 찾으면 reject. o deletePage(id): pages = pages.filter(p => p.id !== id); return Promise.resolve();. 각 함수는 오류 상황 (예: 존재하지 않는 ID 편집 등)에 대한 콘솔 경고나 예외 throw를 넣어두면 디버깅에 도움이 됩니다.</p> </li> <li> <p dir="auto">유틸리티: Optionally, generateId() 함수를 만들어 (shared 폴더나 api.ts 내) 단순 unique ID 생성 (예: 'page-' + Math.random().toString(36).substr(2, 9)). 이렇게 구현한 더미 API는 실제 React Query와 연결되어 사용되므로, TypeScript 타입을 정확히 지정하여 훅에서 타입 추론이 제대로 되도록 합니다. (예: function getPages(): Promise<Page[]> { ... } 등 선언)</p> </li> <li> <p dir="auto">Initialize App Providers (React Query & Router): 애플리케이션의 엔트리 포인트 설정을 완료합니다. src/main.tsx (또는 src/App.tsx)에서 QueryClientProvider와 BrowserRouter를 설정합니다.</p> </li> <li> <p dir="auto">TanStack React Query: import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; 한 뒤 const queryClient = new QueryClient(); 생성. 최상위 <QueryClientProvider client={queryClient}>로 App 컴포넌트를 감쌉니다. 이렇게 함으로써 하위에서 useQuery, useMutation 사용이 가능해집니다[7].</p> </li> <li> <p dir="auto">React Router: import { BrowserRouter, Routes, Route } from 'react-router-dom'; 추가. QueryClientProvider 내부에서 <BrowserRouter>로 라우터를 설정합니다. <Routes> 내에 각 path와 페이지 컴포넌트를 매핑합니다. 예:</p> <Routes> </li> </ol> <p dir="auto"><Route path="/" element={<PageListPage />} /> <Route path="/pages/new" element={<PageEditPage isNew={true} />} /> <Route path="/pages/:id" element={<PageDetailPage />} /> <Route path="/pages/:id/edit" element={<PageEditPage isNew={false} />} /> </Routes> 여기서 PageEditPage 컴포넌트는 isNew prop으로 생성/편집 모드를 구분하도록 설계했습니다. (Alternatively, 분리된 NewPage, EditPage 컴포넌트를 만들어도 됩니다.) 4. 전역 Context: 추후 페이지 간 상태 공유나 UI를 위해 React Context가 필요하다면 Context Provider를 추가할 수 있으나, 현재는 React Query가 데이터를 전역 캐시로 관리하므로 별도 Context는 사용하지 않습니다. 5. 작업 내용: App 초기 구조를 완성짓는 이 단계에서는 아직 각 Page 컴포넌트 내부 구현은 비워둘 수 있습니다. 라우팅이 제대로 동작하는지, 잘못된 경로 접근 시 등의 처리를 확인합니다 (추가로 <Route path="*"에 404 페이지를 만들 수 있지만 필수는 아님). 6. Implement Page List Page (All Pages List + Search): 홈 화면에 해당하는 페이지 목록 화면을 구현합니다. 이는 pages/PageListPage.tsx 컴포넌트로, 내부에서 features/page/PageList와 features/search/SearchBar 컴포넌트를 조합합니다. 7. 데이터 가져오기: React Query의 useQuery 훅을 사용하여 페이지 목록 데이터를 fetch합니다. useQuery(['pages'], getPages) 형태로 키를 'pages'로 주고, 앞서 구현한 getPages API 함수를 연결합니다. 컴포넌트가 마운트되면 pages 데이터를 불러와 캐시에 저장하고, 로딩 상태와 에러를 관리합니다. 8. 로딩/에러 처리: if (isLoading) ... 혹은 Skeleton UI, if (error) ... 오류 메시지 등을 적절히 표시합니다. (공식 문서 느낌을 위해 간략한 텍스트로 표기) 9. 페이지 리스트 표시: 데이터를 받으면 <ul> 혹은 <div> 리스트를 순회하여 각 페이지의 제목을 출력합니다. features/page/PageItem 컴포넌트를 만들어 각 아이템 (제목과 간략 내용 일부?)을 렌더링하고, 클릭하면 해당 페이지 상세로 이동하도록 링크 (<Link to={/pages/${id}}>)를 겉에 감싸줍니다. React Router의 <Link>를 이용하면 a태그 대신 SPA 내부 전환이 이루어집니다. 10. 검색 기능: 상단에 features/search/SearchBar 컴포넌트를 배치합니다. SearchBar는 내부에 <input type="text">를 갖고, onChange 시 상위 컴포넌트로 검색어를 알려주는 콜백 prop을 받을 수 있습니다. PageListPage에서 const [query, setQuery] = useState('')로 상태를 관리하고, SearchBar의 prop으로 onSearchChange={setQuery}를 전달합니다. 검색 구현을 간단히 하기 위해, 클라이언트 필터링을 우선 채택합니다: const filteredPages = data.filter(page => page.title.includes(query) || page.content.includes(query)). 그리고 이 filteredPages를 맵으로 렌더링합니다. (추후 실제 API 사용 시 getPages(query) 형태로 쿼리参数를 전달해 서버 필터링할 수 있음). 11. 새 페이지 버튼: 페이지 상단 또는 하단에 “+ 새 페이지” 버튼을 제공합니다. <Link to="/pages/new">새 페이지</Link> 형태로 구현하여 클릭 시 새 페이지 생성 폼으로 이동합니다. 이 버튼은 Tailwind로 스타일링하고, Radix UI의 <Button>이나 아이콘을 사용할 수 있습니다 (+ 아이콘 등 추가). 12. 작업 내용: PageListPage 구현 및 스타일링. SearchBar 컴포넌트는 <input>에 Tailwind 클래스로 적절한 스타일 (예: border p-2 rounded w-full)을 적용하고 placeholder로 "검색어를 입력하세요". SearchBar의 값을 controlled component로 관리하여, 상위에서 내려온 query 상태와 동기화합니다. 입력이 변경되면 setQuery를 호출해 PageListPage를 re-render하여 filteredPages가 갱신되도록 합니다. 13. 검증: 몇 개의 더미 데이터가 보이는지 확인하고, 검색란에 문자열을 넣었을 때 실시간으로 리스트가 줄어드는지 확인합니다. 없는 단어를 넣으면 빈 상태 표시하는지 검토합니다. 14. Implement Page Detail Page (View Page): 개별 페이지 내용을 보여주는 pages/PageDetailPage.tsx 컴포넌트를 구현합니다. React Router를 통해 경로 /pages/:id로 렌더링되며, useParams() 훅을 사용해 URL에서 id를 받아옵니다. 15. 데이터 가져오기: const { id } = useParams(); 한 후, React Query의 useQuery(['page', id], () => getPage(id))를 사용하여 해당 id의 페이지 데이터를 불러옵니다 (getPage는 앞서 만든 API 함수). 캐싱을 위해 키를 ['page', id]로 구분하였고, 이 데이터는 앞서 'pages' 리스트와 별도로 관리됩니다. (단, React Query가 기본으로 캐시해두므로, 만약 PageListPage에서 이미 전체 리스트를 불러왔다면, 개별 getPage 호출 없이도 캐시에서 찾아오는 최적화가 가능하지만 여기선 단순 구현). 16. UI 표시: 로딩 중이면 "불러오는 중..." 표시, 에러 발생 시 오류 메세지 표시. 데이터가 있으면 페이지 제목과 내용을 보여줍니다. 제목은 <h1 class="text-2xl font-bold mb-4">...</h1> 형식으로 표시하고, 내용은 줄바꿈 등을 유지하도록 <p class="whitespace-pre-line">...</p>로 출력하거나, Markdown 파싱을 고려할 경우 마크업 처리. 17. 편집/삭제 버튼: 페이지 내용 아래 혹은 위에 액션 버튼들을 배치합니다. Tailwind로 버튼 스타일을 지정하고, React Router <Link>로 편집 이동 (to={/pages/${id}/edit})를 설정합니다. 삭제 버튼은 클릭 이벤트 핸들러를 설정하여, AlertDialog 모달을 열도록 합니다. 18. Radix AlertDialog 통합: Radix UI의 AlertDialog를 PageDetailPage 내에서 사용하여 삭제 확인을 구현합니다. AlertDialog.Root로 감싸고, trigger는 삭제 버튼으로 설정 (<AlertDialog.Trigger asChild><button className="...">삭제</button></AlertDialog.Trigger>). 그리고 <AlertDialog.Content>에 모달 내용을 작성합니다: 경고 아이콘(선택), "이 페이지를 삭제하시겠습니까?" 등의 메시지, <AlertDialog.Action> 버튼 (실행), <AlertDialog.Cancel> 버튼 (취소). 스타일링은 Radix 공식 예제 참고하여 Tailwind 클래스 부여[8][9]. 19. Delete Mutation: 삭제 확인 버튼 클릭 시 실제 삭제 로직을 실행해야 합니다. React Query의 useMutation(deletePage)를 사용하여 mutation 훅을 정의합니다:</p> <div data-attr-class="d4a5f20592d01ee5:code-block-container code-overflow-scroll"><pre data-attr-class="d4a5f20592d01ee5:code-block"><code data-attr-class="d4a5f20592d01ee5:chroma language-text" data-code-language="text">const deleteMutation = useMutation(() => deletePage(id!), { </code></pre></div><p dir="auto">onSuccess: () => { // invalidation and navigation } }); onSuccess에서는 React Query 캐시에서 페이지 리스트와 개별 페이지 데이터를 무효화합니다: e.g. queryClient.invalidateQueries(['pages']); queryClient.removeQueries(['page', id]);. 그리고 navigate("/")를 호출하여 목록 화면으로 리디렉션합니다. (React Router v6의 useNavigate 훅 사용). 20. 작업 내용: PageDetailPage에 위 내용들을 모두 조합합니다. 특히 AlertDialog는 별도 컴포넌트로 분리해도 되지만 (features로), 여기서는 PageDetailPage 내부에 직접 작성합니다. 삭제 버튼을 클릭하면 deleteMutation.mutate()를 호출하도록 onClick 또는 AlertDialog Action의 onSelect에 연결합니다. React Query의 mutation 상태 (isLoading, isError)를 관리하여, 삭제 진행중에는 버튼을 비활성화하거나 로딩 표시, 에러 시 alert 표시도 고려합니다. 21. Implement Page Form (Create & Edit): 페이지 생성과 편집을 담당하는 폼 컴포넌트를 구현합니다. features/page/PageForm.tsx로 만들고, 재사용할 수 있도록 입력 필드와 제출 로직을 포함합니다. 그리고 pages/PageEditPage.tsx (혹은 NewPage/EditPage)를 작성하여 PageForm을 사용합니다. 22. PageForm 컴포넌트: props로 initialData (Page 또는 undefined), onSubmit 콜백, isNew (boolean) 등을 받을 수 있습니다. 내부에 제목 입력 (<input value={title} onChange={...} />)과 내용 입력 (<textarea value={content} onChange={...} />)을 state로 관리합니다. initialData가 주어지면 해당 값으로 초기화하고, 없으면 빈 문자열로 시작합니다. 23. 유효성 검사: 제목은 필수, 너무 긴 경우 자를 수도 있음. 간단히 빈 값 체크 정도를 하고, 유효하지 않을 때는 버튼 비활성화 또는 오류 메시지 (예: "제목은 필수입니다")를 폼 상단에 표시합니다. 24. 저장 동작: 폼 제출 시 React Query useMutation을 사용하여 API 호출. const createMutation = useMutation(createPage, { onSuccess: ... }), const updateMutation = useMutation(updatePage, { onSuccess: ... }). PageForm 내부에서 isNew 여부에 따라 적절한 mutation 함수를 호출합니다. onSuccess 시: o 생성의 경우: 새로 생성된 Page 객체를 받으면 navigate("/pages/[newId]")로 상세 페이지로 이동 (또는 페이지 목록으로 이동하고 success 토스트). 그리고 'pages' 리스트를 무효화하여 목록을 갱신시킵니다. o 수정의 경우: 변경 사항이 이미 캐시에 반영되도록 queryClient.setQueryData(['page', id], updatedPage)를 하면 상세보기 즉시 반영 가능. 또한 'pages' 목록도 invalidate (목록에 제목 업데이트 반영 위해). 그리고 navigate(-1) 또는 navigate("/pages/{id}")로 돌아갑니다. 25. 취소 버튼: navigate(-1) 호출하여 이전 페이지로 돌아가도록 처리 (편집 → 상세, 생성 → 목록). 26. 스타일링: 폼 레이아웃은 <div className="max-w-xl mx-auto"> 등 가운데 정렬, 위에 제목 입력 (Label: "제목", Input 박스), 아래 본문 입력 (Label: "내용", Textarea 높이를 적당히). Tailwind로 폼 요소 스타일 지정 (border, rounded 등). Radix UI의 <Form> 컴포넌트는 사용하지 않아도 되지만, Radix의 <Label>을 사용할 수 있습니다: <Label htmlFor="title">제목</Label> 등. 27. pages/PageEditPage.tsx: 이 페이지 컴포넌트는 라우트로부터 id를 얻고, isNew 여부에 따라 동작 분기합니다. id가 있는 경우 편집이므로 React Query로 기존 데이터를 가져와 PageForm에 props로 전달합니다 (initialData=pageData). id가 없는 (예: path=="/pages/new") 경우 PageForm에 initialData={undefined}로 전달. PageEditPage는 PageForm 주위에 적절한 레이아웃이나 헤더 (예: "페이지 생성" 또는 "페이지 편집" 헤딩) 넣어줄 수 있습니다. 28. 작업 내용: PageForm의 state와 이벤트가 제대로 작동하도록 구현하고, PageEditPage에서 이를 사용. React Query mutation이 진행되는 동안 저장 버튼을 disabled 처리하고 "저장 중..." 인디케이터 (스피너 or 텍스트) 보여주기. 에러 발생 시 폼 하단에 오류 메시지 출력. 29. Finalize Delete Functionality: 페이지 삭제 기능 마무리. PageDetailPage에서 구현한 deleteMutation이 전체 앱 상태를 잘 갱신하는지 확인합니다. o PageList (홈)에서 삭제된 페이지가 빠졌는지 확인 (React Query invalidate가 잘 동작하면 자동 갱신될 것). 혹시 캐시 갱신이 실시간으로 안 된다면, 수동으로 상태를 업데이트하거나 PageList에서도 React Query 캐시를 subscribe하여 변경을 감지하는 방안 고려. 하지만 기본적으로 invalidateQueries(['pages']) 호출로 PageListPage의 useQuery가 재실행되어 최신 pages를 가져오게 됩니다. o 삭제 후 navigate("/")로 간 후, PageDetailPage가 언마운트되며 혹시 있을 수 있는 memory leak 방지 (예: 컴포넌트 언마운트 후 setState 없도록). React Query의 자동 취소 기능이 있으므로 대체로 안전하지만, 필요 시 onSettled에서 추가 처리를 검토. o Radix AlertDialog 모달이 ESC나 Cancel로 잘 닫히는지 UX 확인. o 작업 내용: 위 시나리오를 수동 테스트하여 결함이 없는지 점검하고, 필요한 경우 코드 보완. 30. Testing & Polish: 모든 주요 기능을 구현한 뒤, 앱 전반에 걸쳐 QA 테스트를 수행하고 마무리 다듬기를 합니다. o 기능 테스트: 페이지 생성 → 목록/검색 반영 확인, 페이지 편집 → 상세뷰 반영 확인, 페이지 삭제 → 목록 제거/라우팅 확인, 검색 → 올바른 필터링 작동 여부 등을 각각 시나리오별로 테스트합니다. 엣지 케이스로 빈 제목 생성, 매우 긴 내용 입력, 연속 빠른 조작 등에 앱이 잘 대응하는지 확인합니다. o 오류 처리: 더미 API 상에서 발생할 수 있는 에러 (예: 중복된 ID, 없는 페이지 접근 등)에 대비하여 사용자에게 안내를 추가합니다. 예를 들어 존재하지 않는 페이지 ID로 /pages/abc 접근 시 PageDetailPage의 useQuery 결과가 undefined이면 "페이지를 찾을 수 없습니다" 메시지와 홈으로 가는 링크를 제공하는 식으로 처리합니다. o UI 폴리시: 디자인 일관성 점검 – 폰트 크기/색상 통일, 다크모드 미지원 안내 여부, 반응형 동작 확인 (브라우저 크기 줄였을 때 메뉴나 리스트가 깨지지 않는지). 필요하면 CSS 미세 조정. o 코드 정리: 콘솔 로그 등 디버그 코드를 제거하고, 타입 any 남용된 부분 없애기, 불필요한 주석 정리. 컴포넌트 구조가 FSD 규칙에 어긋나는 부분이 없는지 재확인 (shared 폴더의 역할 남용 여부 등). o 문서 보완: README나 주석에 사용 방법, 폴더 구조 설명 등을 추가합니다. 동료 개발자가 본 프로젝트를 쉽게 이해할 수 있도록, PRD 주요 내용을 README에 요약하거나, FSD 구조를 그림으로 넣어도 좋습니다. 이상으로 개인 위키 SPA 프로젝트의 요구사항 정의와 구현 계획을 모두 정리했습니다. 위 계획을 차근차근 실행하면, 공식 문서 느낌의 세련된 Wiki 웹앱을 완성할 수 있을 것입니다. 각 작업이 완료될 때마다 애플리케이션이 의도대로 동작하는지 확인하면서 진행합니다. 필요에 따라 조율하며 개발하면 무리 없이 프로젝트 목표를 달성할 수 있을 것입니다.</p> <hr> <p dir="auto">[1] 쉽게 정리한 Feature-Sliced Design(FSD) 가이드 <a href="https://dansoon-dev.tistory.com/13" data-markdown-generated-content="">https://dansoon-dev.tistory.com/13</a> [2] Welcome | Feature-Sliced Design <a href="https://feature-sliced.design/" data-markdown-generated-content="">https://feature-sliced.design/</a> [3] [7] React-Query 개념 <a href="https://velog.io/@parkcode/React-Query-%EA%B0%9C%EB%85%90" data-markdown-generated-content="">https://velog.io/@parkcode/React-Query-%EA%B0%9C%EB%85%90</a> [4] Headless UI vs Radix UI: Which Component Library Is Right for You? - Lodely <a href="https://www.lodely.com/blog/headless-ui-vs-radix-ui" data-markdown-generated-content="">https://www.lodely.com/blog/headless-ui-vs-radix-ui</a> [5] [6] [8] [9] Building components with Radix UI | Refine <a href="https://refine.dev/blog/radix-ui/" data-markdown-generated-content="">https://refine.dev/blog/radix-ui/</a></p> </body></html>