수집기 (collector)

cd collector
uv sync                                   # Python 3.12 고정 (.python-version)

# 백필 — 네이버가 제공하는 최근 ~6거래일 분봉 전부 → data/minute/*.parquet
uv run python backfill.py                 # 전 종목 (~2,700요청, 기본 0.5초 간격 ≈ 25분)
uv run python backfill.py --tickers 005930,000660
uv run python backfill.py --upload        # GitHub Release 업로드까지 (gh CLI 필요)

# 일일 배치 — Actions가 평일 16:30 KST에 실행하는 것과 동일 진입점
uv run --env-file ../.env python daily.py
uv run python daily.py --tickers 005930 --skip-upload   # 스모크

# 파서 테스트
uv run python test_parse.py

• 분봉 원본은 Turso가 아니라 일자별 parquet(zstd) → GitHub Release(태그 minute-YYYY-MM)에 보관한다. Turso 무료 쓰기 한도(월 1,000만 행) 보호 목적.
• 네이버 분봉은 최근 ~6거래일만 제공되므로(2026-08-01 실측) 일일 적재가 누락되면 그 날짜 분봉은 복구 불가. Actions cron이 핵심이다.
• GitHub Actions 시크릿: TURSO_KRX_MARKET_URL, TURSO_KRX_MARKET_AUTH_TOKEN, TURSO_TRADING_URL, TURSO_TRADING_AUTH_TOKEN(스냅샷·AI 수익률 배치), TURSO_API_TOKEN(주간 덤프 backup.yml).
• 일봉은 그날 수집한 분봉의 정규장(09:00~15:40) 봉에서 파생한다(docs/data-pipeline.md). 지수는 FDR(KS11/KQ11) → 네이버 폴백, 수급은 실패 시 스킵(보조 데이터).

데이터 출처 고지

• v0 분봉 데이터는 네이버 금융의 비공식 엔드포인트를 사용합니다. 개인 연구용 저빈도 호출(초당 1회 이하, 지수 백오프 재시도)만 수행합니다.
• 키움증권 REST API 서버점검 종료 후 KiwoomRestProvider로 교체 예정입니다.

배포 (Vercel)

배포 완료: https://k-papertrade.vercel.app (Google 로그인)

재배포·환경변수 관리는 CLI로 한다:

vercel deploy --prod        # 프로덕션 배포
vercel env ls production    # 등록된 환경변수 확인
printf '%s' "새값" | vercel env add APP_PASSWORD production --force

프로덕션 환경변수 — 전부 서버 전용, NEXT_PUBLIC_ 금지:

Google OAuth 클라이언트 만들기

Google Cloud Console → 사용자 인증 정보 만들기 → OAuth 클라이언트 ID → 웹 애플리케이션

동의 화면은 외부(External) + 테스트 사용자에 본인 계정만 추가하면 충분하다 (게시 검증 불필요). 발급된 ID·시크릿을 AUTH_GOOGLE_ID/AUTH_GOOGLE_SECRET으로 등록하면 로그인이 켜진다.

• 로컬 개발·e2e는 AUTH_GOOGLE_ID가 없으면 인증을 생략한다.
• Vercel 기본 배포 보호(SSO)는 해제되어 있고, 앱은 Google 로그인으로만 보호된다.

브랜치 전략

• main(master 역할) · develop — 상시 브랜치
• 기능 개발: develop에서 feature/* 분기 → 완료 시 develop에 머지
• 릴리스: develop → main PR로 반영

진행 상황

• 1단계: 스캐폴딩(루트 Next.js + /collector) + Turso 스키마 + .env.example + 디자인 시안(K-PaperTrade.dc.html) TS 포팅 — 현재 화면은 더미 데이터
• 2단계: NaverProvider(진짜 분봉 OHLC) + 전 종목 백필 + parquet/Release + 일봉·수급·지수 수집 (GitHub Actions)
• 3단계: 체결 엔진(lib/engine/, 순수 함수) + vitest 18케이스 — docs/engine.md
• 4단계: API Routes(zod) + 리플레이 세션(서버측 커서 컷) + 인증 미들웨어 — docs/api.md
• 5단계: 화면 5개 실데이터 연결 + 장중 폴링(장시간 유틸) — docs/screens.md
• 6단계: 성과 지표(MDD·샤프·누적) + 계좌 일일 스냅샷 + ai_decisions 수익률 배치 + 주간 Turso 덤프 워크플로

v1 범위 밖(미구현): VI(변동성완화장치), 동시호가, 공매도, 실거래 연동.