# 故障排除指南
  
  ## 常见问题及解决方案
  
  ### 1. 数据库字段错误
  
  #### 问题：
  ```
  pymysql.err.OperationalError: (1105, "errCode = 2, detailMessage = Unknown column 'xxx' in 'xxx'")
  ```
  
  #### 原因：
  数据库表结构与代码中使用的字段名不匹配。
  
  #### 解决方案：
  1. 查看 `DATABASE_SETUP.md` 了解如何配置字段
  2. 修改对应脚本中的SQL查询，使用实际存在的字段名
  3. 如果是分类字段不存在，这些字段是可选的，代码会自动跳过
  
  #### 已修复的字段：
  - ✅ `category_level2_id` 和 `category_level3_id` 现在是可选的
  - ✅ 基础功能不依赖分类字段
  
  ---
  
  ### 2. 连接超时
  
  #### 问题：
  ```
  pymysql.err.OperationalError: (2003, "Can't connect to MySQL server...")
  ```
  
  #### 解决方案：
  1. 检查数据库配置：`config/offline_config.py`
  2. 确认网络连接和防火墙设置
  3. 运行测试：`python3 test_connection.py`
  
  ---
  
  ### 3. 内存不足
  
  #### 问题：
  程序运行时内存占用过高或被杀死。
  
  #### 解决方案：
  1. 减少回溯天数：`--lookback_days 365`（从730改为365）
  2. 减少输出数量：`--top_n 20`（从50改为20）
  3. 先运行单个算法：
     ```bash
     python3 scripts/i2i_session_w2v.py  # 内存占用较小
     ```
  4. 跳过Swing算法（内存占用最大）：
     ```bash
     python3 run_all.py --skip-i2i
     ```
  
  ---
  
  ### 4. 运行时间过长
  
  #### 解决方案：
  1. 减少数据量：`--lookback_days 180`
  2. 只运行特定算法：
     ```bash
     python3 run_all.py --only-w2v
     ```
  3. 考虑使用C++版本的Swing（性能提升10倍）
  
  ---
  
  ### 5. 依赖包安装失败
  
  #### 解决方案：
  ```bash
  # 单独安装失败的包
  pip3 install pandas sqlalchemy pymysql gensim numpy
  
  # 或使用国内镜像
  pip3 install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
  ```
  
  ---
  
  ### 6. Redis连接失败
  
  #### 问题：
  ```
  redis.exceptions.ConnectionError: Error connecting to Redis
  ```
  
  #### 解决方案：
  1. Redis是可选的，只影响索引加载功能
  2. 如果不需要Redis，可以跳过：
     ```bash
     python3 run_all.py  # 只运行离线任务，不加载到Redis
     ```
  3. 如果需要Redis，确认Redis已安装并运行：
     ```bash
     redis-cli ping  # 应该返回 PONG
     ```
  
  ---
  
  ### 7. 输出文件为空
  
  #### 可能原因：
  1. 数据量太少（没有满足最小阈值）
  2. 时间范围内没有数据
  3. SQL查询条件过于严格
  
  #### 解决方案：
  1. 检查日志：`tail -f logs/run_all_*.log`
  2. 调整参数：
     - 增加时间范围：`--lookback_days 1000`
     - 减少阈值：修改配置文件中的 `min_interaction_count`
  3. 检查数据库中是否有数据：
     ```python
     # 运行简单查询测试
     python3 test_connection.py
     ```
  
  ---
  
  ### 8. 权限问题
  
  #### 问题：
  ```
  PermissionError: [Errno 13] Permission denied
  ```
  
  #### 解决方案：
  ```bash
  # 给脚本添加执行权限
  chmod +x install.sh run_all.py
  
  # 确保有写入权限
  chmod 755 output/ logs/
  ```
  
  ---
  
  ### 9. Python版本问题
  
  #### 要求：
  Python 3.7+
  
  #### 检查版本：
  ```bash
  python3 --version
  ```
  
  #### 如果版本过低，需要升级Python
  
  ---
  
  ### 10. 编码问题
  
  #### 问题：
  ```
  UnicodeDecodeError: 'utf-8' codec can't decode byte...
  ```
  
  #### 解决方案：
  确保所有文件使用UTF-8编码，特别是配置文件和输出文件。
  
  ---
  
  ## 调试技巧
  
  ### 1. 查看详细日志
  ```bash
  tail -f logs/run_all_*.log
  ```
  
  ### 2. 运行单个任务（便于调试）
  ```bash
  python3 scripts/i2i_swing.py --lookback_days 30 --top_n 10
  ```
  
  ### 3. 使用较小的数据量测试
  ```bash
  python3 run_all.py --lookback_days 30 --top_n 10
  ```
  
  ### 4. 检查中间结果
  ```bash
  ls -lh output/
  head -n 20 output/i2i_swing_*.txt
  ```
  
  ---
  
  ## 获取支持
  
  如果以上方法都无法解决问题：
  
  1. **查看文档**：
     - `README.md` - 详细说明
     - `DATABASE_SETUP.md` - 数据库配置
     - `QUICKSTART.md` - 快速开始
  
  2. **查看日志**：
     - `logs/` 目录下的所有日志文件
  
  3. **简化测试**：
     - 先运行 `test_connection.py`
     - 再运行单个脚本
     - 使用小数据量测试
  
  4. **记录错误信息**：
     - 完整的错误堆栈
     - 使用的命令
     - 配置文件内容
  
  ---
  
  **提示**：大部分问题都与数据库字段名不匹配有关，请优先查看 `DATABASE_SETUP.md`。