# 实施计划: 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` 表中的失败任务列表，方便管理员进行手动处理。