Cloudwiki

FMP Starter 전환 계획

제목: CloudStock/FMP Starter 전환 계획

> [[CloudStock]] Phase 2 — FMP 무료 Basic 플랜의 ticker coverage 제약을 확인하고, 다음 세션에서 FMP Starter 로 전환하기 위한 계획서.
> 작성일: 2026-05-22 (KST). 작성자: Claude Code (eoeoe22 세션).
> **갱신 2026-05-23 (KST): Starter 유료 결제는 보류. 무료 티어에서 시세가 돌아오는 20 종목만 남기고 우선 진행한다.** 아래 [[CloudStock/FMP Starter 전환 계획#s-1|§1 갱신]] 참조 — §3 "결정" 및 §4 "다음 세션 작업" 의 Starter 전제 항목은 superseded.

[목차]

## 갱신 (2026-05-23) — Starter 결제 보류, 무료 티어 universe 로 축소

당장 유료 결제를 미루고, FMP 무료 Basic 플랜에서 시세가 돌아오는 종목만 남겨 진행. 아래는 직전 진단 (38 ticker, per-ticker 402 측정) 기준으로 분류한 결과:

### Covered (20) — free 티어에서 `/stable/quote?symbol=X` OK

NVDA, AAPL, MSFT, GOOGL, AMZN, META, TSLA, AMD, TSM, ASML, ARM, PLTR, CSCO, TER, ABBV, GE, UBER, RIVN, LCID, GRAB

### Uncovered (20) — 402 Payment Required (제거 대상)

AVGO, BRK-B, LLY, SMCI, CRWD, SNOW, MU, ANET, CIEN, LITE, NET, ISRG, ABB, VRT, ETN, PWR, CEG, VST, MBLY, SHIP

### 후속 코드 작업

- tracked ticker 목록을 위 20개로 축소. (`worker/agent/fmp.ts` 또는 universe 정의 파일)
- `fetchBatchQuotes` 는 PR #7/#8 에서 적용한 `/stable/quote?symbol=X` per-symbol 순차 호출 + 150ms throttle 형태를 그대로 유지.
- `FAILURE_THRESHOLD` (>10%) 는 그대로 — 20 개 전수 성공이 기대치이므로 1~2 개 실패해도 hard fail 로 표면화.
- 비용 표 ([[CloudStock#s-1.12]]): FMP 라인은 Free $0 유지. 월 총액은 기존 $14~16 그대로.
- 향후 Starter 전환 필요 시 §3 "결정" 의 분석을 그대로 재활용.

## 배경

Phase 3 까지 완성한 뒤 admin 페이지 수동 발화 시 FMP 호출이 반복 실패. 두 차례 PR 로 엔드포인트 (`/stable/batch-quote` → `/api/v3/quote/{symbols}` → `/stable/quote?symbol=X`) 와 버스트 throttle / 진단 메시지를 차례로 적용한 끝에 진짜 원인을 확인:

```
runId: manual-1779483005853
사유: FMP quote: 23/38 symbol(s) failed
       (>10% threshold; e.g. CRWD(402 Payment Required),
                                 SMCI(402 Payment Required),
                                 SNOW(402 Payment Required))
```

**FMP 무료 Basic 플랜은 종목 universe 가 제한적이라 일부 mid/large-cap NASDAQ ticker 가 시세 자체를 돌려주지 않는다 (per-ticker 402 Payment Required).** 38 ticker 중 23 개 (60%) 가 이 사유로 실패. 코드/네트워크/rate limit 문제가 아닌 플랜 coverage 문제.

## 진단 경로 (오늘 실험 기록)

| 시도 | 결과 |
|------|------|
| `/stable/batch-quote?symbols=...` | 402 Payment Required — Starter 이상 전용 endpoint |
| `/api/v3/quote/{symbols}` | 403 Forbidden — 2025-08-31 이후 신규 키엔 legacy 차단 |
| `/stable/quote?symbol=X` 38회 순차 | 부분 성공 — 23/38 이 per-ticker 402 |
| 150ms throttle 후 재시도 | 동일 — burst rate limit 이 아닌 플랜 제약 |

## 결정

**FMP Starter ($22/월, 연결제 $264) 로 업그레이드.** 비교 결과:

- **Perplexity Search 로 시세 긁기**: 데이터 품질 (LLM 텍스트 파싱) / 속도 (req 당 2~10초 × 38 = cron timeout) / 비용 ($5.7/월부터, 한국주식 매시간 cron 도입 시 폭증) 모두 열위.
- **다른 무료 API (Yahoo/Alpha Vantage 등)**: 신규 플랫폼 추가 (사용자 의도와 반대) + ToSᆞrate limit 리스크.
- **tracked universe 축소**: 프로젝트 취지 (AI/세미콘/클라우드/로보틱스/파워인프라 큐레이션) 가 깨짐.
- **FMP Starter**: 모든 US ticker + `/stable/batch-quote` 1 req 일괄 + 300 req/min + FMP 자체 뉴스 endpoint 도 있어 향후 Finnhub 통합 여지 → "한 플랫폼화" 방향 부합.

비용 영향: 위키 §1.12 "월 총 예상 비용: **$14~16** (FMP 무료티어 유지 시)" → **약 $36~38/월** 로 증액 (FMP $22 추가). 부록 §1.12.1 고정비 표 갱신 필요.

## 다음 세션 작업 (TODO)

### 사용자 작업
1. FMP 대시보드에서 **Starter 결제 진행**.
2. 새 API 키 발급되면 `npx wrangler secret put FMP_API_KEY` 로 덮어쓰기.

### 코드 작업 (claude 세션)
3. `worker/agent/fmp.ts` 의 `fetchBatchQuotes` 를 다시 `/stable/batch-quote?symbols=...` **1-shot 일괄 호출** 로 복원. 다음 항목 정리:
   - `QUOTE_THROTTLE_MS` / `sleep` / per-symbol loop 제거 (Starter 는 burst 무관)
   - `FAILURE_THRESHOLD` 는 그대로 두되, 1-shot 이라 사실상 all-or-nothing 으로 동작
   - 응답 필드는 `changesPercentage` (복수) 그대로 — stable batch 도 동일 (PR #7 Codex P1-3 오진 검증 결과)
4. 위키 [[CloudStock/API 키 발급 목록#s-1.2.1]] FMP 섹션 갱신:
   - "Free 250 req/일로 충분" → "Starter $22/월 (전 ticker coverage)"
   - 호출 확인 URL 을 `/stable/batch-quote?symbols=AAPL,MSFT&apikey=...` 로 복귀
5. 위키 [[CloudStock#s-1.12]] 비용 표 업데이트 — FMP Starter $22/월 반영, 월 총액 재산정.

### 선택 (별도 PR)
6. FMP `/stable/news/*` 시리즈로 Finnhub 대체 검토. Phase 3 의 `fetchGeneralNews` / `fetchCompanyNews` 이전.
   - 효과: API 키 1개 감소 (FINNHUB_API_KEY 제거), throttle 로직 (1 req/sec) 단순화.
   - 리스크: FMP 뉴스 품질이 Finnhub 만큼 한국어 친화적인지 검증 필요.

## 참고 — 오늘 작업한 PR

| PR | 제목 | 결과 |
|----|------|------|
| #6 | FMP 무료 티어 호환 — `/api/v3/quote/{symbols}` 전환 | 머지 (403 으로 후속 실패) |
| #7 | `/stable/quote` 심볼별 순차 호출 + 부분 실패 hard fail | 머지 (per-ticker 402 발견) |
| #8 | burst throttle + 실패 사유 표면화 + `workers_dev` 활성 | 머지 (root cause 확정) |

## 보류 사항

- 위키 [[CloudStock/API 키 발급 목록]] 의 직전 draft (이전 세션) 가 사용자 승인 대기 중 — 본 계획서를 별도 페이지로 두고, 위 4번 작업에서 함께 처리.
- Workers Builds preview URL 은 PR #8 의 `workers_dev = true` 머지로 다음 PR 부터 발급 시작.