# Debug功能快速总结

## ✅ 已完成的工作

### 1. 核心组件

| 组件 | 状态 | 说明 |
|------|------|------|
| `debug_utils.py` | ✅ | Debug工具库（369行） |
| `offline_config.py` | ✅ | 新增DEBUG_CONFIG |
| `i2i_swing.py` | ✅ | 完整debug支持 |
| `run_all.py` | ✅ | 支持--debug参数传递 |

### 2. Debug功能特性

#### A. 详细日志输出
```python
# 自动记录：
- 算法参数
- 数据统计（行数、列数、类型、缺失值）
- 处理进度（每N条显示）
- 每个步骤的耗时
- 数据分布（行为类型、用户数、商品数）
- 中间结果采样
```

#### B. 明文索引文件
```
原始: 12345\t香蕉干\t67890:0.8567,11223:0.7234
明文: [1] i2i:swing:12345(香蕉干)
        1. ID:67890(芒果干) - Score:0.8567
        2. ID:11223(菠萝干) - Score:0.7234
```

#### C. 日志文件
```
offline_tasks/logs/debug/i2i_swing_20251016_193000.log
offline_tasks/output/debug/i2i_swing_20251016_readable.txt
```

## 🚀 使用方法

### 单个脚本
```bash
# i2i_swing.py 已支持debug
python3 scripts/i2i_swing.py --lookback_days 7 --top_n 10 --debug
```

### 所有任务
```bash
# run_all.py 已支持debug参数传递
python3 run_all.py --lookback_days 7 --top_n 10 --debug
```

## 📊 输出示例

### 控制台输出
```
2025-10-16 19:30:00 - i2i_swing - DEBUG - ============================================================
2025-10-16 19:30:00 - i2i_swing - DEBUG - 算法参数:
2025-10-16 19:30:00 - i2i_swing - DEBUG -   alpha: 0.5
2025-10-16 19:30:00 - i2i_swing - DEBUG -   top_n: 10
2025-10-16 19:30:05 - i2i_swing - INFO - 获取到 15234 条记录
2025-10-16 19:30:05 - i2i_swing - DEBUG - 总行数: 15234
2025-10-16 19:30:05 - i2i_swing - DEBUG - 行为类型分布:
2025-10-16 19:30:05 - i2i_swing - DEBUG -   addToCart: 8520 (55.93%)
2025-10-16 19:30:10 - i2i_swing - INFO - 总用户数: 3456, 总商品数: 2345
```

### 明文文件示例
```
================================================================================
明文索引文件
生成时间: 2025-10-16 19:35:00
描述: Swing算法 i2i相似度推荐 (alpha=0.5, lookback_days=7)
总索引数: 2345
================================================================================

[1] i2i:swing:12345(香蕉干)
--------------------------------------------------------------------------------
  1. ID:67890(芒果干) - Score:0.8567
  2. ID:11223(菠萝干) - Score:0.7234
  3. ID:44556(苹果干) - Score:0.6891
```

## 🔧 Debug工具函数

| 函数 | 功能 |
|------|------|
| `setup_debug_logger()` | 设置debug日志 |
| `log_dataframe_info()` | 记录DataFrame详情 |
| `log_dict_stats()` | 记录字典统计 |
| `save_readable_index()` | 保存明文索引 |
| `fetch_name_mappings()` | 获取ID到名称映射 |
| `log_algorithm_params()` | 记录算法参数 |
| `log_processing_step()` | 记录处理步骤 |

## 📝 待完成

需要为以下脚本添加debug支持（使用相同模式）：
- [ ] i2i_session_w2v.py
- [ ] i2i_deepwalk.py
- [ ] i2i_content_similar.py
- [ ] interest_aggregation.py

## 💡 快速测试

```bash
# 1. 测试debug工具
cd /home/tw/recommendation/offline_tasks
python3 -c "from scripts.debug_utils import *; print('✓ Debug utils OK')"

# 2. 测试i2i_swing debug模式
python3 scripts/i2i_swing.py --lookback_days 1 --top_n 5 --debug

# 3. 查看输出
ls -lh logs/debug/
ls -lh output/debug/
```

## 📖 完整文档

详细使用指南：`DEBUG_GUIDE.md`

---

**状态**: 🚧 进行中 (i2i_swing.py完成，其他脚本待更新)  
**下一步**: 批量更新其他4个脚本的debug支持