Finance Helper

미국 공식 이벤트, 미국 시장 반응, 한국 시장의 과거 반응 패턴을 연결해 다음 영업일 한국 시장 테마와 주도주 후보를 예측하는 개인용 리서치 플랫폼입니다.

핵심 목표

• 공식 원문과 신뢰 가능한 시장 데이터만 우선 수집
• 중복 제거와 이벤트 클러스터링을 통해 의미 있는 사건만 남김
• 미국 지수/섹터 ETF/직접 관련주/크로스애셋 반응으로 이벤트를 검증
• 한국 테마와 주도주/2등주를 명시적 규칙과 아날로그 검색으로 번역
• 멀티 에이전트 논증과 판정 모델로 확신과 불확실성을 분리
• 리플레이와 롤링 OOS 평가로 프롬프트/라우팅/가중치를 게이트 방식으로만 개선

기술 스택

• Web: Next.js App Router, TypeScript, Tailwind CSS
• API / Workers: FastAPI, SQLAlchemy, arq, OpenAI Responses API
• Data: PostgreSQL, Redis, TimescaleDB extension
• Infra: Docker Compose
• Testing: Vitest, Pytest

빠른 시작

1. 환경 준비

cp .env.example .env
docker compose up -d db redis

2. Python 의존성 설치와 참조 데이터 시드

cd services/api
python -m venv .venv
.venv/Scripts/activate
pip install -e .[dev]
cd ../..
python scripts/seed_reference_data.py

3. Node 의존성 설치

corepack enable
pnpm install

4. 개발 서버 실행

pnpm dev

• Web: http://localhost:3000
• API: http://localhost:8000/api/v1/health

5. 작업 큐 실행

pnpm --filter finance-helper-api worker

배치 작업

• POST /api/v1/jobs/ingest: 공식 소스 RSS/피드 수집 작업 큐에 적재
• POST /api/v1/jobs/analyze: 이벤트 정규화, 미국 반응 측정, 한국장 번역 작업 큐에 적재

테스트

pnpm test

cd services/api
pytest
ruff check app tests
mypy app

주요 문서

• 아키텍처 개요
• 데이터베이스와 API 설계
• 평가 방법론과 승격 게이트
• UI 페이지 명세
• 리스크와 한계

디렉터리 개요

apps/web             Next.js 한국어 웹앱
services/api         FastAPI API, 분석 엔진, 배치 워커
packages/contracts   Web과 API 응답 계약 스키마
infra/sql/init       DB 초기 SQL
scripts              시드/운영 스크립트
docs                 아키텍처와 운영 문서

현재 구현 범위

• Phase 1: 모노레포, DB 모델, 시드, 대시보드/탐색기/테마/리플레이/평가/관리자 UI
• Phase 2: 이벤트 분류, 점수화, 미국 반응 측정 엔진 기본 구현
• Phase 3: 한국 테마 번역, 주도주/2등주 랭킹 기본 구현
• Phase 4: OpenAI Responses API 기반 역할별 오케스트레이션 기본 구현
• Phase 5: 평가 메트릭, 승격 판정 규칙, 리플레이 기본 응답 구현

주의 사항

• 실거래 주문 엔진은 포함하지 않습니다.
• 프롬프트/라우팅/가중치는 자동 반영되지 않습니다.
• 과거 재현 시 미래 정보 사용을 금지하는 구조를 유지해야 합니다.
• 실제 운영 성능은 데이터 공급원 품질과 참조 매핑 정교도에 크게 의존합니다.

Run Shortcuts

pnpm dev

• Runs the web app and API together.

pnpm app:all

• Runs the web app, API, and worker together in one terminal.

pnpm dev:worker

• Runs only the background worker.