database-api.md

Database Schema And API Design

주요 테이블

• source_configs: 소스 메타데이터, 스케줄, 신뢰도
• ingested_documents: 원문, 파싱 결과, 중복 키, 수집/게시 시각
• event_clusters: 정규화 이벤트, 점수, 클러스터 키
• market_reactions: 미국 반응 측정값
• prompt_versions: 운영 프롬프트 버전 기록
• model_routes: 역할별 모델 라우팅
• prediction_runs: 일자별 최종 예측 산출물
• theme_predictions: 한국 테마 예측
• stock_candidates: 주도주/2등주 랭킹
• korean_securities: 한국 종목 마스터/테마 태그
• theme_maps: 미국 이벤트 카테고리 -> 한국 테마 매핑
• agent_runs: 역할별 모델 실행 로그, 비용, 지연, 캐시
• evaluation_runs: 승격 후보 평가 실행
• evaluation_metrics: 평가 지표 결과

API 엔드포인트

• GET /api/v1/health
• GET /api/v1/dashboard
• GET /api/v1/events
• GET /api/v1/themes
• GET /api/v1/replay/{date_label}
• GET /api/v1/evaluations/summary
• GET /api/v1/admin/settings
• POST /api/v1/jobs/ingest
• POST /api/v1/jobs/analyze

API 응답 계약

웹앱과 API 사이의 계약은 packages/contracts/src/index.ts와 services/api/app/schemas/api.py에 이중으로 정의되어 있습니다.

큐 / 작업 설계

• Redis + arq 사용
• 큐 이름은 함수명 기반
• 현재 제공 작업
  • run_ingestion_job
  • run_analysis_job
• 확장 예정 작업
  • 일일 멀티 에이전트 토론
  • 롤링 평가 실행
  • 알림/경보 집계