chore: initial commit with CI pipeline, review and tasks docs

specs/004-system-integration/plan.md

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

specs/004-system-integration/spec.md

@@ -0,0 +1,32 @@
+# 功能规范: 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调用方式。

specs/004-system-integration/tasks.md

@@ -0,0 +1,32 @@
+# 开发任务列表: 004 - 系统能力与集成
+
+基于实施计划，为“系统能力与集成”功能分解出以下开发任务。
+
+## 后端 (Backend)
+
+### 核心服务与数据库
+
+- [ ] **BE-DB-08**: 创建 `processed_callbacks` 表的数据库迁移脚本。
+- [ ] **BE-DB-09**: 更新 `invitations` 表的迁移脚本，增加 `ip_address` 和 `user_agent` 字段。
+- [ ] **BE-DB-10**: 创建 `failed_reward_jobs` 表的数据库迁移脚本。
+- [ ] **BE-SETUP-01**: 在项目中安装、配置并初始化消息队列服务（如 RabbitMQ 或 BullMQ）。
+- [ ] **BE-WORKER-01**: 创建奖励发放Worker服务的基本结构，并连接到消息队列。
+
+### API & 业务逻辑
+
+- [ ] **BE-API-14**: 开发一个可重用的 `X-API-Key` 认证中间件。
+- [ ] **BE-API-15**: 开发一个可重用的、基于Redis的可配置速率限制中间件。
+- [ ] **BE-API-16**: 实现 `POST /api/v1/callback/register` 接口的完整逻辑，包括认证、速率限制、幂等性检查和向队列分发任务。
+- [ ] **BE-TEST-04**: 为回调API编写完整的测试用例，特别是要覆盖幂等性和速率限制的场景。
+
+### 异步任务 Worker
+
+- [ ] **BE-WORKER-02**: 在Worker中实现调用外部奖励API的逻辑（使用适配器模式）。
+- [ ] **BE-WORKER-03**: 在Worker中实现任务失败后的重试逻辑（指数退避延迟）。
+- [ ] **BE-WORKER-04**: 在Worker中实现任务重试耗尽后，将任务存入 `failed_reward_jobs` 表的逻辑。
+- [ ] **BE-ALERT-01**: 实现一个简单的通知服务，当有新条目写入 `failed_reward_jobs` 时，向管理员发送警报。
+
+## 前端 (Frontend)
+
+- [ ] **FE-UI-16**: （可选）在管理后台创建一个简单的页面，用于展示和管理失败的奖励发放任务。
+- [ ] **FE-API-04**: （可选）为上述页面开发一个获取失败任务列表的API请求函数。