feat: implement TelegramClient core module (issue #31)

Add TelegramClient for real-time trading notifications: - NotificationPriority enum (LOW/MEDIUM/HIGH/CRITICAL) - LeakyBucket rate limiter (1 msg/sec) - 8 notification methods (trade, circuit breaker, fat finger, market open/close, system start/shutdown, errors) - Graceful degradation (optional API, never crashes) - Session management pattern from KISBroker - Comprehensive README with setup guide and troubleshooting Follows NewsAPI pattern for optional APIs. Uses existing aiohttp dependency. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-04 21:29:46 +09:00
parent 87556b145e
commit 73e1d0a54e
3 changed files with 543 additions and 0 deletions
--- a/src/notifications/README.md
+++ b/src/notifications/README.md
@@ -0,0 +1,213 @@
+# Telegram Notifications
+
+Real-time trading event notifications via Telegram Bot API.
+
+## Setup
+
+### 1. Create a Telegram Bot
+
+1. Open Telegram and message [@BotFather](https://t.me/BotFather)
+2. Send `/newbot` command
+3. Follow prompts to name your bot
+4. Save the **bot token** (looks like `1234567890:ABCdefGHIjklMNOpqrsTUVwxyz`)
+
+### 2. Get Your Chat ID
+
+**Option A: Using @userinfobot**
+1. Message [@userinfobot](https://t.me/userinfobot) on Telegram
+2. Send `/start`
+3. Save your numeric **chat ID** (e.g., `123456789`)
+
+**Option B: Using @RawDataBot**
+1. Message [@RawDataBot](https://t.me/rawdatabot) on Telegram
+2. Look for `"id":` in the JSON response
+3. Save your numeric **chat ID**
+
+### 3. Configure Environment
+
+Add to your `.env` file:
+
+```bash
+TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
+TELEGRAM_CHAT_ID=123456789
+TELEGRAM_ENABLED=true
+```
+
+### 4. Test the Bot
+
+Start a conversation with your bot on Telegram first (send `/start`), then run:
+
+```bash
+python -m src.main --mode=paper
+```
+
+You should receive a startup notification.
+
+## Message Examples
+
+### Trade Execution
+```
+🟢 BUY
+Symbol: AAPL (United States)
+Quantity: 10 shares
+Price: 150.25
+Confidence: 85%
+```
+
+### Circuit Breaker
+```
+🚨 CIRCUIT BREAKER TRIPPED
+P&L: -3.15% (threshold: -3.0%)
+Trading halted for safety
+```
+
+### Fat-Finger Protection
+```
+⚠️ Fat-Finger Protection
+Order rejected: TSLA
+Attempted: 45.0% of cash
+Max allowed: 30%
+Amount: 45,000 / 100,000
+```
+
+### Market Open/Close
+```
+ℹ️ Market Open
+Korea trading session started
+
+ℹ️ Market Close
+Korea trading session ended
+📈 P&L: +1.25%
+```
+
+### System Status
+```
+📝 System Started
+Mode: PAPER
+Markets: KRX, NASDAQ
+
+System Shutdown
+Normal shutdown
+```
+
+## Notification Priorities
+
+| Priority | Emoji | Use Case |
+|----------|-------|----------|
+| LOW | ℹ️ | Market open/close |
+| MEDIUM | 📊 | Trade execution, system start/stop |
+| HIGH | ⚠️ | Fat-finger protection, errors |
+| CRITICAL | 🚨 | Circuit breaker trips |
+
+## Rate Limiting
+
+- Default: 1 message per second
+- Prevents hitting Telegram's global rate limits
+- Configurable via `rate_limit` parameter
+
+## Troubleshooting
+
+### No notifications received
+
+1. **Check bot configuration**
+   ```bash
+   # Verify env variables are set
+   grep TELEGRAM .env
+   ```
+
+2. **Start conversation with bot**
+   - Open bot in Telegram
+   - Send `/start` command
+   - Bot cannot message users who haven't started a conversation
+
+3. **Check logs**
+   ```bash
+   # Look for Telegram-related errors
+   python -m src.main --mode=paper 2>&1 | grep -i telegram
+   ```
+
+4. **Verify bot token**
+   ```bash
+   curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe
+   # Should return bot info (not 401 error)
+   ```
+
+5. **Verify chat ID**
+   ```bash
+   curl -X POST https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage \
+     -H 'Content-Type: application/json' \
+     -d '{"chat_id": "<YOUR_CHAT_ID>", "text": "Test"}'
+   # Should send a test message
+   ```
+
+### Notifications delayed
+
+- Check rate limiter settings
+- Verify network connection
+- Look for timeout errors in logs
+
+### "Chat not found" error
+
+- Incorrect chat ID
+- Bot blocked by user
+- Need to send `/start` to bot first
+
+### "Unauthorized" error
+
+- Invalid bot token
+- Token revoked (regenerate with @BotFather)
+
+## Graceful Degradation
+
+The system works without Telegram notifications:
+
+- Missing credentials → notifications disabled automatically
+- API errors → logged but trading continues
+- Network timeouts → trading loop unaffected
+- Rate limiting → messages queued, trading proceeds
+
+**Notifications never crash the trading system.**
+
+## Security Notes
+
+- Never commit `.env` file with credentials
+- Bot token grants full bot control
+- Chat ID is not sensitive (just a number)
+- Messages are sent over HTTPS
+- No trading credentials in notifications
+
+## Advanced Usage
+
+### Group Notifications
+
+1. Add bot to Telegram group
+2. Get group chat ID (negative number like `-123456789`)
+3. Use group chat ID in `TELEGRAM_CHAT_ID`
+
+### Multiple Recipients
+
+Create multiple bots or use a broadcast group with multiple members.
+
+### Custom Rate Limits
+
+Not currently exposed in config, but can be modified in code:
+
+```python
+telegram = TelegramClient(
+    bot_token=settings.TELEGRAM_BOT_TOKEN,
+    chat_id=settings.TELEGRAM_CHAT_ID,
+    rate_limit=2.0,  # 2 messages per second
+)
+```
+
+## API Reference
+
+See `telegram_client.py` for full API documentation.
+
+Key methods:
+- `notify_trade_execution()` - Trade alerts
+- `notify_circuit_breaker()` - Emergency stops
+- `notify_fat_finger()` - Order rejections
+- `notify_market_open/close()` - Session tracking
+- `notify_system_start/shutdown()` - Lifecycle events
+- `notify_error()` - Error alerts