# 11. 브라우저 네비게이션 규칙 (AI/자동화 필수)

> **대상**: AI 에이전트 (Claude, Cursor 등), E2E 테스트 작성자, 브라우저 자동화 개발자
> **버전**: 1.0.0
> **최종 수정**: 2026-03-10

---

## 1. 핵심 원칙

> **URL을 추측하거나 자의적으로 생성하여 주소창에 입력하지 않는다.**
> **반드시 사이드바 메뉴 클릭 또는 앱 내부 라우터(링크/버튼)를 통해서만 페이지를 이동한다.**

### 왜?

SAM ERP는 폐쇄형 시스템으로, 페이지 URL 구조가 외부에 공개되지 않는다.
AI가 URL을 추측하면 존재하지 않는 경로로 이동하여 404가 발생하고,
E2E 테스트에서는 잘못된 URL로 인해 테스트가 실패하거나 의미 없는 결과를 반환한다.

---

## 2. 규칙 상세

### 2.1 페이지 이동

| 상황 | 올바른 방법 | 금지 |
|------|-----------|------|
| 메뉴 페이지 이동 | 사이드바 메뉴 버튼 클릭 | URL 직접 입력 |
| 상세 페이지 이동 | 목록에서 행 클릭 | URL에 ID 직접 조합 |
| 모달/다이얼로그 열기 | 버튼 클릭 | URL 파라미터 추가 |
| 뒤로가기 | 브라우저 뒤로가기 또는 앱 내 버튼 | 이전 URL 추측 입력 |
| 탭 전환 | 탭 버튼 클릭 | URL 해시/쿼리 직접 수정 |

### 2.2 현재 페이지 확인

페이지 이동 전, 반드시 현재 상태를 먼저 확인한다.

```
1. 현재 페이지의 스냅샷/스크린샷 확인
2. 사이드바에서 원하는 메뉴 찾기
3. 메뉴 클릭으로 이동
4. 이동 후 페이지 로드 완료 확인
```

### 2.3 사이드바 메뉴 구조

SAM ERP의 사이드바는 **2단계 계층 구조**이다.

```
1단계: 대분류 (클릭하면 하위 메뉴 펼침)
  └─ 2단계: 실제 페이지 메뉴 (클릭하면 페이지 이동)
```

하위 메뉴가 보이지 않으면, 먼저 대분류 버튼을 클릭하여 펼쳐야 한다.

---

## 3. AI 에이전트 전용 규칙

### 3.1 Chrome DevTools MCP 사용 시

```
✅ 올바른 패턴:
1. take_snapshot → 현재 페이지 및 사이드바 상태 확인
2. click(uid) → 사이드바 대분류 클릭하여 하위 메뉴 펼치기
3. take_snapshot → 하위 메뉴 uid 확인
4. click(uid) → 원하는 페이지 메뉴 클릭
5. take_screenshot → 페이지 로드 확인

❌ 금지 패턴:
- navigate_page("http://localhost:3000/some-guessed-url")
- URL을 추측하여 직접 이동
```

### 3.2 E2E 테스트 (Playwright) 작성 시

```typescript
// ✅ 올바른 패턴 - 메뉴 클릭으로 이동
await page.getByRole('button', { name: '회계관리' }).click();
await page.getByRole('button', { name: '계좌입출금내역' }).click();
await expect(page.getByRole('heading', { name: '계좌 입출금 내역' })).toBeVisible();

// ✅ 허용 - 이미 알려진 URL로 직접 이동 (테스트 효율성)
// 단, URL은 실제 앱에서 확인한 것만 사용
await page.goto('/accounting/bank-transactions');

// ❌ 금지 - URL 추측
await page.goto('/accounting/bank-transaction-inquiry');  // 존재하지 않는 경로
await page.goto('/account/bank');                          // 추측 URL
```

### 3.3 URL 확인이 필요할 때

특정 페이지의 URL을 알아야 한다면:

```
1. 사이드바 메뉴 클릭으로 해당 페이지 이동
2. 이동 후 스냅샷의 RootWebArea url 속성에서 확인
3. 확인된 URL만 이후 작업에 사용
```

---

## 4. 메뉴 → URL 매핑 관리

### 원칙
- URL 매핑 테이블을 별도로 유지하지 않는다 (변경 시 동기화 비용)
- 항상 **앱 사이드바가 Single Source of Truth**
- URL이 필요하면 메뉴 클릭 후 브라우저에서 확인

### 예외: 자주 사용하는 진입점

E2E 테스트 효율을 위해 검증된 URL만 하드코딩 허용:

```typescript
// e2e/fixtures/urls.ts (검증된 URL만 등록)
export const VERIFIED_URLS = {
  dashboard: '/',
  quoteManagement: '/sales/quote-management',
  // ... 실제 앱에서 확인 후 추가
} as const;
```

이 목록에 없는 URL은 반드시 메뉴 클릭으로 이동한다.

---

## 5. 체크리스트

브라우저 자동화 또는 E2E 테스트 작성 시:

- [ ] URL을 추측하여 직접 입력하지 않았는가?
- [ ] 사이드바 메뉴 또는 앱 내 링크/버튼으로 이동했는가?
- [ ] 이동 후 페이지가 정상 로드되었는지 확인했는가?
- [ ] 하드코딩한 URL이 있다면, 실제 앱에서 검증한 URL인가?
- [ ] 존재하지 않는 페이지(404)로 이동하는 테스트가 없는가?