# 项目重构说明 - 2024-10-17
  
  ## ✅ 完成的重构
  
  ### 1. 目录结构调整
  
  **改动**: 将`collaboration`目录移入`offline_tasks`
  
  **之前**:
  ```
  recommendation/
  ├── offline_tasks/
  │   ├── scripts/
  │   └── ...
  └── collaboration/          # 外层目录
      ├── src/
      └── run.sh
  ```
  
  **之后**:
  ```
  recommendation/
  └── offline_tasks/
      ├── scripts/
      ├── collaboration/      # 移入内部
      │   ├── src/
      │   └── run.sh
      └── ...
  ```
  
  **优势**:
  - ✅ 统一目录结构，所有离线任务在同一目录
  - ✅ 简化路径配置
  - ✅ 便于统一管理和部署
  
  ---
  
  ### 2. 执行脚本简化
  
  **改动**: 主执行脚本从`run_all.py`改为`run.sh`，直接调用各个脚本
  
  **之前的流程**:
  ```python
  # run_all.py (Python实现)
  run_script('fetch_item_attributes.py')
  run_script('generate_session.py')
  run_cpp_swing()  # 调用collaboration/run.sh
  run_script('i2i_swing.py')
  # ...
  ```
  
  **现在的流程**:
  ```bash
  # run.sh (Shell实现)
  python3 scripts/fetch_item_attributes.py
  python3 scripts/generate_session.py
  cd collaboration && bash run.sh && cd ..
  python3 scripts/i2i_swing.py
  # ...
  ```
  
  **优势**:
  - ✅ 代码更简洁，减少抽象层
  - ✅ 直接调用，易于理解和调试
  - ✅ 内存监控、错误处理更灵活
  - ✅ 配置参数集中在顶部，便于修改
  
  ---
  
  ### 3. 路径更新
  
  所有相关路径已更新：
  
  **collaboration/run.sh**:
  - `SESSION_DATA_DIR="../offline_tasks/output"` → `"../output"`
  - `DEBUG_SCRIPT="../offline_tasks/scripts/..."` → `"../scripts/..."`
  
  **文档更新**:
  - ✅ `README.md`
  - ✅ `doc/离线索引数据规范.md`
  - ✅ `doc/Redis数据规范.md`
  - ✅ `doc/系统改进总结-20241017.md`
  
  ---
  
  ## 📋 新的项目结构
  
  ```
  offline_tasks/
  ├── scripts/                       # Python脚本
  │   ├── fetch_item_attributes.py  # 前置：获取商品属性
  │   ├── generate_session.py       # 前置：生成session
  │   ├── i2i_swing.py              # Python Swing
  │   ├── i2i_session_w2v.py        # Session W2V
  │   ├── i2i_deepwalk.py           # DeepWalk
  │   ├── i2i_content_similar.py    # 内容相似度
  │   ├── interest_aggregation.py   # 兴趣聚合
  │   ├── load_index_to_redis.py    # 加载到Redis
  │   ├── add_names_to_swing.py     # 添加商品名
  │   └── debug_utils.py            # Debug工具
  ├── collaboration/                 # C++ Swing算法
  │   ├── src/
  │   │   ├── swing.cc              # Swing实现
  │   │   ├── swing_symmetric.cc    # 对称Swing
  │   │   ├── icf_simple.cc         # 简单协同
  │   │   └── ucf.py                # 用户协同
  │   ├── bin/                      # 编译后的二进制
  │   ├── include/                  # 头文件
  │   ├── utils/                    # 工具函数
  │   ├── run.sh                    # C++ Swing执行脚本
  │   ├── Makefile                  # 编译配置
  │   └── output/                   # 输出目录
  ├── config/
  │   └── offline_config.py         # 配置文件
  ├── doc/                          # 文档中心
  │   ├── README.md
  │   ├── 快速开始.md
  │   ├── Swing算法使用指南.md
  │   ├── 离线索引数据规范.md
  │   ├── Redis数据规范.md
  │   └── ...
  ├── output/                       # 输出文件
  │   ├── item_attributes_mappings.json
  │   ├── session.txt.*
  │   └── *.txt
  ├── logs/                         # 日志文件
  ├── run.sh                        # ⭐ 主执行脚本（推荐）
  ├── run_all.py                    # Python版本（保留但简化）
  └── README.md
  ```
  
  ---
  
  ## 🚀 使用方式
  
  ### 主要方式：run.sh（推荐）
  
  ```bash
  cd /home/tw/recommendation/offline_tasks
  
  # 直接运行（使用默认配置）
  bash run.sh
  
  # 修改配置后运行
  # 编辑 run.sh 顶部的配置区域
  vim run.sh
  
  # 查看帮助
  cat run.sh | head -40  # 查看配置说明
  ```
  
  **run.sh配置项**:
  ```bash
  # 算法参数
  LOOKBACK_DAYS=730
  TOP_N=50
  DEBUG_MODE="--debug"  # 留空则不开启debug
  
  # Redis配置
  REDIS_HOST="localhost"
  REDIS_PORT=6379
  
  # 内存监控阈值
  MEM_WARN_THRESHOLD=25  # GB
  MEM_KILL_THRESHOLD=35  # GB
  ```
  
  ### 备用方式：run_all.py（简化版）
  
  ```bash
  cd /home/tw/recommendation/offline_tasks
  
  # 运行（不包括C++ Swing和Redis加载）
  python3 run_all.py --debug
  ```
  
  **注意**: `run_all.py`已简化，只包含：
  - 前置任务（商品属性、session）
  - Python算法任务（Swing、W2V、DeepWalk等）
  - 不包括C++ Swing和Redis加载
  
  ---
  
  ## 📊 执行流程对比
  
  ### run.sh（完整流程）
  
  ```
  1. 环境准备
     ├─ 清理旧进程
     └─ 创建必要目录
  
  2. 前置任务
     ├─ fetch_item_attributes.py    → 商品属性映射
     ├─ generate_session.py          → 用户session
     └─ collaboration/run.sh         → C++ Swing (高性能)
  
  3. i2i算法任务
     ├─ i2i_swing.py                → Python Swing (日期维度)
     ├─ i2i_session_w2v.py          → Session W2V
     ├─ i2i_deepwalk.py             → DeepWalk
     └─ i2i_content_similar.py      → 内容相似度
  
  4. 兴趣聚合
     └─ interest_aggregation.py     → 多维度聚合
  
  5. 加载Redis
     └─ load_index_to_redis.py      → 导入Redis
  
  6. 完成
     └─ 输出结果文件列表
  ```
  
  ### run_all.py（简化流程）
  
  ```
  1. 前置任务
     ├─ fetch_item_attributes.py
     └─ generate_session.py
  
  2. i2i算法任务
     ├─ i2i_swing.py
     ├─ i2i_session_w2v.py
     ├─ i2i_deepwalk.py
     └─ i2i_content_similar.py
  
  3. 兴趣聚合
     └─ interest_aggregation.py
  ```
  
  ---
  
  ## 💡 关键改进
  
  ### 1. 代码简化
  
  **删除的冗余代码**:
  - `run_all.py`中的`run_cpp_swing()`函数（45行）
  - 复杂的子进程调用和错误处理
  
  **简化效果**:
  - run.sh: 直接调用，清晰明了
  - run_all.py: 从270行简化到211行
  
  ### 2. 灵活性提升
  
  **run.sh的优势**:
  ```bash
  # 内存监控（自动）
  check_memory $pid "$task_name" &
  
  # 任务函数（统一）
  run_task "任务名" "python3 scripts/xxx.py"
  
  # 配置集中（顶部）
  LOOKBACK_DAYS=730
  DEBUG_MODE="--debug"
  ```
  
  ### 3. 错误处理
  
  **之前**:
  - Python捕获异常，日志分散
  - 失败后需要手动排查
  
  **现在**:
  - Shell直接显示错误
  - 内存监控自动处理OOM
  - 任务失败继续执行后续任务
  
  ---
  
  ## 🔧 常见操作
  
  ### 修改算法参数
  
  ```bash
  # 编辑 run.sh
  vim run.sh
  
  # 修改这些参数
  LOOKBACK_DAYS=365  # 回看天数
  TOP_N=100          # 推荐数量
  DEBUG_MODE=""      # 关闭debug
  ```
  
  ### 只运行特定任务
  
  ```bash
  cd /home/tw/recommendation/offline_tasks
  
  # 只运行C++ Swing
  cd collaboration && bash run.sh && cd ..
  
  # 只运行Python Swing
  python3 scripts/i2i_swing.py --lookback_days 730 --debug
  
  # 只加载Redis
  python3 scripts/load_index_to_redis.py --redis-host localhost
  ```
  
  ### 查看日志
  
  ```bash
  # 主日志
  tail -f logs/run_all_$(date +%Y%m%d).log
  
  # 内存监控日志
  tail -f logs/memory_monitor.log
  
  # Debug日志
  ls logs/debug/
  ```
  
  ---
  
  ## 📝 迁移指南
  
  如果你之前使用`python3 run_all.py`，现在改用`bash run.sh`：
  
  ### 命令对应关系
  
  | 之前 | 现在 | 说明 |
  |------|------|------|
  | `python3 run_all.py` | `bash run.sh` | 完整流程 |
  | `python3 run_all.py --debug` | `bash run.sh` | run.sh默认开启debug |
  | 无对应命令 | `bash run.sh` | 现在包含Redis加载 |
  
  ### 定时任务更新
  
  **旧的crontab**:
  ```cron
  0 3 * * * cd /home/tw/recommendation/offline_tasks && python3 run_all.py
  ```
  
  **新的crontab**:
  ```cron
  0 3 * * * cd /home/tw/recommendation/offline_tasks && bash run.sh >> logs/cron_$(date +\%Y\%m\%d).log 2>&1
  ```
  
  ---
  
  ## ⚠️ 注意事项
  
  1. **路径依赖**: 
     - 确保在`offline_tasks`目录下执行`bash run.sh`
     - 不要在其他目录执行
  
  2. **内存监控**:
     - 默认阈值：警告25GB，终止35GB
     - 根据服务器配置调整`MEM_WARN_THRESHOLD`和`MEM_KILL_THRESHOLD`
  
  3. **并行执行**:
     - 不建议同时运行多个`run.sh`实例
     - 脚本会自动清理旧进程
  
  4. **失败处理**:
     - 单个任务失败不会终止整体流程
     - 查看日志确认失败原因
  
  ---
  
  ## 🎯 总结
  
  ### 改进前后对比
  
  | 方面 | 改进前 | 改进后 |
  |------|--------|--------|
  | **目录结构** | collaboration在外层 | 统一在offline_tasks内 |
  | **主执行脚本** | run_all.py (Python) | run.sh (Shell) |
  | **代码复杂度** | 270行，多层抽象 | 214行，直接调用 |
  | **配置方式** | 参数分散 | 集中在顶部 |
  | **内存监控** | 无 | 自动监控+自动终止 |
  | **错误处理** | Python异常捕获 | Shell直接显示 |
  | **包含任务** | 不含Redis加载 | 含完整流程 |
  
  ### 核心改进
  
  1. ✅ **结构简化**: collaboration目录移入，统一管理
  2. ✅ **代码简化**: 去除冗余抽象，直接调用脚本
  3. ✅ **功能增强**: 添加内存监控、统一任务管理
  4. ✅ **易用性**: 配置集中、日志清晰、错误明确
  
  ---
  
  ## 📚 相关文档
  
  - [快速开始](./快速开始.md)
  - [运行脚本指南](./运行脚本指南.md)
  - [故障排查指南](./故障排查指南.md)
  - [系统改进总结](./系统改进总结-20241017.md)
  
  ---
  
  **更新时间**: 2024-10-17  
  **状态**: ✅ 已完成并测试