ai-talk-callback/REFACTOR_GUIDE.md

代码重构指南

Service 模块重构

重构内容

将以下业务逻辑函数从 app/celery_tasks.py 移动到独立的 app/callback_service.py 模块中：

移动的函数

1. save_callback_data_items - 保存回调数据到数据库
2. get_uncompleted_callback_log - 获取未完成的回调日志
3. get_callback_log_data - 获取回调日志数据
4. check_phone_number_threshold - 检查手机号阈值
5. call_external_api_with_retry - 带重试的外部API调用
6. mark_callback_log_completed - 标记回调日志为完成
7. _log_dtc_push_call - 记录API调用日志

重构优势

1. 代码组织优化

• 关注点分离：Celery 任务专注于任务调度，业务逻辑独立到 Service 层
• 代码复用：Service 函数可以被其他模块直接调用，不限于 Celery 任务
• 维护性提升：业务逻辑集中管理，便于测试和维护

2. 模块职责清晰

• celery_tasks.py: 负责任务定义和调度逻辑
• callback_service.py: 负责回调处理的核心业务逻辑

3. 可测试性增强

• Service 函数可以独立进行单元测试
• 不依赖 Celery 环境，测试更加便捷

使用方式

在 Celery 任务中使用

from app.callback_service import (
    save_callback_data_items,
    get_uncompleted_callback_log,
    call_external_api_with_retry
)

# 直接调用服务函数
callback_log_data = get_uncompleted_callback_log(conn)
if callback_log_data:
    save_callback_data_items(conn, data_list, callback_log_id)

在其他模块中使用

from app.callback_service import check_phone_number_threshold

# 直接使用业务逻辑
exceeds, is_valid = check_phone_number_threshold(conn, phone_number)

向后兼容性

• ✅ 所有现有功能保持不变
• ✅ Celery 任务正常工作
• ✅ API 接口行为一致
• ✅ 数据库操作不变

文件结构

app/
├── callback_service.py    # 新增：回调处理服务
├── celery_tasks.py        # 重构：仅包含任务定义
├── celery_app.py          # 保持不变
└── ...                     # 其他文件保持不变

这次重构提高了代码的可维护性和可测试性，同时保持了完全的向后兼容性。