# 외부데이터(크롤링) 블록 설계

## 1. 개요

특정 사이트/API의 데이터를 **조건(URL, 검색 파라미터)**에 따라 가져와 **값** 또는 **표**로 보여주고,  
**재조회** 시 캐시를 무시하고 최신 데이터를 반영하는 블록입니다.

### 예시 시나리오

| 용도            | 조건 예시                       | 표시 형태  |
| --------------- | ------------------------------- | ---------- |
| 환율 정보       | URL + 국가(한국) + 통화(파운드) | 값 또는 표 |
| 주식 정보       | URL + 회사명(종목)              | 값 또는 표 |
| 아파트 시세     | URL + 주소                      | 값 또는 표 |
| 농수산물 도매가 | URL + 품목/종류 등 검색조건     | 표         |

---

## 2. 구현 방향 (권장)

- **가능하면 공식 API 사용**
  - 공공데이터포털(환율·주식·농수산물 등), 금융 API 등 **이용약관이 허용하는 API**를 우선 사용합니다.
- **HTML 크롤링**
  - API가 없을 때만 사용하고, 해당 사이트의 **이용약관·robots.txt**를 반드시 확인합니다.
  - 과도한 요청은 차단·법적 문제로 이어질 수 있으므로 **캐시 + 재조회 버튼**으로 요청 횟수를 줄입니다.

### 기술 스택

- **서버(PHP)**: `wp_remote_get()`으로 외부 요청, **Transient**로 캐시, AJAX로 “재조회” 시 캐시 무시 후 재요청.
- **블록(JS)**: 설정(URL, 데이터 소스 타입, 검색 조건, 표시 형태) 저장, 프론트에서 AJAX 호출 후 값/표 렌더링.
- **표시**: 단일 **값** 또는 **테이블**.

---

## 3. 데이터 소스 타입 (설계)

| 타입 ID       | 설명                    | 설정 예시                    |
| ------------- | ----------------------- | ---------------------------- |
| `custom`      | 사용자 지정 URL         | URL 전체 + (선택) 쿼리/헤더  |
| `exchange`    | 환율(프리셋)            | API URL + 국가코드, 통화코드 |
| `stock`       | 주식(프리셋)            | API URL + 종목코드/회사명    |
| `apartment`   | 아파트 시세(프리셋)     | API URL + 지역/주소          |
| `agriculture` | 농수산물 도매가(프리셋) | API URL + 품목/시장 등       |

- 프리셋은 나중에 **공공 API 연동**으로 구체화 가능.
- 1차 구현에서는 **`custom`(URL + 쿼리 파라미터)** 만 지원하고, 응답은 **JSON** 또는 **HTML(선택자)** 로 파싱하는 방식으로 확장할 수 있습니다.

---

## 4. 블록 속성(attributes) 제안

```js
{
  dataSourceType: 'custom' | 'exchange' | 'stock' | 'apartment' | 'agriculture',
  url: '',              // 요청 URL (custom이거나 프리셋 기본 URL)
  params: '{}',         // JSON 문자열. 예: {"country":"KR","currency":"GBP"}
  displayAs: 'value' | 'table',
  cacheMinutes: 15,
  label: '',            // 블록 상단 라벨 (선택)
  refreshButton: true   // "재조회" 버튼 표시 여부
}
```

- **저장**: 에디터에서는 위 설정만 저장하고, **save()는 null**로 두어 동적 블록처럼 처리하거나,  
  프론트에서 채울 **빈 컨테이너**만 저장(예: `data-youelblocks-external-data` + `data-attributes`).

---

## 5. 데이터 흐름

1. **에디터**
   - 사용자가 URL, 데이터 소스 타입, 파라미터, 표시 형태(값/표), 캐시 시간, 재조회 버튼 여부 설정.
2. **프론트**
   - 블록 마운트(또는 페이지 로드) 시 `data-*`에서 설정 읽기 →  
     AJAX `youelblocks_fetch_external_data` 호출(첫 로드 시 캐시 사용).
3. **서버(PHP)**
   - `url` + `params`로 캐시 키 생성.
   - `force_refresh`가 아니면 Transient에서 반환.
   - 없거나 재조회면 `wp_remote_get()` 실행 → 응답 파싱(JSON/HTML) → **구조화된 데이터** 반환 후 캐시 저장.
4. **재조회**
   - “재조회” 버튼 클릭 시 같은 AJAX에 `force_refresh=1` 전달 → 캐시 무시 후 재요청 → 화면 갱신.

---

## 6. 파일 구성 제안

| 파일                                               | 역할                                                                                   |
| -------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `assets/js/blocks/external-data-block.js`          | 블록 등록, 에디터 UI, save 시 컨테이너+data 속성 출력                                  |
| `assets/js/block-frontend.js` (기존)               | 선택: `.youelblocks-external-data` 초기화 및 AJAX 호출, 값/표 렌더링, 재조회 버튼      |
| `includes/class-youelblocks-admin-ajax.php` (기존) | AJAX `youelblocks_fetch_external_data`: 캐시 조회, wp_remote_get, 파싱, Transient 저장 |
| `youel-block-manager.php` (기존)                   | `external-data-block.js` 스크립트 등록 및 의존성                                       |
| `includes/class-youelblocks-public.php` (기존)     | 프론트에서 해당 블록이 있을 때 스크립트/스타일 로드                                    |

---

## 7. 선택자 사용 방법 (기준환율 등 값 하나 가져오기)

**ID나 클래스가 없는 `<td>` 같은 요소**도, 개발자도구 **Copy selector**로 지정할 수 있습니다.

### 1) 값이 보이는 페이지에서

1. 브라우저에서 **F12**로 개발자도구를 연다.
2. **Elements** 탭에서, 가져오고 싶은 **숫자(예: 1,428.60)** 위에 마우스를 올린다.
3. 해당 숫자에 해당하는 **`<td>`** (또는 요소)가 하이라이트되면, 그 요소를 **우클릭**한다.
4. **Copy** → **Copy selector**를 선택한다.
5. 블록의 **「표시할 요소 선택자」** 칸에 **붙여넣기** 한다.  
   예: `#fxprint > table > tbody > tr > td:nth-child(10)`

### 2) 블록 설정

- **데이터 가져오기 방식**: **HTML 페이지 - 값 하나 (ID/클래스 입력)**
- **표시할 요소 선택자**: 위에서 복사한 값 그대로 붙여넣기
- **표시 형태**: **값 하나**

### 3) 주의사항

- **조회 버튼을 눌러야 표가 채워지는 페이지**는, 서버가 받는 HTML에는 표가 비어 있을 수 있어 **요소를 찾을 수 없습니다**라고 나올 수 있습니다.  
  그런 경우에는 해당 사이트의 **공식 API**나 **공공데이터**를 사용하는 편이 안정적입니다.

---

## 8. 보안·제한

- **URL 화이트리스트** 또는 **도메인 제한**: 허용한 도메인만 `wp_remote_get` 하도록 제한 권장.
- **Nonce**: AJAX는 기존 플러그인 nonce 정책에 맞춰 검증.
- **타임아웃·재시도**: `wp_remote_get()` 타임아웃(예: 15초), 실패 시 캐시가 있으면 이전 값 유지.
- **HTML 파싱**: 사용자 입력(CSS 선택자 등)은 이스케이프/검증 후 사용.

---

## 9. 확장 (프리셋 API)

- **환율**: 공공데이터포털 또는 한국수출입은행 등 공식 API URL/키 설정 화면 추가.
- **주식**: 금융위원회 주식시세 API 등 연동.
- **아파트 시세**: 국토교통부/부동산 공공 API 연동.
- **농수산물**: 농수산물유통공사 등 공공 API 연동.

프리셋은 `dataSourceType`별로 **고정 URL + 파라미터 스키마**를 두고,  
사용자는 “회사명”, “주소”, “품목” 등 **값만** 입력하면 되도록 하면 됩니다.

---

이 설계를 바탕으로 `external-data-block.js` 골격과 AJAX 핸들러를 추가하면,  
조건에 따라 데이터를 가져오고 재조회로 반영하는 “크롤링 블록”을 단계적으로 구현할 수 있습니다.