# data_source_policy.md

- 문서명: Data Source Policy
- 프로젝트 코드명: **ACE-F v1**
- 상태: Draft for Phase 0 Sign-off
- 버전: 0.1
- 작성일: 2026-03-12
- 목적: 프로젝트에서 허용되는 데이터 소스, 금지 소스, 사용 원칙, 비용 원칙, 보관 및 변경 정책을 고정합니다.

> 핵심 원칙: **무료**, **공식 우선**, **재현 가능**, **출처 추적 가능**, **약관 위반 금지**

## 1. 데이터 정책의 최상위 원칙

1. **유료 데이터 금지**
   - 구독료, API 요금, 별도 라이선스 비용이 드는 데이터는 v1 범위에서 사용하지 않습니다.

2. **공식 소스 우선**
   - 동일 정보가 여러 곳에 있다면 발행자 또는 공식 기관이 제공한 원문을 우선 사용합니다.

3. **재현 가능성 우선**
   - live에서 쓰는 데이터 경로와 backtest에서 쓰는 데이터 경로를 최대한 같게 유지합니다.

4. **소셜/미디어는 보조 신호**
   - 공식 이벤트를 대체할 수 없습니다.

5. **출처 추적 가능성**
   - 모든 feature는 어느 소스에서 왔는지 provenance를 남겨야 합니다.

6. **약관/쿼터/접속 정책 준수**
   - 무료라고 해서 무제한 사용을 전제로 하지 않습니다.

## 2. 소스 분류

### 2.1 Core Approved Sources (핵심 허용)
이 소스가 없으면 전략이 동작하지 않거나 품질이 크게 저하됩니다.

1. **SEC EDGAR / data.sec.gov**
   - 용도: 8-K, 10-Q, 10-K, 6-K, 20-F, 40-F, XBRL, Exhibit 99.1 수집
   - 역할: 원문 이벤트와 공식 숫자 데이터의 기준 원장
   - 정책:
     - 공정접속 정책 준수
     - user-agent 명시
     - 필요한 문서만 다운로드
     - raw 원문과 정규화 결과를 함께 저장

2. **Alpaca Basic**
   - 용도: 일봉/분봉 시세, paper trading, 주문 상태
   - 역할: 기본 가격 확인 및 시뮬레이션/실행 reference
   - 정책:
     - 무료 플랜 제약에 맞춘 폴링 설계
     - 정교한 intraday 전략의 기준 feed로 사용하지 않음
     - IEX 중심 무료 데이터임을 전제로 해석

3. **FRED API**
   - 용도: 거시/시장 레짐 보조 feature
   - 역할: risk-on / risk-off 필터

4. **FINRA Daily Short Sale Volume**
   - 용도: crowding / short activity overlay
   - 역할: 당일 short sale volume anomaly 탐지
   - 주의:
     - short interest와 동일 개념으로 해석 금지

### 2.2 Secondary Approved Sources (보조 허용)
핵심 전략이 살아 있는 상태에서 보조 feature로만 사용합니다.

1. **Wikimedia Pageviews**
   - 용도: retail curiosity / 관심 급증 측정
   - 역할: attention overlay

2. **YouTube Data API**
   - 용도: whitelist 채널 기반 mention/engagement 추적
   - 역할: 관심 확산 속도 측정
   - 정책:
     - 전수 검색 금지
     - 채널 whitelist 우선
     - 제목/설명/댓글/조회수 기반 feature만 사용
     - 공개 영상 자막 대량 수집 구조 금지

3. **Yahoo Finance RSS**
   - 용도: headline burst / publisher breadth 카운팅
   - 역할: 미디어 확산 보조 판단
   - 정책:
     - 원문 사실 확인 소스가 아니라 보조 attention 레이어로만 사용
     - headline 중복 제거 필수

### 2.3 Experimental Sources (연구용)
즉시 production 의존성을 두지 않습니다.

1. **Google Trends API Alpha**
   - 용도: 테마/키워드 관심 급증
   - 정책:
     - 접근권이 있는 경우에만 사용
     - 핵심 진입 신호로 사용 금지
     - 보유기간/랭킹 보조로만 연구

2. **Reddit**
   - 용도: 연구용 mention/engagement feature
   - 정책:
     - 약관/상업적 사용 가능 여부 확인 전 live 핵심 입력 금지
     - research-only flag 필요

### 2.4 Disallowed / Not-in-scope Sources (금지 또는 범위 밖)
- 유료 earnings estimate API
- 유료 transcript API
- X/Twitter 유료 API 의존 구조
- 현재 신규 접근성이 불안정한 비공식 금융 커뮤니티 API
- robots/약관 위반 가능성이 있는 무단 스크레이핑
- captcha/로그인 우회 수집
- 저작권/재배포 정책이 불명확한 자막 다운로드 사이트
- 웹사이트 화면 파싱을 기반으로 한 핵심 전략

## 3. 소스별 구체 정책

## 3.1 SEC EDGAR
### 허용 사용
- filing metadata
- filing body
- exhibit 99.1
- XBRL facts
- company submissions history

### 요구사항
- 명시적 user-agent
- 합리적 캐시
- 재다운로드 최소화
- 문서 원본 불변 저장

### 금지사항
- 불필요한 전수 크롤링
- rate limit 무시
- 원문 없이 파싱 결과만 보관하는 구조

## 3.2 Alpaca Basic
### 허용 사용
- 일봉/분봉 bars
- latest bar 확인
- paper trading
- 기본 주문 상태 확인

### 제한사항
- 무료 플랜 제약을 고려한 호출 빈도 설계
- IEX 중심 무료 실시간 데이터 한계를 감안한 해석
- v1에서 초단타 실시간 전략의 진실 원장으로 사용 금지

## 3.3 FRED
### 허용 사용
- 금리/스프레드/거시 레짐
- regime filter
### 제한사항
- 개별 종목 진입 신호로 직접 사용하지 않음

## 3.4 FINRA Short Sale Volume
### 허용 사용
- short volume ratio
- abnormal short activity
- off-exchange crowding 힌트
### 제한사항
- short interest 대용으로 사용 금지
- 단독 진입 신호 금지

## 3.5 Wikimedia
### 허용 사용
- 회사/브랜드 pageview spike
- retail curiosity shock
### 제한사항
- 문서/가격 확인 없이 단독 진입 금지

## 3.6 YouTube
### 허용 사용
- whitelist 채널의 업로드 감시
- 제목/설명에서 ticker/키워드 추출
- 조회수 증가 속도
- 댓글 수/간단 감성
### 제한사항
- search.list 남용 금지
- captions.download 기반 대량 수집 금지
- “유명인이 찍었으니 산다” 식 단독 신호 금지

## 3.7 Yahoo Finance RSS
### 허용 사용
- 헤드라인 burst
- 유니크 publisher 수
- 기사 수 증가율
### 제한사항
- 동일 보도자료의 다중 복제 기사 중복 제거
- 공식 사실 검증 소스 아님

## 3.8 Google Trends
### 허용 사용
- 섹터/테마 열기 확인
- 특정 키워드의 관심 확산
### 제한사항
- 접근성/안정성 불확실
- alpha 의존성 때문에 core pipeline 금지

## 4. 데이터 우선순위와 진실 원장(Source of Truth)

### 4.1 이벤트 원장
- 1순위: SEC 공시 원문
- 2순위: 회사 IR 자료
- 3순위: 정규화 파서 결과
- 4순위: 미디어/소셜 overlay

### 4.2 가격 원장
- 1순위: 브로커 reference price feed
- 2순위: 저장된 historical bars
- 3순위: 파생 계산 feature

### 4.3 attention 원장
- 원장 개념보다는 보조 signal
- core signal을 override할 수 없음

## 5. 데이터 비용 정책

### 5.1 외부 데이터 비용
- 데이터 API 구독료는 **0원/0달러**여야 합니다.
- 테스트 편의를 위해 일시적으로 쓰는 유료 trial 데이터도 core feature로 편입하지 않습니다.

### 5.2 LLM 비용
- LLM은 데이터 API가 아니지만 운영비에 포함됩니다.
- 모든 문서에 LLM을 호출하지 않고, 규칙 필터 통과 문서만 호출합니다.
- accession/file hash 단위 캐시 필수
- 비용 상한 초과 시 low-priority 문서는 규칙 기반 fallback

## 6. 수집 및 저장 정책

### 6.1 Raw 저장
- 원문은 수정 없이 보관합니다.
- 원문 저장 경로에는 source / date / entity / accession 정보를 포함합니다.
- raw는 immutable 원칙을 따릅니다.

### 6.2 Structured 저장
- 파싱 결과, feature, label은 별도 테이블로 분리합니다.
- raw와 structured를 섞어 저장하지 않습니다.
- schema version을 관리합니다.

### 6.3 Provenance 필수 필드
모든 구조화 레코드는 최소한 아래를 포함해야 합니다.
- source_name
- source_url
- fetched_at
- document_id or accession
- parser_version
- llm_prompt_version (해당 시)
- feature_build_version

## 7. 검증 정책

### 7.1 ingestion 검증
- 중복 적재 방지
- 누락 탐지
- 스키마 검증
- 일일 job 성공/실패 로그

### 7.2 파서 검증
- 샘플 수동 검수
- low confidence 큐 별도 관리
- source별 실패 패턴 기록

### 7.3 변경 검증
- 소스 포맷이 바뀌면 adapter contract 테스트 업데이트
- source availability 저하 시 fallback 설계 여부 확인

## 8. 장애 및 fallback 정책

### 8.1 SEC 장애
- 신규 이벤트 탐지 중단
- 과거 저장분만으로는 신규 주문 생성 금지

### 8.2 Alpaca 데이터 지연
- 신규 진입 보류
- 보유 포지션 안전관리만 수행

### 8.3 Secondary source 장애
- attention score를 0 또는 missing 처리
- core 전략은 계속 동작해야 함

## 9. 소스 변경 및 폐기 정책
- 무료 정책이 유료 정책으로 바뀌면 즉시 production source에서 제외 검토
- 쿼터/약관/라이선스 변경은 문서화 후 승인
- 핵심 소스 변경은 Phase 0~1 수준의 재검토 필요

## 10. 승인된 소스 목록 요약

| 분류 | 소스 | 역할 | Production 허용 여부 |
|---|---|---|---|
| Core | SEC EDGAR | 이벤트 원문/XBRL | 허용 |
| Core | Alpaca Basic | 가격/주문/paper | 허용 |
| Core | FRED | 시장 레짐 | 허용 |
| Core | FINRA Short Volume | crowding overlay | 허용 |
| Secondary | Wikimedia | attention | 허용 |
| Secondary | YouTube Data API | attention | 허용 |
| Secondary | Yahoo RSS | headline burst | 허용 |
| Experimental | Google Trends Alpha | theme heat | 제한적 |
| Experimental | Reddit | research-only | 제한적 |
| Disallowed | Paid market/earnings APIs | 유료 데이터 | 금지 |
| Disallowed | X/Twitter paid API | 비용/정책 불안정 | 금지 |
| Disallowed | Unofficial scraping | 약관 리스크 | 금지 |

## 11. 변경 관리
- 새로운 소스를 추가하려면 다음을 충족해야 합니다.
  1. 무료 여부
  2. 약관/라이선스 검토
  3. provenance 저장 가능 여부
  4. 핵심 전략을 오염시키지 않을 것
  5. 장애 시 graceful degradation 가능 여부

## 부록 A. 현재 확인된 주요 운영 전제
- SEC는 data.sec.gov에서 인증 없이 JSON API를 제공하며, 실시간 업데이트와 bulk ZIP을 지원합니다.
- SEC는 공정접속을 위해 최대 접근률을 제한하고 과도한 자동 요청을 관리합니다.
- Alpaca Basic은 무료 기본 플랜이며, 주식 무료 실시간 커버리지는 IEX 중심입니다.
- YouTube Data API는 기본 일일 할당량이 존재하며, 검색 호출은 비용이 큽니다.
- 공개 YouTube 자막은 공식 API로 자유롭게 대량 다운로드하는 구조가 아닙니다.
- Wikimedia pageviews는 공개 API로 제공됩니다.
- Google Trends API는 alpha 접근 구조입니다.

## 부록 B. 참고 링크
- SEC EDGAR APIs: https://www.sec.gov/search-filings/edgar-application-programming-interfaces
- SEC Developer Resources: https://www.sec.gov/about/developer-resources
- SEC rate limit / fair access notes: https://www.sec.gov/about/webmaster-frequently-asked-questions
- Alpaca Market Data API: https://docs.alpaca.markets/docs/about-market-data-api
- Alpaca rate limit support note: https://alpaca.markets/support/usage-limit-api-calls
- FINRA short sale volume: https://www.finra.org/finra-data/browse-catalog/short-sale-volume-data/daily-short-sale-volume-files
- FINRA short volume explanation: https://www.finra.org/filing-reporting/adf/adf-regulation-sho
- Wikimedia Analytics API: https://doc.wikimedia.org/generated-data-platform/aqs/analytics-api/reference/page-views.html
- YouTube quota cost: https://developers.google.com/youtube/v3/determine_quota_cost
- YouTube captions download policy: https://developers.google.com/youtube/v3/docs/captions/download
- Yahoo Finance RSS: https://finance.yahoo.com/rss/
- Google Trends API alpha: https://developers.google.com/search/apis/trends