437e709a8d
#325 (#291 후속): - VideoSseController.bulkExtract: Math.random() → ThreadLocalRandom 통일 (bulkTranscript와 일관) - VideoSseController.rebuildVectors: 즉시 complete(total=0) 대신 명시적 'not_implemented' SSE 이벤트로 운영자 가시성 확보 + timeout 600s → 60s - YouTubeService.getTranscript JavaDoc: mode 인자가 youtube-transcript-api 폴백에서만 사용된다는 점, 브라우저 추출은 mode 무관 명시 #319 (#301 후속): - RestaurantDetail: buildSearchQuery 헬퍼 추출 (외부 지도 검색 URL 조합) '한국' 단독 region 더미 케이스 가드 포함 - BottomSheet SNAP_POINTS/VELOCITY_THRESHOLD 정책 fn-doc 신규 (docs/design/279-frontend-restaurant-detail/fn-bottomsheet-snap.md) #344 (#283 후속): - globals.css에 --z-bottom-sheet=50, --z-filter-sheet=60, --z-modal=70 토큰 - LoginMenu: zIndex 99999 매직 넘버 → var(--z-modal) Refs: #319 #325 #344
2.8 KiB
2.8 KiB
함수 설계서: BottomSheet snap 정책 (#319)
상태: Approved 작성: [AI] Architect · 최종수정: 2026-06-15 추적성 — Redmine: #319 / 부모 #301 · 관련 컴포넌트:
frontend/src/components/BottomSheet.tsx
1. 책임
모바일 BottomSheet의 3-snap 점착(snap) 점과 닫힘 임계 속도를 정의하고, 사용자의 드래그 제스처가 어느 snap에 안착할지 결정하는 알고리즘을 명세한다.
2. 상수 (매직 넘버)
| 상수 | 값 | 의미 |
|---|---|---|
SNAP_POINTS.PEEK |
0.4 |
초기/맨 아래 snap. 화면 높이의 40%만 시트가 보임 — 지도와 시트를 함께 보는 균형. |
SNAP_POINTS.HALF |
0.55 |
중간 snap. 시트 콘텐츠 핵심(이름·평점·리뷰 첫 줄)이 잘 보이는 위치. |
SNAP_POINTS.FULL |
0.92 |
거의 풀 화면. 8% 여백은 상단 스와이프 핸들·상태바를 위해 남김. |
VELOCITY_THRESHOLD |
0.5 (vh/s) |
빠른 아래 스와이프 감지 기준. 초당 화면 높이의 50% 이상이면 "닫기 의도"로 간주. |
CLOSE_BELOW_RATIO |
0.6 × PEEK ≈ 0.24 |
snap 후보 중 PEEK의 60% 아래로 끌어내리면 강제 닫힘. |
3. 결정 알고리즘 (snapTo(height, velocity))
입력: height(현재 높이 ratio 0~1), velocity(아래 방향 vh/s, 양수=아래)
1. velocity > VELOCITY_THRESHOLD && height < HALF → onClose()
2. height < CLOSE_BELOW_RATIO → onClose()
3. 그 외: [PEEK, HALF, FULL] 중 height와 최단 거리인 점에 setHeight()
4. 왜 이 값들인가 (근거)
- 0.4/0.55/0.92: 모바일 UX 가이드(Material/iOS BottomSheet)의 30%/50%/95% 패턴을 한국 식당 카드 콘텐츠 길이(이름 18px + 평점 16px + 영상 썸네일 200px 기준)에 맞춰 조정.
- 0.5 vh/s: 일반 손가락 플릭 속도가 0.7~1.2 vh/s, 의도적인 닫기 스와이프 임계점.
- 0.24 close-below: PEEK(0.4)의 60% — 우발적 드래그(<0.05) 차단 + 의도적 닫기(<0.24) 수용.
5. 변경 시 주의
- 사용자의 근육 기억(스와이프 거리 감각) 교란 위험이 있어 SNAP_POINTS 변경은 ADR로 분리할 것.
- VELOCITY_THRESHOLD를 낮추면 의도치 않은 닫힘 ↑, 높이면 닫기 어려움 ↑.
6. 테스트 권고
snapTo(0.45, 0.1)→ HALF로 안착snapTo(0.2, 0.7)→ onClose 호출snapTo(0.85, 0)→ FULL로 안착snapTo(0.1, 0)→ onClose 호출 (CLOSE_BELOW_RATIO)- 단위 테스트는
utils/bottomSheetSnap.ts로 함수 추출 후 #343에서 진행.
7. 미해결 질문
- 가로 모드 / 큰 폰트 접근성 모드에서 PEEK가 너무 작아 보이는 케이스 — 향후 동적 조정 검토.