sam-react-prod/claudedocs/guides/mobile/[PLAN] mobile-overflow-testing.md

# 모바일 화면 오버플로우 테스트 계획서

> 작성일: 2026-01-09
> 대상 기기: Galaxy Z Fold (접힌 상태)
> 목표: 모든 페이지에서 텍스트/요소 오버플로우 검출 및 수정

---

## 1. 개요

### 1.1 목적
Galaxy Fold 접힌 상태(344px)에서 UI 요소가 컨테이너를 벗어나거나 텍스트가 잘리는 문제를 사전에 발견하고 수정

### 1.2 대상 뷰포트

| 기기 | 너비 | 높이 | 비고 |
|------|------|------|------|
| Galaxy Z Fold 5 (접힌) | **344px** | 882px | 주요 테스트 대상 |
| Galaxy Z Fold 5 (펼친) | 1812px | 882px | 참고용 |
| iPhone SE | 375px | 667px | 비교 테스트 |

### 1.3 테스트 범위

**총 페이지 수: 185개**

| 카테고리 | 페이지 수 | 우선순위 |
|----------|----------|----------|
| construction (시공) | 40 | 🔴 높음 |
| accounting (회계) | 26 | 🔴 높음 |
| sales (영업) | 18 | 🔴 높음 |
| settings (설정) | 17 | 🟡 중간 |
| hr (인사) | 14 | 🟡 중간 |
| production (생산) | 10 | 🟡 중간 |
| quality (품질) | 4 | 🟢 낮음 |
| reports (리포트) | 2 | 🟢 낮음 |
| dashboard | 1 | 🔴 높음 |
| 기타 | ~50 | 🟡 중간 |

---

## 2. 테스트 방법

### 2.1 방법 A: Playwright 자동화 (권장)

**장점**
- 전체 페이지 일괄 스크린샷
- 반복 테스트 용이
- 수정 후 비교 테스트 가능

**단점**
- 초기 세팅 필요
- 로그인/인증 처리 필요

**구현 방식**
```typescript
// playwright-mobile-test.ts
import { chromium } from 'playwright';

const VIEWPORT = { width: 344, height: 882 };
const BASE_URL = 'http://localhost:3000/ko';

const pages = [
  '/dashboard',
  '/sales/client-management-sales-admin',
  '/accounting/sales',
  // ... 전체 페이지 목록
];

async function captureScreenshots() {
  const browser = await chromium.launch();
  const context = await browser.newContext({
    viewport: VIEWPORT,
    // 로그인 쿠키 설정
  });

  for (const page of pages) {
    const p = await context.newPage();
    await p.goto(`${BASE_URL}${page}`);
    await p.screenshot({
      path: `screenshots/fold/${page.replace(/\//g, '-')}.png`,
      fullPage: true
    });
  }
}
```

**결과물**
```
screenshots/fold/
├── dashboard.png
├── sales-client-management-sales-admin.png
├── accounting-sales.png
└── ... (185개)
```

---

### 2.2 방법 B: Chrome DevTools 수동 검수

**장점**
- 즉시 시작 가능
- 실시간 CSS 수정 테스트 가능
- 인터랙션 확인 가능

**단점**
- 시간 소요 (페이지당 1-2분)
- 반복 테스트 불편

**설정 방법**
1. Chrome DevTools (F12) 열기
2. Device Toolbar (Ctrl+Shift+M) 활성화
3. 기기 목록 → Edit → Add custom device
4. 이름: `Galaxy Z Fold 5 (Folded)`
5. 너비: `344`, 높이: `882`
6. Device pixel ratio: `3`
7. User agent: Mobile

**체크리스트**
```markdown
## 페이지: [페이지명]

### 레이아웃
- [ ] 헤더 정상 표시
- [ ] 사이드바 접힘/메뉴 버튼 표시
- [ ] 메인 컨텐츠 영역 정상

### 텍스트
- [ ] 제목 텍스트 오버플로우 없음
- [ ] 버튼 텍스트 잘림 없음
- [ ] 테이블 헤더 가독성 확인

### 테이블/리스트
- [ ] 가로 스크롤 정상 동작
- [ ] 컬럼 최소 너비 확보
- [ ] 체크박스/액션 버튼 접근 가능

### 폼
- [ ] 입력 필드 너비 적절
- [ ] 라벨 텍스트 가독성
- [ ] 버튼 터치 영역 충분 (최소 44px)

### 모달/팝업
- [ ] 화면 내 표시
- [ ] 닫기 버튼 접근 가능
- [ ] 스크롤 정상 동작
```

---

### 2.3 방법 C: 혼합 방식 (권장)

1. **1단계**: Playwright로 전체 페이지 스크린샷 캡처
2. **2단계**: 스크린샷에서 문제 있어 보이는 페이지 목록 작성
3. **3단계**: 문제 페이지만 DevTools로 상세 검수
4. **4단계**: 수정 후 Playwright로 재검증

---

## 3. 예상 문제 패턴

### 3.1 높은 위험도 🔴

| 패턴 | 예시 | 해결 방법 |
|------|------|----------|
| 고정 너비 테이블 | `min-w-[800px]` | 가로 스크롤 또는 반응형 |
| 긴 텍스트 nowrap | `whitespace-nowrap` | `truncate` 또는 줄바꿈 |
| 고정 px 버튼 그룹 | `w-[400px]` | `w-full` 또는 flex-wrap |
| 큰 모달 | `max-w-4xl` | `max-w-[calc(100vw-2rem)]` |

### 3.2 중간 위험도 🟡

| 패턴 | 예시 | 해결 방법 |
|------|------|----------|
| Flex 오버플로우 | `flex gap-4` 자식 | `min-w-0` 추가 |
| Grid 고정 컬럼 | `grid-cols-4` | `grid-cols-1 md:grid-cols-4` |
| 이미지 고정 크기 | `w-[200px]` | `max-w-full` |

### 3.3 낮은 위험도 🟢

| 패턴 | 예시 | 해결 방법 |
|------|------|----------|
| 패딩 과다 | `p-8` | `p-4 md:p-8` |
| 폰트 크기 | `text-xl` | `text-lg md:text-xl` |

---

## 4. 수정 가이드라인

### 4.1 테이블 반응형 처리

```tsx
// Before
<div className="overflow-x-auto">
  <table className="min-w-[800px]">

// After
<div className="overflow-x-auto -mx-4 md:mx-0">
  <table className="min-w-[600px] md:min-w-[800px]">
```

### 4.2 텍스트 오버플로우 처리

```tsx
// Before
<span className="whitespace-nowrap">{longText}</span>

// After
<span className="truncate max-w-[200px]" title={longText}>{longText}</span>
```

### 4.3 버튼 그룹 반응형

```tsx
// Before
<div className="flex gap-2">
  <Button>저장</Button>
  <Button>취소</Button>
  <Button>삭제</Button>
</div>

// After
<div className="flex flex-wrap gap-2">
  <Button className="flex-1 min-w-[80px]">저장</Button>
  <Button className="flex-1 min-w-[80px]">취소</Button>
  <Button className="flex-1 min-w-[80px]">삭제</Button>
</div>
```

### 4.4 모달 반응형

```tsx
// Before
<DialogContent className="max-w-2xl">

// After
<DialogContent className="max-w-2xl w-[calc(100vw-2rem)]">
```

---

## 5. 실행 계획

### 5.1 Phase 1: 환경 준비 (30분)

- [ ] Playwright 스크립트 작성
- [ ] 로그인 토큰/쿠키 설정
- [ ] 테스트 페이지 URL 목록 정리
- [ ] 스크린샷 저장 폴더 생성

### 5.2 Phase 2: 스크린샷 캡처 (1-2시간)

- [ ] Playwright 스크립트 실행
- [ ] 185개 페이지 스크린샷 캡처
- [ ] 캡처 실패 페이지 확인 및 재시도

### 5.3 Phase 3: 문제 페이지 분류 (1시간)

스크린샷 검토 후 분류:

| 상태 | 설명 | 액션 |
|------|------|------|
| ✅ OK | 문제 없음 | 스킵 |
| ⚠️ Minor | 경미한 문제 | 백로그 |
| 🔴 Critical | 사용 불가 수준 | 즉시 수정 |

### 5.4 Phase 4: 수정 작업 (문제 수에 따라)

- [ ] Critical 문제 우선 수정
- [ ] 수정 후 해당 페이지 재캡처
- [ ] Before/After 비교 확인

### 5.5 Phase 5: 검증 (30분)

- [ ] 전체 재캡처
- [ ] 수정 결과 확인
- [ ] 결과 보고서 작성

---

## 6. 결과물

### 6.1 스크린샷 폴더 구조

```
screenshots/
├── fold-344px/
│   ├── dashboard.png
│   ├── sales/
│   │   ├── client-management.png
│   │   └── quote-management.png
│   └── accounting/
│       └── ...
├── issues/
│   ├── critical/
│   └── minor/
└── fixed/
    └── before-after/
```

### 6.2 이슈 리포트

```markdown
## 오버플로우 이슈 리포트

### Critical Issues (즉시 수정 필요)

| # | 페이지 | 문제 | 스크린샷 |
|---|--------|------|----------|
| 1 | /sales/quote | 테이블 헤더 잘림 | [링크] |
| 2 | /accounting/daily-report | 차트 오버플로우 | [링크] |

### Minor Issues (백로그)

| # | 페이지 | 문제 | 스크린샷 |
|---|--------|------|----------|
| 1 | /settings/accounts | 버튼 그룹 좁음 | [링크] |
```

---

## 7. 예상 소요 시간

| 단계 | 예상 시간 | 비고 |
|------|----------|------|
| 환경 준비 | 30분 | Playwright 세팅 |
| 스크린샷 캡처 | 1-2시간 | 185페이지, 자동화 |
| 문제 분류 | 1시간 | 수동 검토 |
| 수정 작업 | 2-8시간 | 문제 수에 따라 |
| 검증 | 30분 | 재캡처 |
| **총합** | **5-12시간** | |

---

## 8. 의사결정 포인트

### Q1: 자동화 vs 수동?
- **권장**: 혼합 방식 (자동 캡처 → 수동 분류 → 수정)

### Q2: 전체 vs 우선순위별?
- **권장**: 전체 캡처 후, Critical만 우선 수정

### Q3: 지금 vs 나중에?
- 현재 수정 비용 < 나중 수정 비용
- 가능하면 빠른 시일 내 진행 권장

---

## 9. 시작 전 필요한 것

1. **로컬 개발 서버** 실행 상태
2. **테스트 계정** 로그인 정보
3. **Node.js + Playwright** 설치
4. **약 2-3시간** 집중 시간

---

## 부록: 페이지 URL 목록

<details>
<summary>전체 페이지 목록 (185개) - 클릭하여 펼치기</summary>

### Dashboard
- `/dashboard`

### Sales (18개)
- `/sales/client-management-sales-admin`
- `/sales/quote-management`
- `/sales/order-management`
- ... (상세 목록 필요시 추가)

### Accounting (26개)
- `/accounting/sales`
- `/accounting/vendors`
- `/accounting/bills`
- ... (상세 목록 필요시 추가)

### Construction (40개)
- `/construction/sites`
- `/construction/work-logs`
- ... (상세 목록 필요시 추가)

</details>

---

> **다음 단계**: 이 계획서 검토 후, 진행 방식 결정하면 Playwright 스크립트 작성 시작