Bond Screener

공공데이터포털(data.go.kr)이 제공하는 금융위원회 채권 오픈API 2종(채권기본정보 · 채권시세정보)을 기반으로 한 국내 채권 스크리너입니다.

Astro + React Islands로 UI를 구성하고, Cloudflare Workers에 배포합니다. 데이터는 Workers cron이 매일 오픈API에서 수집해 D1에 적재하고, 정기적으로 R2에 정적 스냅샷을 올려 클라이언트에 서빙합니다.

프로젝트 구조

오픈API는 개발계정 기준 일 10,000건 호출 제한이 있고, 인증키를 클라이언트에 노출할 수도 없습니다. 그래서 클라이언트가 오픈API를 직접 호출하지 않고, Workers가 중간에서 데이터를 미리 수집해 두는 구조를 사용합니다.

flowchart LR
    API[data.go.kr<br/>채권 오픈API] -->|cron: 매일 KST 13-18시 창<br/>tick당 최대 40페이지| W[Cloudflare Workers]
    W --> D1[(D1<br/>채권·시세 이력)]
    D1 -->|매 영업일 cron이 자동 빌드<br/>수요일 전량 · 그 외 델타| R2[(R2<br/>정적 스냅샷 JSON)]
    R2 -->|목록 조회| C[브라우저]
    D1 -->|종목 상세·시계열| C
    D1 -->|/mcp 툴 호출| M[Claude<br/>MCP 커넥터]

• 목록 화면은 R2 스냅샷만 받습니다 → D1 read 0건.
• 종목 상세·가격 시계열만 D1을 직접 쿼리합니다(요청당 쿼리 3~4개).
• /mcp 엔드포인트로 같은 데이터를 Claude에 툴로 노출합니다 (MCP 서버 참고).
• cron은 매일 KST 13:00~17:59 창 안에서 매분 tick마다 최대 40페이지(또는 20초 중 먼저 도달하는 쪽)를 처리합니다 — 오픈API 갱신이 영업일+1일 오후 1시 이후라 그 전에는 돌 필요가 없습니다. 그날 기본정보 수집이 끝나면 다음 tick에서 스크리너 스냅샷도 같은 cron 안에서 이어서 처리됩니다(수요일은 전량 재빌드, 그 외 영업일은 변경분만 담은 델타). 자세한 스케줄링 로직은 AGENTS.md를 참고하세요.

기술 스택

영역	스택
프레임워크	Astro v7 (output: "server")
UI	React 19 (Astro Islands), shadcn/ui (@base-ui/react 기반), Phosphor Icons
스타일	Tailwind CSS v4 (@tailwindcss/vite)
상태 관리	TanStack Query v5, TanStack Table
차트	lightweight-charts v5
인프라	Cloudflare Workers + D1 + R2 (@astrojs/cloudflare)
테스트	Vitest (@cloudflare/vitest-plugin으로 실제 workerd 런타임 위에서 D1/R2 테스트)
툴링	ESLint, Prettier, lefthook, pnpm

시작하기

요구 사항

• Node.js ^22.12.0 || ^24.11.0 (.node-version: 24.18.0)
• pnpm — corepack enable로 활성화하면 package.json에 고정된 버전이 자동으로 사용됩니다(npm·yarn은 지원하지 않습니다).
• 공공데이터포털에서 발급받은 채권 오픈API 인증키
• Cloudflare 계정 (배포 및 원격 D1/R2 사용 시 필요)

설치

pnpm install

pnpm install 시 prepare 스크립트가 lefthook을 자동으로 설치합니다.

인증키 설정

프로젝트 루트에 .dev.vars 또는 .env 파일을 만들고 Decoded 인증키를 넣으세요. 두 파일이 모두 있으면 .dev.vars가 우선하며 .env는 무시됩니다.

BOND_API_SERVICE_KEY="발급받은-인증키"
MCP_AUTH_TOKEN="임의의-긴-난수-문자열"

MCP_AUTH_TOKEN은 /mcp 엔드포인트의 rate limit 면제 키입니다(선택 사항). 값은 자유롭게 정하면 됩니다(openssl rand -hex 32 등). 설정하지 않아도 /mcp는 그대로 동작하며, 면제 수단만 없어집니다 — 자세한 내용은 MCP 서버를 참고하세요.

두 파일 모두 .gitignore 대상입니다. 배포된 Worker에는 전달되지 않으므로, 배포 시에는 별도로 wrangler secret put BOND_API_SERVICE_KEY와 wrangler secret put MCP_AUTH_TOKEN을 실행해야 합니다.

Cloudflare 리소스 준비

wrangler.jsonc에는 이 저장소를 운영 중인 계정 소유의 D1 데이터베이스 ID와 배포 도메인이 들어 있습니다. 자신의 Cloudflare 계정으로 배포하려면 먼저 리소스를 새로 만들고 값을 교체해야 합니다.

wrangler d1 create bond-screener
wrangler r2 bucket create bond-screener-archive

파일	키	설명
wrangler.jsonc	name	Worker 이름 — 원하는 이름으로 변경
wrangler.jsonc	d1_databases[0].database_id	wrangler d1 create 출력값으로 교체
wrangler.jsonc	routes[0].pattern	커스텀 도메인이 있으면 자신의 도메인으로, 없으면 routes를 지우고 workers_dev: true로
astro.config.mjs	site	sitemap 생성 기준 URL — 배포 도메인에 맞춰 변경

ratelimits[0].namespace_id는 별도로 생성하는 리소스가 아니라 계정 내에서 임의로 고유하게 붙이는 식별자이므로 그대로 두어도 됩니다.

값을 정리했다면 마이그레이션을 적용합니다:

pnpm db:migrate

로컬 데이터 채우기

로컬 D1/R2를 채우려면 오픈API에서 원본 데이터를 먼저 수집해야 합니다. .backfill/은 git에 포함되지 않으므로 클론 직후에는 비어 있습니다.

pnpm backfill discover-range                   # 시세 API 보존 한계 탐지 (최초 1회)
pnpm backfill fetch issu  --bas-dt YYYYMMDD    # 기본정보 원본 수집 (D1 미적재)
pnpm backfill fetch price                      # 시세 원본 수집 (D1 미적재)
pnpm backfill build-sql --source issu
pnpm backfill build-sql --source price
pnpm db:reset:local && pnpm seed:local         # 로컬 D1/R2 초기화 → 마이그레이션 → 적용 → 스냅샷 빌드

• fetch는 오픈API 일일 쿼터(개발계정 기준 10,000건)를 소모하므로, 특히 시세 전량 수집은 여러 날에 나눠 돌려야 할 수 있습니다. 중간에 끊겨도 같은 명령을 다시 실행하면 .backfill/state.json에 기록된 지점부터 이어집니다.
• fetch(API 쿼터)와 apply(D1 write 한도)를 분리해 둔 이유는 한쪽이 한도에 걸려도 다른 쪽까지 다시 돌리지 않기 위해서입니다.
• 데이터 수집 없이 화면만 확인하고 싶다면 pnpm test:e2e가 사용하는 E2E 전용 픽스처(scripts/seed-e2e.mjs)로 최소한의 데이터를 채울 수 있습니다.

개발 서버

pnpm dev

localhost:4321에서 실행됩니다.

명령어

모든 명령은 프로젝트 루트에서 실행합니다.

개발 · 빌드

명령	설명
pnpm dev	개발 서버 시작 (localhost:4321)
pnpm build	프로덕션 빌드 (./dist/)
pnpm preview	빌드 결과 로컬 미리보기
pnpm lint	ESLint 실행
pnpm format	Prettier 포매팅 (.prettierignore에 *.md 포함)
pnpm test	Vitest watch 모드 (node/browser/workers 3-프로젝트)
pnpm test --run	Vitest 1회 실행 (CI/pre-push 훅과 동일)
pnpm test:e2e	Playwright E2E (E2E 전용 로컬 D1을 먼저 시딩)
pnpm generate-types	wrangler.jsonc 기반 바인딩 타입 생성

This is the beginning of the README. Read the rest at the original. Read the full README ↗