wenzi/specs/004-system-integration/plan.md

实施计划: 004 - 系统能力与集成

本文档为“系统能力与集成”功能规格的技术实施计划。

1. 总体思路

本功能模块是系统的核心支柱，涉及对外API和内部关键任务处理，必须优先考虑安全性、稳定性和可扩展性。我们将设计一个健壮的回调接口，并使用消息队列来解耦和异步化奖励发放流程。

2. 后端开发任务 (Backend Tasks)

2.1. 核心服务与数据库设计

• 回调API幂等性保证

  • 数据库: 创建 processed_callbacks 表，包含 tracking_id (主键/唯一索引) 和 created_at。用于记录已处理的回调，防止重复处理。

• 防刷单数据支持

  • 数据库: 在 invitations 表（或关联的点击记录表）中增加 ip_address 和 user_agent 字段，在用户点击邀请链接时记录。

• 异步奖励发放服务

  • 技术选型: 引入消息队列系统（如 RabbitMQ 或基于Redis的 BullMQ）。
  • 数据库: 创建 failed_reward_jobs 表，用于记录多次重试后仍失败的奖励任务，字段包括 reward_id, reason, payload, failed_at。
  • 队列定义: 创建一个名为 reward_issuance 的队列。
  • Worker开发: 创建一个独立的Worker进程，专门用于监听和处理 reward_issuance 队列中的任务。

2.2. API Endpoint 设计与实现

• POST /api/v1/callback/register: 接收第三方注册通知
  • 中间件 (Middleware):
    1. 认证: 实现一个检查 X-API-Key 请求头的认证中间件。
    2. 速率限制: 实现一个基于Redis的速率限制中间件，根据API Key进行限制，配置可后台调整。
  • 控制器逻辑 (Controller Logic):
    1. 检查 tracking_id 是否存在于 processed_callbacks 表中，若存在则直接返回 200 OK。
    2. 验证 tracking_id 的有效性。
    3. 将 tracking_id 存入 processed_callbacks 表。
    4. 将一个“发放奖励”的任务（包含奖励所需信息）推送到 reward_issuance 消息队列。
    5. 返回 200 OK。

2.3. 奖励发放Worker实现

• 任务处理逻辑:
  • Worker从队列中获取任务。
  • 根据任务中的奖励类型，调用对应的适配器（Adapter）来与外部奖励系统API交互。
• 错误与重试处理:
  • 如果API调用失败，检查当前任务的重试次数。
  • 如果小于3次，则将任务重新放回队列，并设置指数退避（exponential backoff）的延迟时间（如5m, 15m, 30m）。
  • 如果达到3次，则将任务信息存入 failed_reward_jobs 表，并触发管理员通知（如邮件或Webhook）。

3. 前端开发任务 (Frontend Tasks)

• 本功能模块主要为后端实现，前端开发任务较少。
• 管理员通知: 可能需要在管理后台开发一个界面，用于展示 failed_reward_jobs 表中的失败任务列表，方便管理员进行手动处理。