liurenchaxin/docs/guides/QUICK_START_GUIDE.md

# 🚀 稷下学宫负载均衡系统 - 快速上手指南

## 📋 前置条件

1. **RapidAPI账户**: 确保已订阅以下API服务
   - Alpha Vantage
   - Yahoo Finance 15
   - Webull
   - Seeking Alpha

2. **环境配置**: 已配置Doppler环境变量管理
   ```bash
   doppler secrets | grep RAPIDAPI_KEY
   ```

## ⚡ 5分钟快速体验

### 1. 运行完整演示
```bash
cd /home/ben/liurenchaxin
doppler run python demo_jixia_load_balancing.py
```

### 2. 查看演示结果
```bash
# 查看生成的结果文件
ls demo_results_*.json

# 查看AAPL的详细结果
cat demo_results_aapl.json | jq .
```

## 🎯 核心功能演示

### 单个仙人数据获取
```python
from src.jixia.engines.jixia_load_balancer import JixiaLoadBalancer

# 初始化
load_balancer = JixiaLoadBalancer(rapidapi_key)

# 吕洞宾获取苹果股票数据
result = load_balancer.get_data_for_immortal('吕洞宾', 'stock_quote', 'AAPL')
print(f"价格: ${result.data['price']}, 来源: {result.api_used}")
```

### 八仙论道完整演示
```python
# 进行八仙论道
results = load_balancer.conduct_immortal_debate('TSLA')

# 查看负载分布
distribution = load_balancer.get_load_distribution()
for api, stats in distribution.items():
    print(f"{api}: {stats['calls']}次调用 ({stats['percentage']:.1f}%)")
```

## 📊 预期输出示例

```
🏛️ 稷下学宫八仙论道开始 - 主题: AAPL
============================================================
🎭 吕洞宾 正在获取 stock_quote 数据...
   ✅ 成功从 alpha_vantage 获取数据 (响应时间: 1.33s)
   💰 吕洞宾: $202.38 (-2.5004%) via alpha_vantage

🎭 何仙姑 正在获取 stock_quote 数据...
   ✅ 成功从 yahoo_finance_15 获取数据 (响应时间: 1.87s)
   💰 何仙姑: $N/A (N/A) via yahoo_finance_15

📊 负载分布统计:
   alpha_vantage: 3 次调用 (37.5%) - 健康
   yahoo_finance_15: 2 次调用 (25.0%) - 健康
   webull: 3 次调用 (37.5%) - 健康
```

## 🔧 自定义配置

### 修改仙人API偏好
编辑 `/home/ben/liurenchaxin/src/jixia/config/immortal_api_config.json`:

```json
{
  "immortals": {
    "吕洞宾": {
      "preferred_apis": {
        "stock_quote": "webull",  // 改为使用Webull
        "company_overview": "alpha_vantage"
      }
    }
  }
}
```

### 调整缓存策略
```python
# 修改缓存TTL
load_balancer.cache_ttl = 600  # 10分钟缓存

# 清空缓存
load_balancer.cache.clear()
```

## 🚨 故障排除

### 常见问题

1. **API密钥错误**
   ```
   ❌ 错误: 请设置RAPIDAPI_KEY环境变量
   ```
   **解决**: 确保Doppler配置正确
   ```bash
   doppler secrets set RAPIDAPI_KEY="your_key_here"
   ```

2. **API调用失败**
   ```
   ⚠️ alpha_vantage 不可用，尝试备用API...
   ```
   **解决**: 系统会自动故障转移，无需干预

3. **数据格式异常**
   ```
   💰 价格: $N/A
   ```
   **解决**: 某些API返回格式不同，系统会标准化处理

### 调试模式
```python
# 启用详细日志
import logging
logging.basicConfig(level=logging.DEBUG)

# 查看API健康状态
for api, status in load_balancer.health_checker.health_status.items():
    print(f"{api}: {'健康' if status['healthy'] else '异常'}")
```

## 📈 性能优化建议

### 1. 缓存优化
```python
# 针对不同数据类型设置不同缓存时间
cache_strategies = {
    'stock_quote': 60,      # 1分钟
    'company_overview': 3600, # 1小时
    'market_news': 1800     # 30分钟
}
```

### 2. 并发控制
```python
# 控制并发请求数量
import time
for immortal in immortals:
    result = load_balancer.get_data_for_immortal(immortal, 'stock_quote', symbol)
    time.sleep(0.2)  # 避免过快请求
```

### 3. 批量处理
```python
# 批量获取多个股票数据
symbols = ['AAPL', 'TSLA', 'MSFT', 'GOOGL']
results = {}
for symbol in symbols:
    results[symbol] = load_balancer.conduct_immortal_debate(symbol)
```

## 🎯 最佳实践

### 1. 监控API使用情况
```python
# 定期检查负载分布
distribution = load_balancer.get_load_distribution()
print(f"总调用次数: {sum(stats['calls'] for stats in distribution.values())}")
```

### 2. 合理使用缓存
```python
# 对于实时性要求不高的数据，优先使用缓存
result = load_balancer.get_data_for_immortal('韩湘子', 'company_overview', 'AAPL')
if result.cached:
    print("使用缓存数据，节省API调用")
```

### 3. 错误处理
```python
result = load_balancer.get_data_for_immortal('吕洞宾', 'stock_quote', 'AAPL')
if not result.success:
    print(f"获取数据失败: {result.error}")
    # 实施降级策略
else:
    # 正常处理数据
    process_stock_data(result.data)
```

## 📚 进阶使用

### 自定义数据处理器
```python
class CustomDataNormalizer(DataNormalizer):
    def normalize_stock_quote(self, raw_data, api_source):
        # 自定义数据标准化逻辑
        normalized = super().normalize_stock_quote(raw_data, api_source)
        # 添加自定义字段
        normalized['custom_score'] = self.calculate_score(normalized)
        return normalized

# 使用自定义处理器
load_balancer.data_normalizer = CustomDataNormalizer()
```

### 自定义健康检查
```python
class CustomHealthChecker(APIHealthChecker):
    def _perform_health_check(self, api_name):
        # 自定义健康检查逻辑
        # 例如：检查API响应时间、错误率等
        pass

load_balancer.health_checker = CustomHealthChecker()
```

## 🎉 完成！

现在您已经掌握了稷下学宫负载均衡系统的基本使用方法。

### 下一步
- 📖 阅读完整文档: `README_jixia_load_balancing.md`
- 🔧 查看配置文件: `src/jixia/config/immortal_api_config.json`
- 💻 研究核心代码: `src/jixia/engines/jixia_load_balancer.py`
- 🚀 开始构建您的投资分析系统！

---
*🏛️ 稷下学宫 - 智慧投资，从负载均衡开始*