# 安装问题解决指南

## 问题：Python 3.13 兼容性问题

如果您在安装依赖时遇到 numpy/pandas 编译错误，这是因为 Python 3.13 是最新版本，部分科学计算库还未完全适配。

### 错误信息示例
```
fatal error: 'type_traits' file not found
ERROR: Failed to build 'pandas' when installing build dependencies
```

## 解决方案

### 方案1：使用 Python 3.11 或 3.12（强烈推荐）

这是最简单可靠的方法。

#### macOS (使用 Homebrew)

```bash
# 1. 安装 Python 3.11
brew install python@3.11

# 2. 进入项目目录
cd /Users/aaron/source_code/Stock_Agent/backend

# 3. 删除旧的虚拟环境（如果存在）
rm -rf venv

# 4. 使用 Python 3.11 创建新的虚拟环境
python3.11 -m venv venv

# 5. 激活虚拟环境
source venv/bin/activate

# 6. 升级 pip
pip install --upgrade pip

# 7. 安装依赖
pip install -r requirements.txt
```

#### Linux (Ubuntu/Debian)

```bash
# 1. 安装 Python 3.11
sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-dev

# 2. 创建虚拟环境
python3.11 -m venv venv
source venv/bin/activate

# 3. 安装依赖
pip install --upgrade pip
pip install -r requirements.txt
```

#### Windows

```powershell
# 1. 从 python.org 下载并安装 Python 3.11
# https://www.python.org/downloads/

# 2. 创建虚拟环境
py -3.11 -m venv venv

# 3. 激活虚拟环境
venv\Scripts\activate

# 4. 安装依赖
pip install --upgrade pip
pip install -r requirements.txt
```

### 方案2：使用预编译的 wheel 包（Python 3.13）

如果必须使用 Python 3.13，可以尝试安装预编译的包：

```bash
# 激活虚拟环境
source venv/bin/activate  # macOS/Linux
# 或
venv\Scripts\activate  # Windows

# 先单独安装 numpy 和 pandas
pip install --upgrade pip
pip install numpy --only-binary :all:
pip install pandas --only-binary :all:

# 然后安装其他依赖
pip install -r requirements.txt
```

### 方案3：使用 Conda（推荐用于数据科学项目）

Conda 提供预编译的包，避免编译问题：

```bash
# 1. 安装 Miniconda 或 Anaconda
# https://docs.conda.io/en/latest/miniconda.html

# 2. 创建环境
conda create -n stock_agent python=3.11

# 3. 激活环境
conda activate stock_agent

# 4. 安装依赖
pip install -r requirements.txt
```

## 验证安装

安装完成后，验证是否成功：

```bash
# 检查 Python 版本
python --version
# 应该显示 Python 3.11.x 或 3.12.x

# 检查关键包
python -c "import numpy; print('numpy:', numpy.__version__)"
python -c "import pandas; print('pandas:', pandas.__version__)"
python -c "import fastapi; print('fastapi:', fastapi.__version__)"
python -c "import tushare; print('tushare:', tushare.__version__)"
```

## 启动应用

安装成功后，按以下步骤启动：

```bash
# 1. 确保在虚拟环境中
source venv/bin/activate  # macOS/Linux
# 或
venv\Scripts\activate  # Windows

# 2. 配置环境变量
cd /Users/aaron/source_code/Stock_Agent
cp .env.example .env
# 编辑 .env 文件，填写 API 密钥

# 3. 启动应用
cd backend
python -m app.main
```

## 常见问题

### Q1: 如何检查当前 Python 版本？

```bash
python --version
python3 --version
python3.11 --version
```

### Q2: 如何切换 Python 版本？

macOS/Linux:
```bash
# 使用特定版本创建虚拟环境
python3.11 -m venv venv
```

Windows:
```powershell
py -3.11 -m venv venv
```

### Q3: 虚拟环境激活失败？

确保在正确的目录：
```bash
cd /Users/aaron/source_code/Stock_Agent/backend
ls venv  # 应该能看到 bin 或 Scripts 目录
```

### Q4: pip 安装很慢？

使用国内镜像源：
```bash
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### Q5: 权限错误？

不要使用 sudo，确保在虚拟环境中：
```bash
which python  # 应该显示虚拟环境路径
```

## 推荐的完整安装流程

```bash
# 1. 安装 Python 3.11
brew install python@3.11  # macOS

# 2. 进入项目目录
cd /Users/aaron/source_code/Stock_Agent

# 3. 创建虚拟环境
python3.11 -m venv backend/venv

# 4. 激活虚拟环境
source backend/venv/bin/activate

# 5. 升级 pip
pip install --upgrade pip setuptools wheel

# 6. 安装依赖
cd backend
pip install -r requirements.txt

# 7. 配置环境变量
cd ..
cp .env.example .env
nano .env  # 或使用其他编辑器

# 8. 启动应用
cd backend
python -m app.main
```

## 获取帮助

如果仍然遇到问题：

1. 检查 Python 版本：`python --version`
2. 检查虚拟环境：`which python`
3. 查看完整错误信息
4. 提交 Issue 到项目仓库

## 最小依赖版本

如果遇到版本冲突，可以尝试最小版本：

```txt
fastapi>=0.100.0
uvicorn>=0.23.0
langchain>=0.1.0
tushare>=1.3.0
sqlalchemy>=2.0.0
pydantic>=2.0.0
pandas>=2.0.0
numpy>=1.24.0
```

## 成功标志

当您看到以下输出时，说明安装成功：

```
INFO:     Started server process [xxxxx]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000
```

然后访问 http://localhost:8000 即可使用系统！