1#

handlers/README_CLEANUP.md

-# 调试语句清理工具使用说明
-
-## 工具简介
-
-`cleanup_debug_statements.py` 是一个智能化的调试语句清理脚本,可以自动删除项目中的调试代码,同时保留功能性代码。
-
-## 功能特性
-
-### ✅ 会删除的内容
-
-1. **调试print语句**
-   - 包含调试关键词: `🔍`、`调试`、`DEBUG`、`debug`、`测试`、`test`
-   - 包含调试标记: `[调试]`、`[DEBUG]`、`[测试]`
-   - 空print语句或只打印分隔线的语句
-
-2. **调试日志语句**
-   - `logging.debug(...)` 
-   - `logger.debug(...)`
-
-3. **调试注释**
-   - 包含调试关键词的注释
-   - 不包含重要标记的调试注释
-
-### ❌ 不会删除的内容
-
-1. **功能性输出**
-   - 包含: `错误`、`警告`、`成功`、`失败`、`完成`
-   - 包含: `ERROR`、`WARNING`、`INFO`
-
-2. **重要注释**
-   - `TODO`、`FIXME`、`XXX`、`HACK`、`NOTE`
-
-3. **普通代码**
-   - 所有非调试的正常代码
-
-## 使用方法
-
-### 1. 运行脚本
-
-```bash
-# 在项目根目录下运行
-python handlers/cleanup_debug_statements.py
-```
-
-### 2. 确认操作
-
-脚本会显示清理规则并要求确认:
-```
-是否继续清理? (y/n): 
-```
-
-输入 `y` 继续,输入 `n` 取消。
-
-### 3. 查看结果
-
-清理完成后会显示:
-- 扫描文件总数
-- 修改文件数量
-- 删除语句总数
-- 备份目录位置
-
-## 安全保障
-
-### 自动备份
-
-- 每次运行都会创建完整备份
-- 备份位置: `backups/cleanup_YYYYMMDD_HHMMSS/`
-- 保留原始文件的完整目录结构
-
-### 恢复方法
-
-如果需要恢复,只需从备份目录复制文件回来:
-
-```bash
-# 示例: 恢复单个文件
-cp backups/cleanup_20251126_203000/handlers/app.py handlers/app.py
-
-# 示例: 恢复整个目录
-cp -r backups/cleanup_20251126_203000/handlers/* handlers/
-```
-
-## 清理报告
-
-脚本会生成详细的清理报告: `handlers/CLEANUP_REPORT.md`
-
-报告内容包括:
-- 清理时间
-- 备份目录
-- 清理统计
-- 每个文件的详细清理记录(按删除数量排序)
-
-## 示例
-
-### 会被删除的代码
-
-```python
-# 调试print
-print(f"🔍 [调试] 变量值: {value}")
-print(f"[DEBUG] 进入函数")
-print("="*60)  # 分隔线
-
-# 调试日志
-logging.debug("调试信息")
-logger.debug(f"变量: {var}")
-
-# 调试注释
-# 🔍 调试: 这里需要检查
-# DEBUG: 临时代码
-```
-
-### 会被保留的代码
-
-```python
-# 功能性输出
-print(f"❌ 错误: {error_msg}")
-print(f"✅ 操作成功")
-logging.info("程序启动")
-
-# 重要注释
-# TODO: 需要优化性能
-# FIXME: 修复边界情况
-# NOTE: 这是重要说明
-
-# 普通代码
-result = process_data(input_data)
-```
-
-## 注意事项
-
-1. **首次使用建议**
-   - 先在测试分支运行
-   - 检查清理结果
-   - 确认无误后再应用到主分支
-
-2. **排除目录**
-   - 自动排除: `__pycache__`, `.git`, `venv`, `env`, `backups`, `database`
-   - 只处理 `.py` 文件
-
-3. **保守策略**
-   - 默认采用保守策略
-   - 不确定的语句不会删除
-   - 优先保留而非删除
-
-## 自定义配置
-
-如需修改清理规则,可以编辑脚本中的以下部分:
-
-```python
-# 调试关键词(会被删除)
-self.debug_keywords = [
-    r'🔍', r'调试', r'DEBUG', r'debug', r'测试', r'test',
-    # 添加更多关键词...
-]
-
-# 保留关键词(不会被删除)
-self.keep_keywords = [
-    r'TODO', r'FIXME', r'XXX', r'HACK', r'NOTE',
-    r'错误', r'警告', r'成功', r'失败', r'完成',
-    # 添加更多关键词...
-]
-```
-
-## 技术支持
-
-如遇到问题:
-1. 检查备份目录是否正常创建
-2. 查看清理报告了解详细信息
-3. 从备份恢复文件
-4. 调整清理规则后重新运行
-
----
-
-**最后更新**: 2025-11-26