# 外部API集成文档

## 概述

本系统集成了多个外部API服务，用于获取股票数据和进行AI分析：

- **Tushare API**: 中国股票财务数据和市场数据
- **Yahoo Finance API**: 全球股票数据（美国、香港、日本等）
- **Google Gemini API**: AI分析和内容生成

## 架构设计

### 数据源管理器 (DataSourceManager)
- 统一管理所有数据源
- 支持数据源切换和故障转移
- 提供健康检查和状态监控

### 外部API服务 (ExternalAPIService)
- 提供统一的API接口
- 处理错误和重试机制
- 支持配置动态更新

## 支持的数据源

### 1. Tushare API
- **用途**: 中国股票数据（A股、港股通等）
- **数据类型**: 财务数据、市场数据、基本信息
- **配置要求**: 需要Tushare API Token
- **限制**: 有调用频率限制，需要付费账户获取完整数据

#### 配置示例
```python
{
    "tushare": {
        "enabled": True,
        "api_key": "your_tushare_token",
        "base_url": "http://api.tushare.pro",
        "timeout": 30,
        "max_retries": 3,
        "retry_delay": 1
    }
}
```

### 2. Yahoo Finance API
- **用途**: 全球股票数据
- **数据类型**: 财务数据、市场数据、基本信息
- **配置要求**: 无需API密钥
- **限制**: 有调用频率限制，可能被反爬虫机制阻止

#### 配置示例
```python
{
    "yahoo": {
        "enabled": True,
        "base_url": "https://query1.finance.yahoo.com",
        "timeout": 30,
        "max_retries": 3,
        "retry_delay": 1
    }
}
```

### 3. Google Gemini API
- **用途**: AI分析和内容生成
- **功能**: 业务分析、基本面分析、投资建议等
- **配置要求**: 需要Google Cloud API密钥
- **限制**: 有调用频率和配额限制

#### 配置示例
```python
{
    "gemini": {
        "enabled": True,
        "api_key": "your_gemini_api_key",
        "model": "gemini-pro",
        "timeout": 60,
        "max_retries": 3,
        "retry_delay": 2,
        "temperature": 0.7,
        "max_output_tokens": 8192
    }
}
```

## 数据源切换逻辑

### 市场映射
系统根据股票市场自动选择合适的数据源：

```python
market_mapping = {
    "china": "tushare",      # 中国A股使用Tushare
    "中国": "tushare",
    "hongkong": "yahoo",     # 香港股票使用Yahoo Finance
    "香港": "yahoo",
    "usa": "yahoo",          # 美国股票使用Yahoo Finance
    "美国": "yahoo",
    "japan": "yahoo",        # 日本股票使用Yahoo Finance
    "日本": "yahoo"
}
```

### 故障转移
当主要数据源不可用时，系统会自动切换到备用数据源：

```python
fallback_sources = {
    "tushare": ["yahoo"],    # Tushare失败时使用Yahoo
    "yahoo": ["tushare"]     # Yahoo失败时使用Tushare
}
```

## 错误处理和重试机制

### 错误类型
- `DataSourceError`: 数据源相关错误
- `AIAnalysisError`: AI分析相关错误
- `AuthenticationError`: 认证失败
- `RateLimitError`: 调用频率超限
- `APIError`: 通用API错误

### 重试策略
- **指数退避**: 重试间隔逐渐增加
- **最大重试次数**: 默认3次
- **超时处理**: 每个请求都有超时限制
- **错误分类**: 不同错误类型采用不同的重试策略

## API使用示例

### 1. 获取财务数据
```python
from app.services.external_api_service import get_external_api_service

service = get_external_api_service()

# 获取平安银行财务数据
financial_data = await service.get_financial_data("000001", "中国")
print(f"数据源: {financial_data.data_source}")
print(f"总资产: {financial_data.balance_sheet.get('total_assets')}")
```

### 2. 验证股票代码
```python
# 验证股票代码是否有效
validation = await service.validate_stock_symbol("AAPL", "美国")
if validation.is_valid:
    print(f"公司名称: {validation.company_name}")
```

### 3. AI分析
```python
# 进行业务信息分析
analysis = await service.analyze_business_info(
    "000001", "中国", financial_data.dict()
)
print(f"分析内容: {analysis.content['company_overview']}")
```

### 4. 检查服务状态
```python
# 检查所有外部服务状态
status = await service.check_all_services_status()
print(f"整体状态: {status.overall_status}")

for source in status.sources:
    print(f"{source.name}: {'可用' if source.is_available else '不可用'}")
```

## 配置管理

### 环境变量
在`.env`文件中配置API密钥：

```bash
# Tushare API Token
TUSHARE_TOKEN=your_tushare_token_here

# Gemini API Key
GEMINI_API_KEY=your_gemini_api_key_here
```

### 动态配置更新
```python
# 更新配置
new_config = {
    "data_sources": {
        "tushare": {
            "enabled": True,
            "api_key": "new_token"
        }
    }
}

service.update_configuration(new_config)
```

## 测试和调试

### 运行测试脚本
```bash
cd backend
python test_external_apis.py
```

### 测试单个数据源
```python
# 测试Tushare连接
result = await service.test_data_source_connection("tushare", {
    "api_key": "your_token",
    "base_url": "http://api.tushare.pro"
})
print(f"连接成功: {result['success']}")
```

### 测试AI服务
```python
# 测试Gemini连接
result = await service.test_ai_service_connection("gemini", {
    "api_key": "your_api_key"
})
print(f"连接成功: {result['success']}")
```

## 性能优化

### 缓存策略
- 财务数据缓存1小时
- 市场数据缓存5分钟
- AI分析结果缓存24小时

### 并发控制
- 限制同时进行的API调用数量
- 使用连接池管理HTTP连接
- 实现请求队列避免频率限制

### 监控和日志
- 记录所有API调用和响应时间
- 监控错误率和成功率
- 设置告警机制

## 故障排除

### 常见问题

1. **Tushare API调用失败**
   - 检查API Token是否正确
   - 确认账户是否有足够的积分
   - 检查网络连接

2. **Gemini API调用失败**
   - 检查API Key是否有效
   - 确认配额是否充足
   - 检查请求格式是否正确

3. **Yahoo Finance被限制**
   - 降低请求频率
   - 使用代理服务器
   - 切换到其他数据源

### 调试技巧
- 启用详细日志记录
- 使用测试脚本验证配置
- 检查网络连接和防火墙设置
- 监控API调用的响应时间和错误率

## 扩展性

### 添加新的数据源
1. 继承`DataFetcher`基类
2. 实现必要的方法
3. 在`DataFetcherFactory`中注册
4. 更新配置文件

### 添加新的AI服务
1. 创建新的分析器类
2. 实现统一的接口
3. 在`AIAnalyzerFactory`中注册
4. 更新配置管理

## 安全考虑

- API密钥加密存储
- 使用HTTPS进行所有外部调用
- 实现访问控制和权限管理
- 定期轮换API密钥
- 监控异常访问模式