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

specs/001-activity-management/plan.md

@@ -0,0 +1,86 @@
+# 实施计划: 001 - 活动管理
+
+本文档为“活动管理”功能规格的技术实施计划。
+
+## 1. 总体思路
+
+采用前后端分离的架构。后端负责提供RESTful API，处理所有业务逻辑和数据持久化。前端负责提供一个响应式的、用户友好的管理界面，供管理员创建和配置活动。
+
+## 2. 后端开发任务 (Backend Tasks)
+
+### 2.1. 数据库 Schema 设计
+
+需要设计以下数据表来支持活动管理功能：
+
+- **`activities` (活动表)**
+    - `id` (主键)
+    - `name` (活动名称, string)
+    - `start_time_utc` (开始时间, datetime)
+    - `end_time_utc` (结束时间, datetime)
+    - `target_users_config` (目标用户配置, json) - 存储用户ID列表或标签
+    - `page_content_config` (页面内容配置, json) - 存储文案和图片URL
+    - `reward_calculation_mode` (奖励计算模式, enum: `delta`, `cumulative`)
+    - `status` (活动状态, enum: `draft`, `active`, `ended`)
+
+- **`activity_rewards` (阶梯奖励规则表)**
+    - `id` (主键)
+    - `activity_id` (外键, 关联 `activities`)
+    - `invite_threshold` (邀请人数阈值, integer)
+    - `reward_type` (奖励类型, enum: `points`, `coupon`)
+    - `reward_value` (奖励值, string) - 积分数量或优惠券批次ID
+    - `skip_validation` (跳过校验, boolean)
+
+- **`multi_level_reward_rules` (多级奖励规则表)**
+    - `id` (主键)
+    - `activity_id` (外键, 关联 `activities`)
+    - `level` (奖励层级, integer, e.g., 2, 3)
+    - `coefficient_percent` (衰减系数-百分比, integer)
+
+- **`api_keys` (API密钥表)**
+    - `id` (主键)
+    - `key_hash` (密钥的哈希值, string) - **绝不存储明文密钥**
+    - `scope_type` (范围类型, enum: `account`, `activity`)
+    - `scope_id` (范围ID, integer) - 对应账户ID或活动ID
+    - `created_at` (创建时间, datetime)
+    - `last_used_at` (最后使用时间, datetime, 可选)
+
+### 2.2. API Endpoint 设计
+
+设计以下RESTful API接口：
+
+- `POST /api/v1/activities`: **创建新活动**
+    - Request Body: 包含活动所有配置信息。
+    - Response: 返回创建成功的活动详情。
+
+- `PUT /api/v1/activities/{id}`: **更新活动**
+    - Request Body: 包含需要更新的活动配置。
+    - Response: 返回更新后的活动详情。
+
+- `GET /api/v1/activities/{id}`: **获取活动详情**
+    - Response: 返回指定ID的活动完整配置。
+
+- `POST /api/v1/api-keys`: **创建API密钥**
+    - Request Body: `{ scope_type, scope_id }`
+    - Response: 返回新生成的API Key (仅此一次)。
+
+- `DELETE /api/v1/api-keys/{id}`: **吊销API密钥**
+    - Response: 成功状态码。
+
+## 3. 前端开发任务 (Frontend Tasks)
+
+### 3.1. UI 组件设计
+
+需要开发一系列Vue组件来构建活动创建/编辑表单：
+
+- **`ActivityEditor.vue`**: 主表单容器，管理整个活动配置的状态。
+- **`GeneralSettings.vue`**: 用于配置活动名称、时间（需处理UTC与本地时间的转换）。
+- **`TargetingEditor.vue`**: 用于配置目标用户，支持文本输入或文件上传。
+- **`PageContentEditor.vue`**: 富文本编辑器及图片上传/链接组件（处理30MB大小限制和格式校验）。
+- **`RewardRuleEditor.vue`**: 核心组件，用于配置阶梯奖励和多级奖励，包含奖励模式切换和计算示例的实时预览。
+- **`ApiKeyManager.vue`**: 用于展示API密钥列表（不显示密钥本身）、生成新密钥（弹窗显示一次）、吊销密钥。
+
+### 3.2. 状态管理与API集成
+
+- 使用 `Pinia` 等状态管理库来管理复杂的表单数据。
+- 创建一个API客户端模块 (`apiClient.js`)，封装所有对后端API的请求。
+- 在组件中调用API，并处理加载（loading）和错误（error）状态，提供流畅的用户体验。

specs/001-activity-management/spec.md

@@ -0,0 +1,33 @@
+# 功能规范: 001 - 活动管理
+
+本文档定义了“蚊子”传播系统中与“活动管理”相关的功能。
+
+## 1. 关键实体 (Key Entities)
+
+- **活动 (Activity)**: 营销活动的核心载体，包含生命周期、规则、奖励等信息。
+- **用户 (User)**: 系统的参与者，分为`管理员`和`传播者`两种角色。
+- **奖励 (Reward)**: 用于激励用户的物品，V1.0支持`积分`和`优惠券`。
+- **邀请 (Invitation)**: 用户之间的推荐关系，是构成裂变网络的基础。
+- **API密钥 (API Key)**: 用于第三方系统与本系统认证的凭证。
+- **追踪ID (Tracking ID)**: 标识单次邀请-注册流程的唯一ID。
+
+## 2. 用户故事与验收标准 (User Stories & Acceptance Criteria)
+
+| 用户故事 | 验收标准 | 优先级 |
+| :--- | :--- | :--- |
+| **作为管理员**，我希望能创建一个有时限的邀请活动，以便于策划和管理营销节奏。 | 1. 可设定活动名称、开始时间、结束时间。<br>2. 活动到期后自动停止。<br>3. **(澄清)** 当结束时间早于开始时间时，系统应阻止保存并给出明确提示。 | **高** |
+| **作为管理员**，我希望可以设定活动仅对特定用户群体开放，以便于进行精准营销。 | 1. 可配置活动参与的用户标签或ID列表。<br>2. **(澄清)** 非目标用户访问活动链接时，应被重定向到一个友好的引导页面（如“该活动仅对部分用户开放”）。 | **高** |
+| **作为管理员**，我希望可以自定义邀请页面的文案和图片，以匹配不同的活动主题和品牌风格。 | 1. 支持富文本编辑器修改文案。<br>2. 支持上传/链接图片。<br>3. **(澄清)** 上传图片大小超过30MB或格式不被支持时，应给出明确提示：“暂不支持，请重新上传”。 | **高** |
+| **作为管理员**，我希望设置阶梯式奖励规则，以便激励用户完成更高挑战。 | 1. 可配置多个奖励档位，如“邀请3人得A奖励，邀请10人得B奖励”。<br>2. **(澄清)** 管理员可选择奖励计算模式：“补差”（默认）或“叠加”。 | **高** |
+| **作为管理员**，我希望设置带有衰减系数的多级邀请奖励，以鼓励用户发展下线，扩大传播范围。 | 1. 可配置奖励层级（最多如3级）。<br>2. 可配置每一级奖励的比例或固定值。<br>3. **(澄清)** 衰减系数默认为百分比，设置界面需提供一个实时计算示例以便查看。 | **高** |
+| **作为管理员**，我希望奖励类型可以支持积分和优惠券，以适应不同运营场景。 | 1. 可选择奖励类型为积分或优惠券。<br>2. 可填写对应的积分数量或优惠券批次ID。<br>3. **(澄清)** 系统默认会校验优惠券批次ID的有效性，管理员可选择跳过校验。 | **高** |
+| **作为管理员**，我希望能为我的应用生成和管理API密钥，以便安全地将我的系统与“蚊子”系统对接。 | 1. **(澄清)** 后台提供API Key生成功能，密钥仅在生成时显示一次，后续不可查看，只能重置。<br>2. 密钥与具体活动或账户关联。 | **高** |
+
+## 3. 澄清与边缘场景 (Clarifications & Edge Cases)
+
+- **时区**: 所有时间均以 **UTC** 为准进行存储和计算，在前端展示时，应根据用户浏览器设置转换为本地时间。
+- **阶梯奖励模式**: 
+    - **补差 (默认)**: 用户达到更高奖励等级时，获得的奖励为该等级奖励与已获得奖励的差值。
+    - **叠加**: 用户达到更高奖励等级时，直接获得该等级的全部奖励，不扣除低等级奖励。
+- **多级奖励计算示例**: 在设置界面需提供一个实时计算示例，例如：`原始奖励: 100积分, L2衰减: 50%, L3衰减: 20% -> L2获得: 50积分, L3获得: 20积分`。
+- **API密钥范围**: 密钥默认为“**活动级**”。同时，管理员可在账户设置中生成“**账户级**”密钥，并在创建活动时选择使用账户级密钥或创建新的活动级密钥。

specs/001-activity-management/tasks.md

@@ -0,0 +1,38 @@
+# 开发任务列表: 001 - 活动管理
+
+基于实施计划，为“活动管理”功能分解出以下开发任务。
+
+## 后端 (Backend)
+
+### 数据库 (Database)
+
+- [x] **BE-DB-01**: 创建 `activities` 表的数据库迁移（migration）脚本。
+- [x] **BE-DB-02**: 创建 `activity_rewards` 表的数据库迁移脚本。
+- [x] **BE-DB-03**: 创建 `multi_level_reward_rules` 表的数据库迁移脚本。
+- [x] **BE-DB-04**: 创建 `api_keys` 表的数据库迁移脚本，确保 `key_hash` 字段已建立索引。
+
+### API & 业务逻辑
+
+- [x] **BE-API-01**: 实现创建活动 (`POST /api/v1/activities`) 的业务逻辑，包括输入验证。
+- [x] **BE-API-02**: 实现更新活动 (`PUT /api/v1/activities/{id}`) 的业务逻辑。
+- [x] **BE-API-03**: 实现获取活动详情 (`GET /api/v1/activities/{id}`) 的业务逻辑。
+- [x] **BE-API-04**: 实现API密钥的创建 (`POST /api/v1/api-keys`) 与安全存储（哈希加盐）。
+- [x] **BE-API-05**: 实现API密钥的吊销 (`DELETE /api/v1/api-keys/{id}`) 逻辑。
+- [x] **BE-TEST-01**: 为所有 `activities` 和 `api-keys` 相关的API Endpoints 编写单元测试和集成测试。
+
+## 前端 (Frontend)
+
+### UI 组件
+
+- [ ] **FE-UI-01**: 开发 `ActivityEditor` 核心布局组件。
+- [ ] **FE-UI-02**: 开发 `GeneralSettings` 组件，包含名称、时间选择器和客户端验证逻辑。
+- [ ] **FE-UI-03**: 开发 `TargetingEditor` 组件，用于配置目标用户。
+- [ ] **FE-UI-04**: 开发 `PageContentEditor` 组件，集成富文本编辑器和图片上传功能（包含客户端校验）。
+- [ ] **FE-UI-05**: 开发 `RewardRuleEditor` 组件，处理复杂的阶梯和多级奖励配置，并提供实时计算预览。
+- [ ] **FE-UI-06**: 开发 `ApiKeyManager` 组件，包括密钥列表（屏蔽密钥）、生成和吊销功能。
+
+### 状态管理与集成
+
+- [ ] **FE-STATE-01**: 配置 Redux/Zustand store，用于管理 `ActivityEditor` 的全局状态。
+- [ ] **FE-API-01**: 创建一个API客户端服务，用于封装所有与后端交互的fetch请求。
+- [ ] **FE-INT-01**: 将API客户端服务集成到所有相关UI组件中，并妥善处理加载（Loading）、错误（Error）和成功（Success）的UI状态反馈。

specs/002-data-analytics/plan.md

@@ -0,0 +1,52 @@
+# 实施计划: 002 - 数据与分析
+
+本文档为“数据与分析”功能规格的技术实施计划。
+
+## 1. 总体思路
+
+数据分析功能对性能有较高要求。为避免实时计算带来的延迟，核心指标将通过定时任务进行预聚合。前端将使用专业的图表和网络图库来提供丰富的可视化效果。
+
+## 2. 后端开发任务 (Backend Tasks)
+
+### 2.1. 数据处理与存储
+
+- **创建预聚合统计表**: 
+    - 新建 `daily_activity_stats` 表，字段包括 `activity_id`, `date`, `pv`, `uv`, `participants`, `new_registrations`, `k_factor`, `total_rewards_cost`。
+- **开发定时任务 (Cron Job)**:
+    - 创建一个每日执行的定时任务，用于计算前一天的各项核心指标，并填充到 `daily_activity_stats` 表中。
+- **缓存策略**: 
+    - 为“超级传播者榜单”的查询结果设置缓存（如 Redis，缓存时间5-10分钟），以降低数据库压力。
+
+*技术选型说明*: 裂变网络图的查询，V1.0阶段可通过SQL的递归查询（CTE）实现。若未来性能遇到瓶颈，可考虑引入图数据库（如 Neo4j）进行优化。
+
+### 2.2. API Endpoint 设计
+
+- `GET /api/v1/activities/{id}/stats`: **获取仪表盘数据**
+    - Query Params: `start_date`, `end_date`。
+    - Logic: 从 `daily_activity_stats` 表中查询指定时间范围的数据。
+
+- `GET /api/v1/activities/{id}/graph`: **获取裂变网络图数据**
+    - Query Params: `center_user_id`, `depth`。
+    - Logic: 根据中心用户ID，递归查询指定深度的上下级关系并返回节点和边的集合。
+
+- `GET /api/v1/activities/{id}/leaderboard`: **获取超级传播者榜单**
+    - Query Params: `sort_by` (enum: `direct`, `total`), `page`, `limit`。
+    - Logic: 执行排序和分页查询，优先从缓存读取。
+
+- `GET /api/v1/activities/{id}/leaderboard/export`: **导出榜单**
+    - Logic: 查询完整榜单数据，生成CSV格式的文件流并返回。
+
+## 3. 前端开发任务 (Frontend Tasks)
+
+### 3.1. UI 组件设计
+
+- **`AnalyticsDashboard.vue`**: 数据分析页面的主容器，包含日期选择器和各个图表/榜单组件。
+- **`DateRangePicker.vue`**: 可复用的日期范围选择组件，包含预设（昨天、过去7天等）和自定义范围功能。
+- **`StatsChart.vue`**: 使用 `ECharts for Vue` 库，将核心指标以折线图或柱状图的形式进行可视化展示。
+- **`NetworkGraphViewer.vue`**: 使用 `Vue Flow` 库，渲染网络图。需要实现节点的懒加载、点击展开、缩放和平移功能。
+- **`LeaderboardTable.vue`**: 可排序的表格组件，包含排序切换控件和“导出CSV”按钮。
+
+### 3.2. API 集成
+
+- 在API客户端模块中新增上述4个数据相关接口的请求函数。
+- 在 `AnalyticsDashboard.vue` 组件中统一管理数据获取、加载状态和错误处理，并将数据分发给各个子组件。

specs/002-data-analytics/spec.md

@@ -0,0 +1,28 @@
+# 功能规范: 002 - 数据与分析
+
+本文档定义了“蚊子”传播系统中与“数据与分析”相关的功能。
+
+## 1. 用户故事与验收标准 (User Stories & Acceptance Criteria)
+
+| 用户故事 | 验收标准 | 优先级 |
+| :--- | :--- | :--- |
+| **作为管理员**，我希望在后台看到活动的核心数据仪表盘，以便实时监控活动健康度。 | 1. 仪表盘展示PV, UV, 参与人数, 新增注册数, K因子, CAC。<br>2. **(澄清)** 数据仪表盘提供时间范围选择器，支持“今天(默认)”、“昨天”、“过去7天”、“本月”、“上个月”以及自定义起止日期。<br>3. **(澄清)** 各指标定义清晰（详见下方澄清部分）。 | **高** |
+| **作为管理员**，我希望以网络图的形式查看用户裂变路径，以便快速定位关键传播节点（KOL）。 | 1. 图形化展示用户间的邀请关系。<br>2. 节点可点击，并显示该用户的关键信息（用户ID、昵称、直接邀请人数、总邀请人数、注册时间）。<br>3. **(澄清)** 默认只展示目标用户的前后各一层关系，提供点击扩展功能，最多可扩展5层。 | **高** |
+| **作为管理员**，我希望能看到一个按邀请数排序的“超级传播者”榜单，以便对他们进行额外奖励或运营。 | 1. 榜单展示用户昵称、头像、总邀请人数。<br>2. **(澄清)** 默认按“直接邀请人数”排序，但支持切换为按“总邀请人数”排序。<br>3. **(澄清)** 支持将当前榜单导出为CSV文件。<br>4. **(澄清)** 排名相同时，按先达到该数量的时间排序。 | **中** |
+
+## 2. 澄清与边缘场景 (Clarifications & Edge Cases)
+
+- **指标定义 (Metric Definitions)**:
+    - **参与人数**: 成功分享了邀请链接的独立用户数。
+    - **K-因子 (K-Factor)**: `K = (总邀请转化数 / 总分享次数)`。这是一个简化的K因子，V1.0阶段用于衡量分享内容的吸引力。
+    - **CAC (用户获客成本)**: `总成本 / 新增用户数`。在V1.0中，“总成本”仅计算“已发放的奖励总价值”。
+
+- **网络图谱性能 (Graph Performance)**:
+    - 为保证性能，图谱默认只展示目标用户及与他直接关联的上下级。 
+    - 用户每次点击图谱中的一个节点，会异步加载并展开该节点的下一层关系。
+    - 从初始节点开始，最多允许用户展开5层深的关系网络。
+
+- **榜单规则 (Leaderboard Rules)**:
+    - **排序**: 榜单提供一个下拉菜单或切换按钮，允许管理员在“按直接邀请数”和“按总邀请数”之间切换视图。
+    - **平分处理**: 当排序依据的数值相同时，优先排名先达到该数值的用户。
+    - **导出**: 导出功能将当前视图（排序和筛选结果）生成一个CSV文件。

specs/002-data-analytics/tasks.md

@@ -0,0 +1,34 @@
+# 开发任务列表: 002 - 数据与分析
+
+基于实施计划，为“数据与分析”功能分解出以下开发任务。
+
+## 后端 (Backend)
+
+### 数据层 (Data Layer)
+
+- [x] **BE-DB-05**: 创建 `daily_activity_stats` 表的数据库迁移脚本。
+- [x] **BE-CRON-01**: 实现一个每日运行的定时任务，用于聚合原始数据并填充 `daily_activity_stats` 表。
+- [x] **BE-CACHE-01**: 为排行榜查询配置并实现Redis缓存逻辑。
+
+### API & 业务逻辑
+
+- [ ] **BE-API-07**: 实现获取仪表盘数据 (`GET /api/v1/activities/{id}/stats`) 的业务逻辑。
+- [ ] **BE-API-08**: 实现获取裂变网络图 (`GET /api/v1/activities/{id}/graph`) 的业务逻辑，包含递归查询。
+- [ ] **BE-API-09**: 实现获取排行榜 (`GET /api/v1/activities/{id}/leaderboard`) 的业务逻辑，包含缓存处理。
+- [ ] **BE-API-10**: 实现导出排行榜CSV文件 (`GET /api/v1/activities/{id}/leaderboard/export`) 的逻辑。
+- [ ] **BE-TEST-02**: 为所有数据分析相关的API Endpoints 编写单元测试和集成测试。
+
+## 前端 (Frontend)
+
+### UI 组件
+
+- [ ] **FE-UI-07**: 开发 `AnalyticsDashboard` 页面主容器组件。
+- [ ] **FE-UI-08**: 开发可复用的 `DateRangePicker` 组件。
+- [ ] **FE-UI-09**: 开发 `StatsChart` 组件，集成 `Recharts` 等图表库，并实现数据可视化。
+- [ ] **FE-UI-10**: 开发 `NetworkGraphViewer` 组件，集成 `react-flow` 等网络图库，并实现懒加载和交互功能。
+- [ ] **FE-UI-11**: 开发 `LeaderboardTable` 组件，实现前端排序切换和导出CSV的触发功能。
+
+### 状态管理与集成
+
+- [ ] **FE-API-02**: 在API客户端中新增所有数据分析相关的请求函数。
+- [ ] **FE-INT-02**: 在 `AnalyticsDashboard` 容器组件中集成API调用，管理整个页面的数据流、加载和错误状态。

specs/003-user-experience/plan.md

@@ -0,0 +1,54 @@
+# 实施计划: 003 - 用户端体验
+
+本文档为“用户端体验”功能规格的技术实施计划。
+
+## 1. 总体思路
+
+用户端体验是转化的关键，需要保证页面的高性能和交互的流畅性。后端需提供快速响应的API，前端则通过无限滚动等技术优化大数据量下的列表展示。
+
+## 2. 后端开发任务 (Backend Tasks)
+
+### 2.1. 新增服务与数据库设计
+
+- **短链接服务 (Short Link Service)**
+    - **数据库**: 创建 `short_links` 表，包含 `id`, `code` (唯一索引), `original_url`, `created_at`。
+    - **内部API**: 创建一个内部 `POST /api/v1/internal/shorten` 接口，用于生成和存储短链接。
+    - **公共重定向**: 创建一个公共 `GET /r/{code}` 接口，用于处理短链接的302重定向。
+
+- **海报生成服务 (Poster Generation Service)**
+    - **技术选型**: 引入图像处理库（如 Node.js 的 `sharp` 或 Python 的 `Pillow`）。
+    - **API设计**: 创建 `GET /api/v1/me/poster` 接口。默认返回 `image/png` 格式的图片文件流。当接收到 `?render=client` 参数时，返回构建海报所需的JSON数据（背景图URL、文案、二维码数据等），以支持客户端渲染的降级方案。
+
+- **数据库更新**
+    - 在 `invitations` 表（或类似表）中增加 `status` 字段 (enum: `clicked`, `registered`, `ordered`)，用于追踪邀请状态。
+
+### 2.2. API Endpoint 设计
+
+- `GET /api/v1/me/invitation-info`: **获取当前用户的邀请信息**
+    - Response: `{ short_link, ... }`，返回已生成的专属短链接。
+
+- `GET /api/v1/me/invited-friends`: **获取邀请好友列表（分页）**
+    - Query Params: `page`, `limit`。
+    - Response: 返回经过隐私处理（昵称、打码手机号、头像）的好友列表及其状态。
+
+- `GET /api/v1/me/rewards`: **获取奖励明细列表（分页）**
+    - Query Params: `page`, `limit`。
+    - Response: 返回当前用户的奖励记录列表。
+
+## 3. 前端开发任务 (Frontend Tasks)
+
+### 3.1. UI 组件设计
+
+- **`UserCenter.vue`**: 用户个人中心的主页面，整合分享和记录查看功能。
+- **`ShareModule.vue`**: 用于展示分享信息的组件，包含：
+    - “一键复制”短链接的按钮。
+    - 展示分享海报，并处理服务端/客户端渲染的逻辑。
+- **`InfiniteScrollList.vue`**: 一个可复用的列表组件，封装“滚动到底部自动加载下一页”的逻辑。
+- **`InvitedFriendItem.vue`**: 用于渲染“邀请记录”列表中的单项，展示好友的隐私保护信息和邀请状态。
+- **`RewardItem.vue`**: 用于渲染“奖励明细”列表中的单项。
+
+### 3.2. API 集成与状态管理
+
+- 在API客户端中新增与用户中心相关的接口请求函数。
+- 使用 `Pinia` 管理用户状态，并可以结合 `useSWRV` 或自定义的 `useFetch` Composable 函数来管理分页数据的获取、缓存和“无限滚动”的状态。
+- 在 `ShareModule.vue` 中实现降级逻辑：当从服务端获取海报图片失败或超时，能自动切换到客户端渲染模式。

specs/003-user-experience/spec.md

@@ -0,0 +1,29 @@
+# 功能规范: 003 - 用户端体验
+
+本文档定义了“蚊子”传播系统中与“用户端体验”相关的功能。
+
+## 1. 用户故事与验收标准 (User Stories & Acceptance Criteria)
+
+| 用户故事 | 验收标准 | 优先级 |
+| :--- | :--- | :--- |
+| **作为参与者**，我希望能方便地获取专属的邀请链接和海报，以便分享给朋友。 | 1. 页面显著位置提供“一键复制链接”按钮。<br>2. **(澄清)** 复制的链接为短链接形式。<br>3. 可生成带专属二维码的分享海报。<br>4. **(澄清)** 海报内容由管理员在活动中配置，默认在服务端生成，并提供客户端渲染作为高负载降级方案。 | **高** |
+| **作为参与者**，我希望在个人中心看到我的邀请记录和奖励明细，以便了解我的贡献和收益。 | 1. 列表展示我邀请的好友及其状态。<br>2. **(澄清)** 好友信息包含：昵称、头像、部分打码的手机号。<br>3. **(澄清)** 好友状态包含：“已点击但未注册”、“已注册”、“已下单”等。<br>4. 列表展示我获得的每一笔奖励。<br>5. **(澄清)** “邀请记录”和“奖励明细”列表均采用无限滚动方式进行分页加载。 | **高** |
+
+## 2. 澄清与边缘场景 (Clarifications & Edge Cases)
+
+- **海报生成 (Poster Generation)**: 
+    - 默认在服务端生成图片，以保证跨平台显示一致性。
+    - 需监控服务负载，当图片生成请求队列过长或CPU占用过高时，应自动切换到客户端动态渲染模式，作为降级方案。
+
+- **链接形式 (Link Format)**: 
+    - 所有向用户展示的邀请链接，都必须经过短链接服务处理，生成类似 `t.cn/xxxx` 的短格式。
+
+- **好友状态列表 (Friend Statuses)**: 
+    - V1.0阶段，需要明确追踪并展示以下几种状态：`已点击`、`已注册`、`已下单`。
+    - 该状态列表应可扩展，以适应未来更多的转化事件。
+
+- **隐私保护 (Privacy Protection)**: 
+    - 在“邀请的好友”列表中，手机号必须进行打码处理，例如 `138****1234`，仅展示头三位和后四位。
+
+- **列表加载 (List Loading)**: 
+    - 两个列表（邀请记录、奖励明细）在用户滚动到列表底部时，应自动触发加载下一页数据，无需用户点击“加载更多”按钮。

specs/003-user-experience/tasks.md

@@ -0,0 +1,35 @@
+# 开发任务列表: 003 - 用户端体验
+
+基于实施计划，为“用户端体验”功能分解出以下开发任务。
+
+## 后端 (Backend)
+
+### 核心服务与数据库
+
+- [ ] **BE-DB-06**: 创建 `short_links` 表的数据库迁移脚本。
+- [ ] **BE-DB-07**: 为 `invitations` 表增加 `status` 字段的数据库迁移脚本。
+- [ ] **BE-SVC-01**: 实现短链接生成服务，包括 `POST /api/v1/internal/shorten` 内部接口。
+- [ ] **BE-SVC-02**: 实现短链接重定向的公共接口 `GET /r/{code}`。
+- [ ] **BE-SVC-03**: 实现海报生成服务 `GET /api/v1/me/poster`，需支持图片和JSON两种返回模式。
+
+### API & 业务逻辑
+
+- [ ] **BE-API-11**: 实现获取用户专属邀请信息 (`GET /api/v1/me/invitation-info`) 的业务逻辑。
+- [ ] **BE-API-12**: 实现获取邀请好友列表 (`GET /api/v1/me/invited-friends`) 的业务逻辑，包含分页和隐私处理。
+- [ ] **BE-API-13**: 实现获取用户奖励列表 (`GET /api/v1/me/rewards`) 的业务逻辑，包含分页。
+- [ ] **BE-TEST-03**: 为所有用户端相关的API Endpoints 编写单元测试和集成测试。
+
+## 前端 (Frontend)
+
+### UI 组件
+
+- [ ] **FE-UI-12**: 开发 `UserCenter` 页面的主布局组件。
+- [ ] **FE-UI-13**: 开发 `ShareModule` 组件，实现短链接复制、海报展示及客户端渲染降级逻辑。
+- [ ] **FE-UI-14**: 开发一个可复用的 `InfiniteScrollList` 无限滚动列表组件。
+- [ ] **FE-UI-15**: 开发 `InvitedFriendItem` 和 `RewardItem` 列表项组件。
+
+### 状态管理与集成
+
+- [ ] **FE-API-03**: 在API客户端中新增所有用户端相关的请求函数。
+- [ ] **FE-INT-03**: 使用 `React Query` 或类似工具库，将 `InfiniteScrollList` 组件与后端分页接口集成。
+- [ ] **FE-INT-04**: 在 `ShareModule` 组件中，实现对海报生成接口的调用及失败/降级时的客户端渲染逻辑。

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请求函数。