docs: add Telegram notifications documentation (issue #35)

Update project documentation to include Telegram notification feature that was added in issues #31-34. Changes: - CLAUDE.md: Add Telegram quick setup section with examples - README.md (Korean): Add 텔레그램 알림 section with setup guide - docs/architecture.md: Add Notifications component documentation - New section explaining TelegramClient architecture - Add notification step to data flow diagram - Add Telegram config to environment variables - Document error handling for notification failures Documentation covers: - Quick setup instructions (bot creation, chat ID, env config) - Notification types (trades, circuit breaker, fat-finger, etc.) - Fail-safe behavior (notifications never crash trading) - Links to detailed guide in src/notifications/README.md Project structure updated to reflect notifications/ directory and updated test count (273 tests). Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-04 23:48:01 +09:00
parent 5f7d61748b
commit 881bbb4240
3 changed files with 111 additions and 11 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -17,6 +17,34 @@ pytest -v --cov=src
 python -m src.main --mode=paper
 ```

+## Telegram Notifications (Optional)
+
+Get real-time alerts for trades, circuit breakers, and system events via Telegram.
+
+### Quick Setup
+
+1. **Create bot**: Message [@BotFather](https://t.me/BotFather) on Telegram → `/newbot`
+2. **Get chat ID**: Message [@userinfobot](https://t.me/userinfobot) → `/start`
+3. **Configure**: Add to `.env`:
+   ```bash
+   TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
+   TELEGRAM_CHAT_ID=123456789
+   TELEGRAM_ENABLED=true
+   ```
+4. **Test**: Start bot conversation (`/start`), then run the agent
+
+**Full documentation**: [src/notifications/README.md](src/notifications/README.md)
+
+### What You'll Get
+
+- 🟢 Trade execution alerts (BUY/SELL with confidence)
+- 🚨 Circuit breaker trips (automatic trading halt)
+- ⚠️ Fat-finger rejections (oversized orders blocked)
+- ℹ️ Market open/close notifications
+- 📝 System startup/shutdown status
+
+**Fail-safe**: Notifications never crash the trading system. Missing credentials or API errors are logged but trading continues normally.
+
 ## Documentation

 - **[Workflow Guide](docs/workflow.md)** — Git workflow policy and agent-based development
@@ -42,11 +70,12 @@ src/
 ├── core/            # Risk manager (READ-ONLY)
 ├── evolution/       # Self-improvement optimizer
 ├── markets/         # Market schedules and timezone handling
+├── notifications/   # Telegram real-time alerts
 ├── db.py            # SQLite trade logging
 ├── main.py          # Trading loop orchestrator
 └── config.py        # Settings (from .env)

-tests/               # 54 tests across 4 files
+tests/               # 273 tests across 13 files
 docs/                # Extended documentation
 ```

--- a/README.md
+++ b/README.md
@@ -29,6 +29,7 @@ KIS(한국투자증권) API로 매매하고, Google Gemini로 판단하며, 자
 | 브로커 | `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 거래 로그 기록 |

@@ -75,6 +76,34 @@ python -m src.main --mode=paper
 docker compose up -d ouroboros
 ```

+## 텔레그램 알림 (선택사항)
+
+거래 실행, 서킷 브레이커 발동, 시스템 상태 등을 텔레그램으로 실시간 알림 받을 수 있습니다.
+
+### 빠른 설정
+
+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` 전송) 후 에이전트 실행
+
+**상세 문서**: [src/notifications/README.md](src/notifications/README.md)
+
+### 알림 종류
+
+- 🟢 거래 체결 알림 (BUY/SELL + 신뢰도)
+- 🚨 서킷 브레이커 발동 (자동 거래 중단)
+- ⚠️ 팻 핑거 차단 (과도한 주문 차단)
+- ℹ️ 장 시작/종료 알림
+- 📝 시스템 시작/종료 상태
+
+**안전장치**: 알림 실패해도 거래는 계속 진행됩니다. 텔레그램 API 오류나 설정 누락이 있어도 거래 시스템은 정상 작동합니다.
+
 ## 테스트

 35개 테스트가 TDD 방식으로 구현 전에 먼저 작성되었습니다.
@@ -104,15 +133,16 @@ The-Ouroboros/
 │   ├── 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     # 리스크 관리
-│   ├── evolution/optimizer.py   # 전략 진화 엔진
-│   └── strategies/base.py       # 전략 베이스 클래스
+│   ├── 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           # 서비스 오케스트레이션
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -51,7 +51,26 @@ Self-evolving AI trading agent for global stock markets via KIS (Korea Investmen
 - **Fat-Finger Protection**: Rejects orders exceeding 30% of available cash
  - Must always be enforced, cannot be disabled

-### 4. Evolution (`src/evolution/optimizer.py`)
+### 4. Notifications (`src/notifications/telegram_client.py`)
+
+**TelegramClient** — Real-time event notifications via Telegram Bot API
+
+- Sends alerts for trades, circuit breakers, fat-finger rejections, system events
+- Non-blocking: failures are logged but never crash trading
+- Rate-limited: 1 message/second default to respect Telegram API limits
+- Auto-disabled when credentials missing
+- Gracefully handles API errors, network timeouts, invalid tokens
+
+**Notification Types:**
+- Trade execution (BUY/SELL with confidence)
+- Circuit breaker trips (critical alert)
+- Fat-finger protection triggers (order rejection)
+- Market open/close events
+- System startup/shutdown status
+
+**Setup:** See [src/notifications/README.md](../src/notifications/README.md) for bot creation and configuration.
+
+### 5. Evolution (`src/evolution/optimizer.py`)

 **StrategyOptimizer** — Self-improvement loop

@@ -115,6 +134,14 @@ Self-evolving AI trading agent for global stock markets via KIS (Korea Investmen
                           │
                           ▼
        ┌──────────────────────────────────┐
+        │ Notifications: Send Alert         │
+        │ - Trade execution notification    │
+        │ - Non-blocking (errors logged)    │
+        │ - Rate-limited to 1/sec           │
+        └──────────────────┬────────────────┘
+                           │
+                           ▼
+        ┌──────────────────────────────────┐
        │ Database: Log Trade               │
        │ - SQLite (data/trades.db)         │
        │ - Track: action, confidence,      │
@@ -164,6 +191,11 @@ CONFIDENCE_THRESHOLD=80
 MAX_LOSS_PCT=3.0
 MAX_ORDER_PCT=30.0
 ENABLED_MARKETS=KR,US_NASDAQ  # Comma-separated market codes
+
+# Telegram Notifications (optional)
+TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
+TELEGRAM_CHAT_ID=123456789
+TELEGRAM_ENABLED=true
 ```

 Tests use in-memory SQLite (`DB_PATH=":memory:"`) and dummy credentials via `tests/conftest.py`.
@@ -189,3 +221,12 @@ Tests use in-memory SQLite (`DB_PATH=":memory:"`) and dummy credentials via `tes
 - Wait until next market opens
 - Use `get_next_market_open()` to calculate wait time
 - Sleep until market open time
+
+### Telegram API Errors
+- Log warning but continue trading
+- Missing credentials → auto-disable notifications
+- Network timeout → skip notification, no retry
+- Invalid token → log error, trading unaffected
+- Rate limit exceeded → queued via rate limiter
+
+**Guarantee**: Notification failures never interrupt trading operations.