# 🐛 Debug功能实现总结
  
  ## ✅ 完成情况
  
  ### 已实现 ✓
  
  1. **Debug工具库** (`scripts/debug_utils.py`) - ✅ 完成
     - 369行完整实现
     - 7个核心函数
     - 支持日志、明文输出、数据统计
  
  2. **配置更新** (`config/offline_config.py`) - ✅ 完成
     - 新增DEBUG_CONFIG配置段
     - 默认参数配置（DEFAULT_LOOKBACK_DAYS=30）
  
  3. **i2i_swing.py** - ✅ 完成
     - 完整debug日志
     - 明文索引输出
     - --debug参数支持
  
  4. **run_all.py** - ✅ 完成
     - 支持--debug参数
     - 自动传递给所有子脚本
  
  5. **文档** - ✅ 完成
     - DEBUG_GUIDE.md (完整使用指南)
     - QUICK_DEBUG_SUMMARY.md (快速总结)
     - UPDATE_CONFIG_GUIDE.md (配置调整指南)
  
  ### 待实现（可选）
  
  其他4个脚本可以按需添加debug支持：
  - i2i_session_w2v.py
  - i2i_deepwalk.py  
  - i2i_content_similar.py
  - interest_aggregation.py
  
  **实现模式**：与i2i_swing.py相同，只需：
  1. 导入debug_utils
  2. 添加--debug参数
  3. 调用log函数记录关键信息
  4. 生成明文文件
  
  ## 🎯 核心功能
  
  ### 1. 详细日志
  
  ```python
  # 自动记录的信息：
  ✓ 算法参数（alpha, top_n, lookback_days等）
  ✓ SQL查询和数据获取（行数、时间范围）
  ✓ DataFrame详情（列名、类型、缺失值、统计）
  ✓ 行为类型分布（百分比）
  ✓ 用户/商品数量统计
  ✓ 处理进度（每N条/每N个商品）
  ✓ 中间结果采样（Top3展示）
  ✓ 每个步骤耗时
  ✓ 相似度分布统计（min/max/avg）
  ```
  
  ### 2. 明文索引
  
  ```
  ID全部带名称，格式清晰：
  
  [1] i2i:swing:12345(香蕉干)
  --------------------------------------------------------------------------------
    1. ID:67890(芒果干) - Score:0.8567
    2. ID:11223(菠萝干) - Score:0.7234
    3. ID:44556(苹果干) - Score:0.6891
  
  [2] interest:hot:category_level2:200(水果类)
  --------------------------------------------------------------------------------
    1. ID:12345(香蕉干)
    2. ID:67890(芒果干)
    3. ID:11223(菠萝干)
  ```
  
  ### 3. 名称映射
  
  自动从数据库获取：
  - 商品名称 (prd_goods_sku.name)
  - 分类名称 (prd_category.name)
  - 供应商名称 (sup_supplier.name)
  - 平台名称（硬编码映射）
  
  ## 📊 使用示例
  
  ### 基础使用
  
  ```bash
  # 单个脚本debug
  python3 scripts/i2i_swing.py --lookback_days 7 --top_n 10 --debug
  
  # 所有任务debug
  python3 run_all.py --lookback_days 7 --top_n 10 --debug
  ```
  
  ### 输出位置
  
  ```
  offline_tasks/
  ├── logs/debug/
  │   └── i2i_swing_20251016_193000.log    # 详细日志
  └── output/debug/
      └── i2i_swing_20251016_readable.txt  # 明文索引
  ```
  
  ### 查看输出
  
  ```bash
  # 实时查看日志
  tail -f logs/debug/i2i_swing_*.log
  
  # 查看明文索引
  less output/debug/i2i_swing_*_readable.txt
  
  # 搜索特定商品
  grep "香蕉干" output/debug/*_readable.txt -A 5
  ```
  
  ## 🔧 技术实现
  
  ### Debug Logger
  
  ```python
  from offline_tasks.scripts.debug_utils import setup_debug_logger
  
  # 自动设置：
  logger = setup_debug_logger('script_name', debug=True)
  # - DEBUG级别
  # - 控制台 + 文件双输出
  # - 彩色格式化
  ```
  
  ### 数据统计
  
  ```python
  from offline_tasks.scripts.debug_utils import log_dataframe_info
  
  # 自动记录：
  log_dataframe_info(logger, df, "数据名称", sample_size=10)
  # - 行列数
  # - 数据类型
  # - 缺失值
  # - 采样数据
  # - 数值统计
  ```
  
  ### 明文输出
  
  ```python
  from offline_tasks.scripts.debug_utils import (
      save_readable_index, fetch_name_mappings
  )
  
  # 获取名称映射
  name_mappings = fetch_name_mappings(engine, debug=True)
  
  # 保存明文文件
  readable_file = save_readable_index(
      output_file,
      index_data,
      name_mappings,
      description="算法描述"
  )
  ```
  
  ## 💡 使用建议
  
  ### 开发阶段
  ```bash
  # 小数据量 + debug
  python3 run_all.py --lookback_days 3 --top_n 10 --debug
  ```
  ✓ 快速验证  
  ✓ 详细排错  
  ✓ 检查效果
  
  ### 调优阶段
  ```bash
  # 中等数据量 + debug
  python3 scripts/i2i_swing.py --lookback_days 30 --top_n 50 --debug
  ```
  ✓ 查看分布  
  ✓ 评估质量  
  ✓ 调整参数
  
  ### 生产阶段
  ```bash
  # 大数据量 + 正常模式
  python3 run_all.py --lookback_days 730 --top_n 50
  ```
  ✓ 高效运行  
  ✓ 必要日志  
  ✓ 节省空间
  
  ## 📈 性能影响
  
  | 模式 | 运行时间 | 磁盘占用 | 日志详细度 |
  |------|---------|---------|-----------|
  | 正常 | 基准 | 基准 | INFO |
  | Debug | +10-20% | +50MB-500MB | DEBUG |
  
  **建议**：
  - 开发/调试：始终使用debug
  - 生产环境：关闭debug
  - 定期清理：`rm -rf logs/debug/* output/debug/*`
  
  ## 🎉 主要优势
  
  1. **数据可见** - 看清楚每一步的数据流向
  2. **效果可查** - 明文文件直接检查推荐质量  
  3. **性能可测** - 每个步骤的耗时统计
  4. **问题可追** - 详细日志快速定位错误
  5. **参数可调** - 对比不同参数的效果
  
  ## 📚 相关文档
  
  1. **DEBUG_GUIDE.md** - 完整使用指南（200+行）
  2. **QUICK_DEBUG_SUMMARY.md** - 快速参考
  3. **UPDATE_CONFIG_GUIDE.md** - 配置调整指南
  4. **scripts/debug_utils.py** - 源代码和注释
  
  ## ✨ 下一步（可选）
  
  如需为其他脚本添加debug支持，参考i2i_swing.py的模式：
  
  ```python
  # 1. 导入
  from offline_tasks.scripts.debug_utils import (
      setup_debug_logger, log_dataframe_info, ...
  )
  
  # 2. 添加参数
  parser.add_argument('--debug', action='store_true')
  
  # 3. 设置logger
  logger = setup_debug_logger('script_name', debug=args.debug)
  
  # 4. 记录信息
  log_algorithm_params(logger, params)
  log_dataframe_info(logger, df, "名称")
  
  # 5. 生成明文
  if args.debug:
      name_mappings = fetch_name_mappings(engine, debug=True)
      save_readable_index(output_file, index_data, name_mappings)
  ```
  
  ---
  
  **状态**: ✅ 核心功能已完成  
  **当前**: i2i_swing.py + run_all.py完整支持  
  **扩展**: 其他脚本可按需添加（模式已建立）