# ThreadAuto 카드뉴스 CLI 사용 가이드

**작성일**: 2026-03-24
**근거**: task-922.1 분석 결과

---

## 핵심 규칙

> **카드뉴스(6장 캐러셀)를 생성하려면 반드시 `-t cardnews`를 사용하세요.**
> TypeA~TypeE는 레거시 단일 이미지 렌더러입니다.

---

## 1. 콘텐츠 타입별 올바른 명령

### 카드뉴스 (6장 캐러셀) — 가장 자주 사용

```bash
# 생성 + Threads/Instagram 캐러셀 업로드
python3 cli.py pipeline -t cardnews --source news --upload

# 생성만 (업로드 없음, output/ 디렉토리에 저장)
python3 cli.py pipeline -t cardnews --source news

# 전용 스크립트 (fact_guard 검증 포함, 추천)
python3 run_card_post.py

# 풀 파이프라인 스크립트
python3 run_full_pipeline.py
```

**결과물**: `output/cardnews_{YYYYMMDD}_{HHMMSS}_{00~06}.png` (5-7장)
**업로드 방식**: `post_carousel()` (Threads + Instagram 동시)
**브랜딩**: "서울대보험크루" badge + "서울대보험쌤" watermark + "인카다이렉트 TOP사업단" bar

### 텍스트 포스트

```bash
python3 cli.py pipeline -t text --source news --upload
```

**결과물**: 텍스트만 (이미지 없음)
**업로드 방식**: `post_text()`

### 레거시 단일 이미지 (TypeA~TypeE) — 주의 필요

```bash
# ⚠️ 단일 이미지 1장만 생성. 캐러셀 아님.
# ⚠️ --upload 플래그가 무시됨 (업로드 안 됨)
python3 cli.py pipeline -t TypeA --source news   # 숫자훅 카드
python3 cli.py pipeline -t TypeB --source news   # 뉴스 카드
python3 cli.py pipeline -t TypeC --source news   # 비교 카드
python3 cli.py pipeline -t TypeD --source news   # 성공스토리 카드
python3 cli.py pipeline -t TypeE --source news   # 체크리스트 카드
```

**결과물**: `output/{YYYYMMDD}_{HHMMSS}_{TypeX}.png` (1장)
**업로드 방식**: 미구현 (--upload 무시됨)
**브랜딩**: "인카다이렉트 TOP사업단"만 (하드코딩)

---

## 2. `-t` 파라미터 값 매핑표

| `-t` 값 | 렌더러 | 슬라이드 수 | 업로드 | 브랜딩 |
|---|---|---|---|---|
| `cardnews` | CardNewsRenderer (V2) | 5-7장 | post_carousel() | 서울대보험크루 + 서울대보험쌤 + TOP사업단 |
| `text` | 없음 (텍스트만) | 0 | post_text() | 없음 |
| `TypeA` | templates.py:TypeA | 1장 | 미구현 | TOP사업단만 |
| `TypeB` | templates.py:TypeB | 1장 | 미구현 | TOP사업단만 |
| `TypeC` | templates.py:TypeC | 1장 | 미구현 | TOP사업단만 |
| `TypeD` | templates.py:TypeD | 1장 | 미구현 | TOP사업단만 |
| `TypeE` | templates.py:TypeE | 1장 | 미구현 | TOP사업단만 |

---

## 3. card_type vs template_type (혼동 주의)

이 두 개념은 **완전히 다른 것**입니다:

### template_type (`-t` 파라미터)
- CLI에서 지정하는 **렌더러 선택** 파라미터
- 값: `cardnews`, `text`, `TypeA`~`TypeE`
- **어떤 렌더러**로 이미지를 생성할지 결정

### card_type (토픽 메타데이터)
- `content/evergreen_topics.json`에서 각 토픽에 부여된 **콘텐츠 분류** 레이블
- 값: `I`(정보제공), `E`(공감), `S`(사회적증거), `C`(CTA), `T`(동향)
- 렌더링 경로에 영향 **없음** — Claude 프롬프트 참고 정보로만 사용

---

## 4. 자주 하는 실수와 방지

### 실수 1: `-t TypeB`로 카드뉴스 생성 시도
```bash
# ❌ 잘못된 명령 — 단일 이미지 1장만 생성됨
python3 cli.py pipeline -c 1 -t TypeB --source news --format image --upload

# ✅ 올바른 명령 — 6장 캐러셀 생성 + 업로드
python3 cli.py pipeline -t cardnews --source news --upload
```

### 실수 2: `--upload`이 모든 타입에서 작동한다고 가정
```bash
# ❌ --upload이 무시됨 (TypeA~E는 업로드 미구현)
python3 cli.py pipeline -t TypeA --source news --upload

# ✅ 업로드가 필요하면 cardnews 또는 text 사용
python3 cli.py pipeline -t cardnews --source news --upload
```

### 실수 3: card_type "I"를 `-t I`로 사용
```bash
# ❌ card_type은 CLI 파라미터가 아님
python3 cli.py pipeline -t I --source news

# ✅ card_type은 자동 선택됨 (evergreen_topics.json 기반)
python3 cli.py pipeline -t cardnews --source news
```

---

## 5. 위임 시 표준 명령 템플릿

### 일일 카드뉴스 생성 + 업로드
```bash
cd /home/jay/projects/ThreadAuto
python3 cli.py pipeline -t cardnews --source news --upload
```

### 일일 카드뉴스 생성 (검수 후 수동 업로드)
```bash
cd /home/jay/projects/ThreadAuto
python3 cli.py pipeline -t cardnews --source news
# output/cardnews_{ts}_00~06.png 확인 후
python3 cli.py post-carousel output/cardnews_{ts}_*.png --caption "..."
```

### 전용 스크립트 사용 (가장 안전)
```bash
cd /home/jay/projects/ThreadAuto
python3 run_card_post.py
```

---

## 6. 코드 경로 참조 (개발자용)

### V2 카드뉴스 파이프라인 흐름
```
cli.py (pipeline -t cardnews)
  → pipeline/orchestrator.py: run_cardnews()
    → content/five_stage_pipeline.py: generate()
    → renderer/cardnews.py: CardNewsRenderer.render_from_slides()
    → publisher/threads_publisher.py: publish_cardnews()
      → publisher/threads_client.py: post_carousel()
```

### 레거시 단일 카드 흐름
```
cli.py (pipeline -t TypeB)
  → pipeline/orchestrator.py: run_single()
    → content/generator.py: generate()
    → renderer/templates.py: TypeB.render()
    → pipeline/orchestrator.py: render_image()
```

### 주요 파일 경로
- CLI 엔트리포인트: `/home/jay/projects/ThreadAuto/cli.py`
- 오케스트레이터: `/home/jay/projects/ThreadAuto/pipeline/orchestrator.py`
- V2 카드뉴스 렌더러: `/home/jay/projects/ThreadAuto/renderer/cardnews.py`
- 레거시 템플릿: `/home/jay/projects/ThreadAuto/renderer/templates.py`
- 브랜드 설정: `/home/jay/projects/ThreadAuto/renderer/themes.py`
- 기본 렌더러: `/home/jay/projects/ThreadAuto/renderer/engine.py`
- 토픽 데이터: `/home/jay/projects/ThreadAuto/content/evergreen_topics.json`