bindbox-game/docs/优化抖音定时任务/ALIGNMENT_优化抖音定时任务.md

ALIGNMENT - 优化抖音定时任务

原始需求

由于抖音 API 被风控,系统使用代理 IP 导致请求速度很慢。需要优化定时任务,在保证功能不丢失的前提下降低 API 调用频率和成本。

项目上下文分析

现有技术栈

• 语言: Go 1.24
• 框架: Gin
• 数据库: MySQL (GORM)
• 定时任务: 原生 goroutine + time.Sleep
• 外部 API: 抖音开放平台订单接口

现有架构

internal/service/douyin/
├── scheduler.go        # 定时任务调度器
├── order_sync.go       # 订单同步逻辑
└── reward_dispatcher.go # 奖励发放逻辑

现有定时任务

1. FetchAndSyncOrders: 按用户同步订单 (每 5 分钟)
2. SyncAllOrders: 全量订单同步 (每 5 分钟)
3. GrantLivestreamPrizes: 直播奖品发放 (每 5 分钟)
4. SyncRefundStatus: 退款状态同步 (每 5 分钟)
5. GrantMinesweeperQualifications: 扫雷资格补发 (已禁用)

核心业务目标

1. 同步最新订单: 及时获取抖店订单状态变更
2. 按用户同步: 关联订单到已绑定用户
3. 下发奖励: 自动发放游戏券、积分、直播奖品

需求理解

核心问题

• 代理 IP 请求慢 (每次 API 调用可能需要 10-60 秒)
• 每 5 分钟执行 4 个任务,频繁调用抖音 API
• 存在功能重复 (FetchAndSyncOrders 和 SyncAllOrders)

优化目标

• 降低 API 调用频率 80%+
• 保持核心功能完整性
• 支持手动触发同步
• 用户体验不受影响

边界确认

包含范围:

• 调整定时任务执行频率
• 移除冗余的同步逻辑
• 新增管理后台手动同步接口
• 保留前端按需同步 (已有 5 秒限流)

不包含范围:

• 不修改抖音 API 调用逻辑
• 不修改奖励发放逻辑
• 不修改数据库结构

技术方案 (方案 3: 混合模式)

定时任务调整

原频率 (每 5 分钟):
- FetchAndSyncOrders (按用户)
- SyncAllOrders (全量)
- GrantLivestreamPrizes (直播)
- SyncRefundStatus (退款)

新频率:
- SyncAllOrders: 每 1 小时 (降低 92%)
- GrantLivestreamPrizes: 每 5 分钟 (保持)
- SyncRefundStatus: 每 2 小时 (降低 96%)
- 移除 FetchAndSyncOrders (冗余)

前端按需同步 (已有)

• GET /api/public/livestream/{access_code}/pending-orders
• 内部调用 SyncAllOrders (5 秒限流)
• 用户主动刷新时触发

管理后台手动触发 (新增)

• POST /api/admin/douyin/sync-all - 全量同步
• POST /api/admin/douyin/sync-refund - 退款同步
• POST /api/admin/douyin/grant-prizes - 发放奖品
• 仅管理员可访问

验收标准

1. ✅ 定时任务频率调整完成
2. ✅ 移除 FetchAndSyncOrders 调用
3. ✅ 管理后台接口实现并测试通过
4. ✅ API 调用频率降低 80% 以上
5. ✅ 直播奖品发放延迟 ≤ 5 分钟
6. ✅ 用户前端体验无影响
7. ✅ 编译通过,无语法错误

风险评估

• 低风险: 定时任务频率调整
• 低风险: 移除冗余逻辑
• 中风险: 新增管理接口 (需要权限控制)

疑问澄清

无疑问,需求明确。