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

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调用，管理整个页面的数据流、加载和错误状态。