kt-event-marketing/distribution-service/NAVER_BLOG_SETUP.md

# 네이버 블로그 포스팅 설정 가이드

## 개요
Distribution Service는 Playwright를 사용하여 네이버 블로그에 자동으로 포스팅합니다.

## 사전 준비

### 1. Playwright 설치
처음 실행 시 Playwright 브라우저가 자동으로 다운로드됩니다. 수동으로 설치하려면:

```bash
# Windows (PowerShell)
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install chromium"

# Linux/Mac
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install chromium"
```

### 2. 네이버 계정 준비
- 네이버 계정 (아이디/비밀번호)
- 네이버 블로그 개설 (blog.naver.com에서 블로그 만들기)
- 블로그 ID 확인 (예: blog.naver.com/YOUR_BLOG_ID)

## 환경 변수 설정

### IntelliJ 실행 프로파일 설정
`.run/DistributionServiceApplication.run.xml` 파일에서 다음 환경 변수를 설정:

```xml
<env name="NAVER_BLOG_USERNAME" value="your_naver_id" />
<env name="NAVER_BLOG_PASSWORD" value="your_password" />
<env name="NAVER_BLOG_BLOG_ID" value="your_blog_id" />
<env name="NAVER_BLOG_HEADLESS" value="false" />  <!-- 브라우저 표시 여부 -->
<env name="NAVER_BLOG_SESSION_PATH" value="playwright-sessions" />
```

### 환경 변수 설명

| 환경 변수 | 설명 | 기본값 | 필수 |
|----------|------|--------|------|
| `NAVER_BLOG_USERNAME` | 네이버 아이디 | - | ✅ |
| `NAVER_BLOG_PASSWORD` | 네이버 비밀번호 | - | ✅ |
| `NAVER_BLOG_BLOG_ID` | 네이버 블로그 ID | - | ✅ |
| `NAVER_BLOG_HEADLESS` | Headless 모드 (true/false) | true | ❌ |
| `NAVER_BLOG_SESSION_PATH` | 세션 저장 경로 | playwright-sessions | ❌ |

### Headless 모드
- **false**: 브라우저 창이 표시되어 디버깅에 유용 (개발 환경 권장)
- **true**: 백그라운드 실행, 서버 환경에 적합 (운영 환경 권장)

## 사용 방법

### API 호출 예시

```bash
# 배포 요청
curl -X POST http://localhost:8085/distribution/api/v1/distributions \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "EVT001",
    "title": "신규 이벤트 안내",
    "content": "이벤트 상세 내용입니다.",
    "imageUrl": "https://example.com/event.jpg",
    "channels": ["NAVER"]
  }'
```

### 응답 예시

```json
{
  "eventId": "EVT001",
  "status": "SUCCESS",
  "totalChannels": 1,
  "successCount": 1,
  "failureCount": 0,
  "channels": [
    {
      "channel": "NAVER",
      "success": true,
      "distributionId": "NAVER-abc123",
      "distributionUrl": "https://blog.naver.com/your_blog_id/222999999999",
      "estimatedReach": 2000,
      "executionTimeMs": 5234
    }
  ],
  "distributedAt": "2025-10-29T10:30:00"
}
```

## 세션 관리

### 자동 로그인
- 최초 실행 시 네이버에 로그인하고 세션이 저장됩니다
- 이후 요청은 저장된 세션을 사용하여 로그인 없이 진행됩니다
- 세션 파일 위치: `playwright-sessions/naver-blog-session.json`

### 세션 만료 시
세션이 만료되면 자동으로 재로그인을 시도합니다.

### 수동 세션 초기화
```bash
# 세션 파일 삭제
rm -rf playwright-sessions/naver-blog-session.json
```

## 문제 해결

### 1. 로그인 실패
**증상**: "Login failed" 에러 발생

**해결 방법**:
- 네이버 아이디/비밀번호 확인
- 네이버 로그인 보안 설정 확인 (캡차, 2단계 인증 등)
- Headless 모드를 false로 설정하여 브라우저 동작 확인
- 세션 파일 삭제 후 재시도

### 2. 브라우저 실행 실패
**증상**: "Failed to initialize Playwright" 에러

**해결 방법**:
```bash
# Playwright 브라우저 재설치
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install chromium"
```

### 3. 포스팅 실패
**증상**: 포스팅 URL이 반환되지 않음

**해결 방법**:
- Headless 모드를 false로 설정하여 UI 확인
- 네이버 블로그 에디터 구조 변경 여부 확인
- 로그 확인: `logs/distribution-service.log`

### 4. 성능 이슈
브라우저 자동화는 리소스를 많이 사용하므로:
- Resilience4j Bulkhead 설정으로 동시 실행 제한 (현재 10개)
- Circuit Breaker로 반복 실패 방지
- 실패 시 자동 재시도 (최대 3회)

## 보안 고려사항

### 1. 비밀번호 관리
- **절대로** 소스 코드에 비밀번호를 하드코딩하지 마세요
- 환경 변수 또는 시크릿 관리 서비스 사용
- Git에 `.run/*.xml` 파일을 커밋하지 마세요 (`.gitignore` 추가)

### 2. 세션 파일 보안
- `playwright-sessions/` 디렉토리를 `.gitignore`에 추가
- 서버 환경에서 파일 권한 설정 (chmod 600)

### 3. 네트워크 보안
- HTTPS만 사용
- 프록시 사용 시 안전한 프록시 설정

## 운영 환경 배포

### Docker 환경
```dockerfile
# Dockerfile에 Playwright 설치 추가
RUN apt-get update && apt-get install -y \
    libnss3 \
    libatk-bridge2.0-0 \
    libdrm2 \
    libxkbcommon0 \
    libgbm1 \
    libasound2

# Playwright 브라우저 설치
RUN mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install chromium"
```

### Kubernetes 환경
```yaml
apiVersion: v1
kind: Secret
metadata:
  name: naver-blog-credentials
type: Opaque
stringData:
  username: your_naver_id
  password: your_password
  blog-id: your_blog_id
---
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - name: distribution-service
        env:
        - name: NAVER_BLOG_USERNAME
          valueFrom:
            secretKeyRef:
              name: naver-blog-credentials
              key: username
        - name: NAVER_BLOG_PASSWORD
          valueFrom:
            secretKeyRef:
              name: naver-blog-credentials
              key: password
        - name: NAVER_BLOG_BLOG_ID
          valueFrom:
            secretKeyRef:
              name: naver-blog-credentials
              key: blog-id
        - name: NAVER_BLOG_HEADLESS
          value: "true"
```

## 제약사항

1. **동시 실행 제한**: Bulkhead 설정으로 최대 10개 동시 실행
2. **실행 시간**: 브라우저 자동화는 API 호출보다 느림 (평균 5-10초)
3. **네이버 정책**: 네이버 블로그 정책 변경 시 업데이트 필요
4. **UI 변경**: 네이버 블로그 UI 변경 시 코드 수정 필요

## 모니터링

### 로그 확인
```bash
# 실시간 로그
tail -f logs/distribution-service.log

# 에러만 필터
grep ERROR logs/distribution-service.log
```

### 주요 로그 메시지
- `Initializing Playwright for Naver Blog`: Playwright 초기화
- `Starting Naver login process`: 로그인 시작
- `Naver login successful`: 로그인 성공
- `Post published successfully`: 포스팅 성공
- `Failed to post to Naver blog`: 포스팅 실패

## 참고 자료

- [Playwright for Java](https://playwright.dev/java/)
- [네이버 블로그 고객센터](https://help.naver.com/service/5614/)
- [Resilience4j 문서](https://resilience4j.readme.io/)

## 지원

문제 발생 시:
1. 로그 파일 확인: `logs/distribution-service.log`
2. Headless 모드를 false로 설정하여 브라우저 동작 확인
3. GitHub Issue 등록 (로그 첨부)