功能规范: 004 - 系统能力与集成

本文档定义了“蚊子”传播系统中与“系统能力与集成”相关的功能。

1. 用户故事与验收标准 (User Stories & Acceptance Criteria)

用户故事	验收标准	优先级
作为第三方应用，当一个新用户通过邀请链接完成注册后，我希望能通过API通知“蚊子”系统，以便为邀请者记功和发放奖励。	1. 提供一个安全的、基于`X-API-Key` HTTP头认证的回调API。 2. API需接收一个在邀请链接中传递的唯一`tracking_id`（必需），以及第三方系统中的`external_user_id`（可选）。 3. API有清晰的成功/失败返回码。 4. (澄清) API需具备幂等性，对于重复的`tracking_id`调用应返回成功，但只记功一次。	高
作为系统，需要能初步识别和拦截刷单行为，以保证活动的公平性和数据准确性。	1. (澄清) 在用户点击邀请链接的环节，收集其IP和设备指纹信息。 2. (澄清) 对回调API进行速率限制，默认为“每分钟100次/API Key”，并支持在后台配置此数值。 3. 可配置是否对来源IP进行校验。	高
作为系统，需要能自动完成奖励发放，以降低运营成本和提升用户体验。	1. 可通过API与内部账户系统或第三方API打通，完成积分/优惠券发放。 2. (澄清) 当奖励发放失败时，应自动进入延迟重试队列，重试3次后仍失败则标记为“发放失败”并通知管理员。	中

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调用方式。