04 quest game ui

Quest Game UI Overlay — 설계 (Week 2 추가 결정)

작성: 박동제 (pkdje) · 2026-06-02 · Week 2 시작 시점에 추가된 결정

1. 동기

기존 01-project-plan.md 의 DAG 시각화는 "노드 + 엣지 + 상태별 색" 의 깔끔한 todo 톤이었다. 사용자가 핵심 메커니즘(선행 작업 완료 → 후속 작업 해금)을 게임 퀘스트 진행 느낌으로 재해석하고 싶다고 결정함. 동시에 기존 모델이 다루지 않던 "선후관계가 없는 독립 태스크"의 분류도 명확히 한다.

이 문서는 그 결정을 구체화한다. 데이터 모델은 거의 그대로 두고, 시각/인터랙션 레이어를 퀘스트 톤으로 통일한다.

2. 합의된 결정 (요약)

항목	결정
게이미피케이션 강도	C — 중간 (퀘스트 카드 톤). 카드 디자인 + 라벨(REWARD, LOCKED, CLEARED) + 해금 애니메이션 + QUEST LINE 진행률.
독립 태스크 분류	B + D. 좌측 패널 하단에 별도 "사이드 퀘스트" 섹션. 새 태스크 생성 시 prerequisite 비우면 자동 분류.
퀘스트 라인 정의	DAG 의 연결 컴포넌트 = 1 퀘스트 라인. 크기 1 = 사이드 퀘스트.
REWARD 텍스트	DAG 구조에서 자동 생성 (직속 후속 노드 기반). 사용자 입력 없음.
아이콘	선택 emoji 필드 (icon?: string). 기본 ⚡. 새 태스크/편집 시 picker.
추천 패널 통합	A — 추천 패널을 "▶ NEXT QUEST" 로 리스킨. 전체 UI 톤 통일.
스코프	Week 3 안에 끼움. #16(기존 노드 polish) 흡수 + 신규 #21–#23 추가.

3. 데이터 모델 변경

type Task = {
  // ... 기존 필드 그대로
  icon?: string   // 추가. 이모지 1자. 미지정 시 렌더 시 ⚡ fallback.
}

• 다른 필드는 변동 없음.
• 모든 퀘스트 라인/REWARD 정보는 저장하지 않고 DAG 구조에서 파생 계산.
• 마이그레이션 불필요 (기존 task 들은 icon 없이도 ⚡ 로 렌더).

4. 파생 계산 (lib/quest.ts)

모두 순수 함수. TDD 대상.

// 4.1 연결 컴포넌트 (Union-Find 또는 BFS)
function connectedComponents(tasks: Task[]): Component[]
// Component { id: string, taskIds: TaskId[] }
// 사이즈 1 = 사이드 퀘스트.

// 4.2 컴포넌트 진척도
function questLineProgress(componentId, components, tasks): { done: number, total: number }

// 4.3 REWARD 텍스트 자동 생성
function rewardText(task: Task, tasks: Task[]): string
// 규칙:
//   직속 후속 1개   → "{이름} 해금"
//   직속 후속 2~3개 → "{이름1}, {이름2} 해금"
//   직속 후속 4개+ → "{N}개 작업 해금"
//   후속 없음 + 컴포넌트 크기 > 1 → "메인 퀘스트 X/Y 완료"
//   후속 없음 + 컴포넌트 크기 == 1 → "사이드 퀘스트 완료"

// 4.4 해금 감지 (애니메이션 트리거)
function detectUnlocks(prev: Task[], next: Task[]): TaskId[]
// 이전에 막힘(prereq 미완), 지금은 ready 인 task 들.
// 다음 렌더 사이클에서 0.9초 펄스 애니메이션.

복잡도: 모두 O(V+E). 수백 노드 기준 즉시 끝남.

5. UI 변경

5.1 DAG 캔버스 — 퀘스트 카드 노드

React Flow 의 Custom Node 로 구현. 기존 단순 박스 노드 교체.

┌─────────────────────────┐
│ 🎨 priority ★★★★★      │  아이콘 + 우선순위
│ 디자인                   │  제목 (굵게)
│ D-3 · score 7.4          │  마감 + (추천 후보일 때) 점수
│ ─────────────────       │
│ ▷ REWARD                │
│ 프론트, 백엔드 해금        │  자동 생성
└─────────────────────────┘

상태별 변형:

상태	시각
todo (ready)	흰 배경, 기본 테두리
todo (locked — prereq 미완)	회색 배경, opacity 0.6, 좌상단 🔒 LOCKED 배지
in_progress	파란 톤
done	초록 톤, 우상단 ✓ CLEARED 배지
just unlocked (1 사이클)	0.9 초 scale+rotate+노란 강조 펄스

5.2 좌측 패널 — "퀘스트 로그"

기존 추천 패널을 NEXT QUEST 로 리스킨. 그 아래 SIDE QUESTS 섹션 추가. 맨 아래 진행 현황.

┌────────────────────────┐
│ ▶ NEXT QUEST (Top 3)   │
│ ┌──────────────────┐   │
│ │ 🎨 디자인 score 8.2│   │  ← 카드 톤 통일
│ │ ★★★★★            │   │
│ │ ▷ 프론트, 통합 해금 │   │
│ └──────────────────┘   │
│ ...                    │
│                        │
│ ⚡ SIDE QUESTS (5)     │  ← 신규
│ ┌──────────────────┐   │
│ │ ⚡ 우유 사기      │   │  ← 단일 노드 컴포넌트
│ └──────────────────┘   │
│ ...                    │
│                        │
│ ─ 진행 현황 ─           │
│ 메인 퀘스트 4/12       │
│ 사이드 2/5             │
└────────────────────────┘

NEXT QUEST 카드:

• 기존 추천 점수 + 별 + 핀/snooze 액션 (#15) 그대로 유지
• 시각만 퀘스트 카드 톤
• 클릭 → React Flow 캔버스에서 해당 노드로 카메라 이동 + 강조

SIDE QUESTS 카드:

• icon + 제목만 (점수/별 표시 안 함, 짧은 가로 카드)
• 클릭 → 캔버스에서 해당 노드 강조

진행 현황 박스:

• 메인 퀘스트: 사이즈 ≥ 2 인 모든 컴포넌트의 done/total 합산
• 사이드: 사이즈 == 1 인 컴포넌트의 done/total 합산

5.3 모달 / 드로어

• 새 태스크 모달: 제목 입력 위에 이모지 picker 1줄. 추천 8 ~ 12 개 (⚡ 🎨 💻 🔬 📝 🏃 🎯 🛠 🎁 📞 🍴 🛒) + "다른 이모지" 입력. 기본 ⚡.
• 편집 드로어: 같은 picker 추가.
• prerequisite 비어있는 상태로 저장 → 자동으로 사이드 퀘스트 분류 (별도 토글 없음).

5.4 기존 인터랙션 보존

• 노드 클릭 → 편집 드로어
• 노드 더블클릭 → 상태 순환
• 노드 끝 드래그 → 의존성 엣지 생성

6. 스코프 변경

Week 2 — 최소 영향

• #6 Task CRUD API: icon?: string 필드 추가 (수용/저장만, 검증 불필요).

Week 3 — 6 → 8 이슈

이슈	변경
#15 추천 핀 / Snooze	그대로
#16 노드 시각 다듬기	삭제, #22 에 흡수
#17 가중치 슬라이더	그대로
#18 빈/로딩/에러 UI	그대로
#19 배포	그대로
#20 회고 + 워크플로우 doc	그대로
#21 lib/quest.ts + 단위 테스트 (신규)	파생 함수 4개. TDD. ≈ 1일.
#22 퀘스트 카드 노드 (React Flow custom node) (신규)	카드 디자인 + 상태별 변형 + 해금 펄스 애니메이션. ★/D-n/막힘 흐림 흡수. ≈ 1.5일.
#23 좌측 패널 리스킨 + 사이드 퀘스트 + 이모지 picker (신규)	NEXT QUEST 리스킨, SIDE QUESTS 섹션, 진행 현황, 모달/드로어 picker. ≈ 1일.

합계: +2 ~ 2.5일.

의존성

#21 (lib/quest.ts) ─┬─ #22 (카드 노드 — REWARD 등 소비)
                    └─ #23 (사이드 퀘스트 분류 — connectedComponents 소비)

#22 ←─ #8 (기존 DAG 렌더) 의 확장
#23 ←─ #14 (기존 추천 패널) 의 확장

7. 위험

위험	대응
Week 3 빡빡함 (+2 ~ 2.5일)	Week 2 가 1일이라도 밀리면 #15(핀/snooze) 또는 #17(가중치 슬라이더) 를 Week 4 후 추가 작업으로 미룸.
퀘스트 카드 톤이 큰 그래프에서 시각 노이즈	스파이크 #2 (React Flow + dagre) 에서 카드 톤 mock 으로 검증. 50+ 노드에서 견디는지.
해금 펄스 애니메이션이 매 클릭마다 발동되어 산만	detectUnlocks 가 상태가 just-transitioned 인 경우만 반환. 일반 리렌더에는 트리거 안 됨.
REWARD 텍스트가 후속 이름 길면 카드 깨짐	2 ~ 3개 이름 직접 노출 후 그 이상은 "{N}개 해금" 으로 축약.
이모지 picker 가 모바일 키보드 UX 와 충돌	1주차에 모바일 반응형은 스코프 외. 데스크탑 기준만.

8. Implementation Hints (Spike #2 결과 반영)

Spike #2 (React Flow + dagre) 에서 검증된 구체 설정값. #8 (DAG 렌더), #22 (퀘스트 카드 노드) 구현 시 시작점으로 사용. 전체 findings: spike/SPIKE.md (브랜치).

8.1 dagre 자동 레이아웃 설정

const dagreConfig = {
  rankdir: 'TB',           // Top → Bottom (LR 도 옵션)
  nodesep: 12,             // 가로 간격. 기본 30 너무 spacious
  ranksep: 28,             // 세로 간격. 기본 60 너무 spacious
  ranker: 'tight-tree',    // 'network-simplex' 보다 컴팩트
  marginx: 16,
  marginy: 16,
};

이 값에서 50 ~ 80 노드 그래프가 시각적으로 견딤. 더 spacious 가 필요해지면 사용자 설정으로 노출 가능 (3주 스코프 외).

8.2 퀘스트 카드 dagre 노드 크기

dagre 에 전달할 노드 박스 사이즈 (실제 렌더 카드 사이즈와 일치):

g.setNode(taskId, { width: 150, height: 76 });

폰트: 본문 11px / 메타·REWARD 9px. 패딩 6/10 px. (자세한 카드 디자인은 §5.1.)

8.3 React Flow fitView 설정

<ReactFlow
  fitView
  fitViewOptions={{
    padding: 0.08,
    minZoom: 0.6,   // 글자 가독성 한계
    maxZoom: 1.5,
  }}
  minZoom={0.1}      // 사용자 줌 아웃 한계
  maxZoom={2}
/>

fitViewOptions.minZoom: 0.6 이 중요. 이 값 없이 fitView 사용하면 노드 수가 늘어날수록 글자 안 보일 정도로 축소됨.

8.4 MiniMap 가시성

<MiniMap
  pannable          // 미니맵 드래그로 메인 뷰포트 이동
  zoomable          // 스크롤로 줌
  nodeStrokeColor="#37474f"
  nodeStrokeWidth={1}
  maskColor="rgba(15,23,42,0.55)"
  style={{
    backgroundColor: '#fff',
    border: '2px solid #455a64',
    borderRadius: 6,
    boxShadow: '0 4px 12px rgba(0,0,0,0.18)',
  }}
  nodeColor={(n) =>
    n.data?.status === 'done' ? '#a5d6a7'
      : n.id === selectedId ? '#ff6f00'
      : '#90a4ae'
  }
/>

pannable + zoomable 로 미니맵이 단순 표시에서 인터랙티브 컨트롤로 격상. 테두리/그림자/흰배경 으로 메인 화면과 명확히 분리.

8.5 노드 클릭 → 연결 엣지/노드 강조 (인지 부하 해소)

엣지 교차는 DAG 구조에서 오는 inherent 특성이라 알고리즘으로 완전히 없앨 수 없음. 대신 "지금 보고 싶은 엣지만" 분리해서 보는 UX 로 해소:

const [selectedId, setSelectedId] = useState<string | null>(null);

// onNodeClick → setSelectedId(node.id)
// onPaneClick → setSelectedId(null)

const connectedIds = useMemo(() => {
  if (!selectedId) return null;
  const s = new Set([selectedId]);
  edges.forEach(e => {
    if (e.source === selectedId) s.add(e.target);
    if (e.target === selectedId) s.add(e.source);
  });
  return s;
}, [selectedId, edges]);

// 노드: 비연결은 opacity 0.18
// 연결 엣지: 주황(#ff6f00) + strokeWidth 2.5 + animated
// 비연결 엣지: 회색 + opacity 0.3

이 인터랙션은 #22 안에 포함 (퀘스트 카드 노드의 자연스러운 일부로 구현).

8.6 성능 측정 (스파이크)

노드 수	layout 시간 (Mac M-series)
50	< 5 ms
80	< 10 ms
120	< 25 ms

3주 스코프(수십 ~ 100 노드)에서 충분. 200+ 노드 측정은 Week 3 회고에서.

8.7 검증 안 된 항목 (구현 중 확인)

• 실제 CRUD 와 결합한 인터랙션 성능 (정적 렌더만 측정)
• 사이클 시도 시 거부 피드백 UX
• 노드 추가/삭제 시 자동 레이아웃 재계산의 시각적 부드러움 (즉시 vs 트랜지션)
• 모바일 (스코프 외)
• 다크 모드 (스코프 외)

---

9. 회고에서 확인할 것

• 게이미피케이션 톤이 실제 사용에서 재미 인가 노이즈 인가? (본인 사용 후 평가)
• 사이드 퀘스트 자동 분류가 직관적이었는가? 별도 토글이 필요한가?
• 해금 애니메이션의 빈도/길이가 적절했는가?
• Week 3 시간 예산 대비 +2.5일이 실제로 얼마였는가?