# 스크래핑 플레이북 (세션 실전 노하우)

작성일: 2026-03-03 (KST)

## 목적

이 문서는 이번 세션에서 검증된 실측 절차를 재사용하기 위한 운영 가이드입니다.  
핵심 원칙은 **추정하지 말고, Playwright MCP로 사용자 동작을 먼저 재현**하는 것입니다.

---

## 1) 첫 시도 원칙

### 원칙 1. 첫 분석은 Playwright MCP로 시작

- 많은 서비스가 본문이 아니라 iframe/동적 렌더링 영역에서 실제 데이터를 로드합니다.
- `curl`만으로 시작하면 핵심 요청을 놓치기 쉽습니다.
- 따라서 초기 진입은 반드시:
  1. Playwright로 페이지 진입
  2. 실제 사용자 클릭 흐름 재현
  3. 호출 순서와 파라미터를 먼저 파악

### 원칙 2. 정적 분석은 보조 수단

- HTML/JS 정적 분석은 “후보 URL 찾기” 용도
- 실제 구현 판단은 브라우저 실측 결과로만 확정

---

## 2) 권장 작업 순서

1. **Playwright로 플로우 재현**
- 진입 페이지에서 iframe/내부 화면 URL 확인
- 실제 데이터가 로드되는 페이지를 직접 열어 검증

2. **요청 분기 구조 확인**
- 필터/탭/항목 선택마다 어떤 API가 호출되는지 확인
- 본조회 전에 사전 체크 API(팝업/권한/가능 여부)가 선행되는지 확인

3. **핵심 API 고정**
- 목록 API: 대상 목록/상세를 반환하는 핵심 API
- 상세 API: 선택 항목의 세부 데이터(예: 좌표, 옵션, 좌석 구조)
- 검증 API: 선점/중복/가능 여부를 체크하는 API

4. **curl 리플레이로 최소 조건 검증**
- 헤더 최소화 (`content-type: application/json`)
- 브라우저 없이 재현 가능한지 확인
- 실패 시 필수 필드 역추적

---

## 3) 이번 세션에서 확인한 실전 규칙

### 규칙 A. iframe/동적 컨테이너를 먼저 찾는다

- 초기 페이지에서 데이터가 없으면 실패가 아니라 정상일 수 있음
- iframe 내부 페이지를 직접 열어야 실데이터 API가 보임

### 규칙 B. “중심 허브 API”를 먼저 확정한다

- 한 번의 응답에 아래가 함께 옴:
  - 대상 목록
  - 필터/카테고리 목록
  - 상세/가용성 정보
- 특정 날짜/조건에서는 상세 목록이 비어 있을 수 있으므로 조건을 바꿔 재검증

### 규칙 C. 검증 API는 식별자 1개만으로 안 되는 경우가 많다

- 선점/검증 API는 보통 상세 조합 필드가 필요
- 예: 선택 항목 문자열, 수량, 금액, 등급/존 코드

### 규칙 D. 좌표/주소는 HTML 상세 블록에도 숨어 있을 수 있다

- JSON API에 좌표가 없어도 HTML 링크 쿼리(`lat/lng`)에서 추출 가능
- 위치 기반 기능은 좌표 캐시 전략으로 안정화 가능

---

## 4) 디버깅 체크리스트

### A. 호출이 안 잡힐 때

- 요소가 접힘/스크롤 영역 내부인지 확인
- 클릭 대신 evaluate로 이벤트 강제 실행 검토
- 분기 조건(`form-at`, 선택 개수)에 따라 다른 API를 타는지 확인

### B. 응답이 비어 있을 때

- 조회 조건(날짜/지역/항목)을 유효한 값으로 변경
- 다중 선택 조합을 단순화(항목 1개, 지점 1개)

### C. 500 오류가 날 때

- 최소 필드로 호출했는지 확인
- 프론트에서 실제 생성하는 payload 구조를 그대로 복제

---

## 5) 구현 전 판정 기준

### 즉시 구현 가능 조건

- 브라우저 없이 `curl` 재현 성공
- 응답 필드가 기능 요구를 직접 충족
  - 위치 기반: 주소/좌표
  - 목록 기반: 항목/회차/상태
  - 가용성: 잔여 수량/가능 여부

### 보류 조건

- 필수 파라미터를 프론트 내부 상태 없이 만들 수 없음
- 세션/토큰/런타임 의존성이 높아 재현 실패 반복

---

## 6) 다음 서비스에도 적용할 공통 원칙

1. 첫 접근은 Playwright MCP  
2. 실제 클릭 시나리오를 먼저 고정  
3. 그 다음 `curl` 리플레이 최소조건 찾기  
4. 마지막에 구현 가능성(A/B/C) 판정 문서화
