# ThreadAuto Phase 1: Threads API OAuth 인증 + 단일 게시 검증

## 개요
ThreadAuto 프로젝트의 첫 Phase. Threads API 연동 기반을 구축하고, 실제로 게시물 1건을 발행하여 전체 파이프라인을 검증한다.

## 프로젝트 경로
- **프로젝트**: `/home/jay/projects/ThreadAuto/`
- **기술 리서치**: `/home/jay/workspace/memory/research/threadauto-tech-research.md` (반드시 읽을 것)
- **요구사항**: `/home/jay/workspace/memory/specs/thread-auto/requirements-v1.md`

## 환경변수 (.env.keys에 저장됨)
- `THREADS_APP_ID` — Meta 앱 ID
- `THREADS_APP_SECRET` — Meta 앱 시크릿 코드
- 토큰은 이 Phase에서 발급받아 저장해야 함

## Threads 계정 정보
- 계정명: 서울대보험그룹
- 사용자명: snu_insurance_group
- 앱 이름: ThreadAuto
- 테스터 등록 완료 (승인됨)

## Phase 1 목표
Threads API를 통해 **텍스트 게시물 1건 + 이미지 게시물 1건**을 실제로 발행하여 API 연동을 검증한다.

## 구현 범위

### 1. 프로젝트 초기화
- Python 3.12 프로젝트 구조 생성
- FastAPI 기본 세팅
- `.env` / `.env.example` 환경변수 관리
- `.env.keys` 자동 로드 (`source /home/jay/workspace/.env.keys`)

### 2. OAuth 2.0 인증 모듈 (`auth/`)
- `auth/oauth.py` — OAuth 2.0 플로우 구현
  - 인증 URL 생성 (authorize endpoint)
  - 단기 액세스 토큰 발급 (code → short-lived token)
  - 장기 액세스 토큰 교환 (short → long-lived, 60일)
  - 토큰 갱신 로직 (만료 전 자동 갱신)
- `auth/token_store.py` — 토큰 파일 저장/로드 (JSON)
  - 토큰 + 만료일 + user_id 저장
  - 경로: `/home/jay/projects/ThreadAuto/.tokens/` (gitignore)

### 3. Threads API 클라이언트 (`api/`)
- `api/client.py` — Threads Graph API 래퍼
  - 프로필 조회 (`GET /me`)
  - 텍스트 게시 (`POST /{user_id}/threads` → `POST /{user_id}/threads_publish`)
  - 이미지 게시 (미디어 컨테이너 생성 → 30초 대기 → 발행)
  - Rate limit 핸들링 (429 → Exponential Backoff)
  - 에러 핸들링 (API 에러코드별 처리)
- `api/models.py` — Pydantic 모델 (요청/응답)

### 4. OAuth 콜백 서버
- FastAPI 엔드포인트: `GET /auth/callback` — OAuth redirect_uri 수신
- 로컬 개발: `http://localhost:8100/auth/callback`
- 토큰 발급 후 자동 저장

### 5. CLI 도구 (`cli.py`)
- `python cli.py auth` — 브라우저에서 OAuth 인증 시작
- `python cli.py post-text "텍스트 내용"` — 텍스트 게시
- `python cli.py post-image "이미지URL" "캡션"` — 이미지 게시
- `python cli.py profile` — 프로필 조회 (연결 확인)

### 6. 테스트
- OAuth 플로우 단위 테스트 (mock)
- API 클라이언트 단위 테스트 (mock)
- 토큰 저장/로드 테스트

## 디렉터리 구조
```
/home/jay/projects/ThreadAuto/
├── api/
│   ├── __init__.py
│   ├── client.py        # Threads API 래퍼
│   └── models.py        # Pydantic 모델
├── auth/
│   ├── __init__.py
│   ├── oauth.py         # OAuth 2.0 플로우
│   └── token_store.py   # 토큰 저장/로드
├── tests/
│   ├── test_oauth.py
│   ├── test_client.py
│   └── test_token_store.py
├── cli.py               # CLI 도구
├── config.py            # 환경변수 로드
├── main.py              # FastAPI 앱 (OAuth 콜백 서버)
├── requirements.txt
├── .env.example
└── .gitignore
```

## 기술 참고 (리서치에서 발췌)

### Threads API Base URL
`https://graph.threads.net/v1.0/`

### OAuth 인증 URL
```
GET https://threads.net/oauth/authorize
  ?client_id={APP_ID}
  &redirect_uri={REDIRECT_URI}
  &scope=threads_basic,threads_content_publish,threads_manage_replies,threads_manage_insights
  &response_type=code
```

### 이미지 게시 (2단계)
```
# Step 1: 미디어 컨테이너 생성
POST /v1.0/{USER_ID}/threads
  { "media_type": "IMAGE", "image_url": "https://공개URL", "text": "캡션" }

# 30초 대기

# Step 2: 발행
POST /v1.0/{USER_ID}/threads_publish
  { "creation_id": "MEDIA_CONTAINER_ID" }
```

### 이미지 제약
- 반드시 **공개 HTTPS URL** (로컬 파일 업로드 불가)
- Threads 권장: 1080 x 1350px (4:5)

## LLM 사용 시 주의
- LLM이 필요한 경우 `claude -p` (Claude CLI subprocess) 사용
- 외부 API (Gemini, OpenAI 등) 사용 금지
- 이 Phase에서는 LLM 불필요 (API 연동만)

## 완료 조건
1. OAuth 인증 플로우 동작 (토큰 발급 + 저장)
2. `cli.py profile` — snu_insurance_group 프로필 조회 성공
3. `cli.py post-text` — 텍스트 게시물 1건 발행 성공
4. `cli.py post-image` — 이미지 게시물 1건 발행 성공 (테스트 이미지)
5. 단위 테스트 전체 PASS
6. `.env.example` + 설치 가이드 포함