ID: key_26_22_05_25_P2_2_2 Created date: 5월 25 2026 월요일
연관 문서
개발 일정 > Phase 2 UI 개발 | 2-1_칸반-보드-API
개요
Drag & Drop 기반 칸반 보드 UI를 구현한다.
@hello-pangea/dnd 라이브러리를 사용하며, 낙관적 업데이트로 즉각적인 UX를 제공한다.
- 예상 소요: 4~5일
- 선행 조건: 2-1_칸반-보드-API 완료, D&D 라이브러리 결정
- 완료 기준: 카드 D&D 후 서버 저장, 새로고침 시 순서 유지 확인
Claude Code 작업 수행서
작업 지시
CIRA UI에 칸반 보드 페이지를 구현해줘.
[프로젝트 경로]
- UI 레포 경로: (web-plate 실제 경로)
[수행 작업]
1. 패키지 설치 (미설치 시)
- @hello-pangea/dnd
2. 보드 페이지 구성
파일: src/app/(main)/projects/[projectId]/board/page.tsx
컴포넌트 계층:
BoardPage
└── BoardView
├── BoardHeader (스프린트 선택, 필터)
└── DragDropContext (onDragEnd 핸들러)
└── BoardColumn[] (Droppable)
├── ColumnHeader (이름, 이슈수, WIP 표시)
└── IssueCard[] (Draggable)
3. BoardColumn 컴포넌트
파일: src/components/board/BoardColumn.tsx
- Droppable 영역
- WIP 제한 시각화:
* 현재 카드 수 / WIP 제한 표시
* 초과 시 컬럼 헤더 빨간색 강조
- 카드 없을 때 빈 상태 (점선 박스)
- 컬럼 최소 높이 보장 (드롭 영역 유지)
4. IssueCard 컴포넌트
파일: src/components/board/IssueCard.tsx
표시 정보:
- 이슈 타입 아이콘
- 이슈 키 (예: CIRA-1)
- 제목 (최대 2줄, 말줄임)
- 우선순위 아이콘
- 담당자 아바타
- 스토리 포인트 배지
- 마감일 (D-day 또는 초과 빨간색)
동작:
- 카드 클릭 → 이슈 상세 사이드 패널 (슬라이드-인)
- Draggable 핸들: 카드 전체 또는 좌측 핸들 아이콘
5. onDragEnd 로직
const onDragEnd = (result: DropResult) => {
const { source, destination, draggableId } = result;
if (!destination) return;
if (source.droppableId === destination.droppableId &&
source.index === destination.index) return;
// 1. 낙관적 UI 업데이트 (로컬 상태 즉시 변경)
// 2. API 호출: PUT /issues/{draggableId}/position
// { columnId: destination.droppableId,
// previousIssueId: 앞 카드 ID,
// nextIssueId: 뒷 카드 ID }
// 3. 실패 시 원래 상태로 롤백 + 에러 토스트
}
6. 이슈 상세 사이드 패널
파일: src/components/board/IssueDetailPanel.tsx
- 우측에서 슬라이드-인 애니메이션
- [[1-6_UI-이슈-목록-상세-생성]]의 상세 컴포넌트 재사용
- 배경 클릭 또는 ESC로 닫기
7. 보드 필터
- 스프린트 선택 드롭다운 (Active 스프린트 기본 선택)
- 담당자 필터 (아바타 토글)
- 이슈 타입 필터
- 필터 적용 시 카드 opacity 조절 (해당 카드만 선명)
8. 성능 최적화
- React.memo로 IssueCard 메모이제이션
- 보드 데이터 폴링: 30초 간격 (useQuery refetchInterval)
- 타인의 이동 반영 (폴링 또는 WebSocket — Phase 3 이전까지는 폴링)
[준수 사항]
- 낙관적 업데이트 필수 (D&D 후 API 응답 기다리지 않음)
- WIP 초과 이동 시 API 에러 → 원위치 롤백 + 경고 메시지
- 드래그 중 다른 컬럼 진입 시 배경색 강조
완료 기준
| 항목 | 기준 |
|---|---|
| 칸반 보드 렌더링 | 컬럼 4개 + 카드 표시 |
| D&D 이동 | 같은 컬럼 / 다른 컬럼 이동 모두 동작 |
| 낙관적 업데이트 | D&D 즉시 UI 반영 |
| WIP 초과 | 경고 표시 + 롤백 |
| 상태 자동 변경 | 컬럼 이동 시 이슈 상태 변경 반영 |