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