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
55 lines
2.8 KiB
Markdown
55 lines
2.8 KiB
Markdown
<!-- 함수 설계서. 작성: [AI] Architect. -->
|
||
|
||
# 함수 설계서: BottomSheet snap 정책 (#319)
|
||
|
||
> **상태**: Approved <!-- Draft | Approved | Superseded -->
|
||
> **작성**: [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가 너무 작아 보이는 케이스 — 향후 동적 조정 검토.
|