David Brain

4-3_Wiki-문서-기능

4 min read

ID: key_26_22_05_25_P4_4_3 Created date: 5월 25 2026 월요일

연관 문서

개발 일정 > Phase 4 서버 개발 | UI 개발

개요

프로젝트 내 Wiki 문서 기능을 구현한다. 계층 구조, 마크다운 에디터, 이슈 임베드를 지원한다.

  • 예상 소요: 5~6일
  • 선행 조건: Phase 3 완료

Claude Code 작업 수행서

작업 지시

CIRA 서버 + UI에 Wiki 문서 기능을 구현해줘.

[수행 작업]

1. DB 마이그레이션
   V220__create_wiki.sql:
   wiki_pages: id(UUID), project_id(FK NOT NULL), parent_id(FK→wiki_pages — 셀프참조),
               title(VARCHAR 500 NOT NULL), content(TEXT),
               content_html(TEXT — 렌더링 캐시),
               author_id(FK→users), sort_order(INT),
               version(INT DEFAULT 1 — 낙관적 잠금)
   wiki_page_versions: id(UUID), page_id(FK), version(INT), content(TEXT),
                       edited_by(FK→users), edited_at(TIMESTAMPTZ)

2. Wiki API
   GET    /api/v1/projects/{projectId}/wiki              — 트리 구조 조회
   POST   /api/v1/projects/{projectId}/wiki              — 페이지 생성
   GET    /api/v1/wiki/{pageId}                          — 페이지 상세
   PUT    /api/v1/wiki/{pageId}                          — 페이지 수정
   DELETE /api/v1/wiki/{pageId}                          — 페이지 삭제 (하위 포함)
   GET    /api/v1/wiki/{pageId}/versions                 — 버전 이력
   PUT    /api/v1/wiki/{pageId}/move                     — 트리 이동 (parent_id 변경)

3. 마크다운 처리
   - 서버: commonmark-java 라이브러리로 content → content_html 변환
   - 이슈 임베드 처리: [[CIRA-123]] 패턴 파싱
     → <a href="/issues/CIRA-123">CIRA-123: 제목 [상태]</a> 변환
   - content 수정 시 content_html 자동 재생성

4. 버전 관리
   - 페이지 수정 시 이전 버전을 wiki_page_versions에 저장
   - GET /wiki/{pageId}/versions/{version} — 특정 버전 조회
   - 버전 간 diff 표시 (문자열 diff)

[UI 수행 작업]

5. Wiki 사이드바
   파일: src/components/wiki/WikiTree.tsx
   - 트리 구조 (재귀 컴포넌트)
   - 접기/펼치기 토글
   - 드래그로 순서/부모 변경
   - "+ 새 페이지" 버튼 (현재 위치 하위)

6. Wiki 에디터
   파일: src/components/wiki/WikiEditor.tsx
   - TipTap 에디터 (추천) 또는 Milkdown
   - 툴바: H1~H3, Bold, Italic, Code, 코드블록, 링크, 이미지, 테이블
   - 이슈 임베드: @[[ 입력 시 이슈 검색 팝업
   - 저장: Ctrl+S 단축키 + 저장 버튼
   - 자동 저장: 30초 간격 드래프트 저장 (localStorage)

7. Wiki 뷰어
   파일: src/app/(main)/projects/[projectId]/wiki/[pageId]/page.tsx
   - 마크다운 HTML 렌더링
   - 이슈 임베드 링크 (상태 배지 포함)
   - 목차 (H1~H3 자동 추출)
   - 수정 버튼 → 에디터 모드
   - 버전 이력 링크

8. 버전 이력 페이지
   - 버전 목록 (날짜, 수정자)
   - 두 버전 선택 → diff 뷰어 (추가: 초록, 삭제: 빨강)

완료 기준

항목기준
Wiki 트리계층 구조 표시 + 순서 변경
마크다운 에디터툴바 + 이슈 임베드 동작
버전 관리수정 시 이전 버전 저장
이슈 임베드CIRA-123 클릭 → 이슈 이동
Diff 뷰어두 버전 간 변경사항 표시

Graph View