diff --git a/.github/ISSUE_TEMPLATE/versioned-feature-issue.md b/.github/ISSUE_TEMPLATE/versioned-feature-issue.md new file mode 100644 index 0000000..522ee9d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/versioned-feature-issue.md @@ -0,0 +1,25 @@ +--- +name: Versioned Feature Issue +about: 버전과 기능 단위로 작업을 분해하는 이슈 템플릿 +title: "[v0.x.x] " +labels: ["type:feature"] +assignees: [] +--- + +## 배경 + +- + +## 범위 + +- + +## 완료 조건 + +- [ ] +- [ ] +- [ ] + +## 비고 + +- diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..5490c67 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,25 @@ +## 요약 +- + +## 관련 이슈 +- Closes # + +## 변경 범위 +- + +## 설계/제품 규칙 체크 +- [ ] look-ahead bias를 추가하지 않았다 +- [ ] production prompt self-modification을 추가하지 않았다 +- [ ] 모델 라우팅은 role 기준으로 configurable 하다 +- [ ] deterministic parsing/scoring 우선 원칙을 유지했다 +- [ ] LLM 호출은 explicit schema / structured output 기준을 따른다 +- [ ] prediction artifact 저장 필드가 필요한 경우 함께 반영되었다 +- [ ] UI가 uncertainty와 invalidation condition을 숨기지 않는다 + +## 검증 +- [ ] `pytest services/api/tests -q` +- [ ] `npx pnpm --filter @finance-helper/web exec tsc --noEmit` +- [ ] 로컬에서 핵심 플로우를 직접 확인했다 + +## 리스크 / 후속 작업 +- diff --git a/.gitignore b/.gitignore index 46ca50e..51c15fc 100644 --- a/.gitignore +++ b/.gitignore @@ -18,3 +18,4 @@ services/api/alembic/versions/__pycache__ scripts/__pycache__ .codex-*.log TT_Main/ +*.egg-info/ diff --git a/README.md b/README.md index 3a32f30..5a4c751 100644 --- a/README.md +++ b/README.md @@ -1 +1,133 @@ -# TT_Main \ No newline at end of file +# 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. 환경 준비 + +```bash +cp .env.example .env +docker compose up -d db redis +``` + +### 2. Python 의존성 설치와 참조 데이터 시드 + +```bash +cd services/api +python -m venv .venv +.venv/Scripts/activate +pip install -e .[dev] +cd ../.. +python scripts/seed_reference_data.py +``` + +### 3. Node 의존성 설치 + +```bash +corepack enable +pnpm install +``` + +### 4. 개발 서버 실행 + +```bash +pnpm dev +``` + +- Web: [http://localhost:3000](http://localhost:3000) +- API: [http://localhost:8000/api/v1/health](http://localhost:8000/api/v1/health) + +### 5. 작업 큐 실행 + +```bash +pnpm --filter finance-helper-api worker +``` + +## 배치 작업 + +- `POST /api/v1/jobs/ingest`: 공식 소스 RSS/피드 수집 작업 큐에 적재 +- `POST /api/v1/jobs/analyze`: 이벤트 정규화, 미국 반응 측정, 한국장 번역 작업 큐에 적재 + +## 테스트 + +```bash +pnpm test +``` + +```bash +cd services/api +pytest +ruff check app tests +mypy app +``` + +## 주요 문서 + +- [아키텍처 개요](docs/architecture.md) +- [데이터베이스와 API 설계](docs/database-api.md) +- [평가 방법론과 승격 게이트](docs/evaluation.md) +- [UI 페이지 명세](docs/ui-spec.md) +- [리스크와 한계](docs/risks.md) + +## 디렉터리 개요 + +```text +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 + +```bash +pnpm dev +``` + +- Runs the web app and API together. + +```bash +pnpm app:all +``` + +- Runs the web app, API, and worker together in one terminal. + +```bash +pnpm dev:worker +``` + +- Runs only the background worker. diff --git a/docs/github-issue-pr-plan-ko.md b/docs/github-issue-pr-plan-ko.md new file mode 100644 index 0000000..ac45f0b --- /dev/null +++ b/docs/github-issue-pr-plan-ko.md @@ -0,0 +1,122 @@ +# GitHub Issue & PR Plan + +이 문서는 지금까지 사용자가 내린 주요 명령과 그에 따른 구현 흐름을 기능별, 버전별로 나눈 GitHub 작업 계획이다. + +## 명령 기준 분해 + +1. `Please create a web project ... Start implementing the project files.` +2. `Project rules ...` +3. `Please design the project using DESIGN.md file.` +4. `로컬에서 돌려볼라 하는데 명령어 뭐 입력해야돼` +5. `그럼 버튼을 누르면 ... 작업이 실행되도록 수정해줄 수 있을까?` +6. `작업 중 표시 / 최근 실행 결과 / 자동 새로고침` +7. `수집 후 분석 실행` 오류 수정들 +8. `내일 한국장 예상 테마와 주도주 / 2등주 후보가 계속 중복` +9. `과거 7일치 한국 증시 분석 ... 실제로 돌려서 채워넣어줘` +10. `npx pnpm dev는 웹+API / npx pnpm app:all은 웹+API+워커` +11. `AWS나 Oracle Cloud에 올리고 싶다` + +## 실제 생성할 Issue 목록 + +### Issue A +- 버전: `v0.1.0` +- 제목: `[v0.1.0] 개인용 한미 이벤트 리서치 플랫폼 모노레포 스캐폴딩 구축` +- 기준 명령: + - `Please create a web project ...` + - `Project rules ...` + +### Issue B +- 버전: `v0.2.0` +- 제목: `[v0.2.0] 미국 공식 소스 수집, 이벤트 정규화, 시장 반응 엔진 구현` +- 기준 명령: + - `Please create a web project ...` + +### Issue C +- 버전: `v0.3.0` +- 제목: `[v0.3.0] 한국 테마 번역, 주도주/2등주 랭킹, 대시보드 기본 UI 연결` +- 기준 명령: + - `Please create a web project ...` + +### Issue D +- 버전: `v0.4.0` +- 제목: `[v0.4.0] DESIGN.md 기반 전체 UI 리디자인과 공통 스타일 시스템 정리` +- 기준 명령: + - `Please design the project using DESIGN.md file.` + - `변경된 DESIGN.md로 재 디자인해줘` + - `전체 페이지 전부 동일하게 다듬어줘` + +### Issue E +- 버전: `v0.4.0` +- 제목: `[v0.4.0] 웹 버튼 기반 파이프라인 실행, 작업 상태 표시, 자동 새로고침 추가` +- 기준 명령: + - `그럼 버튼을 누르면 ...` + - `작업 중 표시 ...` + - `최근 실행 결과 ... 최대 최근 두 개` + +### Issue F +- 버전: `v0.4.1` +- 제목: `[v0.4.1] 수집/분석 파이프라인 런타임 오류 복구와 안정성 하드닝` +- 기준 명령: + - Treasury 404 오류 + - `float() argument must be a string or a real number, not 'Series'` + - 버튼/작업 상태 관련 반복 검증 + +### Issue G +- 버전: `v0.4.2` +- 제목: `[v0.4.2] 한국장 예상 테마와 종목 후보 중복 제거 로직 개선` +- 기준 명령: + - `내일 한국장 예상 테마와 주도주 / 2등주 후보가 계속 중복` + +### Issue H +- 버전: `v0.5.0` +- 제목: `[v0.5.0] 최근 7거래일 리플레이와 실제 한국장 반응 비교 페이지 구현` +- 기준 명령: + - `현재 추론 과정을 통한 ... 일주일치의 과거 자료` + - `의미 없는 더미 데이터가 아니라 ... 실제로 돌려서 채워넣어줘` + +### Issue I +- 버전: `v0.5.1` +- 제목: `[v0.5.1] 예측 아티팩트 감사 추적과 프롬프트/모델 게이팅 평가 보강` +- 기준 명령: + - `Project rules ...` + - 리플레이/평가 관련 후속 요구 + +### Issue J +- 버전: `v0.6.0` +- 제목: `[v0.6.0] 로컬 실행 단순화와 클라우드 배포 준비 문서 정리` +- 기준 명령: + - `로컬에서 돌려볼라 하는데 명령어 뭐 입력해야돼` + - `지금 명령어 입력하는게 너무 귀찮은데` + - `AWS나 Oracle ...` + +## PR 초안 분리안 + +### PR 1 +- 제목: `feat: bootstrap monorepo and core platform contracts` +- 브랜치: `codex/v0.1-bootstrap-platform` +- 닫는 이슈: `A` + +### PR 2 +- 제목: `feat: add us ingestion pipeline and reaction engine` +- 브랜치: `codex/v0.2-ingestion-reaction` +- 닫는 이슈: `B` + +### PR 3 +- 제목: `feat: add korea translation engine and dashboard experience` +- 브랜치: `codex/v0.3-korea-dashboard` +- 닫는 이슈: `C`, `D` + +### PR 4 +- 제목: `feat: add job controls and harden pipeline reliability` +- 브랜치: `codex/v0.4-pipeline-ops` +- 닫는 이슈: `E`, `F`, `G`, `J` + +### PR 5 +- 제목: `feat: add weekly replay and evaluation audit trail` +- 브랜치: `codex/v0.5-replay-eval` +- 닫는 이슈: `H`, `I` + +## 메모 + +- 현재 작업물은 하나의 큰 변경 세트로 누적되어 있어, 실제 PR 생성 전에는 브랜치 분리와 커밋 재구성이 필요하다. +- 따라서 이슈는 지금 바로 GitHub에 생성하고, PR은 위 분리안을 기준으로 후속 정리하는 편이 가장 안전하다. diff --git a/docs/github-pr-drafts-ko.md b/docs/github-pr-drafts-ko.md new file mode 100644 index 0000000..f930438 --- /dev/null +++ b/docs/github-pr-drafts-ko.md @@ -0,0 +1,202 @@ +# GitHub PR Drafts + +실제 이슈는 생성 완료되었다. 현재 저장소 작업은 하나의 큰 변경 세트로 누적되어 있으므로, 실제 PR은 아래 분리안대로 브랜치/커밋을 나눈 뒤 생성하는 것을 권장한다. + +## 생성된 Issue + +- #1 [v0.1.0] 개인용 한미 이벤트 리서치 플랫폼 모노레포 스캐폴딩 구축 +- #2 [v0.2.0] 미국 공식 소스 수집, 이벤트 정규화, 시장 반응 엔진 구현 +- #3 [v0.3.0] 한국 테마 번역, 주도주/2등주 랭킹, 대시보드 기본 UI 연결 +- #4 [v0.4.0] DESIGN.md 기반 전체 UI 리디자인과 공통 스타일 시스템 정리 +- #5 [v0.4.0] 웹 버튼 기반 파이프라인 실행, 작업 상태 표시, 자동 새로고침 추가 +- #6 [v0.4.1] 수집/분석 파이프라인 런타임 오류 복구와 안정성 하드닝 +- #7 [v0.4.2] 한국장 예상 테마와 종목 후보 중복 제거 로직 개선 +- #8 [v0.5.0] 최근 7거래일 리플레이와 실제 한국장 반응 비교 페이지 구현 +- #9 [v0.5.1] 예측 아티팩트 감사 추적과 프롬프트/모델 게이팅 평가 보강 +- #10 [v0.6.0] 로컬 실행 단순화와 AWS·OCI 배포 준비 문서 정리 + +## PR 1 + +**Title** +`feat: bootstrap finance-helper monorepo and core platform docs` + +**Branch** +`codex/v0.1-bootstrap-platform` + +**Closes** +- `Closes #1` + +**Body** + +```md +## 요약 +- 개인용 한미 이벤트 리서치 플랫폼의 모노레포 기본 구조를 추가했습니다. +- Next.js 웹, FastAPI API, 공용 contracts, Docker Compose, seed script, 기본 문서를 정리했습니다. + +## 포함 내용 +- 루트 workspace / package manager 설정 +- `apps/web`, `services/api`, `packages/contracts` 초기 구조 +- `.env.example`, `docker-compose.yml`, README, AGENTS.md, docs 추가 + +## 검증 +- [ ] 로컬 의존성 설치 +- [ ] 웹/API 기동 확인 +- [ ] 참조 데이터 시드 확인 + +## 관련 이슈 +- Closes #1 +``` + +## PR 2 + +**Title** +`feat: add us ingestion pipeline, event scoring, and market reaction engine` + +**Branch** +`codex/v0.2-ingestion-reaction` + +**Closes** +- `Closes #2` + +**Body** + +```md +## 요약 +- 미국 공식/시장 데이터 수집 파이프라인을 추가했습니다. +- 이벤트 정규화, 클러스터링, 점수화, 미국 시장 반응 엔진을 구현했습니다. + +## 포함 내용 +- source connector 및 raw/parsed document 저장 +- event categorization / clustering / scoring +- market confirmation, cross-asset reaction 계산 +- reaction engine 회귀 테스트 추가 + +## 검증 +- [ ] 수집 작업 실행 후 문서/이벤트 생성 확인 +- [ ] 시장 반응 row 생성 확인 +- [ ] pytest 통과 + +## 관련 이슈 +- Closes #2 +``` + +## PR 3 + +**Title** +`feat: add korea translation workflow and unified dashboard experience` + +**Branch** +`codex/v0.3-korea-dashboard` + +**Closes** +- `Closes #3` +- `Closes #4` + +**Body** + +```md +## 요약 +- 검증된 미국 이벤트를 한국 테마/주도주/2등주 후보로 번역하는 엔진을 추가했습니다. +- Dashboard, Event Explorer, Theme Board를 연결하고 DESIGN.md 기반 디자인 시스템을 통일했습니다. + +## 포함 내용 +- korea translation engine +- prediction run / theme prediction / stock candidate 저장 +- invalidation condition, uncertainty, risk flag 노출 +- 전체 페이지 공통 rounded style / typography 정리 + +## 검증 +- [ ] 대시보드/이벤트 탐색기/테마 보드 렌더링 확인 +- [ ] theme translation 결과 확인 +- [ ] 타입체크 통과 + +## 관련 이슈 +- Closes #3 +- Closes #4 +``` + +## PR 4 + +**Title** +`feat: add pipeline controls and harden runtime reliability` + +**Branch** +`codex/v0.4-pipeline-ops` + +**Closes** +- `Closes #5` +- `Closes #6` +- `Closes #7` +- `Closes #10` + +**Body** + +```md +## 요약 +- 웹에서 수집/분석을 실행하는 버튼과 작업 상태 UI를 추가했습니다. +- 최근 실행 결과, 자동 새로고침, 최근 2건 제한을 추가했습니다. +- Treasury 404, yfinance Series 오류, 중복 테마/종목 문제를 해결했습니다. +- `pnpm dev`, `pnpm app:all` 실행 전략과 로컬 실행 문서를 정리했습니다. + +## 포함 내용 +- job control API / UI +- job_runs 저장 구조와 recent jobs 조회 +- source failure 격리와 reaction engine 방어 로직 +- theme/stock dedupe +- one-terminal 실행 스크립트 + +## 검증 +- [ ] `수집 후 분석 실행` 완료 확인 +- [ ] 최근 실행 결과 UI 확인 +- [ ] pytest / tsc 통과 +- [ ] `pnpm app:all` 실행 확인 + +## 관련 이슈 +- Closes #5 +- Closes #6 +- Closes #7 +- Closes #10 +``` + +## PR 5 + +**Title** +`feat: add weekly replay, real evidence backfill, and evaluation audit trail` + +**Branch** +`codex/v0.5-replay-eval` + +**Closes** +- `Closes #8` +- `Closes #9` + +**Body** + +```md +## 요약 +- 최근 7거래일을 현재 추론 로직으로 재분석하는 weekly replay를 추가했습니다. +- 실제 미국 기사 근거와 실제 익일 한국장 반응을 같은 화면에서 비교할 수 있게 했습니다. +- 예측 아티팩트와 평가 게이팅 규칙을 보강했습니다. + +## 포함 내용 +- weekly replay service / API / UI +- 실제 기사 source/link 표시 +- 한국 종목/지수 반응 계산 +- prediction artifact 저장 필드와 평가 규칙 보강 + +## 검증 +- [ ] replay API 응답 확인 +- [ ] 최근 7거래일 리플레이 화면 확인 +- [ ] pytest 통과 + +## 관련 이슈 +- Closes #8 +- Closes #9 +``` + +## 실제 PR 생성 전 체크 + +1. 변경 파일을 위 PR 범위에 맞춰 브랜치별로 나눈다. +2. `.codex-*.log`, 로컬 임시 파일, `.env` 등은 제외한다. +3. 각 브랜치에서 관련 없는 파일 변경은 빼고 커밋한다. +4. 그다음 `gh pr create --draft`로 올린다. diff --git a/docs/github-work-items.md b/docs/github-work-items.md new file mode 100644 index 0000000..55ef9a5 --- /dev/null +++ b/docs/github-work-items.md @@ -0,0 +1,511 @@ +# GitHub Work Items + +이 문서는 지금까지의 구현/대화 내용을 바탕으로 `TradeTrigger/TT_Main` 저장소에 올릴 이슈와 PR을 기능별, 버전별로 나눈 초안이다. 실제 GitHub 앱 권한이 현재 저장소에 연결되어 있지 않아 자동 생성은 못 했고, 아래 본문을 그대로 복붙해서 사용하면 된다. + +## 버전 로드맵 + +| 버전 | 목표 | 상태 | +| --- | --- | --- | +| v0.1.0 | 모노레포 스캐폴딩, 로컬 실행, 기본 스키마, 문서화 | 초안 완료 | +| v0.2.0 | 수집 파이프라인, 이벤트 정규화, 미국 반응 엔진 | 초안 완료 | +| v0.3.0 | 한국 테마 번역, 주도주/2등주 예측, 대시보드 | 초안 완료 | +| v0.4.0 | 작업 실행 UX, 중복 제거, 파이프라인 안정화, UI 정리 | 초안 완료 | +| v0.5.0 | 과거 7거래일 리플레이, 실제 한국장 반응 비교, 평가 보강 | 초안 완료 | +| v0.6.0 | 운영 배포 패키징, 스케줄링, 관측성, 클라우드 배포 문서 | 예정 | + +## Issue Drafts + +### Issue 1 + +**Title** +`[v0.1.0] 모노레포 스캐폴딩 및 로컬 실행 기반 구축` + +**Labels** +`type:feature`, `area:platform`, `version:v0.1.0` + +**Body** + +```md +## 배경 +개인용 이벤트 기반 한미 증시 리서치 플랫폼의 초기 구조를 세팅한다. 웹, API, 워커, DB, 캐시를 분리하고 로컬에서 일관되게 재현 가능한 실행 환경이 필요하다. + +## 범위 +- Next.js App Router + TypeScript + Tailwind 웹앱 구성 +- FastAPI + SQLAlchemy + arq 워커 서비스 구성 +- PostgreSQL / Redis / Docker Compose 로컬 개발 환경 구성 +- 공용 contracts 패키지 구성 +- README, 아키텍처 문서, 환경변수 예시, AGENTS.md 작성 + +## 완료 조건 +- `npx pnpm dev`로 웹/API가 함께 실행된다 +- 워커를 별도 프로세스로 실행할 수 있다 +- `.env.example` 기준으로 로컬 실행이 가능하다 +- 핵심 아키텍처/DB/API 문서가 저장소에 포함된다 + +## 비고 +- 브로커 연동, 실주문, 소셜 기능은 제외한다 +``` + +### Issue 2 + +**Title** +`[v0.2.0] 미국 공식/시장 데이터 수집 및 이벤트 정규화 엔진 구현` + +**Labels** +`type:feature`, `area:ingestion`, `area:event-engine`, `version:v0.2.0` + +**Body** + +```md +## 배경 +미국 뉴스/정책/공시/시장 데이터를 수집하고, 이를 중복 제거 가능한 정규 이벤트로 바꿔야 다음 단계 분석이 가능하다. + +## 범위 +- 공식 소스/시장 뉴스 커넥터 구현 +- 소스 메타데이터, fetch/publication timestamp, raw/parsed content 저장 +- deduplication key / reliability score / cluster id 저장 구조 구현 +- 이벤트 카테고리 분류 +- duplicate detection / clustering / novelty/directness/surprise/persistence scoring 구현 + +## 완료 조건 +- 최소 1회 수집 작업이 DB에 원문과 파싱 결과를 저장한다 +- 동일 문서 재수집 시 dedupe가 동작한다 +- 이벤트 클러스터가 생성되고 점수 필드가 채워진다 +- 핵심 분류/스코어링 로직에 테스트가 있다 + +## 비고 +- 모델은 보조 수단이고, 파싱/분류/스코어링은 우선 deterministic 하게 처리한다 +``` + +### Issue 3 + +**Title** +`[v0.2.0] 미국 시장 반응 엔진 및 교차자산 확인 로직 추가` + +**Labels** +`type:feature`, `area:market-reaction`, `version:v0.2.0` + +**Body** + +```md +## 배경 +단순 뉴스 수집만으로는 다음날 한국장에 연결할 수 없다. 이벤트 이후 미국 시장이 실제로 어떻게 반응했는지 확인하는 단계가 필요하다. + +## 범위 +- 주요 지수, 섹터 ETF, 직접 수혜/피해 종목 반응 계산 +- intraday / after-hours 구분 +- reaction window metric 계산 +- DXY, 금리, 원자재, BTC 등 교차자산 확인 로직 추가 +- yfinance 기반 반응 계산 방어 로직 추가 + +## 완료 조건 +- 이벤트 단위로 market reaction row가 저장된다 +- confirmation score가 계산된다 +- MultiIndex/Series 반환 같은 공급자 예외 케이스를 방어한다 +- 반응 계산 테스트가 포함된다 + +## 비고 +- 데이터 소스는 향후 Polygon/기관급 공급자로 교체 가능하도록 구조를 유지한다 +``` + +### Issue 4 + +**Title** +`[v0.3.0] 미국 이벤트를 한국 테마/주도주 후보로 번역하는 엔진 구현` + +**Labels** +`type:feature`, `area:korea-translation`, `version:v0.3.0` + +**Body** + +```md +## 배경 +검증된 미국 이벤트를 다음 한국장 테마와 종목 후보로 연결하는 번역 계층이 핵심 제품 가치다. + +## 범위 +- explicit theme mapping rule 적용 +- historical analog retrieval 기반 보강 +- theme fit / tradability / gap-fade / priced-in risk 점수화 +- leader / second-tier candidate 추출 +- invalidation condition 저장 +- 동일 테마/종목 중복 제거 로직 구현 + +## 완료 조건 +- 예측 결과에 한국 테마, 주도주, 2등주, 무효화 조건이 저장된다 +- 동일 테마/종목이 반복 저장되지 않는다 +- 최신 prediction run 기준으로 화면이 정리된다 +- 번역/중복 제거 테스트가 있다 +``` + +### Issue 5 + +**Title** +`[v0.3.0] 대시보드·이벤트 탐색기·한국 테마 보드 기본 UI 구축` + +**Labels** +`type:feature`, `area:web`, `area:dashboard`, `version:v0.3.0` + +**Body** + +```md +## 배경 +실제 개인 사용 환경을 위해 장전/장후에 빠르게 훑어볼 수 있는 UI가 필요하다. + +## 범위 +- Dashboard 페이지 +- Event Explorer 페이지 +- Korea Theme Board 페이지 +- 불확실성, confidence, risk flag 노출 +- 테마/종목 rationale과 invalidation condition 노출 +- 한국어 중심의 compact typography 정리 + +## 완료 조건 +- 세 페이지가 API와 연결된다 +- 데이터 없을 때와 데이터 있을 때 상태가 모두 정리된다 +- UI가 불확실성을 숨기지 않는다 +- 주요 카드/배지/버튼 스타일이 공통 컴포넌트로 정리된다 +``` + +### Issue 6 + +**Title** +`[v0.4.0] 수집 후 분석 실행 버튼, 작업 상태 표시, 최근 실행 결과 UI 추가` + +**Labels** +`type:feature`, `area:ops`, `area:web`, `version:v0.4.0` + +**Body** + +```md +## 배경 +개인 도구라도 매번 터미널에서 수집/분석 작업을 수동 호출하면 사용성이 떨어진다. UI에서 파이프라인을 제어하고 최근 실행 결과를 확인할 수 있어야 한다. + +## 범위 +- ingest / analyze / refresh API 추가 +- run_full_pipeline_job 구현 +- job_runs 저장 구조 추가 +- 작업 중 상태, 최근 실행 결과, 자동 새로고침 UI 추가 +- 최근 실행 결과는 최대 2개만 표시하도록 제한 + +## 완료 조건 +- 웹에서 버튼 클릭으로 파이프라인 실행이 가능하다 +- 작업 상태가 queued/running/completed/failed 로 기록된다 +- 최근 실행 결과가 과도하게 쌓이지 않고 compact 하게 보인다 +- 워커 실행 전제와 실패 메시지가 분명하게 드러난다 +``` + +### Issue 7 + +**Title** +`[v0.4.0] 파이프라인 신뢰성 보강 및 외부 소스 실패 격리` + +**Labels** +`type:bug`, `type:hardening`, `area:ingestion`, `version:v0.4.0` + +**Body** + +```md +## 배경 +외부 소스 URL 변경이나 공급자 응답 형태 변화로 전체 파이프라인이 깨지면 실사용성이 떨어진다. + +## 범위 +- Treasury 소스 404 대응 +- 단일 소스 실패 시 전체 파이프라인이 중단되지 않도록 격리 +- yfinance 반환 형태 방어 +- 안정적인 dedupe key 보강 +- 회귀 테스트 추가 + +## 완료 조건 +- 특정 소스 실패가 전체 작업 실패로 곧바로 이어지지 않는다 +- `수집 후 분석 실행` 경로가 반복 실행돼도 치명 오류 없이 완료된다 +- 관련 회귀 테스트가 추가된다 +``` + +### Issue 8 + +**Title** +`[v0.5.0] 최근 7거래일 리플레이 및 실제 한국장 반응 비교 페이지 구현` + +**Labels** +`type:feature`, `area:replay`, `area:evaluation`, `version:v0.5.0` + +**Body** + +```md +## 배경 +현재 추론 과정이 과거 구간에서 실제로 어떤 결과를 냈는지 검증할 수 있어야 신뢰할 수 있다. + +## 범위 +- 최근 7거래일 리플레이 생성 +- 각 날짜 장전 시점 이전 정보만 사용하도록 time cutoff 적용 +- 미국 뉴스/시장 반응을 같은 로직으로 재분석 +- 실제 한국 주도주/2등주 시가 갭, 종가 수익률, 장중 움직임 계산 +- hit day, 평균 leader 수익률 등 집계 표시 +- 리플레이 전용 응답 스키마/API/페이지 구현 + +## 완료 조건 +- 더미 데이터가 아닌 실제 기사/시장 데이터 기반으로 7일치가 채워진다 +- look-ahead bias가 없다 +- 리플레이 화면에서 evidence source/link 와 실제 반응을 같이 볼 수 있다 +- 관련 테스트가 포함된다 +``` + +### Issue 9 + +**Title** +`[v0.5.0] 평가 센터와 프롬프트/모델 변경 게이팅 규칙 보강` + +**Labels** +`type:feature`, `area:eval`, `area:llm`, `version:v0.5.0` + +**Body** + +```md +## 배경 +프롬프트/모델/라우팅은 자동으로 바뀌면 안 되고, 롤링 OOS 검증을 통과한 뒤 수동 승인되어야 한다. + +## 범위 +- prediction artifact 저장 필드 점검 +- prompt version / model role-version / evidence hash 저장 강화 +- eval 결과와 promoted configuration 분리 저장 +- rolling out-of-sample 비교 뷰 설계 +- false positive / confusion by regime 분석 보강 + +## 완료 조건 +- 예측 산출물에 감사 추적 필드가 모두 들어간다 +- production prompt self-modification이 불가능하다 +- 승인 전 검증 규칙이 문서와 UI에 드러난다 +``` + +### Issue 10 + +**Title** +`[v0.6.0] AWS/OCI 배포 패키지 및 운영 문서 작성` + +**Labels** +`type:feature`, `area:deploy`, `version:v0.6.0` + +**Body** + +```md +## 배경 +개인용 실서비스로 사용하려면 로컬 개발 환경을 넘어 클라우드 배포 구조와 운영 문서가 필요하다. + +## 범위 +- production env example 분리 +- web/api/worker 컨테이너 분리 실행 전략 문서화 +- AWS ECS/Fargate + RDS + ElastiCache + ALB 배포 문서 +- OCI Compute/Container 기반 배포 문서 +- 스케줄러, 로깅, 시크릿, 헬스체크 전략 정리 + +## 완료 조건 +- 최소 1개 클라우드 타깃에 대해 재현 가능한 배포 절차가 있다 +- worker와 scheduler 운영 방식이 문서화된다 +- production 환경 변수와 시크릿 관리 정책이 포함된다 +``` + +## Pull Request Drafts + +### PR 1 + +**Title** +`feat: bootstrap finance-helper monorepo and local runtime` + +**Branch** +`codex/v0.1-bootstrap-platform` + +**Body** + +```md +## 요약 +- Next.js 웹, FastAPI API, arq 워커 기반의 모노레포를 초기 구성했습니다 +- PostgreSQL/Redis/Docker Compose 기반 로컬 개발 환경을 추가했습니다 +- README, 아키텍처, DB/API, 평가 문서와 AGENTS.md를 작성했습니다 + +## 포함 이슈 +- Closes #1 + +## 주요 변경 +- monorepo 구조 생성 +- web/api/contracts 패키지 추가 +- Docker Compose 및 환경변수 예시 추가 +- 초기 문서 및 실행 가이드 작성 + +## 검증 +- [ ] 로컬 개발 서버 실행 확인 +- [ ] 시드 실행 확인 +- [ ] 문서 링크 검토 +``` + +### PR 2 + +**Title** +`feat: add us ingestion pipeline, event clustering, and market reaction engine` + +**Branch** +`codex/v0.2-ingestion-reaction` + +**Body** + +```md +## 요약 +- 미국 공식/시장 데이터 수집 커넥터와 이벤트 정규화 엔진을 추가했습니다 +- 미국 시장 반응 엔진과 교차자산 확인 로직을 추가했습니다 +- scoring 및 reaction 회귀 테스트를 보강했습니다 + +## 포함 이슈 +- Closes #2 +- Closes #3 + +## 주요 변경 +- ingestion connectors 추가 및 소스 메타데이터 저장 +- event clustering / novelty / directness / surprise / persistence scoring 구현 +- 지수/섹터 ETF/종목/교차자산 반응 계산 추가 +- yfinance 예외 케이스 방어 로직 추가 + +## 검증 +- [ ] pytest 통과 +- [ ] 수집 작업 후 이벤트/반응 데이터 생성 확인 +``` + +### PR 3 + +**Title** +`feat: translate validated us events into korea themes and leader candidates` + +**Branch** +`codex/v0.3-korea-theme-board` + +**Body** + +```md +## 요약 +- 미국 이벤트를 한국 테마/주도주/2등주 후보로 번역하는 엔진을 추가했습니다 +- Dashboard, Event Explorer, Korea Theme Board를 연결했습니다 +- 불확실성, 리스크 플래그, invalidation condition을 UI에 반영했습니다 + +## 포함 이슈 +- Closes #4 +- Closes #5 + +## 주요 변경 +- KoreaTranslationEngine 및 theme merge/dedupe 로직 추가 +- prediction runs / theme predictions / stock candidates 저장 +- dashboard/theme board API 및 화면 연결 + +## 검증 +- [ ] theme dedupe 테스트 통과 +- [ ] 대시보드에서 최신 예측 결과 확인 +``` + +### PR 4 + +**Title** +`feat: add pipeline controls, job status panels, and reliability hardening` + +**Branch** +`codex/v0.4-pipeline-ops-hardening` + +**Body** + +```md +## 요약 +- 웹에서 수집 후 분석 실행을 제어할 수 있는 버튼과 최근 실행 결과 패널을 추가했습니다 +- 외부 소스 실패 격리, dedupe 안정화, 파이프라인 회귀 버그를 수정했습니다 +- UI를 더 compact 하고 일관된 rounded style로 정리했습니다 + +## 포함 이슈 +- Closes #6 +- Closes #7 + +## 주요 변경 +- refresh job / job_runs / recent jobs API 추가 +- 최근 실행 결과 2개 제한 +- Treasury 404 대응 및 source failure 격리 +- Series/float 변환 오류 방어 및 회귀 테스트 추가 +- 버튼/배지/패널 라운딩 일관화 + +## 검증 +- [ ] 수집 후 분석 실행 완료 확인 +- [ ] 최근 실행 결과 UI 확인 +- [ ] pytest 및 tsc 통과 +``` + +### PR 5 + +**Title** +`feat: add weekly replay with real us evidence and korea market outcomes` + +**Branch** +`codex/v0.5-weekly-replay` + +**Body** + +```md +## 요약 +- 최근 7거래일을 동일 추론 로직으로 재분석하는 weekly replay를 추가했습니다 +- 실제 미국 기사 근거와 실제 한국장 반응을 함께 비교할 수 있게 했습니다 +- look-ahead bias 방지용 cutoff와 관련 테스트를 보강했습니다 + +## 포함 이슈 +- Closes #8 +- Closes #9 + +## 주요 변경 +- weekly replay service / API / frontend page 추가 +- Reuters/CNBC/MarketWatch 기반 evidence source 표시 +- 한국 종목/지수 실제 움직임 계산 +- aggregate metrics 및 리플레이 UI 추가 +- scoring false positive 감소 + +## 검증 +- [ ] pytest 통과 +- [ ] replay API 응답에 최근 7거래일 데이터 확인 +- [ ] 리플레이 페이지에서 실제 근거 링크/종목 반응 확인 +``` + +### PR 6 + +**Title** +`docs: add production deployment plans for aws and oci` + +**Branch** +`codex/v0.6-deployment-docs` + +**Body** + +```md +## 요약 +- AWS와 OCI 대상 운영 배포 구조와 절차를 문서화했습니다 +- web/api/worker 분리 배포, DB/Redis 관리형 서비스, 스케줄링/시크릿/로깅 전략을 정리했습니다 + +## 포함 이슈 +- Closes #10 + +## 주요 변경 +- production env example 추가 +- AWS ECS/Fargate 배포 문서 추가 +- OCI Compute 또는 Container 기반 배포 문서 추가 +- 운영 체크리스트와 리스크 노트 정리 + +## 검증 +- [ ] 환경변수/헬스체크/스케줄링 문서 검토 +- [ ] 대상 클라우드 기준 재현 가능성 점검 +``` + +## 권장 업로드 순서 + +1. Issue 1, 2, 3 생성 +2. PR 1, PR 2 업로드 +3. Issue 4, 5, 6, 7 생성 +4. PR 3, PR 4 업로드 +5. Issue 8, 9 생성 +6. PR 5 업로드 +7. Issue 10 생성 +8. PR 6 업로드 + +## 메모 + +- 현재 로컬 작업은 아직 큰 단일 변경 세트에 가깝다. +- 실제 Git 히스토리를 깔끔하게 맞추려면 위 PR 단위에 맞게 커밋/브랜치를 다시 나누는 편이 좋다. +- 이슈 번호는 실제 생성 순서에 따라 본문의 `Closes #...`를 맞춰서 바꾸면 된다.