도커 컨텐츠 뷰어 Dock마루 0.0.3-beta 업데이트

# Dockmaru 플러그인 개발 가이드

## 개요

Dockmaru 플러그인은 JavaScript로 작성되며, 사용자 브라우저에서 실행됩니다.
서버의 Proxy API를 통해 외부 사이트에 요청을 보낼 수 있습니다.

---

## 플러그인 구조

```javascript
const plugin = {
  // 필수 속성
  name: 'Plugin Name',           // 플러그인 이름
  version: '1.0.0',              // 버전
  description: '설명',           // 설명
  
  // 필수 메서드 (메타데이터 검색 플러그인)
  async search(query) {
    // 검색어로 책 목록 검색
    // 반환: Array<{title, author, cover, description, url, extra}>
  },
  
  // 선택 메서드
  async getMetadata(url) {
    // URL에서 상세 메타데이터 추출
    // 반환: {title, author, cover, description}
  }
};
```

---

## Proxy API 사용법

### proxyFetch(url, options)

외부 사이트에 HTTP 요청을 보냅니다. CORS 제한을 우회합니다.

```javascript
// GET 요청
const response = await proxyFetch('https://example.com/api/search?q=test', {
  headers: {
    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
    'Accept': 'text/html,application/xhtml+xml'
  }
});

// POST 요청
const response = await proxyFetch('https://example.com/api', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: 'test' })
});
```

### 반환값

```javascript
{
  status: 200,           // HTTP 상태 코드
  headers: {...},        // 응답 헤더
  body: '...',           // 원본 응답 (문자열)
  json: () => {...},     // JSON 파싱 함수
  text: () => '...'      // 텍스트 반환 함수
}
```

---

## 검색 결과 반환 형식

```javascript
async search(query) {
  const response = await proxyFetch(
    `https://api.example.com/search?q=${encodeURIComponent(query)}`
  );
  const data = response.json();
  
  return data.results.map(item => ({
    title: item.title,           // 필수: 제목
    author: item.author,         // 선택: 저자
    cover: item.thumbnailUrl,    // 선택: 표지 이미지 URL
    description: item.synopsis,  // 선택: 줄거리
    url: item.detailUrl,         // 선택: 상세 페이지 URL (getMetadata에서 사용)
    extra: {                     // 선택: 추가 정보
      platform: 'Example',
      genre: item.genre
    }
  }));
}
```

---

## HTML 파싱 기법

proxyFetch는 HTML을 문자열로 반환합니다. 정규식으로 파싱할 수 있습니다.

### 기본 패턴

```javascript
async getMetadata(url) {
  const response = await proxyFetch(url);
  const html = response.body || '';
  
  // OG 태그 파싱 (가장 일반적)
  const titleMatch = html.match(/<meta[^>]+property="og:title"[^>]+content="([^"]+)"/i);
  const title = titleMatch ? titleMatch[1] : '';
  
  const imageMatch = html.match(/<meta[^>]+property="og:image"[^>]+content="([^"]+)"/i);
  const cover = imageMatch ? imageMatch[1] : '';
  
  const descMatch = html.match(/<meta[^>]+property="og:description"[^>]+content="([^"]+)"/i);
  const description = descMatch ? descMatch[1] : '';
  
  return { title, cover, description };
}
```

### 정규식 작성 팁

1. **속성 순서 고려**: HTML 속성 순서가 다를 수 있음
   ```javascript
   // 나쁜 예: 특정 순서 가정
   /<img src="([^"]+)" alt="([^"]+)">/
   
   // 좋은 예: [^>]*로 유연하게
   /<img[^>]+alt="([^"]+)"[^>]*>/
   ```

2. **공백 처리**: HTML 포맷팅에 따라 공백이 다름
   ```javascript
   // 나쁜 예: 정확한 공백 위치 가정
   /<a href="\/path\/"><img
   
   // 좋은 예: \s* 또는 [^>]* 사용
   /<a[^>]+href="\/path\/"[^>]*><img/
   ```

3. **HTML 엔티티 디코딩**: `&amp;`, `&lt;` 등 처리
   ```javascript
   cover = cover.replace(/&amp;/g, '&');
   description = description
     .replace(/&nbsp;/g, ' ')
     .replace(/&lt;/g, '<')
     .replace(/&gt;/g, '>')
     .replace(/&quot;/g, '"')
     .replace(/&#39;/g, "'");
   ```

4. **JSON-LD 데이터 활용**: 일부 사이트는 구조화된 데이터 제공
   ```javascript
   const jsonLdMatch = html.match(/<script[^>]+type="application\/ld\+json"[^>]*>([\s\S]*?)<\/script>/i);
   if (jsonLdMatch) {
     try {
       const data = JSON.parse(jsonLdMatch[1]);
       title = data.name || '';
       cover = data.image || '';
       description = data.description || '';
     } catch (e) {
       console.log('JSON-LD 파싱 실패');
     }
   }
   ```

---

## 디버깅 팁

### 콘솔 로그 활용

```javascript
async search(query) {
  console.log('[플러그인] 검색:', query);
  
  const response = await proxyFetch(url);
  console.log('[플러그인] 응답 상태:', response.status);
  console.log('[플러그인] HTML 길이:', response.body.length);
  
  // 문제 발생 시 HTML 일부 출력
  const idx = html.indexOf('target-element');
  if (idx > 0) {
    console.log('[플러그인] 타겟 주변:', html.substring(idx, idx + 200));
  }
  
  // 결과 개수 확인
  console.log('[플러그인] 결과:', results.length);
  return results;
}
```

### 일반적인 문제와 해결

| 문제 | 원인 | 해결 |
|------|------|------|
| 검색 결과 0 | 정규식 불일치 | HTML 구조 재분석, 패턴 수정 |
| 504 Gateway Timeout | 서버 차단 또는 과부하 | 요청 간격 조절, User-Agent 변경 |
| 403 Forbidden | 봇 차단 | User-Agent 헤더 추가 |
| HTML 비어있음 | JavaScript 렌더링 필요 | SSR 사이트만 지원 가능 |

---

## 플러그인 테스트

1. Dockmaru 앱에서 **계정 설정 > 플러그인** 탭 이동
2. **플러그인 추가** 클릭
3. 코드 입력 후 **검증** 버튼으로 구문 확인
4. 저장 후 **책 수정** 화면에서 **메타데이터 검색** 버튼 사용
5. 브라우저 개발자 도구(F12) 콘솔에서 로그 확인

---

## 주의사항

1. **법적 책임**: 플러그인 사용으로 인한 법적 문제는 사용자 책임입니다.
2. **사이트 정책**: 대상 사이트의 이용약관 및 robots.txt를 준수하세요.
3. **Rate Limiting**: 과도한 요청은 IP 차단될 수 있습니다.
4. **HTTPS 전용**: Proxy API는 HTTPS URL만 지원합니다.
5. **SSR 사이트 전용**: JavaScript로 렌더링되는 SPA 사이트는 지원하지 않습니다.

---

## 사이트 유형별 접근법

| 사이트 유형 | 특징 | 접근법 |
|-------------|------|--------|
| API 제공 | JSON 응답 | response.json() 사용 |
| SSR (서버 렌더링) | HTML 완성 | 정규식 파싱 |
| SPA (클라이언트 렌더링) | JavaScript 필요 | ❌ 지원 불가 |
| 로그인 필요 | 세션/쿠키 필요 | ❌ 지원 불가 |