# 모바일 핀치 줌(Pinch Zoom) 이슈 해결 가이드

> **작성일**: 2026-01-15
> **상태**: 해결 완료
> **적용 범위**: iOS Safari, Android Chrome

---

## 1. 문제 현상

### 1-1. 초기 증상
- 모바일에서 핀치 줌(손가락 확대)이 **특정 화면에서만** 동작
- 확대 시 **아래에서 회색/어두운 영역**이 올라와 화면을 가림
- Android / iOS 모두 동일한 현상

### 1-2. 영향 범위
| 화면 | 줌 가능 | 회색 영역 |
|------|---------|----------|
| 로그인 페이지 | ✅ 정상 | ❌ 없음 |
| 인증된 내부 페이지 | ❌ 불가 → ✅ 수정 후 가능 | ✅ 발생 → ❌ 수정 후 해결 |

---

## 2. 원인 분석

### 2-1. 핀치 줌 차단 원인
**파일**: `src/layouts/AuthenticatedLayout.tsx`

```tsx
// 문제 코드 - touch-pan-y가 핀치 줌 차단
<main className="... touch-pan-y" style={{ WebkitOverflowScrolling: 'touch' }}>
```

| touch-action 값 | 세로 스크롤 | 핀치 줌 |
|----------------|------------|--------|
| `pan-y` | ✅ | ❌ 차단 |
| `pan-y pinch-zoom` | ✅ | ✅ |
| `manipulation` | ✅ | ❌ 더블탭만 |

### 2-2. 회색 영역 발생 원인

**원인 1**: `body`에 추가된 safe-area 패딩
```css
/* globals.css - 문제 코드 */
body {
  padding-bottom: env(safe-area-inset-bottom, 0px);
}
```
- 확대 시 body가 확장되면서 패딩 영역이 화면에 노출

**원인 2**: 모바일 레이아웃 wrapper에 배경색 미지정
```tsx
// 문제 코드 - 배경색 없음
<div className="flex flex-col overflow-hidden" style={{ height: 'var(--app-height)' }}>
```
- 배경색이 없어서 확대 시 뒤에 있는 요소(어두운 배경)가 투과되어 보임

**원인 3**: `overflow-hidden`으로 인한 콘텐츠 클리핑
- 고정 높이 + overflow-hidden = 확대 시 콘텐츠가 잘림

---

## 3. 해결 방법

### 3-1. 핀치 줌 활성화
**파일**: `src/layouts/AuthenticatedLayout.tsx` (Line 615)

```tsx
// 변경 전
<main className="flex-1 overflow-y-auto px-3 overscroll-contain touch-pan-y"
      style={{ WebkitOverflowScrolling: 'touch' }}>

// 변경 후
<main className="flex-1 overflow-y-auto px-3 overscroll-contain"
      style={{ WebkitOverflowScrolling: 'touch', touchAction: 'pan-y pinch-zoom' }}>
```

### 3-2. body 패딩 제거
**파일**: `src/app/globals.css`

```css
/* 변경 전 */
body {
  padding-bottom: env(safe-area-inset-bottom, 0px);
}

/* 변경 후 - 해당 코드 제거 */
/* safe-area 변수는 유지, body 패딩만 제거 */
:root {
  --safe-area-inset-top: env(safe-area-inset-top, 0px);
  --safe-area-inset-right: env(safe-area-inset-right, 0px);
  --safe-area-inset-bottom: env(safe-area-inset-bottom, 0px);
  --safe-area-inset-left: env(safe-area-inset-left, 0px);
}
```

### 3-3. 모바일 레이아웃 배경색 및 높이 수정
**파일**: `src/layouts/AuthenticatedLayout.tsx` (Line 370)

```tsx
// 변경 전
<div className="flex flex-col overflow-hidden" style={{ height: 'var(--app-height)' }}>

// 변경 후
<div className="flex flex-col bg-background min-h-screen" style={{ height: 'var(--app-height)' }}>
```

| 변경 항목 | 효과 |
|----------|------|
| `bg-background` | 배경색 명시적 지정 → 어두운 영역 가림 |
| `min-h-screen` | 최소 높이 보장 → 확대 시에도 배경 커버 |
| `overflow-hidden` 제거 | 확대 시 콘텐츠 클리핑 방지 |

---

## 4. Viewport 설정 (참고)

**파일**: `src/app/[locale]/layout.tsx`

```tsx
// 현재 설정 - 줌 허용 + iOS safe-area 지원
export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  minimumScale: 1,        // 최소 100%
  maximumScale: 5,        // 최대 500%까지 확대 가능
  userScalable: true,     // 손가락 확대 허용
  viewportFit: 'cover',   // 아이폰 노치/다이나믹 아일랜드/하단 홈바 영역 커버
};
```

---

## 5. 최종 변경 파일 목록

| 파일 | 변경 내용 |
|------|----------|
| `src/layouts/AuthenticatedLayout.tsx` | touch-action 수정, 배경색/높이 추가 |
| `src/app/globals.css` | body padding-bottom 제거 |
| `src/app/[locale]/layout.tsx` | viewport 설정 (이전에 적용됨) |

---

## 6. 테스트 체크리스트

- [x] iOS Safari 핀치 줌 동작
- [x] Android Chrome 핀치 줌 동작
- [x] 확대 시 회색 영역 미노출
- [x] 로그인 페이지 정상 동작
- [x] 내부 페이지(AuthenticatedLayout) 정상 동작
- [x] 세로 스크롤 정상 동작

---

## 7. 관련 문서

- `[REF] mobile-zoom-prevention-guide.md` - 줌 방지가 필요할 때 적용 가이드

---

## 변경 이력

| 날짜 | 내용 |
|------|------|
| 2026-01-15 | 문서 작성, 이슈 해결 완료 |
