33 lines
3.1 KiB
Markdown
33 lines
3.1 KiB
Markdown
# 功能规范: 004 - 系统能力与集成
|
||
|
||
本文档定义了“蚊子”传播系统中与“系统能力与集成”相关的功能。
|
||
|
||
## 1. 用户故事与验收标准 (User Stories & Acceptance Criteria)
|
||
|
||
| 用户故事 | 验收标准 | 优先级 |
|
||
| :--- | :--- | :--- |
|
||
| **作为第三方应用**，当一个新用户通过邀请链接完成注册后，我希望能通过API通知“蚊子”系统，以便为邀请者记功和发放奖励。 | 1. 提供一个安全的、基于`X-API-Key` HTTP头认证的回调API。<br>2. API需接收一个在邀请链接中传递的唯一`tracking_id`（必需），以及第三方系统中的`external_user_id`（可选）。<br>3. API有清晰的成功/失败返回码。<br>4. **(澄清)** API需具备幂等性，对于重复的`tracking_id`调用应返回成功，但只记功一次。 | **高** |
|
||
| **作为系统**，需要能初步识别和拦截刷单行为，以保证活动的公平性和数据准确性。 | 1. **(澄清)** 在用户点击邀请链接的环节，收集其IP和设备指纹信息。<br>2. **(澄清)** 对回调API进行速率限制，默认为“每分钟100次/API Key”，并支持在后台配置此数值。<br>3. 可配置是否对来源IP进行校验。 | **高** |
|
||
| **作为系统**，需要能自动完成奖励发放，以降低运营成本和提升用户体验。 | 1. 可通过API与内部账户系统或第三方API打通，完成积分/优惠券发放。<br>2. **(澄清)** 当奖励发放失败时，应自动进入延迟重试队列，重试3次后仍失败则标记为“发放失败”并通知管理员。 | **中** |
|
||
|
||
## 2. 澄清与边缘场景 (Clarifications & Edge Cases)
|
||
|
||
- **API幂等性 (API Idempotency)**:
|
||
- 回调API必须是幂等（idempotent）的。系统将记录已成功处理的 `tracking_id`。如果收到一个已处理过的 `tracking_id`，系统将直接返回成功状态，但不会重复执行奖励逻辑。
|
||
|
||
- **回调API负载 (Callback API Payload)**:
|
||
- `tracking_id` (string, required): 从邀请链接中获得的唯一追踪ID。
|
||
- `external_user_id` (string, optional): 新用户在第三方系统中的ID，用于对账。
|
||
- `timestamp` (integer, optional): 事件发生的时间戳。
|
||
|
||
- **防刷单信息收集 (Anti-Fraud Info Collection)**:
|
||
- 用户的IP和设备指纹信息在点击我方生成的邀请链接（重定向前）时捕获，并与 `tracking_id` 关联存储。后续可基于此信息进行风险评估。
|
||
|
||
- **奖励发放重试机制 (Reward Issuance Retries)**:
|
||
- 首次发放失败的奖励任务将进入一个延迟队列。
|
||
- 队列将以递增的时间间隔（例如：5分钟后，15分钟后，30分钟后）自动重试最多3次。
|
||
- 3次全部失败后，该任务将被标记为“永久失败”，并生成一条待办事项或通知给系统管理员进行人工干预。
|
||
|
||
- **奖励接口适配 (Reward API Adaptability)**:
|
||
- 奖励发放模块在设计上应是可扩展的，通过适配器模式（Adapter Pattern）来支持未来接入不同类型的第三方奖励系统。V1.0将优先实现一种基于 `token` 认证的RESTful API调用方式。
|