# 故障排查文档

本目录包含 TradingAgents-CN 项目的常见问题排查和解决方案。

## 文档列表

### [批量分析并发执行问题修复](./batch-analysis-concurrent-fix.md) ⭐ **重要**

**问题**：批量分析3个股票时，任务是串行执行的，而不是并发执行。

**根本原因**：FastAPI 的 `BackgroundTasks` 默认是串行执行的！

**解决方案**：
1. **主要修复**：使用 `asyncio.create_task` 代替 `BackgroundTasks` 实现真正的并发
2. **附加修复**：使用共享线程池（`ThreadPoolExecutor(max_workers=3)`）
3. **安全修复**：每次创建新的 `TradingAgentsGraph` 实例，避免数据混淆

**性能提升**：总耗时从12-15分钟降低到5-7分钟，提升约2-3倍。

**关键教训**：FastAPI 的 `BackgroundTasks` 不适合长时间运行的并发任务，应该使用 `asyncio.create_task` 或专业的任务队列（如 Celery）。

**修复文件**：
- `app/services/simple_analysis_service.py`（第446-462行，第848-869行）

---

## 如何使用本文档

1. **遇到问题时**：先在本目录中搜索相关关键词
2. **查看详细文档**：点击文档链接查看完整的问题分析和解决方案
3. **验证修复**：按照文档中的"验证方法"部分检查问题是否解决
4. **贡献文档**：如果遇到新问题并解决了，请添加新的故障排查文档

## 文档模板

创建新的故障排查文档时，请遵循以下结构：

```markdown
# [问题标题]

## 问题描述
- 现象1
- 现象2
- 现象3

## 问题分析
### 根本原因
[详细分析]

### 问题详解
[技术细节]

## 解决方案
### 方案1：[推荐方案]
[代码示例]

### 方案2：[备选方案]
[代码示例]

## 验证方法
### 1. 查看日志
[日志示例]

### 2. 功能测试
[测试步骤]

### 3. 性能对比
[性能数据]

## 相关问题
[相关问题链接]

## 测试用例
[测试代码]

## 总结
[简短总结]
```

## 常见问题快速索引

### 性能问题
- [批量分析顺序执行](./batch-analysis-sequential-issue.md) - 线程池配置问题

### 并发问题
- [批量分析顺序执行](./batch-analysis-sequential-issue.md) - 共享线程池解决方案

### 配置问题
- （待添加）

### 数据库问题
- （待添加）

### API问题
- （待添加）

---

**维护者**：TradingAgents-CN 开发团队  
**最后更新**：2025-01-10

