docs: sync V2 status and process docs for issue #131

README.md

@@ -1,154 +1,96 @@
 # The Ouroboros — 자가 진화형 AI 투자 시스템
 
-KIS(한국투자증권) API로 매매하고, Google Gemini로 판단하며, 자체 전략 코드를 TDD 기반으로 진화시키는 자율 주식 트레이딩 에이전트.
+KIS API 기반 자동매매 + Gemini 기반 장전 전략 생성 + 장중 로컬 시나리오 실행 + 장후 리뷰/진화 루프를 결합한 시스템입니다.
 
-## 아키텍처
+## 현재 상태 (2026-02-16)
 
-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│  KIS Broker │◄───►│    Main     │◄───►│ Gemini Brain│
-│  (매매 실행) │     │ (거래 루프)  │     │  (의사결정)  │
-└─────────────┘     └──────┬──────┘     └─────────────┘
-                           │
-                    ┌──────┴──────┐
-                    │Risk Manager │
-                    │  (안전장치)  │
-                    └──────┬──────┘
-                           │
-                    ┌──────┴──────┐
-                    │  Evolution  │
-                    │ (전략 진화)  │
-                    └─────────────┘
-```
+- V2 계획 기준 완료: **18/20**
+- 부분 완료: **1/20** (`1-7` 일부 항목)
+- 미완료: **1/20** (`4-1` Telegram 확장 명령어)
 
-## 핵심 모듈
+핵심 전환은 이미 반영되었습니다.
 
-| 모듈 | 파일 | 설명 |
-|------|------|------|
-| 설정 | `src/config.py` | Pydantic 기반 환경변수 로딩 및 타입 검증 |
-| 브로커 | `src/broker/kis_api.py` | KIS API 비동기 래퍼 (토큰 갱신, 레이트 리미터, 해시키) |
-| 두뇌 | `src/brain/gemini_client.py` | Gemini 프롬프트 구성 및 JSON 응답 파싱 |
-| 방패 | `src/core/risk_manager.py` | 서킷 브레이커 + 팻 핑거 체크 |
-| 알림 | `src/notifications/telegram_client.py` | 텔레그램 실시간 거래 알림 (선택사항) |
-| 진화 | `src/evolution/optimizer.py` | 실패 패턴 분석 → 새 전략 생성 → 테스트 → PR |
-| DB | `src/db.py` | SQLite 거래 로그 기록 |
+- 기존: 장중 `brain.decide()` 실시간 의존
+- 현재: 장전 `DayPlaybook` 생성 + 장중 `ScenarioEngine` 로컬 매칭
 
-## 안전장치
+## 핵심 구성
 
-| 규칙 | 내용 |
-|------|------|
-| 서킷 브레이커 | 일일 손실률 -3.0% 초과 시 전체 매매 중단 (`SystemExit`) |
-| 팻 핑거 방지 | 주문 금액이 보유 현금의 30% 초과 시 주문 거부 |
-| 신뢰도 임계값 | Gemini 신뢰도 80 미만이면 강제 HOLD |
-| 레이트 리미터 | Leaky Bucket 알고리즘으로 API 호출 제한 |
-| 토큰 자동 갱신 | 만료 1분 전 자동으로 Access Token 재발급 |
+- `src/main.py`: 시장 루프, 플레이북 생성/적용, EOD 집계, 리뷰/진화 연결
+- `src/strategy/`: `models`, `pre_market_planner`, `scenario_engine`, `playbook_store`
+- `src/context/`: `store`, `aggregator`, `scheduler` (L1~L7)
+- `src/evolution/daily_review.py`: 시장별 scorecard/lessons 생성
+- `src/dashboard/app.py`: FastAPI 관측 API
+- `src/notifications/telegram_client.py`: 알림 및 명령 핸들러
 
-## 빠른 시작
+## 실행
 
-### 1. 환경 설정
-
-```bash
-cp .env.example .env
-# .env 파일에 KIS API 키와 Gemini API 키 입력
-```
-
-### 2. 의존성 설치
-
-```bash
-pip install ".[dev]"
-```
-
-### 3. 테스트 실행
-
-```bash
-pytest -v --cov=src --cov-report=term-missing
-```
-
-### 4. 실행 (모의투자)
+### 기본 실행
 
 ```bash
 python -m src.main --mode=paper
 ```
 
-### 5. Docker 실행
+### 대시보드 포함 실행
 
 ```bash
-docker compose up -d ouroboros
+python -m src.main --mode=paper --dashboard
 ```
 
-## 텔레그램 알림 (선택사항)
+또는 환경변수:
 
-거래 실행, 서킷 브레이커 발동, 시스템 상태 등을 텔레그램으로 실시간 알림 받을 수 있습니다.
+```bash
+DASHBOARD_ENABLED=true
+DASHBOARD_HOST=127.0.0.1
+DASHBOARD_PORT=8080
+```
 
-### 빠른 설정
+## 주요 API/기능
 
-1. **봇 생성**: 텔레그램에서 [@BotFather](https://t.me/BotFather) 메시지 → `/newbot` 명령
-2. **채팅 ID 확인**: [@userinfobot](https://t.me/userinfobot) 메시지 → `/start` 명령
-3. **환경변수 설정**: `.env` 파일에 추가
-   ```bash
-   TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
-   TELEGRAM_CHAT_ID=123456789
-   TELEGRAM_ENABLED=true
-   ```
-4. **테스트**: 봇과 대화 시작 (`/start` 전송) 후 에이전트 실행
+- 플레이북 저장: `playbooks` 테이블 (`date + market` UNIQUE)
+- 의사결정/결과 연결: `trades.decision_id` + `DecisionLogger.update_outcome()`
+- 시장별 scorecard 컨텍스트: `scorecard_KR`, `scorecard_US`
+- 컨텍스트 스케줄러: weekly/monthly/quarterly/annual/legacy + cleanup
+- 대시보드 API:
+- `/api/status`
+- `/api/playbook/{date}?market=KR`
+- `/api/scorecard/{date}?market=KR`
+- `/api/performance?market=all`
+- `/api/context/{layer}`
+- `/api/decisions?market=KR`
+- `/api/scenarios/active?market=US`
 
-**상세 문서**: [src/notifications/README.md](src/notifications/README.md)
+## 현재 갭 (코드 기준)
 
-### 알림 종류
-
-- 🟢 거래 체결 알림 (BUY/SELL + 신뢰도)
-- 🚨 서킷 브레이커 발동 (자동 거래 중단)
-- ⚠️ 팻 핑거 차단 (과도한 주문 차단)
-- ℹ️ 장 시작/종료 알림
-- 📝 시스템 시작/종료 상태
-
-**안전장치**: 알림 실패해도 거래는 계속 진행됩니다. 텔레그램 API 오류나 설정 누락이 있어도 거래 시스템은 정상 작동합니다.
+- `Issue 4-1` 미구현: `/report`, `/scenarios`, `/review`, `/dashboard` Telegram 명령 미등록
+- `Issue 1-7` 일부 미완:
+- `price_change_pct` 정규화 어댑터 명시 구현 없음
+- HOLD 시 별도 손절 모니터링 플래그 처리 분리 미흡
+- 시장 코드 정합성 이슈:
+- 설정 기본값은 `ENABLED_MARKETS="KR,US"`
+- 스케줄 정의는 `US_NASDAQ`, `US_NYSE` 중심
+- 완전 통합 전 추가 정리 필요
 
 ## 테스트
 
-35개 테스트가 TDD 방식으로 구현 전에 먼저 작성되었습니다.
+로컬 수집 기준:
 
-```
-tests/test_risk.py   — 서킷 브레이커, 팻 핑거, 통합 검증 (11개)
-tests/test_broker.py — 토큰 관리, 타임아웃, HTTP 에러, 해시키 (6개)
-tests/test_brain.py  — JSON 파싱, 신뢰도 임계값, 비정상 응답 처리 (15개)
+```bash
+pytest --collect-only -q
+# 538 tests collected
 ```
 
-## 기술 스택
+권장 검증:
 
-- **언어**: Python 3.11+ (asyncio 기반)
-- **브로커**: KIS Open API (REST)
-- **AI**: Google Gemini Pro
-- **DB**: SQLite
-- **검증**: pytest + coverage
-- **CI/CD**: GitHub Actions
-- **배포**: Docker + Docker Compose
-
-## 프로젝트 구조
-
-```
-The-Ouroboros/
-├── .github/workflows/ci.yml     # CI 파이프라인
-├── docs/
-│   ├── agents.md                # AI 에이전트 페르소나 정의
-│   └── skills.md                # 사용 가능한 도구 목록
-├── src/
-│   ├── config.py                      # Pydantic 설정
-│   ├── logging_config.py              # JSON 구조화 로깅
-│   ├── db.py                          # SQLite 거래 기록
-│   ├── main.py                        # 비동기 거래 루프
-│   ├── broker/kis_api.py              # KIS API 클라이언트
-│   ├── brain/gemini_client.py         # Gemini 의사결정 엔진
-│   ├── core/risk_manager.py           # 리스크 관리
-│   ├── notifications/telegram_client.py # 텔레그램 알림
-│   ├── evolution/optimizer.py         # 전략 진화 엔진
-│   └── strategies/base.py             # 전략 베이스 클래스
-├── tests/                       # TDD 테스트 스위트
-├── Dockerfile                   # 멀티스테이지 빌드
-├── docker-compose.yml           # 서비스 오케스트레이션
-└── pyproject.toml               # 의존성 및 도구 설정
+```bash
+pytest -v --cov=src
+ruff check src/ tests/
+mypy src/ --strict
 ```
 
-## 라이선스
+## 문서
 
-이 프로젝트의 라이선스는 [LICENSE](LICENSE) 파일을 참조하세요.
+- 아키텍처: `docs/architecture.md`
+- 컨텍스트 트리: `docs/context-tree.md`
+- 워크플로우: `docs/workflow.md`
+- 요구사항 로그: `docs/requirements-log.md`
+- 명령 레퍼런스: `docs/commands.md`