[feature] 동아리 카드 hover/touch/focus prefetch 및 캐시 히트율 측정

[seongwon030]

#️⃣ 연관된 이슈

#1599, MOA-905

📝 작업 내용

• usePrefetchClubDetail 훅 신규 — prefetchQuery + hasCachedData 반환, InAppWebView 환경 제외
• ClubCard 트리거 이벤트 확장: onMouseEnter / onTouchStart / onFocus
  • 모바일에서 touchstart 시점에 prefetch 시작 → click까지 100~300ms 확보
  • as const 패턴으로 PREFETCH_TRIGGER 상수 도입
• ClubDetailPage 가 @${clubName} 형식 사용하도록 통일 → prefetch 캐시 그대로 재사용
• Mixpanel 이벤트 4종 추가 (src/constants/eventName.ts)
  • Club Prefetch Triggered — hover/touch/focus 발생
  • Club Prefetch Hit — 클릭 시 캐시에 데이터 존재
  • Club Prefetch Miss — 클릭 시 캐시 미스 (네트워크 지연)
  • Club Prefetch Wasted — prefetch 후 클릭 없이 카드 이탈

Mixpanel 분석 지표

지표	공식
캐시 히트율	HIT / (HIT + MISS)
Prefetch 효율	(HIT + MISS) / TRIGGERED
낭비율	WASTED / TRIGGERED
평균 hover→click 시간	avg(hover_to_click_ms)
트리거 분포	TRIGGERED.group_by(trigger_type) (mouse/touch/focus)

중점적으로 리뷰받고 싶은 부분(선택)

• onTouchStart 트리거가 스크롤 중에도 발화되어 낭비율이 높을 수 있음 — 실데이터 보고 IntersectionObserver 기반으로 전환 검토 예정
• hasCachedData 의 hit 판정 기준이 status === 'success' 만 체크 — staleness 고려 안 함 (느슨한 판정)

🫡 참고사항

• 백엔드 @{clubName} 엔드포인트 의존 (ClubProfileController.getClubDetailByClubName)
• 실제 효과 측정은 며칠 데이터 누적 후 Mixpanel 대시보드에서 확인 예정

Summary by CodeRabbit

Release Notes

• 새로운 기능

  • 동아리 카드 호버/터치/포커스 시 상세 정보를 미리 로드하여 페이지 이동 속도 향상

• 분석

  • 프리페칭 성공/실패 및 사용 현황을 추적하는 이벤트 트래킹 추가

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
moadong	Ready	Preview, Comment	May 24, 2026 10:00am

[coderabbitai]

Warning

.coderabbit.yaml has a parsing error

The CodeRabbit configuration file in this repository has a parsing error and default settings were used instead. Please fix the error(s) in the configuration file. You can initialize chat with CodeRabbit to get help with the configuration file.

💥 Parsing errors (1)

Validation error: Invalid regex pattern for base branch. at "reviews.auto_review.base_branches[0]"

⚙️ Configuration instructions

• Please see the configuration documentation for more information.
• You can also validate your configuration using the online YAML validator.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Walkthrough

동아리 카드에서 마우스 진입, 터치, 포커스 시 동아리 상세 데이터를 프리페치하고, 프리페치 성공 여부와 최종 클릭 여부를 Mixpanel 이벤트로 추적하는 기능이 추가됩니다.

Changes

Club Detail Prefetch

Layer / File(s)	Summary
Prefetch event constants and React Query hook frontend/src/constants/eventName.ts, frontend/src/hooks/Queries/usePrefetchClubDetail.ts	CLUB_PREFETCH_TRIGGERED, CLUB_PREFETCH_HIT, CLUB_PREFETCH_MISS, CLUB_PREFETCH_WASTED 이벤트 키가 추가되고, usePrefetchClubDetail 훅이 React Query의 prefetchQuery와 getQueryState를 사용해 60초 staleTime으로 프리페치하고 캐시 여부를 검사합니다.
Club identifier parameter normalization frontend/src/pages/ClubDetailPage/ClubDetailPage.tsx	클럽 이름이 존재하면 @${clubName} 형식으로, 없으면 `clubId
ClubCard prefetch wiring and tracking frontend/src/pages/MainPage/components/ClubCard/ClubCard.tsx	마우스 진입/터치/포커스 시 handlePrefetch를 호출해 프리페치를 트리거하고, prefetchTriggeredAtRef로 1회만 실행하도록 제어합니다. 클릭 시 캐시 여부에 따라 HIT 또는 MISS 이벤트를 기록하고, 언마운트 전 미클릭 상태면 WASTED 이벤트를 기록합니다.

Sequence Diagram

sequenceDiagram
  participant User
  participant ClubCard
  participant usePrefetchClubDetail
  participant QueryClient
  participant Backend
  User->>ClubCard: 마우스 진입/터치/포커스
  ClubCard->>ClubCard: handlePrefetch 실행
  ClubCard->>usePrefetchClubDetail: prefetch(clubParam)
  ClubCard->>ClubCard: CLUB_PREFETCH_TRIGGERED 이벤트 기록
  usePrefetchClubDetail->>QueryClient: prefetchQuery(60s staleTime)
  QueryClient->>Backend: getClubDetail(clubParam)
  Backend-->>QueryClient: 상세 데이터
  QueryClient-->>usePrefetchClubDetail: true 반환
  User->>ClubCard: 카드 클릭
  ClubCard->>usePrefetchClubDetail: hasCachedData(clubParam)
  usePrefetchClubDetail->>QueryClient: getQueryState 확인
  QueryClient-->>usePrefetchClubDetail: 캐시 상태
  alt 캐시 존재
    ClubCard->>ClubCard: CLUB_PREFETCH_HIT 이벤트 기록
  else 캐시 없음
    ClubCard->>ClubCard: CLUB_PREFETCH_MISS 이벤트 기록
  end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• Moadong/moadong#1599: PR이 요청된 동아리 상세 프리페치 기능을 구현하며, 프리페치 훅, 이벤트 추적, ClubCard 상호작용 핸들러 연결이 모두 이슈 요구사항과 일치합니다.

Possibly related PRs

• Moadong/moadong#856: 두 PR 모두 frontend/src/constants/eventName.ts의 USER_EVENT 상수를 다루며, #856의 이벤트 네임스페이스 정리에 맞춰 메인 PR이 CLUB_PREFETCH_* 키들을 추가하므로 코드 레벨에서 연관됩니다.

• Moadong/moadong#1542: 두 PR 모두 MainPage/components/ClubCard/ClubCard.tsx의 카드 상호작용 및 Mixpanel 이벤트 추적 로직을 다루며, 메인 PR의 프리페치 HIT/MISS/WASTED 이벤트 추가가 #1542의 카드 뷰/히트맵 트래킹과 같은 컴포넌트 수준에서 직접 통합됩니다.

Suggested labels

✨ Feature, 💻 FE

Suggested reviewers

• oesnuj
• suhyun113
• lepitaaar

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	제목이 변경사항의 주요 내용을 정확하게 반영합니다. 동아리 카드의 hover/touch/focus 프리페치 기능과 캐시 히트율 측정이라는 핵심 변경사항을 명확하고 간결하게 요약했습니다.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/#1599-club-card-prefetch-on-hover-MOA-906

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

✅ UI 변경사항 없음

구분	링크
📖 Storybook	https://67904e61c16daa99a63b44a7-fssyglciud.chromatic.com/

전체 57개 스토리 · 22개 컴포넌트